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.tex47
1 files changed, 34 insertions, 13 deletions
diff --git a/macros/luatex/latex/pyluatex/pyluatex.tex b/macros/luatex/latex/pyluatex/pyluatex.tex
index d6c0325350..86374249af 100644
--- a/macros/luatex/latex/pyluatex/pyluatex.tex
+++ b/macros/luatex/latex/pyluatex/pyluatex.tex
@@ -15,7 +15,7 @@
\usepackage{url}
\title{The \emph{pyluatex} package}
\author{Tobias Enderle\\\url{https://github.com/tndrle/PyLuaTeX}}
-\date{v0.3.0 (2021/08/07)}
+\date{v0.4.0 (2021/11/05)}
\begin{document}
\maketitle
\raggedright
@@ -29,10 +29,6 @@ PyLuaTeX allows you to execute Python code and to include the resulting output i
\section{Example}
\begin{enumerate}
\item \LaTeX{} document \inlcode|example.tex|\\[0.5ex]
-\textbf{Note:} PyLuaTeX starts Python 3 using the command \inlcode|python3| by default.
-If \inlcode|python3| does not start Python 3 on your system, find the correct command
-and replace \inlcode|\usepackage{pyluatex}| with \inlcode|\usepackage[executable={your python command}]{pyluatex}|.
-For example, \inlcode|\usepackage[executable=python.exe]{pyluatex}|.
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
\documentclass{article}
@@ -58,28 +54,35 @@ $\sqrt{371} = \py{math.sqrt(371)}$
\randint{2}{5}
\end{document}
\end{tcblisting}
+\textbf{Note:} PyLuaTeX starts Python 3 using the command \inlcode|python3| by default.
+If \inlcode|python3| does not start Python 3 on your system, find the correct command
+and replace \inlcode|\usepackage{pyluatex}| with \inlcode|\usepackage[executable={your python command}]{pyluatex}|.
+For example, \inlcode|\usepackage[executable=python.exe]{pyluatex}|.
\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.
-
+\end{enumerate}
\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|beamer.tex|\\[0.5ex]
+ Demonstrates the use of PyLuaTeX environments and typesetting in \textit{BEAMER} presentations. In particular, the \inlcode|fragile| option for frames is highlighted.
\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}
+\item \inlcode|readme-example.tex|\\[0.5ex]
+ The example above
+\item \inlcode|repl.tex|\\[0.5ex]
+ Demonstrates how a Python console/REPL can be run and typeset
+\item \inlcode|sessions.tex|\\[0.5ex]
+ Demonstrates the use of different Python sessions in a document
\item \inlcode|typesetting-example.tex|\\[0.5ex]
The code typesetting example below
\item \inlcode|typesetting-listings.tex|\\[0.5ex]
@@ -127,12 +130,19 @@ For an example, see the Typesetting Code section.
\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]
+ If this option is set, Python input and output is written to the \LaTeX{} 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}|
+\item \inlcode|ignoreerrors|\\[0.5ex]
+ By default, PyLuaTeX aborts the compilation process when Python reports an error.
+ If the \inlcode|ignoreerrors| option is set, the compilation process is not aborted.\\[0.5ex]
+ \textit{Example:} \inlcode|\usepackage[ignoreerrors]{pyluatex}|
\end{itemize}
+Package options (except for \inlcode|executable|) can be changed in the document with the
+\inlcode|\pyoption| command, e.g. \inlcode|\pyoption{verbose}{true}| or \inlcode|\pyoption{ignoreerrors}{false}|.
+
\subsection{Macros}
\begin{itemize}
\item \inlcode|\py{code}|\\[0.5ex]
@@ -157,6 +167,10 @@ For an example, see the Typesetting Code section.
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}|
+\item \inlcode|\pyoption{option}{value}|\\[0.5ex]
+ Assigns \inlcode|value| to the package option \inlcode|option| anywhere in the document. For more information consider
+ the Package Options section.\\[0.5ex]
+ \textit{Example:} \inlcode|\pyoption{verbose}{true}|
\end{itemize}
\subsection{Environments}
\begin{itemize}
@@ -175,8 +189,13 @@ For an example, see the Typesetting Code section.
\end{tcblisting}
\item \inlcode|pythonq|\\[0.5ex]
Same as the \inlcode|python| environment, but any output is suppressed.
+\item \inlcode|pythonrepl|\\[0.5ex]
+ Executes the provided block of Python code in an interactive console/REPL. Code and output are
+ stored together in the output buffer and can be typeset as explained in section
+ Typesetting Code or as shown in the example \inlcode|repl.tex| in the folder
+ \inlcode|example|.
\end{itemize}
-You can create your own environments based on the \inlcode|python| and \inlcode|pythonq| environments.
+You can create your own environments based on the \inlcode|python|, \inlcode|pythonq| and \inlcode|pythonrepl| environments.
However, since they are verbatim environments, you have to use the macro \inlcode|\PyLTVerbatimEnv|
in your environment definition, e.g.
\begin{tcblisting}{breakable,listing only,
@@ -249,6 +268,8 @@ Using a different code listings package like \textit{minted}, or typesetting inl
You can also define your own environments that combine Python code and typesetting.
See the \inlcode|typesetting-*.tex| examples in the \inlcode|example| folder.
+To emulate an interactive Python console/REPL, the \inlcode|pythonrepl| environment can be used.
+
\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.