\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\<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}
