diff options
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex')
-rw-r--r-- | Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex new file mode 100644 index 00000000000..a6a66fbde27 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/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.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} |