1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
\documentclass{article}
\usepackage{helvet}
\usepackage{courier}
\renewcommand{\familydefault}{\sfdefault}
\usepackage[margin=2.5cm]{geometry}
\usepackage{parskip}
\linespread{1.2}
\usepackage{tabularx}
\usepackage{xcolor}
\usepackage[listings,breakable,xparse]{tcolorbox}
\tcbset{breakable,listing only,size=fbox,colframe=black!10,boxrule=3pt,colback=black!10}
\NewTotalTCBox{\inlcode}{ v }{
on line,boxsep=0pt,left=0.5ex,right=0.5ex,top=0pt,bottom=0pt,
boxrule=0pt}{\lstinline[style=tcblatex]|#1|\rule[-.3\baselineskip]{0pt}{0.9\baselineskip}}
\usepackage{url}
\title{The \emph{pyluatex} package}
\author{Tobias Enderle\\\url{https://github.com/tndrle/PyLuaTeX}}
\date{v0.1.3 (2021/07/15)}
\begin{document}
\maketitle
\raggedright
\textbf{Execute Python code on the fly in your \LaTeX{} documents}
PyLuaTeX allows you to execute Python code and to include the resulting output in your \LaTeX{} documents in a \textit{single compilation run}.
\LaTeX{} documents must be compiled with Lua\LaTeX{} for this to work.
\section{Example}
\begin{enumerate}
\item \LaTeX{} document \inlcode|example.tex|
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
\documentclass{article}
\usepackage{pyluatex}
\begin{python}
import math
import random
random.seed(0)
greeting = 'Hello PyLuaTeX!'
\end{python}
\newcommand{\randint}[2]{\py{random.randint(#1, #2)}}
\begin{document}
\py{greeting}
$\sqrt{371} = \py{math.sqrt(371)}$
\randint{2}{5}
\end{document}
\end{tcblisting}
\item Compile using Lua\LaTeX{} (shell escape is required)
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
lualatex -shell-escape example.tex
\end{tcblisting}
\end{enumerate}
\textbf{Note:} Running \LaTeX{} with the shell escape option enabled allows arbitrary code to be
executed. For this reason, it is recommended to compile trusted documents only.
\subsection{Further Examples}
The folder \inlcode|example| contains additional example documents:
\begin{itemize}
\item \inlcode|readme-example.tex|\\[0.5ex]
The example above
\item \inlcode|sessions.tex|\\[0.5ex]
Demonstrates the use of different Python sessions in a document
\item \inlcode|data-visualization.tex|\\[0.5ex]
Demonstrates the visualization of data using \textit{pgfplots} and \textit{pandas}
\item \inlcode|matplotlib-external.tex|\\[0.5ex]
Demonstrates how \textit{matplotlib} plots can be generated and included in a document
\item \inlcode|matplotlib-pgf.tex|\\[0.5ex]
Demonstrates how \textit{matplotlib} plots can be generated and included in a document using \textit{PGF}
\end{itemize}
For more intricate use cases have a look at our tests in the folder \inlcode|test|.
\section{Installation}
PyLuaTeX is available on CTAN\footnote{\url{https://ctan.org/pkg/pyluatex}} and in MiKTeX.
It will be available in TeX Live soon (when you read this it probably already is).
To install PyLuaTeX \textbf{manually}, do the following steps:
\begin{enumerate}
\item Locate your local \textit{TEXMF} folder\\[0.5ex]
The location of this folder may vary. Typical defaults for TeX Live are \inlcode|~/texmf| for Linux,
\inlcode|~/Library/texmf| for macOS, and \inlcode|C:\Users\<user name>\texmf| for Windows.
If you are lucky, the command \inlcode|kpsewhich -var-value=TEXMFHOME| tells you the location.
For MiKTeX, the folder can be found and configured in the \textit{MiKTeX Console}.
\item Download the latest release\footnote{\url{https://github.com/tndrle/PyLuaTeX/releases/latest}} of PyLuaTeX
\item Put the downloaded files in the folder \inlcode|TEXMF/tex/latex/pyluatex| (where \inlcode|TEXMF| is the folder located in 1.)\\[0.5ex]
The final folder structure must be
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
TEXMF/tex/latex/pyluatex/
|-- pyluatex-interpreter.py
|-- pyluatex-json.lua
|-- pyluatex.lua
|-- pyluatex.sty
|-- ...
\end{tcblisting}
\end{enumerate}
\section{Reference}
PyLuaTeX offers a simple set of options, macros and environments.
\subsection{Package Options}
\begin{itemize}
\item \inlcode|verbose|\\[0.5ex]
If this option is enabled, Python input and output is written to the log file.\\[0.5ex]
\textit{Example:} \inlcode|\usepackage[verbose]{pyluatex}|
\item \inlcode|executable|\\[0.5ex]
Specifies the path to the Python executable. (default: \inlcode|python3|)\\[0.5ex]
\textit{Example:} \inlcode|\usepackage[executable=/usr/local/bin/python3]{pyluatex}|
\end{itemize}
\subsection{Macros}
\begin{itemize}
\item \inlcode|\py{code}|\\[0.5ex]
Executes \inlcode|code| and writes the output to the document.\\[0.5ex]
\textit{Example:} \inlcode|\py{3 + 7}|
\item \inlcode|\pyc{code}|\\[0.5ex]
Executes \inlcode|code|\\[0.5ex]
\textit{Example:} \inlcode|\pyc{x = 5}|
\item \inlcode|\pyfile{path}|\\[0.5ex]
Executes the Python file specified by \inlcode|path|.\\[0.5ex]
\textit{Example:} \inlcode|\pyfile{main.py}|
\item \inlcode|\pysession{session}|\\[0.5ex]
Selects \inlcode|session| as Python session for subsequent Python code.\\[0.5ex]
The session that is active at the beginning is \inlcode|default|.\\[0.5ex]
\textit{Example:} \inlcode|\pysession{main}|
\end{itemize}
\subsection{Environments}
\begin{itemize}
\item \inlcode|python|\\[0.5ex]
Executes the provided block of Python code.\\[0.5ex]
The environment handles characters like \inlcode|_|, \inlcode|#|, \inlcode|%|, \inlcode|\|, etc.\\[0.5ex]
Code on the same line as \inlcode|\begin{python}| is ignored, i.e., code must start on the next line.\\[0.5ex]
If leading spaces are present they are gobbled automatically up to the first level of indentation.\\[0.5ex]
\textit{Example:}
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
\begin{python}
x = 'Hello PyLuaTeX'
print(x)
\end{python}
\end{tcblisting}
\end{itemize}
\section{Requirements}
\begin{itemize}
\item Lua\LaTeX{}
\item Python 3
\item Linux, macOS or Windows
\end{itemize}
Our automated tests currently use TeX Live 2021 and Python 3.7+ on
Ubuntu 20.04, macOS Catalina 10.15 and Windows Server 2019.
\section{How It Works}
PyLuaTeX runs a Python \inlcode|InteractiveInterpreter|\footnote{\url{https://docs.python.org/3/library/code.html#code.InteractiveInterpreter}} (actually several if you use different sessions) in the background for on the fly code execution.
Python code from your \LaTeX{} file is sent to the background interpreter through a TCP socket.
This approach allows your Python code to be executed and the output to be integrated in your \LaTeX{} file in a single compilation run.
No additional processing steps are needed.
No intermediate files have to be written.
No placeholders have to be inserted.
\section{License}
LPPL 1.3c\footnote{\url{http://www.latex-project.org/lppl.txt}} for \LaTeX{} code and
MIT license\footnote{\url{https://opensource.org/licenses/MIT}} for Python and Lua code.
We use the great json.lua\footnote{\url{https://github.com/rxi/json.lua}} library under the terms
of the MIT license\footnote{\url{https://opensource.org/licenses/MIT}}.
\end{document}
|
