\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.2 (2021/07/14)} \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} \end{itemize} For more intricate use cases have a look at our tests in the folder \inlcode|test|. \section{Installation} PyLuaTeX is not yet available through package managers or CTAN\footnote{\url{https://ctan.org}}. To install PyLuaTeX, 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\\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}