PythonTeX (von Geoffrey M. Poore) ist ein Paket, das den Python-Code, den Sie im Dokument schreiben, beim Kompilieren tatsächlich ausführt und die Ergebnisse wieder in den Text einfügt. Grafiken, Tabellen und berechnete Werte stehen direkt neben dem Code, der sie erzeugt hat; dadurch entfällt das Risiko, Zahlen von Hand falsch zu übertragen, und nach einer Änderung am Quelltext werden die Resultate beim Neubau automatisch aktualisiert. Neben Python kann es auch Ruby, Julia, R, Octave und weitere Sprachen ansteuern.
Was es tut
Gewöhnliche Pakete wie listings oder minted setzen Code nur so, wie er aussieht; sie führen ihn nicht aus (siehe „Code listings“). PythonTeX unterscheidet sich dadurch, dass es Code ausführt und dessen Ausgabe in das Dokument holt. Schreiben Sie im Text \py{2**10}, wertet Python 2**10 aus und die 1024 wird genau dort gesetzt. Schreiben Sie Python-Code, der eine Grafik erzeugt, erscheint die erzeugte Abbildung als Abbildung.
Geladen wird es mit einer einzigen Zeile: \usepackage{pythontex}. Zum Ausführen brauchen Sie Python selbst; für Syntaxhervorhebung nutzt es Pygments (pip install pygments). Code läuft je „Session“ in einem eigenen Prozess, und nur geänderte Teile werden erneut ausgeführt. Auch mit schweren Rechnungen bleibt ein Neubau dadurch leichtgewichtig.
Die Befehle und Umgebungen bilden eine Familie: ein gemeinsamer Basisname wie py plus Suffix. Man wählt danach, ob ein einzelner Ausdruck inline ausgeführt werden soll, ein ganzer Block, ob der Code mit gezeigt werden soll oder nur das Ergebnis benötigt wird.
Die wichtigsten Befehle und Umgebungen
Beginnen wir mit den Inline-Befehlen. \py{expr} übergibt den Ausdruck an Python und setzt seine Stringdarstellung (\py{2**10} → 1024). Neben geschweiften Klammern funktionieren auch gleiche Begrenzungszeichen als Paar, also bedeuten \py#2**10# und \py@2**10@ dasselbe. Der Befehl dient zum Einfügen eines Werts; Zuweisungen sind nicht erlaubt (\py{a=1} ist ungültig). Wurde eine Variable vorher definiert, lässt sich ihr Wert mit \py{a} abrufen.
\py{expr}— führt den Ausdruck aus und setzt das Ergebnis (ohne Suffix).\pyc{code}— führt Code aus, setzt aber nichts (cfür code). Alles, was darin perprintausgegeben wird, wird übernommen.\pyv{code}— führt nicht aus, sondern setzt den Code unverändert (vfür verb; entsprichtpyverbatim).\pyb{code}— führt aus und setzt zugleich (bfür block).print-Ausgaben werden nicht automatisch eingefügt.\pys{code}— String-Interpolation: ersetzt!{expr}durch den ausgewerteten Wert und interpretiert den Code dann als LaTeX (sfür sub).
Für mehrere Zeilen verwendet man Umgebungen. pycode führt den Code aus, setzt aber nichts (ideal für Berechnungen oder Grafikerzeugung). pyverbatim setzt nur und führt nicht aus. pyblock führt aus und setzt zugleich. pysub ist die Umgebungsform von \pys (Interpolation von !{expr}). Ausgaben von print in pyblock oder \pyb erscheinen nicht von selbst; setzen Sie \printpythontex an die Stelle, an der sie eingefügt werden sollen.
Für eine interaktive Sitzung gibt es die Umgebung pyconsole. Jede Zeile wird behandelt, als wäre sie in einen interaktiven Python-Interpreter eingegeben worden; >>>-Prompt sowie Eingabe und Ausgabe werden gemeinsam wiedergegeben. Die Inline-Form \pycon{code} führt Code aus und übernimmt nur die Ausgabe (die Eingabe wird verworfen), praktisch zum Referenzieren von Konsolenvariablen.
Ein Beispiel
Ein typischer Ablauf: In einer pycode-Umgebung wird ein Wert berechnet, und im Fließtext wird er mit \py{…} gesetzt. Beachten Sie, dass Code und Ergebnis vollständig in einem Manuskript zusammenleben.
\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{pythontex}
\begin{document}
% 実行されるが、何も組版されない
\begin{pycode}
from math import sqrt
radius = 2.5
area = 3.14159 * radius**2
hyp = sqrt(3**2 + 4**2)
\end{pycode}
半径 \py{radius} の円の面積はおよそ \py{round(area, 2)} です。
\(2^{10} = \py{2**10}\)、また \(\sqrt{3^2+4^2} = \py{hyp}\)。
\end{document}Das ergibt sinngemäß „Die Fläche eines Kreises mit Radius 2.5 beträgt ungefähr 19.63“, gefolgt von den Gleichungen 2¹⁰ = 1024 und √(3²+4²) = 5.0. Ändern Sie radius und bauen Sie neu, ändern sich alle Zahlen im Text mit.
Der Build-Ablauf (drei Schritte)
Ein PythonTeX-Build hat drei Phasen. (1) Führen Sie wie gewohnt die LaTeX-Engine aus, etwa pdflatex; dabei wird der Code noch nicht ausgeführt, sondern in eine externe Datei extrahiert. (2) Das mitgelieferte Programm pythontex führt diesen extrahierten Code aus und speichert die Ergebnisse. (3) Führen Sie die LaTeX-Engine erneut aus; die gespeicherten Ergebnisse werden zurück ins Dokument geholt und die PDF entsteht.
pdflatex document.tex # 1) コードを抽出 / extract the code
pythontex document.tex # 2) Python で実行 / run it with Python
pdflatex document.tex # 3) 結果を取り込む / pull the output back inDer entscheidende Punkt: Der Code wird nicht von LaTeX selbst ausgeführt, sondern von einem separaten Programm pythontex dazwischen. Deshalb braucht der manuelle Drei-Schritte-Build kein --shell-escape; genau darin unterscheidet er sich von minted, das von LaTeX aus externe Befehle startet. Soll das Ganze mit einem Werkzeug wie latexmk in eine automatische Kompilation integriert werden, aktiviert man oft -shell-escape, damit der LaTeX-Lauf pythontex aufrufen kann. Mit einer Abhängigkeitsregel in .latexmkrc laufen pythontex und die nötigen Neubauten bei Codeänderungen automatisch.
Auch für japanische Dokumente funktioniert es. Ersetzen Sie pdflatex durch lualatex, und unabhängig von der Engine gelten dieselben drei Schritte; auch japanisches platex ist möglich. Wenn der Code Unicode enthält, richten Sie die Kodierung des Dokuments passend ein: unter pdfLaTeX etwa \usepackage[T1]{fontenc} zusammen mit \usepackage[utf8]{inputenc}, unter LuaLaTeX \usepackage{fontspec}.
Die sympy- und pylab-Familien
Standardmäßig gibt es neben der Python-Familie py zwei Familien für wissenschaftliches Arbeiten. Sie ersetzen lediglich den Basisnamen durch sympy oder pylab, behalten aber dieselbe Befehlsauswahl: \sympy, sympycode, sympyblock sowie \pylab, pylabcode, pylabblock.
- Die sympy-Familie — lädt die Symbolikbibliothek SymPy mit
from sympy import *. Ein mit\sympyeingefügtes Ergebnis wird mit SymPysLatexPrinterkontextgerecht als LaTeX formatiert. - Die pylab-Familie — lädt matplotlibs Modul
pylabmitfrom pylab import *und bringt Plotten und NumPy in einen gemeinsamen Namensraum.
Die Familien können parallel als unabhängige Befehls- und Umgebungssätze genutzt werden. Man kann etwa einen symbolisch mit SymPy gelösten Ausdruck per \sympy als saubere Formel setzen und zugleich in pylabcode eine matplotlib-Grafik erzeugen, die mit \includegraphics eingebunden wird.
depythontex und Sicherheit
Ein PythonTeX-Dokument mischt LaTeX und Python; es eignet sich daher schlecht für Einreichungssysteme, die Spezialpakete ablehnen, oder für Konvertierungen in andere Formate. Hier hilft depythontex. Wird mit der Paketoption depythontex gebaut, entsteht eine Hilfsdatei <jobname>.depytx; das Skript depythontex.py gleicht sie mit dem Original ab und erzeugt ein separates Dokument, in dem alle PythonTeX-Befehle und -Umgebungen durch den gesetzten Code und seine Ausgabe ersetzt sind. Das Ergebnis ist normales, von PythonTeX unabhängiges LaTeX mit eingebrannten Resultaten, geeignet zum Teilen oder für Journal-Einreichungen.
# 1) depythontex オプション付きで通常の 3 ステップを実行
# Run the usual three steps with the depythontex option on
pdflatex document.tex
pythontex document.tex
pdflatex document.tex
# 2) 静的な版を書き出す（-o で出力名を指定）
# Write the static version (-o gives the output name)
depythontex -o document-plain.tex document.texBeachten Sie schließlich die Sicherheit. Das Kompilieren eines Dokuments mit PythonTeX führt tatsächlich Python, und unter Umständen andere Programme, auf Ihrem Rechner aus. Kompilieren Sie daher nur Dokumente aus vertrauenswürdigen Quellen. Das ist eine unvermeidliche Eigenschaft jedes Mechanismus, der Code „ausführt“, genau wie bei anderen Ansätzen mit --shell-escape.