summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/lualatex/pyluatex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-11-06 20:40:00 +0000
committerKarl Berry <karl@freefriends.org>2021-11-06 20:40:00 +0000
commit5c835cb7fc402dcaf0f66aad522767cb5d078237 (patch)
tree3ddf594876f9fb802903d48191ffebcdc3d3171a /Master/texmf-dist/doc/lualatex/pyluatex
parent557478dc45d15c122ff22b79ec1e321c2062b909 (diff)
pyluatex (6nov21)
git-svn-id: svn://tug.org/texlive/trunk@60977 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/pyluatex')
-rw-r--r--Master/texmf-dist/doc/lualatex/pyluatex/README.md10
-rw-r--r--Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdfbin79524 -> 82190 bytes
-rw-r--r--Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex47
3 files changed, 39 insertions, 18 deletions
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/README.md b/Master/texmf-dist/doc/lualatex/pyluatex/README.md
index 3165301bd89..feb77a04bcf 100644
--- a/Master/texmf-dist/doc/lualatex/pyluatex/README.md
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/README.md
@@ -8,10 +8,6 @@ LaTeX documents must be compiled with LuaLaTeX for this to work.
## Example
1\. LaTeX document `example.tex`
-**Note:** PyLuaTeX starts Python 3 using the command `python3` by default.
-If `python3` does not start Python 3 on your system, find the correct command
-and replace `\usepackage{pyluatex}` with `\usepackage[executable={your python command}]{pyluatex}`.
-For example, `\usepackage[executable=python.exe]{pyluatex}`.
```latex
\documentclass{article}
@@ -36,11 +32,15 @@ $\sqrt{371} = \py{math.sqrt(371)}$
\randint{2}{5}
\end{document}
```
+**Note:** PyLuaTeX starts Python 3 using the command `python3` by default.
+If `python3` does not start Python 3 on your system, find the correct command
+and replace `\usepackage{pyluatex}` with `\usepackage[executable={your python command}]{pyluatex}`.
+For example, `\usepackage[executable=python.exe]{pyluatex}`.
+
2\. Compile using LuaLaTeX (shell escape is required)
```
lualatex -shell-escape example.tex
```
-
**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.
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
index 49fee5afac4..0318eda2cbd 100644
--- a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
index d6c03253508..86374249af9 100644
--- a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
+++ b/Master/texmf-dist/doc/lualatex/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.