summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/pyluatex/pyluatex.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/latex/pyluatex/pyluatex.tex')
-rw-r--r--macros/luatex/latex/pyluatex/pyluatex.tex168
1 files changed, 168 insertions, 0 deletions
diff --git a/macros/luatex/latex/pyluatex/pyluatex.tex b/macros/luatex/latex/pyluatex/pyluatex.tex
new file mode 100644
index 0000000000..4552698539
--- /dev/null
+++ b/macros/luatex/latex/pyluatex/pyluatex.tex
@@ -0,0 +1,168 @@
+\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.1 (2021/07/12)}
+\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/
+|-- interpreter.py
+|-- 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}