summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pythonimmediate/pythonimmediate.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/pythonimmediate/pythonimmediate.tex')
-rw-r--r--macros/latex/contrib/pythonimmediate/pythonimmediate.tex92
1 files changed, 65 insertions, 27 deletions
diff --git a/macros/latex/contrib/pythonimmediate/pythonimmediate.tex b/macros/latex/contrib/pythonimmediate/pythonimmediate.tex
index 877bc3a05e..eacffa24f6 100644
--- a/macros/latex/contrib/pythonimmediate/pythonimmediate.tex
+++ b/macros/latex/contrib/pythonimmediate/pythonimmediate.tex
@@ -1,4 +1,4 @@
-\ProvidesFile{pythonimmediate.tex}[2022/12/23 0.0.0 Library to run Python code]
+\ProvidesFile{pythonimmediate.tex}[2023/01/09 0.1.0 Library to run Python code]
\RequirePackage{fvextra}
\documentclass{l3doc}
\usepackage{tikz}
@@ -53,12 +53,25 @@ so you don't need to write a single line of \TeX\ code.
%You need to install Python \pkg{daemoniker} and \pkg{psutil} package.
-The package should work out of the box with no additional Python package needed.
+In addition to the \LaTeX\ package, you need the Python \pkg{pythonimmediate-tex} package,
+installation instruction can be found at \url{https://pypi.org/project/pythonimmediate-tex/}.
-\subsection{Installation on Overleaf}
+Note that not all \TeX\ package versions are compatible with all Python package versions.
+This \TeX\ package is compatible with Python package version |0.1.2|.
+
+Remember to enable unrestricted\footnote{
+ There's little point in supporting restricted mode, since it's possible to execute arbitrary shell commands in Python anyway.
+ If it's needed to execute untrusted \TeX\ code, separate sandboxing should be used.
+} shell-escape. (there's a guide on \TeX.SE if necessary: \url{https://tex.stackexchange.com/q/598818/250119})
+
+\subsection{Installation on Overleaf}\label{installation-on-overleaf}
At the point of writing, this package can be used on Overleaf.
+Nevertheless, you cannot use |pip| to install Python packages on Overleaf directly, instead it's possible to
+download |.zip| file, include it in your Overleaf project, and specify where the package can be found to Python
+using |PYTHONPATH| environment variable.
+
Instruction:
\begin{itemize}
@@ -67,14 +80,27 @@ Instruction:
\item \file{saveenv.sty}
\item \file{precattl.sty}
\item \file{pythonimmediate.sty}
- \item \file{pythonimmediate_script_textopy.py}
- \item \file{pythonimmediate_script_pytotex.py}
+ \item \file{pythonimmediate-tex-0.1.2.zip}
\end{itemize}
+ The |0.1.2| part should be replaced with the desired version
+ of the Python package.
+
+ The |.sty| files can be downloaded from CTAN at
+ \url{https://ctan.org/pkg/saveenv},
+ \url{https://ctan.org/pkg/precattl},
+ \url{https://ctan.org/pkg/pythonimmediate}
+ respectively.
+
+ The |.zip| file containing Python source code
+ can be downloaded from PyPI: \url{https://pypi.org/project/pythonimmediate-tex/\#files}.
+
\item Write the following in the preamble:
\begin{verbatim}
\usepackage[abspath]{currfile}
-\usepackage[mode=unnamed-pipe]{pythonimmediate}
+\usepackage[python-executable={PYTHONPATH=pythonimmediate-tex-0.1.2.zip/pythonimmediate-tex-0.1.2/ python3},args={--mode=unnamed-pipe}]{pythonimmediate}
\end{verbatim}
+As above, replace both occurrences of |0.1.2| with the downloaded version specified in the zip file above.
+
Refer to \ref{troubleshoot-source-file-not-found} for explanation of the |abspath| option.
\end{itemize}
@@ -84,32 +110,37 @@ so in that case consider writing |\errorstopmode|.
Refer to \ref{troubleshoot-Python-error} to read the error traceback in case of Python error.
+Some construct inside the |pycode| block might make the code editor on Overleaf report an error,
+even though the code is valid. Refer to \url{https://www.overleaf.com/learn/how-to/Code_Check#Code_Check_Limitations}.
+
\section{Usage}
\subsection{Package options}
-\DescribeOption{outputdir=}
-Specify the output directory if it's not the default value.
+Normally no options are required.
+If you're not sure what they do, just use the default options.
-\begin{texnote}
- The value will be |x|-expanded.
-\end{texnote}
-
-Using the \pkg{outputdir} package, it's possible to determine the output directory automatically, subject to restrictions.
-
-An usage example, if you invoked |pdflatex| with the command
+\DescribeOption{args=}
+Arguments to be passed to the Python component of the program. Run
\begin{verbatim}
-pdflatex --output-directory=/tmp/ a.tex
-\end{verbatim}
-then in the file \file{a.tex} you should have
-\begin{verbatim}
-\usepackage[outputdir=/tmp/]{pythonimmediate}
+python -m pythonimmediate.pytotex --help
\end{verbatim}
+on the command-line to view the available options.
+
+The documentation is also available at
+\url{https://pythonimmediate.readthedocs.io/en/latest/pythonimmediate.html#module-pythonimmediate.pytotex}.
-\DescribeOption{mode=}
-Method to communicate between \TeX\ and Python. Usually the method will be automatically detected.
+\DescribeOption{python-executable=}
+The name/path to the Python executable. Default to |python3|.
-Possible values include |multiprocessing-network| and |unnamed-pipe|.
+Can also be used to provide environment variables to the Python process.
+An example how to do that is explained in \ref{installation-on-overleaf}.
+
+\DescribeOption{python-flags=}
+Flags to be passed to the Python interpreter. For example pass |-O| to disable assertions.
+
+The documentations can be found by running |python --help| on the command-line,
+or visit \url{https://docs.python.org/3/using/cmdline.html}.
\subsection{\TeX\ interface}
@@ -226,16 +257,22 @@ The \TeX\ interface is only used to call Python. Apart from that, all the work c
All functions in this section should be imported from |pythonimmediate| package, unless specified otherwise.
+Currently, all the documentations are moved to the Python package documentation,
+see \url{https://pythonimmediate.readthedocs.io/}.
+
+Documentation of a few functions are still kept here for convenience, but \textbf{they might be outdated}.
+Always refer to the online documentation.
+
\subsubsection{Print to \TeX}\label{print-to-TeX}
-\DescribePython{.print()}
+\DescribePython{.print_TeX()}
\DescribePython{.file}
These functions are used in |\pyc| command or |pycode| environment.
Unlike most other packages, using |print()| function in Python will print to the console (\TeX\ standard output).
In order to print \TeX\ code to be executed, you can do one of
\begin{verbatim}
-pythonimmediate.print(...)
+pythonimmediate.print_TeX(...)
print(..., file=pythonimmediate.file)
with contextlib.redirect_stdout(pythonimmediate.file):
print(...)
@@ -286,7 +323,8 @@ This is an example of how the functions could be used. The name should be mostly
\usepackage{pythonimmediate}
\begin{document}
\begin{pycode}
-from pythonimmediate import newcommand, peek_next_char, get_next_char, get_arg_str, print
+from pythonimmediate import newcommand, peek_next_char, get_next_char, get_arg_str
+from pythonimmediate import print_TeX as print
@newcommand
def innerproduct():
s = get_arg_str() # in the example below this will have the value '\mathbf{a},\mathbf{b}'
@@ -334,7 +372,7 @@ Similar to some functions above, except that the argument is fully expanded and
similar to how |\py| command (\ref{py-command}) reads its arguments.
\DescribePython{.execute()}
-Takes a string and execute it immediately. (so that any |.execute()| will be executed before any |.print()|)
+Takes a string and execute it immediately. (so that any |.execute()| will be executed before any |.print_TeX()|)
Assuming \TeX\ is in errorstopmode (i.e. errors halt \TeX\ execution),
any error in \TeX\ will create an error in Python and the traceback should point to the correct line of code.