% \iffalse meta-comment

%

% Copyright (C) 2012-2018 by Geoffrey M. Poore <[email protected]>

% ---------------------------------------------------------------------------

% This work may be distributed and/or modified under the

% conditions of the LaTeX Project Public License, either version 1.3

% of this license or (at your option) any later version.

% The latest version of this license is in

% http://www.latex-project.org/lppl.txt

% and version 1.3 or later is part of all distributions of LaTeX

% version 2005/12/01 or later.

%

% This work has the LPPL maintenance status `maintained'.

%

% The Current Maintainer of this work is Geoffrey M. Poore.

%

% This work consists of the files pythontex.dtx and pythontex.ins

% and the derived filebase pythontex.sty.

%

% \fi

%

% \iffalse

%<*driver>

\ProvidesFile{pythontex.dtx}

%</driver>

%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]

%<package>\ProvidesPackage{pythontex}

%<*package>

[2018/11/10 v0.17dev execute and typeset Python code and other languages]

%</package>

%

%<*driver>

\documentclass{ltxdoc}

\makeatletter

\usepackage[T1]{fontenc}

\usepackage[utf8]{inputenc}

\usepackage{lmodern}

\usepackage{textcomp}

\usepackage[svgnames]{xcolor}

\usepackage{environ}

\usepackage{enumitem}

\usepackage{fvextra}

\usepackage{pythontex}

\usepackage{hyperref}

\hypersetup{

pdftitle=The PythonTeX package,

pdfauthor=Geoffrey M. Poore,

pdfsubject={PythonTeX LaTeX package manual},

colorlinks=true,

allcolors=ForestGreen,

}

\usepackage{cleveref}

\newcommand{\pytxtodo}[1]{}

%\newcommand{\pytxtodo}[1]{\textcolor{red}{TO~DO: \scantokens{#1}}}

\newcommand{\changestext}{}

\NewEnviron{changelog}[2]{%

\g@addto@macro\changestext{\subsection*{\textbf{#1} (#2)}}%

\expandafter\g@addto@macro\expandafter\changestext\expandafter{\BODY}%

\g@addto@macro\changestext{}%

}

\newcommand{\PrintChangelog}{%

\addcontentsline{toc}{section}{Version History}

\section*{Version History}%

\changestext

}

% Create a short verbatim pipe that handles quotation marks properly

\begingroup

\catcode`\|=\active

\gdef\pipe@active@verbatim{%

\begingroup

\let\do\@makeother\dospecials

\catcode`\|=\active

\catcode`\`=\active

\catcode`\'=\active

\catcode`\<=\active

\catcode`\>=\active

\catcode`\-=\active

\catcode`\,=\active

\catcode`\ =\active

\pipe@active@verbatim@i}

\gdef\pipe@active@verbatim@i#1|{%

\endgroup

\begingroup

\def\FV@SV@pipe@active@verbatim{%

\FV@Gobble

\expandafter\FV@ProcessLine\expandafter{#1}}%

%\let\FV@BeginVBox\relax

%\let\FV@EndVBox\relax

%\def\FV@BProcessLine##1{\FancyVerbFormatLine{##1}}%

\BUseVerbatim{pipe@active@verbatim}%

\endgroup}

\AtBeginDocument{\let|\pipe@active@verbatim}

\endgroup

\def\MacroFont{%

\fontencoding\encodingdefault%

\fontfamily\ttdefault%

\fontseries\mddefault%

\fontshape\updefault%

\small}

\def\PrintMacroName#1{{\strut\MacroFont\color{DarkGreen}\footnotesize\string #1\ }}

\def\PrintDescribeMacro#1{\strut\MacroFont\textcolor{DarkGreen}{\string #1\ }}

\let\PrintDescribeEnv\PrintDescribeMacro

%\let\PrintMacroName\PrintDescribeMacro

\let\PrintEnvName\PrintDescribeEnv

\def\theCodelineNo{\textcolor{DarkGreen}{\sffamily\scriptsize{\arabic{CodelineNo}}}}

\let\orig@footnote\footnote

\renewcommand{\footnote}{%

\begingroup

\let\do\@makeother

\dospecials

\catcode`\{=1

\catcode`\}=2

\new@footnote}

\newcommand{\new@footnote}[1]{%

\endgroup

\orig@footnote{\scantokens{#1}}}

%\EnableCrossrefs

%\CodelineIndex

%\RecordChanges

\makeatother

\begin{document}

\DocInput{pythontex.dtx}

%\PrintChanges

%\PrintIndex

\end{document}

%</driver>

% \fi

%

% \CheckSum{3285}

%

% \CharacterTable

% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z

% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z

% Digits \0\1\2\3\4\5\6\7\8\9

% Exclamation \! Double quote \" Hash (number) \#

% Dollar \$ Percent \% Ampersand \&

% Acute accent \' Left paren \( Right paren \)

% Asterisk \* Plus \+ Comma \,

% Minus \- Point \. Solidus \/

% Colon \: Semicolon \; Less than \<

% Equals \= Greater than \> Question mark \?

% Commercial at \@ Left bracket \[ Backslash \\

% Right bracket \] Circumflex \^ Underscore \_

% Grave accent \` Left brace \{ Vertical bar \|

% Right brace \} Tilde \~}

%

%

%

% \begin{changelog}{v0.17}{2018/11/??}

% \begin{itemize}

% \item Updated Julia support for Julia versions 0.6 (\#107), and 0.7 and 1.0 (\#126, \#130).

% \item There are now meaningful error messages for Julia console when Weave.jl is not installed or raises errors (\#131).

% \item \texttt{pythontexcustomcode} and \texttt{\string\pythontexcustomc} now set \texttt{pytex.context} (\#65).

% \item Added support for R. The \texttt{R} family of commands and environments (\texttt{\string\R}, \texttt{\string\Rc}, \texttt{Rcode}, ...) executes code as a script. There is currently no utilities class or equivalent. The \texttt{Rcon} family (\texttt{Rconsole}) executes code to emulate an interactive R session (\#121).

% \item \texttt{fancyvrb} settings from \texttt{\string\setpythontexfv} and console environments now work with Julia and R consoles.

% \item \texttt{pythontexcustomcode} now works with |juliacon|. There are now proper \texttt{juliaconcode} and \texttt{Rconcode} environments that execute code but typeset nothing, to parallel \texttt{pyconcode} (\#134).

% \item Added support for Perl with the \texttt{perl} and \texttt{pl} families of commands and environments. There is currently no utilities class or equivalent.

% \item Added support for Perl 6 with the \texttt{perlsix} and \texttt{psix} families of commands and environments (\#104). There is currently no utilities class or equivalent.

% \item Under Windows, capitalization of script paths in \texttt{stderr} is now preserved.

% \end{itemize}

% \end{changelog}

%

%

% \begin{changelog}{v0.16}{2017/07/20}

% \begin{itemize}

% \item Added preliminary console support for Julia (\#98).

% \item Fixed Python console compatibility with Python 3.6 by setting the \texttt{code} module's new \texttt{exitmsg} argument to suppress the exit message (\#100).

% \item Improved Rust support, including tracking of created files and dependencies (\#91).

% \end{itemize}

% \end{changelog}

%

%

% \begin{changelog}{v0.15}{2016/07/21}

% \textbf{New features}

% \begin{itemize}

% \item The \texttt{fvextra} package is now required. This provides line breaking with fine-grained control over break locations, the ability to highlight specific lines or ranges of lines, improved handling of tabs, and several additional features.

% \item Added \texttt{sub} commands and environments (\texttt{\string\pys}, \texttt{pysub}, ...). These commands and environments perform string interpolation on text. Fields delimited by \texttt{!\{...\}} are replaced by the result of evaluating and then printing their content. This works for all families of commands and environments, not just Python. See the documentation for details about field delimiters and escaping.

% \item Added \texttt{rust} and \texttt{rs} families of commands and environments. These provide essentially complete support for Rust, except that \texttt{rstex.formatter()}, \texttt{rstex.before()}, and \texttt{rstex.after()} will likely need additional refinement (\#90).

% \item Added the \texttt{sage} family of commands and environments, which provide support for Sage (\#63).

% \item Added \texttt{bash} family of commands and environments. This provides basic support for bash (no utilities class or equivalent). Bash works with Windows if it is installed.

% \item Improved \texttt{console} compatibility under Linux with Python 3 (\#70).

% \item Counters for default sessions are now created automatically. This prevents counter errors under some circumstances when working with \texttt{\string\includeonly}.

% \item Commands like \texttt{\string\py} can now output verbatim content under LuaTeX.

% \end{itemize}

% \textbf{Bugfixes}

% \begin{itemize}

% \item Fixed a bug that could cause an endless loop when a \texttt{code} command or environment printed a \texttt{code} command or environment of the same family with \texttt{autoprint=true}.

% \end{itemize}

% \end{changelog}

%

%

% \begin{changelog}{v0.14}{2014/07/17}

% \textbf{New features}

% \begin{itemize}

% \item All commands for working with code inline are now robust, via \texttt{etoolbox}'s \texttt{\string\newrobustcmd}. Among other things, this allows commands like \texttt{\string\py} to work in standard captions that have not been redefined to avoid protection issues.

% \item Upgraded \texttt{syncpdb} to v0.2, which provides better list formatting.

% \end{itemize}

% \textbf{Backward-incompatible changes}

% \begin{itemize}

% \item The default working directory is now the main document directory instead of the output directory. Using the output directory was a common source of confusion for new users and was incompatible with plans for future development. Old documents in which the working directory was not specified will continue to use the output directory, but PythonTeX will print an upgrade message; new documents will use the new setting. The output directory may be selected as the working directory manually, or with the shorthand ``\texttt{\string\setpythontexworkingdir\{<outputdir>\}}''.

% \item Standardized version numbering by removing the ``v'' prefix from the stored version numbers in Python variables and LaTeX macros. Standardized the PythonTeX scripts by renaming \texttt{version} to \texttt{\_\_version\_\_}.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.13}{2014/07/14}

% \textbf{New features}

% \begin{itemize}

% \item Added \texttt{-{}-interactive} command-line option. This runs a single session in interactive mode, allowing user input. Among other things, this is useful when working with debuggers.

% \item Added \texttt{-{}-debug} command-line option. This runs a single session with the default debugger in interactive mode. Currently, only standard (non-console) Python sessions are supported. The default Python debugger is the new \texttt{syncpdb}, which wraps \texttt{pdb} and synchronizes code line numbers with document line numbers. All \texttt{pdb} commands that take a line number or filename:lineno as an argument will refer to document files and line numbers when the argument has a percent symbol (\texttt{\%}) as a prefix. For example, \texttt{list \%50} lists code that came from around line 50 in the document. The \texttt{-{}-debug} option will support other languages and provide for customization in the future.

% \item Added command-line option \texttt{-{}-jobs}, which allows the maximum number of concurrent processes to be specified (\#35).

% \item Added support for GNU Octave, via the \texttt{octave} family of commands and environments (\#36). Parsing of Octave stderr is not ideal, though synchronization works in most cases; this will be addressed by a future rewrite of the stderr parser.

% \item Installer now automatically works with MiKTeX, not just TeX Live.

% \item The PythonTeX utilities class has a new \texttt{open()} method that opens files and automatically tracks dependencies/created files.

% \item When \texttt{pythontex2.py} and \texttt{pythontex3.py} are run directly, the Python interpreter is automatically set to a reasonable default (\texttt{py -2} or \texttt{py -3} under Windows, using the Python 3.3+ wrapper; \texttt{python2} or \texttt{python3} under other systems).

% \item The installer now creates symlinks for the numbered scripts \texttt{pythontex*.py} and \texttt{depythontex*.py}.

% \item Added Python version checking to all numbered scripts.

% \item Under Python, the type of data passed via \texttt{\string\setpythontexcontext} may now be set using YAML-style tags (\texttt{!!str}, \texttt{!!int}, \texttt{!!float}). For example, \texttt{\string\setpythontexcontext\{myint=!!int 123\}}.

% \item The \texttt{fancyvrb} options \texttt{firstline} and \texttt{lastline} now work with the \texttt{pygments} environment and \texttt{\string\inputpygments} command. This required some additional patching of \texttt{fancyvrb}.

% \item The \texttt{pytx@Verbatim} and \texttt{pytx@SaveVerbatim} environments are now used for typesetting verbatim code. These are copies of the \texttt{fancyvrb} environments. This prevents conflicts when literal \texttt{Verbatim} and \texttt{SaveVerbatim} environments need to be typeset.

% \item Improved \texttt{latexmk} compatibility (\#40). Added discussion of \texttt{latexmk} usage to documentation.

% \item Tildes \texttt{\string~} may now be used in \texttt{outputdir} and \texttt{workingdir} to refer to the user's home directory, even under Windows.

% \end{itemize}

% \textbf{Bugfixes}

% \begin{itemize}

% \item Fixed a bug that prevented created files from being cleaned up when the working directory was not the document root directory and the full path to the files was not provided.

% \item Fixed a bug that prevented the \texttt{fvextfile} option from working when external files were highlighted.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.13-beta}{2014/02/06}

% \textbf{New features}

% \begin{itemize}

% \item Switching to GitHub's Releases for downloads.

% \item TeX information such as page dimensions may now be easily passed to the programming-language side, using the new \texttt{\string\setpythontexcontext} command. Contextual information is stored in the \texttt{context} attribute of the utilities class, which is a dictionary (and also has attributes in Python).

% \item The utilities class now has \texttt{pt\_to\_in()}, \texttt{pt\_to\_cm()}, and \texttt{pt\_to\_mm()} methods for converting units of TeX points into inches, centimeters, and millimeters. These work with integers and floats, as well as strings that consist of numbers and optionally end in ``pt''. There is also a \texttt{pt\_to\_bp()} for converting TeX points (1/72.27 inch) into big (DTP or PostScript) points (1/72 inch).

% \item Expanded Quickstart. Quickstart is now compatible with all LaTeX engines. Quickstart now avoids \texttt{microtype} issues on some systems (\#32).

% \item Added information on citing PythonTeX (\#28).

% \item Utilities class has a new attribute \texttt{id}, which is a string that joins the command family name, session name, and session restart parameters with underscores. This may be used in creating files that need a name that contains a unique, session-based identifier (for example, names for figures that are saved automatically).

% \end{itemize}

% \textbf{Backward-incompatible changes}

% \begin{itemize}

% \item All utilities-class attributes with names of the form \texttt{input\_*} have been renamed with the ``\texttt{input\_}'' removed. Among other things, this makes it easier to access the \texttt{context} attribute (\texttt{pytex.context} vs.\ \texttt{pytex.input\_context}).

% \item \texttt{depythontex} now has \texttt{-o} and \texttt{-{}-output} command-line options for specifying the name of the output file. If an output file is not specified, then output is written to \texttt{stdout}. This allows \texttt{depythontex} output to be piped to another program.

% \item All scripts \texttt{*2.py} now have shebangs with \texttt{env python2}, and all scripts \texttt{*3.py} now have shebangs with \texttt{env python3}. This allows the wrapper scripts (\texttt{env python} shebang) to be used with the default Python installation, and the numbered scripts to be used with specific versions. Remember that except for console content, the \texttt{-{}-interpreter} option is what determines the Python version that actually executes code. The version of Python used to launch \texttt{pythontex.py} merely determines the version that manages code execution. (\texttt{-{}-interpreter} support for console content is coming.)

% \item Changed the template style used in the \texttt{CodeEngine} class. Replacement fields are now surrounded by single curly braces (as in Python's format string syntax), rather than double curly braces. Literal curly braces are obtained by doubling braces. This allows the use of literal adjacent double braces in templates, which was not possible previously.

% \item The Julia template now uses the new \texttt{in()} function, replacing \texttt{contains()}. This requires Julia v0.2.0+.

% \end{itemize}

% \textbf{Bugfixes}

% \begin{itemize}

% \item Modified test for LuaTeX, so that \texttt{\string\directlua} is not \texttt{\string\let} to \texttt{\string\relax} if it does not exist. This was causing incompatibility with \texttt{babel} under pdfTeX and XeTeX (\#33).

% \item Added missing shebangs to \texttt{depythontex*.py}. Handling of \texttt{utilspath} is now more forgiving, so that \texttt{pythontex\_utils.py} can be installed in alternate locations (\#23).

% \item \texttt{depythontex} no longer leaves a blank line where \texttt{\string\usepackage\{pythontex\}} was removed.

% \item Console environments typeset with \texttt{fancyvrb} no longer end with an unnecessary empty line.

% \item Fixed bug in installer when \texttt{kpsewhich} was not found (\#21).

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.12}{2013/08/26}

% \begin{itemize}

% \item Added support for the Julia language, with the \texttt{julia} and \texttt{jl} families of commands and environments. (Note that Pygments only added Julia support in version 1.6.)

% \item Warnings and errors are now synchronized with the line numbers of files brought in via \texttt{\string\input}, \texttt{\string\include}, etc. This is accomplished using the \texttt{currfile} package.

% \item Added package option \texttt{gobble}. When \texttt{gobble=auto}, all code is dedented before being executed and/or typeset. The current implementation is functional but basic; it will be improved and extended in the future.

% \item The document root directory is now always added to \texttt{sys.path} (or its equivalent), even when it is not the working directory. (The working directory has been added to \texttt{sys.path} since v0.12beta.) The document directory is added after the working directory, so that the working directory has precedence.

% \item Fixed a bug in \texttt{console} commands and environments; \texttt{sys.path} now contains the working and document directories, and the working directory is now the output directory by default. This parallels the behavior of non-\texttt{console} commands and environments.

% \item Added command-line option \texttt{-{}-interpreter} that allows an interpreter to be invoked via a specific command. This allows, for example, a specific version of Python to be invoked.

% \item Improved synchronization of stderr in cases when an error is triggered far after its origin (for example, an error caused by a multiline string that is lacking a closing quote/delimiter, and thus may span several chunks of user code).

% \item Modified usage of the \texttt{shlex} module to work around its lack of Unicode support in Python versions prior to 2.7.3.

% \item Fixed a bug from v0.12beta that prevented \texttt{\string\inputpygments} from working when \texttt{pygments=true}.

% \item Fixed a bug with counters that caused errors when content spanning multiple columns was created within a \texttt{tabular} environment.

% \item Added checking for compatible Python versions in \texttt{pythontex.py}.

% \item Improved execution of \texttt{*.bat} and \texttt{*.cmd} files under Windows. The solution from v0.12beta allowed \texttt{*.bat} and \texttt{*.cmd} to be found and executed when the extension was not given, but did not give correct return codes.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.12beta}{2013/06/24}

% \begin{itemize}

% \item Merged \texttt{pythontex\_types*.py} into a single replacement \texttt{pythontex\_engines.py} compatible with both Python 2 and 3. It is now much simpler to add support for additional languages.

% \item Added support for the Ruby language as a demonstration of new capabilities. The \texttt{ruby} and \texttt{rb} families of commands and environments may be enabled via the new \texttt{usefamily} package option. Support for additional languages is coming soon. See the new section in the documentation on support for other languages for more information.

% \item Reimplemented treatment of Pygments content for better efficiency. Now a Pygments process only runs if there is content to highlight. Eliminated redundant highlighting of unmodified code.

% \item Improved treatment of dependencies. If a dependency is modified (\texttt{os.path.getmtime()}) after the current PythonTeX run starts, then code that depends on it will be re-executed the next time PythonTeX runs. A message is also issued to indicate that this is the case.

% \item The utilities class now has \texttt{before()} and \texttt{after()} methods that are called immediately before and after user code. These may be redefined to customize output. For example, LaTeX commands could be printed before and after user code; stdout could be redirected to \texttt{StringIO} for further processing; or matplotlib figures could be automatically detected, saved, and included in the document.

% \item Added explanation of how to track dependencies and created files automatically, and how to include matplotlib figures automatically, to the documentation for the PythonTeX utilities class.

% \item Created a new system for parsing and synchronizing stderr.

% \begin{itemize}

% \item Exceptions that do not reference a line number in user code (such as those from \texttt{warnings.warn()} in a module) are now traced back to a single command or environment. Previously no synchronization was attempted. This is accomplished by writing delimiters to stderr before executing the code from each command/environment.

% \item Exceptions that do reference a line in user code are more efficiently synchronized with a document line number. This is accomplished by careful record keeping as each script is assembled. Line number synchronization no longer involves parsing the script that was executed.

% \item Improved and generalized parsing of stderr, in preparation for supporting additional languages. Exceptions that cannot be identified as errors or warnings are treated based on \texttt{Popen.returncode}.

% \end{itemize}

% \item Created a new system for \texttt{console} content.

% \begin{itemize}

% \item There are now separate families of \texttt{console} commands and environments. No Pygments or \texttt{fancyvrb} settings are shared with the non-\texttt{console} families, as was previously the case. There is a new family of commands and environments based on \texttt{pycon}, including the \texttt{\string\pycon} command (inline reference to console variable), \texttt{pyconsole} environment (same as the old one), \texttt{\string\pyconc} and \texttt{pyconcode} (execute only), and \texttt{\string\pyconv} and \texttt{pyconverbatim} (typeset only). There are equivalent families based on \texttt{pylabcon} and \texttt{sympycon}.

% \item Each console session now runs in its own process and is cached individually. Console output is now cached so that changing Pygments settings no longer requires re-execution.

% \item Unicode is now supported under Python 2.

% \item The new package option \texttt{pyconfuture} allows automatic imports from \texttt{\_\_future\_\_} for \texttt{console} families under Python 2, paralleling the \texttt{pyfuture} option.

% \item Any errors or warnings caused by code that is not typeset (\texttt{code} command and environment, startup code) are reported in the run summary. This ensures that such code does not create mischief.

% \item \texttt{customcode} is now supported for \texttt{console} content.

% \end{itemize}

% \item Better support for \texttt{latexmk} and similar build tools. PythonTeX creates a file of macros (\texttt{*.pytxmcr}) that is always included in a document, and thus can be automatically detected and tracked by \texttt{latexmk}. This file now contains the time at which PythonTeX last created files. When new files are created, the macro file will have a new hash, triggering another document compile.

% \item Improved the way in which the PythonTeX \texttt{outputdir} is added to the graphics path. This had been done with \texttt{\string\graphicspath}, but that overwrites any graphics path previously specified by the user. Now the \texttt{outputdir} is appended to any pre-existing path.

% \item Added the \texttt{depythontex} option \texttt{-{}-graphicspath}. This adds the \texttt{outputdir} to the graphics path of the \texttt{depythontex} document.

% \item The installer now provides more options for installation locations. It will now create missing directories if desired.

% \item The working directory (\texttt{workingdir}) is now appended to \texttt{sys.path}, so that code there may be imported.

% \item Under Windows, \texttt{subprocess.Popen()} is now invoked with \texttt{shell=True} if \texttt{shell=False} results in a WindowsError. This allows commands involving \texttt{*.bat} and \texttt{*.cmd} files to be executed when the extension is not specified; otherwise, only \texttt{*.exe} can be found and run.

% \item The path to utils is now found in \texttt{pythontex.py} via \texttt{sys.path[0]} rather than \texttt{kpsewhich}. This allows the PythonTeX scripts to be executed in an arbitrary location; they no longer must be installed in a texmf tree where \texttt{kpsewhich} can find them.

% \item Added \texttt{rerun} value \texttt{never}.

% \item At the end of each run, data and macros are only saved if modified, improving efficiency.

% \item The number of temporary files required by each process was reduced by one. All macros for commands like \texttt{\string\py} are now returned within stdout, rather than in their own file.

% \item Fixed a bug with \texttt{\string\stderrpythontex}; it was defaulting to \texttt{verb} rather than \texttt{verbatim} mode.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.11}{2013/04/21}

% \begin{itemize}

% \item As the first non-beta release, this version adds several features and introduces several changes. You should read these release notes carefully, since some changes are not backwards-compatible. Changes are based on a thorough review of all current and planned features. PythonTeX's capabilities have already grown beyond what was originally intended, and a long list of features still remains to be implemented. As a result, some changes are needed to ensure consistent syntax and naming in the future. Insofar as possible, all command names and syntax will be frozen after this release.

% \item Added the \texttt{pythontex.py} and \texttt{depythontex.py} wrapper scripts. When run, these detect the current version of Python and import the correct PythonTeX code. It is still possible to run \texttt{pythontex*.py} and \texttt{depythontex*.py} directly, but the new wrapper scripts should be used instead for simplicity. There is now only a single \texttt{pythontex\_utils.py}, which works with both Python 2 and Python 3.

% \item Added the \texttt{beta} package option. This makes the current version behave like v0.11beta, for compatibility. This option is temporary and will probably only be retained for a few releases.

% \item Backward-incompatible changes (require the \texttt{beta} option to restore old behavior)

% \begin{itemize}

% \item The \texttt{pyverb} environment has been renamed \texttt{pyverbatim}. The old name was intended to be concise, but promoted confusion with LaTeX's \texttt{\string\verb} macro.

% \item For \texttt{\string\printpythontex}, \texttt{\string\stdoutpythontex}, and \texttt{\string\stderrpythontex}, the modes \texttt{inlineverb} and \texttt{v} have been replaced by \texttt{verb}, and the old mode \texttt{verb} has been replaced by \texttt{verbatim}. This brings naming conventions in line with standard LaTeX \texttt{\string\verb} and \texttt{verbatim}, avoiding a source of potential confusion.

% \item The \texttt{\string\setpythontexpyglexer}, \texttt{\string\setpythontexpygopt}, and \texttt{\string\setpygmentspygopt} commands now take an optional argument and a mandatory argument, rather than two mandatory arguments. This creates better uniformity among current and planned settings macros.

% \item The \texttt{\string\setpythontexformatter} and \texttt{\string\setpygmentsformatter} commands have been replaced by the \texttt{\string\setpythontexprettyprinter} and \texttt{\string\setpygmentsprettyprinter} commands. This anticipates possible upcoming features. It also avoids potential confusion with Pygments's formatters and the utilities class's \texttt{formatter()} method.

% \end{itemize}

% \item Deprecated (still work, but raise warnings; after a few releases, they will raise errors instead, and after that eventually be removed)

% \begin{itemize}

% \item The \texttt{rerun} setting \texttt{all} was renamed \texttt{always}, in preparation for upcoming features.

% \item The \texttt{stderr} option is replaced by \texttt{makestderr}. The \texttt{print}/\texttt{stdout} option is replaced by \texttt{debug}. These are intended to prevent confusion with future features.

% \item The \texttt{fixlr} option is deprecated. It was originally introduced to deal with some of SymPy's LaTeX formatting, which has since changed.

% \item The utilities class method \texttt{init\_sympy\_latex()} is deprecated. The \texttt{sympy\_latex()} and \texttt{set\_sympy\_latex()} methods now automatically initialize themselves on first use.

% \end{itemize}

% \item Added \texttt{autostdout} package option and \texttt{\string\setpythontexautostdout}, to complement \texttt{autoprint}. Added |prettyprinter| and |prettyprintinline| package options to complement new settings commands.

% \item Added quickstart guide.

% \item Installer now installs gallery and quickstart files, if present.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.11beta}{2013/02/17}

% \begin{itemize}

% \item Commands like \texttt{\string\py} can now bring in any valid LaTeX code, including verbatim content, under the pdfTeX and XeTeX engines. Verbatim content was not allowed previously. LuaTeX cannot bring in verbatim, due to a known bug.

% \item Added package option \texttt{depythontex} and scripts \texttt{depythontex*.py}. These allow a PythonTeX document to be converted into a pure LaTeX document, with no Python dependency. The package option creates an auxiliary file with extension \texttt{.depytx}. The \texttt{depythontex*.py} scripts take this auxiliary file and the original LaTeX document, and combine the two to produce a new document that does not rely on the PythonTeX package. All PythonTeX commands and environments are replaced by their output. All Python-generated content is substituted directly into the document. By default, all typeset code is wrapped in \texttt{\string\verb} and \texttt{verbatim}, but \texttt{depythontex*.py} has a \texttt{-{}-listing} option that allows \texttt{fancyvrb}, \texttt{listings}, \texttt{minted}, or \texttt{pythontex} to be used instead.

% \item The current PythonTeX version is now saved in the \texttt{.pytxcode}. If this does not match the version of the PythonTeX scripts, a warning is issued. This makes it easier to determine errors due to version mismatches.

% \item Fixed an incompatibility with the latest release of \texttt{xstring} (version 1.7, 2013/01/13).

% \item Fixed a bug in the \texttt{console} environment that could cause problems when switching from Pygments highlighting to \texttt{fancyvrb} when using the \texttt{fvextfile} option. Fixed a bug introduced in the v0.10beta series that prevented the \texttt{console} environment from working with \texttt{fancyvrb}.

% \item Fixed a bug with PythonTeX verbatim commands and environments that use Pygments. The verbatim commands and environments were incorrectly treated as if they had the attributes of executed code in the v0.10beta series.

% \item Fixed a bug from the v0.10beta series that sometimes prevented imports from \texttt{\_\_future\_\_} from working when there were multiple sessions.

% \item Fixed a bug related to hashing dependencies' mtime under Python 3.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.10beta2}{2013/01/23}

% \begin{itemize}

% \item Improved \texttt{pythontex*.py}'s handling of the name of the file being processed. A warning is no longer raised if the name is given with an extension; extensions are now processed (stripped) automatically. The filename may now contain a path to the file, so you need not run \texttt{pythontex*.py} from within the document's directory.

% \item Added command-line option \texttt{-{}-verbose} for more verbose output. Currently, this prints a list of all processes that are launched.

% \item Fixed a bug that could crash \texttt{pythontex*.py} when the package option \texttt{pygments=false}.

% \item Added documentation about \texttt{autoprint} behavior in the preamble. Summary: \texttt{code} commands and environments are allowed in the preamble as of v0.10beta. \texttt{autoprint} only applies to the body of the document, because nothing can be typeset in the preamble. Content printed in the preamble can be brought in by explicitly using \texttt{\string\printpythontex}, but this should be used with great care.

% \item Revised \texttt{\string\stdoutpythontex} and \texttt{\string\printpythontex} so that they work in the preamble. Again, this should be used with great care if at all.

% \item Revised treatment of any content that custom code attempts to print. Custom code is not allowed to print to the document (see documentation). If custom code attempts to print, a warning is raised, and the printed content is included in the \texttt{pythontex*.py} run summary.

% \item One-line entries in stderr, such as those produced by Python's \texttt{warnings.warn()}, were not previously parsed because they are of the form \texttt{:<linenumber>:} rather than \texttt{line~<linenumber>}. These are now parsed and synchronized with the document. They are also correctly parsed for inclusion in the document via \texttt{\string\stderrpythontex}.

% \item If the package option \texttt{stderrfilename} is changed, all sessions that produced errors or warnings are now re-executed automatically, so that their stderr content is properly updated with the new filename.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.10beta}{2013/01/09}

% \begin{itemize}

% \item Backward-incompatible: Redid treatment of command-line options for \texttt{pythontex*.py}, using Python's \texttt{argparse} module. Run \texttt{pythontex*.py} with option \texttt{-h} to see new command line options.

% \item Deprecated: \texttt{\string\setpythontexcustomcode} is deprecated in favor of the \texttt{\string\pythontexcustomc} command and \texttt{pythontexcustomcode} environment. These allow entry of pure code, unlike \texttt{\string\setpythontexcustomcode}. These also allow custom code to be added to the beginning or end of a session, via an optional argument. Improved treatment of errors and warnings associated with custom code.

% \item The summary of errors and warnings now correctly differentiates errors and warnings produced by user code, rather than treating all of them as errors. By default, \texttt{pythontex*.py} now returns an exit code of 1 if there were errors.

% \item The PythonTeX utilities class now allows external file dependencies to be specified via \texttt{pytex.add\_dependencies()}, so that sessions are automatically re-executed when external dependencies are modified (modification is determined via either hash or mtime; this is governed by the new \texttt{hashdependencies} option).

% \item The PythonTeX utilities class now allows created files to be specified via \texttt{pytex.add\_created()}, so that created files may be automatically cleaned up (deleted) when the code that created them is modified (for example, name change for a saved plot).

% \item Added the following package options.

% \begin{itemize}

% \item \texttt{stdout} (or \texttt{print}): Allows input of stdout to be disabled. Useful for debugging.

% \item \texttt{runall}: Executes everything. Useful when code depends on external data.

% \item \texttt{rerun}: Determines when code is re-executed. Code may be set to always run (same as \texttt{runall} option), or only run when it is modified or when it produces errors or warnings. By default, code is always re-executed if there are errors or modifications, but not re-executed if there are warnings.

% \item \texttt{hashdependencies}: Determines whether external dependencies (data, external code files highlighted with Pygments, etc.) are checked for modification via hashing or modification time. Modification time is default for performance reasons.

% \end{itemize}

% \item Added the following new command line options. The options that are equivalent to package options are overridden by the package options when present.

% \begin{itemize}

% \item \texttt{-{}-error-exit-code}: Determines whether an exit code of 1 is returned if there were errors. On by default, but can be turned off since it is undesirable when working with some editors.

% \item \texttt{-{}-runall}: Equivalent to new package option.

% \item \texttt{-{}-rerun}: Equivalent to new package option.

% \item \texttt{-{}-hashdependencies}: Equivalent to new package option.

% \end{itemize}

% \item Modified the \texttt{fixlr} option, so that it only patches commands if they have not already been patched (avoids package conflicts).

% \item Added \texttt{\string\setpythontexautoprint} command for toggling autoprint on/off within the body of the document.

% \item Installer now attempts to create symlinks under OS X and Linux with TeX Live, and under OS X with MacPorts Tex Live.

% \item Performed compatibility testing under lualatex and xelatex (previously, had only tested with pdflatex). Added documentation for using these TeX engines; at most, slightly different preambles are needed. Modified the PythonTeX gallery to support all three engines.

% \item Code commands and environments may now be used in the preamble. This, combined with the new treatment of custom code, allows PythonTeX to be used in creating LaTeX packages.

% \item Added documentation for using PythonTeX in LaTeX programming.

% \item Fixed a bug that sometimes caused incorrect line numbers with \texttt{stderr} content. Improved processing of stderr.

% \item Fixed a bug in automatic detection of pre-existing listings environment.

% \item Improved the detection of imports from \texttt{\_\_future\_\_}. Detection should now be stricter, faster, and more accurate.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.9beta3}{2012/07/17}

% \begin{itemize}

% \item Added Unicode support, which required the Python code to be split into one set for Python 2 and another set for Python 3. This will require any old installation to be completely removed, and a new installation created from scratch.

% \item Refactoring of Python code. Documents should automatically re-execute all code after updating to the new version. Otherwise, you should delete the PythonTeX directory and run PythonTeX.

% \item Improved installation script.

% \item Added package options: pyfuture, stderr, upquote, pyglexer, pyginline. Renamed the pygextfile option to fvextfile.

% \item Added custom code and workingdir commands.

% \item Added the console environment and associated options.

% \item Rewrote pythontex\_utils*.py, creating a new, context-aware interface to SymPy's LatexPrinter class.

% \item Content brought in via macros no longer uses labels. Rather, long defs are used, which allows line breaks.

% \item Pygments highlighting is now default for PythonTeX commands and environments

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.9beta2}{2012/05/09}

% \begin{itemize}

% \item Changed Python output extension to .stdout.

% \end{itemize}

% \end{changelog}

%

% \begin{changelog}{v0.9beta}{2012/04/27}

% \begin{itemize}

% \item Initial public beta release.

% \end{itemize}

% \end{changelog}

%

%

% \DoNotIndex{\newcommand,\newenvironment}

% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }

% \DoNotIndex{\@ne}

% \DoNotIndex{\advance,\begingroup,\catcode,\closein}

% \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup}

% \DoNotIndex{\begin,\end,\bgroup,\egroup}

%

% \providecommand*{\url}{\texttt}

% \newcommand{\pytex}{Python\TeX}

% \GetFileInfo{pythontex.dtx}

% \title{\vspace{-0.5in}The \textsf{pythontex} package}

% \author{Geoffrey M.\ Poore \\ \url{[email protected]} \\ \href{https://github.com/gpoore/pythontex}{\texttt{github.com/gpoore/pythontex}}}

% \date{\fileversion~from \filedate}

%

% \maketitle

%

% \begin{abstract}

% \pytex\ provides access to Python from within \LaTeX\ documents. It allows Python code entered within a \LaTeX\ document to be executed, and the results to be included within the original document. Python code may be adjacent to the figure or calculation it produces. The package also makes possible macro definitions that mix Python and \LaTeX\ code. In addition, \pytex\ provides syntax highlighting for many programming languages via the Pygments syntax highlighter.

%

% \pytex\ is fast and user-friendly. Python code is only executed when it has been modified, or when user-specified criteria are met. When code is executed, user-defined sessions automatically run in parallel. If Python code produces errors, the error message line numbers are synchronized with the \LaTeX\ document line numbering, simplifying debugging. Dependencies may be specified so that code is automatically re-executed whenever they are modified.

%

% Because documents that use \pytex\ mix \LaTeX\ and Python code, they are less suitable than plain \LaTeX\ documents for journal submission, sharing, and conversion to other formats. \pytex\ includes a |depythontex| utility that creates a copy of a document in which all \pytex\ content is replaced by its output.

%

% While Python is the focus of \pytex, adding basic support for an additional language is usually as simple as creating a new class instance and a few templates, usually totaling less than 100 lines of code. The following languages already have built-in support: Ruby, Julia, and Octave.

% \end{abstract}

%

%

% \section*{\centering Warning}

%

% \pytex\ makes possible some pretty amazing things. But that power brings with it a certain risk and responsibility. Compiling a document that uses \pytex\ involves executing Python code, and potentially other programs, on your computer. You should only compile \pytex\ documents from sources you trust. \pytex\ comes with NO WARRANTY.\footnote{All \LaTeX\ code is licensed under the \href{http://www.latex-project.org/lppl.txt}{\LaTeX\ Project Public License (LPPL)} and all Python code is licensed under the \href{http://www.opensource.org/licenses/BSD-3-Clause}{BSD 3-Clause License}.} The copyright holder and any additional authors will not be liable for any damages.

%

%

% \pagebreak

% \tableofcontents

% \pagebreak

%

%

% \section{Introduction}

%

% This introduction provides background and objectives for the \pytex\ package. To jump right in and get started, you may wish to consult the |pythontex_quickstart| and |pythontex_gallery| documents, as well as Sections~\ref{sec:installing-and-running} and \ref{sec:usage}, below. If you are primarily interested in using \pytex\ with a language other than Python, see Section~\ref{sec:other-languages}.

%

% \LaTeX\ can do a lot,\footnote{\TeX\ is a Turing-complete language.} but the programming required can sometimes be painful.\footnote{As I learned in creating this package.} In spite of the many packages available for \LaTeX, the libraries and packages of a general-purpose programming language are lacking. Furthermore, it can be convenient to include non-\LaTeX\ code in a document to make it more reproducible. For these reasons, there have been multiple systems that allow other languages to be used within \LaTeX\ documents.\footnote{I am not including the various web and weave dialects in my discussion, since they typically involve a web or weave document from which the .tex source is generated, and thus weaker integration with \LaTeX. Two sophisticated examples of this approach are \href{http://www.stat.uni-muenchen.de/~leisch/Sweave/}{Sweave} and \href{http://yihui.name/knitr/}{knitr}, both of which combine \LaTeX\ with the R language for tasks such as dynamic report generation.}

% \begin{itemize}

% \item \href{http://www.ctan.org/pkg/perltex}{Perl\TeX} allows the bodies of \LaTeX\ macros to be written in Perl.

% \item \href{http://www.ctan.org/pkg/sagetex/}{Sage\TeX} allows code for the Sage mathematics software to be executed from within a \LaTeX\ document.

% \item Martin R.\ Ehmsen's \href{http://www.ctan.org/pkg/python}{|python.sty|} provides a very basic method of executing Python code from within a \LaTeX\ document.

% \item \href{http://elec.otago.ac.nz/w/index.php/SympyTeX}{Sympy\TeX} allows more sophisticated Python execution, and is largely based on a subset of Sage\TeX.

% \item \href{http://www.luatex.org/}{Lua\TeX} extends the pdf\TeX\ engine to provide Lua as an embedded scripting language, and as a result yields tight, low-level Lua integration.

% \end{itemize}

%

% \pytex\ attempts to fill a perceived gap in the current integrations of \LaTeX\ with an additional language. It has a number of objectives, only some of which have been met by previous packages.

% \begin{description}

% \item[Execution speed]\hfill\\ In the approaches mentioned above, all the non-\LaTeX\ code is executed at every compilation of the \LaTeX\ document (Perl\TeX, Lua\TeX, and |python.sty|), or all the non-\LaTeX\ code is executed every time it is modified (Sage\TeX\ and Sympy\TeX). However, many tasks such as plotting and data analysis take a significant time to execute. We need a way to fine-tune code execution, so that independent blocks of slow code may be separated into their own sessions and are only executed when modified. If we are going to split code into multiple sessions, we might as well run these sessions in parallel, further increasing speed. A byproduct of this approach is that it now becomes much more feasible to include slower code, since we can still have fast compilations whenever the slow code isn't modified.

% \item[Compiling without executing]\hfill\\ Even with all of these features to boost execution speed, there will be times when we have to run slow code. Thus, we need the execution of non-\LaTeX\ code to be separated from compiling the \LaTeX\ document. We need to be able to edit and compile a document containing unexecuted code. Unexecuted code should be invisible or be replaced by placeholders. Sage\TeX\ and Sympy\TeX\ have implemented such a separation of compiling and executing. In contrast, Lua\TeX\ and Perl\TeX\ execute all the code at each compilation---but that is appropriate given their goal of simplifying macro programming.

% \item[Error messages]\hfill\\ Whenever code is saved from a \LaTeX\ document to an external file and then executed, the line numbers for any error messages will not correspond to the line numbering of the original \LaTeX\ document. At one extreme, |python.sty| doesn't attempt to deal with this issue, while at the other extreme, Sage\TeX\ uses an ingenous system of |Try|/|Except| statements on every chunk of code. We need a system that translates all error messages so that they correspond to the line numbering of the original \LaTeX\ document, with minimal overhead when there are no errors.

% \item[Syntax highlighting]\hfill\\ Once we begin using non-\LaTeX\ code, sooner or later we will want to typeset some of it, which means we need syntax highlighting. A number of syntax highlighting packages currently exist for \LaTeX; perhaps the most popular are |listings| and |minted|. |listings| uses pure \LaTeX. It has not been updated since 2007, which makes it a less ideal solution in some circumstances. |minted| uses the Python-based syntax highlighter Pygments to perform highlighting. Pygments can provide superior syntax highlighting, but |minted| can be very slow because all code must be highlighted at each compilation and each instance of highlighting involves launching an external Python process. We need high-speed, user-friendly syntax highlighting via Pygments.\footnote{The author recently started maintaining the \texttt{minted} package. In the near future, \texttt{minted} will inherit \pytex's speed enhancements, and the two packages will become more compatible.}

% \item[Printing]\hfill\\ It would be nice for the |print| statement/function,\footnote{In Python, |print| was a statement until Python 3, when it became a function. The function form is available via import from |\textunderscore\textunderscore future\textunderscore\textunderscore| in Python 2.6 and later.} or its equivalent, to automatically return its output within the \LaTeX\ document. For example, using |python.sty| it is possible to generate some text while in Python, open a file, save the text to it, close the file, and then |\input| the file after returning to \LaTeX. But it is much simpler to generate the text and |print| it, since the printed content is automatically included in the \LaTeX\ document. This was one of the things that |python.sty| really got right.

% \item[Pure code]\hfill\\ \LaTeX\ has a number of special characters (|#| \texttt{\$} |%| |&| |~| |_| |^| |\| |{| |}|), which complicates the entry of non-\LaTeX\ code since these same characters are common in many languages. Sage\TeX\ and Sympy\TeX\ delimit all inline code with curly braces (|{}|), but this approach fails in the (somewhat unlikely) event that code needs to contain an unmatched brace. More seriously, they do not allow the percent symbol |%| (modular arithmetic and string formatting in Sage and Python) to be used within inline code. Rather, a |\percent| macro must be used instead. This means that code must (sometimes) be entered as a hybrid between \LaTeX\ and the non-\LaTeX\ language. Lua\TeX\ is somewhat similar: ``The main thing about Lua code in a TeX document is this: the code is expanded by TeX before Lua gets to it. This means that all the Lua code, even the comments, must be valid TeX!''\footnote{\url{http://wiki.contextgarden.net/Programming_in_LuaTeX}} In the case of Lua\TeX, though, there is the \href{http://www.ctan.org/pkg/luacode}{\texttt{luacode}} package that allows for pure Lua.

%

% This language hybridization is not terribly difficult to work around in the Sage\TeX\ and Sympy\TeX\ cases, and is actually a Lua\TeX\ feature in many contexts. But if we are going to create a system for general-purpose access to a non-\LaTeX\ language, we need \textbf{all} valid code to work correctly in \textbf{all} contexts, with no hybridization of any sort required. We should be able to copy and paste valid code into a \LaTeX\ document, without having to worry about hybridizing it. Among other things, this means that inline code delimiters other than \LaTeX's default curly braces |{}| must be available.

% \item[Hybrid code]\hfill\\ Although we need a system that allows input of pure non-\LaTeX\ code, it would also be convenient to allow hybrid code, or code in which \LaTeX\ macros may be present and are expanded before the code is executed. This allows \LaTeX\ data to be easily passed to the non-\LaTeX\ language, facilitating a tighter integration of the two languages and the use of the non-\LaTeX\ language in macro definitions.

% \item[Math and science libraries]\hfill\\ The author decided to create \pytex\ after writing a physics dissertation using \LaTeX\ and realizing how frustrating it can be to switch back and forth between a \TeX\ editor and plotting software when fine-tuning figures. We need access to a non-\LaTeX\ language like Python, MATLAB, or Mathematica that provides strong support for data analysis and visualization. To maintain broad appeal, this language should primarily involve open-source tools, should have strong cross-platform support, and should also be suitable for general-purpose programming.

% \item[Language-independent implementation]\hfill\\ It would be nice to have a system for executing non-\LaTeX\ code that depends very little on the language of the code. We should not expect to escape all language dependence. But if the system is designed to be as general as possible, then it may be expanded in the future to support additional languages.

% \end{description}

%

% Python was chosen as the language to fulfill these objectives for several reasons.

% \begin{itemize}

% \item It is open-source and has good cross-platform support.

% \item It has a strong set of scientific, numeric, and visualization packages, including \href{http://numpy.scipy.org/}{NumPy}, \href{http://www.scipy.org/}{SciPy}, \href{http://matplotlib.sourceforge.net/}{matplotlib}, and \href{http://sympy.org}{SymPy}. Much of the initial motivation for \pytex\ was the ability to create publication-quality plots and perform complex mathematical calculations without having to leave the \TeX\ editor.

% \item We need a language that is suitable for scripting. Lua is already available via Lua\TeX, and in any case lacks the math and science tools.\footnote{One could use \href{http://labix.org/lunatic-python}{Lunatic Python}, and some numeric packages for Lua are \href{http://numlua.luaforge.net/}{in development}.} Perl is already available via Perl\TeX, although Perl\TeX's emphasis on Perl for macro creation makes it rather unsuitable for scientific work using the \href{http://pdl.perl.org/}{Perl Data Language (PDL)} or for more general programming. Python is one logical choice for scripting.

% \end{itemize}

%

% Now at this point there will almost certainly be some reader, sooner or later, who wants to object, ``But what about language \textit{X}!'' Well, yes, in some respects the choice to use Python did come down to personal preference. But you should give Python a try, if you haven't already. You may also wish to consider the many interfaces that are available between Python and other languages. If you still aren't satisfied, keep in mind \pytex's ``language-independent'' implementation! In many cases, adding support for additional languages is relatively simple (see Section~\ref{sec:other-languages}).

%

%

% \section{Citing \pytex}

% \label{sec:citing}

%

% If you use \pytex\ in your writing and research, please consider citing it in any resulting publications. The best and most recent paper is in \textit{Computational Science \& Discovery}.

% \begin{itemize}

% \item ``PythonTeX: reproducible documents with LaTeX, Python, and more,'' Geoffrey M Poore. \textit{Computational Science \& Discovery} 8 (2015) 014010. Full text and Bib\TeX\ entry available at \url{http://stacks.iop.org/1749-4699/8/i=1/a=014010}.

% \item ``Reproducible Documents with PythonTeX,'' Geoffrey M.\ Poore. \textit{Proceedings of the 12th Python in Science Conference} (2013), pp.\ 73--79. Full text and Bib\TeX\ entry available at \url{http://conference.scipy.org/proceedings/scipy2013/poore.html}.

% \end{itemize}

%

%

% \section{Installing and running}

% \label{sec:installing-and-running}

%

% \subsection{Installing \pytex}

%

% \pytex\ requires a \TeX\ installation. It has been tested with \href{http://www.tug.org/texlive/}{\TeX\ Live} and \href{http://miktex.org/}{MiK\TeX}, but should work with other distributions. The following \LaTeX\ packages, with their dependencies, are required: |fancyvrb|, |fvextra|, |etoolbox|, |xstring|, |pgfopts|, |newfloat| (part of the |caption| bundle), |currfile|, and |color| or |xcolor|. A current \TeX\ installation is recommended, since some features require recent versions of the packages. If you are creating and including graphics, you will also need |graphicx|. The \href{http://www.ctan.org/pkg/mdframed}{\texttt{mdframed}} package is recommended for enclosing typeset code in boxes with fancy borders and/or background colors; \href{http://www.ctan.org/pkg/tcolorbox}{\texttt{tcolorbox}} and \href{http://www.ctan.org/pkg/framed}{\texttt{framed}} are alternatives.

%

% \pytex\ also requires a \href{http://www.python.org/}{Python} installation. Python 2.7 is recommended for the greatest compatibility with scientific tools, although many scientific packages are now compatible with Python 3. \pytex\ is compatible with Python 2.7 and 3.2+. The Python package \href{http://pygments.org/}{Pygments} must be installed for syntax highlighting to function. \pytex\ has been tested with Pygments 1.4 and later, but the latest version is recommended. For scientific work, or to compile |pythontex_gallery.tex|, the following are also recommended: \href{http://numpy.scipy.org/}{NumPy}, \href{http://www.scipy.org/}{SciPy}, \href{http://matplotlib.sourceforge.net/}{matplotlib}, and \href{http://sympy.org}{SymPy}. When using \pytex\ with LyX, be aware that LyX may try to use its own version of Python; you may need to reconfigure LyX.

%

% \pytex\ also provides support for other languages such as Ruby, so you will need to install any additional languags you plan to use. Typically, the most recent major version of these languages is supported.

%

% \pytex\ consists of the following files:

% \begin{itemize}

% \item Installer file |pythontex.ins|

% \item Documented \LaTeX\ source file |pythontex.dtx|, from which |pythontex.pdf| and |pythontex.sty| are generated

% \item Main script |pythontex.py|, which imports from |pythontex2.py| or |pythontex3.py|, based on the Python version

% \item Language definitions |pythontex_engines.py|

% \item Utilities class |pythontex_utils.py|

% \item |depythontex.py|, which imports from |depythontex2.py| or |depythontex3.py|, based on the Python version; used to remove \pytex\ dependence

% \item Synchronized Python Debugger |syncpdb.py|

% \item |README| (in rst style)

% \item |pythontex_gallery.tex| and |pythontex_gallery.pdf|

% \item |pythontex_quickstart.tex| and |pythontex_quickstart.pdf|

% \item Optional installation script |pythontex_install.py| for \TeX\ Live and MiKTeX

% \item Optional batch file |pythontex.bat| for use in launching |pythontex.py| under Windows

% \item Optional conversion script |pythontex_2to3.py| for converting \pytex\ code written for Python 2 into a form compatible with Python 3

% \end{itemize}

% The style file |pythontex.sty| may be generated by running \LaTeX\ on |pythontex.ins|. The documentation you are reading may be generated by running \LaTeX\ on |pythontex.dtx|. Some code is provided in two forms, one for Python 2 and one for Python 3 (names ending in |2| and |3|). Whenever this is the case, a version-independent wrapper is supplied that automatically runs the correct code based on the Python version. For example, there are two main scripts, |pythontex2.py| and |pythontex3.py|, but you should actually run |pythontex.py|, which imports the correct code based on the Python version.\footnote{Unfortunately, it is not possible to provide full Unicode support for both Python 2 and 3 using a single script. Currently, all code is written for Python 2, and then the Python 3 version is automatically generated via the |pythontex\_2to3.py| script. This script comments out code that is only for Python 2, and un-comments code that is only for Python 3.}

%

% If you want the absolute latest version of \pytex, you should install it manually from \href{https://github.com/gpoore/pythontex}{github.com/gpoore/pythontex}. A Python installation script is provided for use with \TeX\ Live and MiKTeX. It has been tested with Windows, Linux, and OS~X, but may need manual input or slight modifications depending on your system. The installation script performs the steps described below.

%

% \textbf{For a MiKTeX installation, you may need administrator privileges; running \texttt{pythontex\_install.bat} as administrator may be simplest.}

%

% \textbf{Note that for a typical \TeX\ setup under Linux, you may need to run the script with elevated privileges, and may need to run it with the user's PATH.} This can be necessary when you are using a Linux distribution that includes an outdated version of \TeX\ Live, and have installed a new version manually. \textbf{If you are installing \pytex\ on a machine with multiple versions of \TeX, make sure you install \pytex\ for the correct version.} For example, under Ubuntu Linux, you will probably need the following command if you have installed the latest version of \TeX\ Live manually:

% \begin{verbatim}

% sudo env PATH=$PATH python pythontex_install.py

% \end{verbatim}

%

% The installer creates the following files. It will offer to create the paths if they do not exist. If you are installing in TEXMFLOCAL, the paths will have an additional |local/| at the end.

% \begin{itemize}

% \item \meta{\TeX\ tree root}|/doc/latex/pythontex/|

% \begin{itemize}

% \item |pythontex.pdf|

% \item |README|

% \item |pythontex_quickstart.tex|

% \item |pythontex_quickstart.pdf|

% \item |pythontex_gallery.tex|

% \item |pythontex_gallery.pdf|

% \end{itemize}

% \item \meta{\TeX\ tree root}|/scripts/pythontex/|

% \begin{itemize}

% \item |pythontex.py|, |pythontex2.py| and |pythontex3.py|

% \item |pythontex_engines.py|

% \item |pythontex_utils.py|

% \item |depythontex.py|, |depythontex2.py| and |depythontex3.py|

% \item |syncpdb.py|

% \end{itemize}

% \item \meta{\TeX\ tree root}|/source/latex/pythontex/|

% \begin{itemize}

% \item |pythontex.dtx|

% \item |pythontex.ins|

% \end{itemize}

% \item \meta{\TeX\ tree root}|/tex/latex/pythontex/|

% \begin{itemize}

% \item |pythontex.sty|

% \end{itemize}

% \end{itemize}

% After the files are installed, the system must be made aware of their existence. The installer runs |mktexlsr| to do this. In order for |pythontex.py| and |depythontex.py| to be executable, a symlink (\TeX\ Live under Linux), launching wrapper (\TeX\ Live under Windows), or batch file (general Windows) should be created in the |bin/|\meta{system} directory. The installer attempts to create a symlink or launching wrapper automatically. For \TeX\ Live under Windows, it copies |bin/win32/runscript.exe| to |bin/win32/pythontex.exe| to create the wrapper.\footnote{See the output of |runscript -h| under Windows for additional details.}

%

%

% \subsection{Compiling documents using \pytex}

% \label{sec:installing-and-running:compiling}

%

% Compiling a document with \pytex\ involves three steps: running a \LaTeX-compatible \TeX\ engine (binary executable), running |pythontex.py| (preferably via a symlink, wrapper, or batch file, as described above), and finally running the \TeX\ engine again. The first \TeX\ run saves code into an external file where \pytex\ can access it. The second \TeX\ run pulls the \pytex\ output back into the document.

%

% If you plan to use code that contains non-ASCII characters such as Unicode, you should make sure that your document is properly configured:

% \begin{itemize}

% \item Under pdfLaTeX, your documents need |\usepackage[T1]{fontenc}| and |\usepackage[utf8]{inputenc}|, or a similar configuration.

% \item Under LuaLaTeX, your documents need |\usepackage{fontspec}|, or a similar configuration.

% \item Under XeLaTeX, your documents need |\usepackage{fontspec}| as well as |\defaultfontfeatures{Ligatures=TeX}|, or a similar configuration.

% \end{itemize}

% For an example of a \pytex\ document that will correctly compile under all three engines, see the |pythontex_gallery.tex| source.

%

% If you use XeLaTeX, and your non-\LaTeX\ code contains tabs, you \textbf{must} invoke XeLaTeX with the |-8bit| option so that tabs will be written to file as actual tab characters rather than as the character sequence |^^I|.\footnote{See \url{http://tex.stackexchange.com/questions/58732/how-to-output-a-tabulation-into-a-file} for more on tabs with XeTeX.}

%

% |pythontex.py| requires a single command-line argument: the name of the .tex file to process. The filename can be passed with or without an extension; the script really only needs the |\jobname|, so any extension is stripped off.\footnote{Thus, \pytex\ works happily with .tex, .ltx, .dtx, and any other extension.} The filename may include the path to the file; you do not have to be in the same directory as the file to run \pytex. If you are configuring your editor to run \pytex\ automatically via a shortcut, you may want to wrap the filename in double quotes |"| to allow for space characters.\footnote{Using spaces in the names of .tex files is apparently frowned upon. But if you configure things to handle spaces whenever it doesn't take much extra work, then that's one less thing that can go wrong.} For example, under Windows with \TeX\ Live and Python 2.7 we would create the wrapper |pythontex.exe|. Then we could run \pytex\ on a file \meta{file~name}.tex using the command |pythontex.exe "|\meta{file~name}|"|.

%

% |pythontex.py| accepts the following optional command-line arguments. Some of these options duplicate package-level options, so that settings may be configured either within the document or at the command line. In the event that the command-line and package options conflict, the package options always override the command-line options. For variations on these options that are acceptable, run |pythontex.py -h|.

% \begin{itemize}

% \item |--encoding=|\meta{encoding} This sets the file encoding. Any encoding supported by Python's \href{http://docs.python.org/library/codecs.html}{\texttt{codecs}} module may be used. The encoding should match that of the \LaTeX\ document. If an encoding is not specified, \pytex\ uses UTF-8. If support for characters beyond ASCII is required, then additional \LaTeX\ packages are required; see the discussion of \TeX\ engines above.

% \item |--error-exit-code={true,false}| By default, |pythontex.py| returns an exit code of 1 if there were any errors, and an exit code of 0 otherwise. This may be useful when \pytex\ is used in a scripting or command-line context, since the presence of errors may be easily detected. It is also useful with some \TeX\ editors. For example, \href{http://www.tug.org/texworks/}{TeXworks} automatically hides the output of external programs unless there are errors.

%

% In some contexts, returning a nonzero exit code can be redundant. For example, with the \href{http://winshell.de/}{WinShell} editor under Windows with TeX Live, the complete output of \pytex\ is always available in the ``Output'' view, so it is clear if errors have occurred. Having a nonzero exit code causes |runscript.exe| to return an additional, redundant error message in the ``Output'' view. In such situations, it may be desirable to disable the nonzero exit code.

% \item |--runall=[{true,false}]| This causes \textbf{all} code to be executed, regardless of modification or |rerun| settings. It is useful when code has not been modified, but a dependency such as a library or external data has changed. Note that the \pytex\ utilities class also provides a mechanism for automatically re-executing code that depends on external files when those external files are modified.

%

% There is an equivalent |runall| package option. The command-line option |--rerun=always| is essentially equivalent.

% \item |--rerun={never,modified,errors,warnings,always}| This sets the threshold for re-executing code. By default, \pytex\ will rerun code that has been modified or that produced errors on the last run. Sometimes, we may wish to have a more lenient setting (only rerun if modified) or a more stringent setting (rerun even for warnings, or just rerun everything). |never| never executes code; a warning is issued if there is modified code. |modified| only executes code that has been modified (or that has modified dependencies). |errors| executes all modified code as well as all code that produced errors on the last run; this is the default. |warnings| executes all modified code, as well as all code that produced errors or warnings. |always| executes all code always and is essentially equivalent to |--runall|.

%

% There is an equivalent |rerun| package option.

% \item |--hashdependencies=[{true,false}]| This determines whether dependencies (external files highlighted by Pygments, code dependencies specified via |pytex.add_dependencies()|, etc.) are checked for changes via their hashes or modification times. By default, mtime is used, since it is faster. The package option |hashdependencies| is equivalent.

%

% \item |--jobs| This sets the maximum number of concurrent processes. By default, this will be Python's |multiprocessing.cpu_count()|, which is the number of CPUs in the system. It may be useful to set a smaller value when some jobs are particularly resource intensive or themselves use subprocesses.

%

% \item |--verbose| This gives more verbose output, including a list of all processes that are launched.

%

% \item |--interpreter| This allows the interpreter for a given language to be specified. The argument should be in the form

% \begin{verbatim}

%--interpreter "<interpreter>:<command>, <interp>:<cmd>, ..."

% \end{verbatim}

% where |<interpreter>| is |python|, |ruby|, etc., and |<command>| is the command for invoking the desired interpreter. The argument to |--interpreter| may also be in the form of a Python dictionary. The argument need not be enclosed in quotation marks if it contains no spaces.

%

% For example, by default Python code is executed with whatever interpreter the |python| command invokes. But Python 3 could be specified using |--interpreter python:python3| (many Linux distributions) or |--interpreter "python:py -3"| (Windows, with Python 3.3 installed so that the |py| wrapper is available).

%

% \item |--interactive [<family>:<session>:<restart>]| This is used to run a single session in interactive mode. This allows user input. Code output is written to stdout. Interactive mode is particularly useful when working with debuggers (but also see the |--debug| option).

%

% |[<family>:<session>:<restart>]| is optional; if it is not provided, the default session is executed. For non-default sessions (or if there are multiple default sessions, due to the use of multiple families of commands), simply supplying the session name is usually sufficient (for example, |--debug session|). The full combination of |[<family>:<session>:<restart>]| (for example, |py:session:default|) is only necessary when the session name alone would be ambiguous.

%

% Note that when a session is run in interactive mode, it will \emph{not} save printed content in a form that may be brought back into the document. You will have to run the session again in normal mode to complete document compilation.

%

% Code that requires user input will cause \pytex\ to ``hang'' when \pytex\ is not running in interactive mode. This is because the code will request user input, but no input is possible given the way that the code is being executed, so the code will wait for input forever. It is inefficient constantly to add and then delete interactive code as you switch between normal and interactive modes. To avoid this, you can conditionally invoke code that requires input. In interactive mode, the temporary script that is executed is given the command-line argument |--interactive|. You can check for the presence of this argument, and only invoke interactive code if it is present. For example, under Python you could start the |pdb| debugger, only when the code is being executed in interactive mode, using commands such as the following.

%\begin{verbatim}

%import pdb

%import sys

%if '--interactive' in sys.argv[1:]:

% pdb.set_trace()

%\end{verbatim}

%

% This option is currently not compatible with Python console commands and environments.

%

% \item |--debug [<family>:<session>:<restart>]| This is used to run a single session with the default debugger in interactive mode. Currently, only standard Python sessions are supported. (Python console commands and environments are not supported.) Support for other languages and support for customization will be added in the future.

%

% |[<family>:<session>:<restart>]| is optional; if it is not provided, the default session is executed. For non-default sessions (or if there are multiple default sessions, due to the use of multiple families of commands), simply supplying the session name is usually sufficient (for example, |--debug session|). The full combination of |[<family>:<session>:<restart>]| (for example, |py:session:default|) is only necessary when the session name alone would be ambiguous.

%

% Note that when a session is run in debug mode, it will \emph{not} save printed content in a form that may be brought back into the document. You will have to run the session again in normal mode to complete document compilation.

%

% The default Python debugger is |syncpdb|, the Synchronized Python Debugger. It provides a wrapper around |pdb| that is aware of the connection between the code and the \LaTeX\ document from which it was extracted. All |pdb| commands function normally. In addition, commands that take a line number or filename:lineno as an argument will also take these same values with a percent symbol |%| prefix. If the percent symbol is present, then |syncpdb| interprets the filename and line number as referring to the document, rather than to the code that is executed. It will translate the filename and line number to the corresponding code equivalents, and then pass these to the standard |pdb| internals. For example, the |pdb| command |list 50| would list the code that is being executed, centered around line 50. |syncpdb| allows the command |list %10|, which would list the code that is being executed, centered around the code that came from line 10 in the main \LaTeX\ document. (If no file name is given, then the main \LaTeX\ document is assumed.) If the code instead came from an inputed file |input.tex|, then |list %input.tex:10| could be used. Further details are provided at \href{https://github.com/gpoore/syncpdb}{github.com/gpoore/syncpdb}.

%

% The temporary script that is executed is given the command-line argument |--interactive| when run in debug mode. You can check for the presence of this argument if you wish to invoke code that requires user input conditionally. See the |--interactive| command-line option for more details.

%

% \end{itemize}

%

% \pytex\ attempts to check for a wide range of errors and return meaningful error messages. But due to the interaction of \LaTeX\ and Python code, some strange errors are possible. If you cannot make sense of errors when using \pytex, the simplest thing to try is deleting all files created by \pytex, then recompiling. By default, these files are stored in a directory called |pythontex-files-|\meta{jobname}, in the same directory as your .tex document. See Section \ref{sec:troubleshooting} for more details regarding troubleshooting.

%

%

% \section{Usage}

% \label{sec:usage}

%

% \subsection{Package options}

% Package options may be set in the standard manner when the package is loaded:

% \begin{quote}

% |\usepackage|\oarg{options}|{pythontex}|

% \end{quote}

%

% All options are described as follows. The option is listed, followed by its possible values. When a value is not required, \meta{none} is listed as a possible value. In this case, the value to which \meta{none} defaults is also given. Each option lists its default setting, if the option is not invoked when the package is loaded.

%

% Some options have a command-line equivalent. Package options override command-line options.

%

% All options related to printed content are provided in two forms for convenience: one based on the word |print| and one based on |stdout|.

%

%

% \DescribeMacro{usefamily=\meta{basename}/\marg{basename1,~basename2,~...}}

%

% By default, only the |py|, |sympy|, and |pylab| families of commands and environments are defined, to prevent possible package conflicts.\footnote{For example, a \texttt{\string\ruby} command for Ruby code, and the \texttt{\string\ruby} command defined by the Ruby package in the \href{http://www.ctan.org/pkg/cjk}{CJK package}.} This option defines preconfigured families for other available languages. It takes either a single language base name, or a list of comma-separated names enclosed in curly braces. Currently, the Ruby families |rb| and |ruby|, the Julia families |jl| and |julia|, and the Octave family |octave| may be created.

%

%

% \DescribeMacro{gobble=none/auto default:none}

%

% This option is still under development and may change somewhat in future releases. If that occurs, equivalent functionality will be provided.

%

% This option determines how code indentation is handled. By default, indentation is left as-is; leading whitespace is significant. |auto| will dedent all code by gobbling the largest common leading whitespace, using Python's |textwrap.dedent()|.\footnote{It would be possible to do the dedent on the \LaTeX\ side, as is done manually in the \texttt{fancyvrb} and \texttt{listings} packages with the \texttt{gobble} option and is done automatically in the \texttt{lstautogobble} package. This is not done for stability and security reasons. \texttt{lstautogobble} determines the dedent by extracting the leading whitespace from the first line of code, and then applying this dedent to each subsequent line. This is adequate for \textbf{typesetting} code, since the worst-case scenario is that a subsequent line with less indentation will be typeset with the first few characters missing. Such an approach is not acceptable when the code will be \textbf{executed}, since a few missing characters could in principle cause serious damage. Doing the dedent on the Python side ensures that no characters are discarded, even if that results in an indentation error.} Keep in mind that Python's dedent will not work correctly with mixed tabs and spaces.

%

% The |gobble| option always works correctly with \textbf{executed} code. However, currently the option \textbf{only works with typeset code when Pygments is used}. The option is currently only available at the document level, but finer-grained control is planned in the future.

%

% The |gobble| option is supported by |depythontex|.

%

%

% \DescribeMacro{beta=\meta{none}/true/false default:false \meta{none}=true}

%

% This option provides compatibility with the beta releases from before the full v0.11 release, which introduced some changes in syntax and command names. This option should \textbf{only} be used with old \pytex\ documents that require it.

%

% You are encouraged to update old documents, since this compatility option will only be provided for a few releases.

%

%

% \DescribeMacro{runall=\meta{none}/true/false default:false \meta{none}=true}

%

% This option causes all code to be executed, regardless of whether it has been modified. This option is primarily useful when code depends on external files, and needs to be re-executed when those external files are modified, even though the code itself may not have changed. Note that the \pytex\ utilities class also provides a mechanism for automatically re-executing code that depends on external files when those external files are modified.

%

% A command-line equivalent |--runall| exists for |pythontex.py|. The package option |rerun=always| is essentially equivelent.

%

%

% \DescribeMacro{rerun=never/modified/errors/warnings/always default:errors}

%

% This option sets the threshold for re-executing code. By default, \pytex\ will rerun code that has been modified or that produced errors on the last run. Sometimes, we may wish to have a more lenient setting (only rerun if modified) or a more stringent setting (rerun even for warnings, or always rerun). |never| never executes code; a warning is issued if there is modified code. |modified| only executes code that has been modified. |errors| executes all modified code as well as all code that produced errors on the last run; this is the default. |warnings| executes all modified code, as well as all code that produced errors or warnings. |always| executes all code regardless of its condition.

%

% A command-line equivalent |--rerun| exists for |pythontex.py|.

%

%

% \DescribeMacro{hashdependencies=\meta{none}/true/false default:false \meta{none}=true}

%

% When external code files are highlighted with Pygments, or external dependencies are specified via the \pytex\ utilities class, they are checked for modification via their modification time (Python's |os.path.getmtime()|). Usually, this should be sufficient---and it offers superior performance, which is important if data sets are large enough that hashing takes a noticeable amount of time. However, occasionally hashing may be necessary or desirable, so this option is provided.

%

% A command-line equivalent |--hashdependencies| exists for |pythontex.py|.

%

%

% \DescribeMacro{autoprint=\meta{none}/true/false default:true \meta{none}=true}

%

% \DescribeMacro{autostdout=\meta{none}/true/false default:true \meta{none}=true}

%

% Whenever a |print| command/statement is used, the printed content will automatically be included in the document, unless the code doing the printing is being typeset.\footnote{Note that |autoprint| only works within the body of the document. The |code| command and environment can be used in the preamble, but |autoprint| is disabled there. It is usually a not a good idea to print in the preamble, because nothing can be typeset; the only thing that could be validly printed is \LaTeX\ commands that do not typeset content, such as macro definitions. Thus, it is appropriate that printed content is only brought in while in the preamble if it is explicitly requested via |\string\printpythontex|. This approach is also helpful for writing packages using \pytex, since the author does not have to worry about any \LaTeX\ commands printed by the package either not being included (if |autoprint| is relied upon, but the user turns it off) or being included twice (if |\string\printpythontex| is used and |autoprint| is enabled). Printing should only be used in the preamble with great care.} In that case, the printed content must be included using the |\printpythontex| or |\stdoutpythontex| commands.

%

% Printed content is pulled in directly from the external file in which it is saved, and is interpreted by \LaTeX\ as \LaTeX\ code. If you wish to avoid this, you should print appropriate \LaTeX\ commands with your content to ensure that it is typeset as you desire. Alternatively, you may use |\printpythontex| or |\stdoutpythontex| to bring in printed content in verbatim form, using those commands' optional |verb| and |verbatim| options.

%

% The |autoprint| (|autostdout|) option sets autoprint behavior for the entire document. This may be overridden within the document using the |\setpythontexautoprint| command.

%

% \DescribeMacro{debug}

%

% This option aids in debugging invalid \LaTeX\ code that is brought in from Python. It disables the inclusion of printed content/content written to stdout. Since printed content should almost \textbf{always} be included, a warning is raised when this option is used.

%

% Not including printed content is useful when the printed content contains \LaTeX\ errors, and would cause document compilation to fail. When the document fails to compile, this can prevent modified Python code from being written to the code file, resulting in an inescapable loop unless printed content is disabled or the saved output is deleted.

%

% Note that since commands like |\py| involve printing, they are also disabled.

%

%

% \DescribeMacro{makestderr=\meta{none}/true/false default:false \meta{none}=true}

%

% This option determines whether the stderr produced by scripts is available for input by \pytex, via the |\stderrpythontex| macro. This will not be needed in most situations. It is intended for typeseting incorrect code next to the errors that it produces. This option is not |true| by default, because additional processing is required to synchronize stderr with the document.

%

% \DescribeMacro{stderrfilename=full/session/genericfile/genericscript default:full}

%

% This option governs the file name that appears in |stderr|. Python errors begin with a line of the form

% \begin{quote}

% | File "<file or source>", line <line>|

% \end{quote}

% By default (option |full|), |<file or source>| is the actual name of the script that was executed. The name will be in the form \meta{family~name}|_|\meta{session}|_|\meta{restart}|.|\meta{extension}. For example, an error produced by a |py| command or environment, in the session |mysession|, using the default restart (that is, the default |\restartpythontexsession| treatment), would be reported in |py_mysession_default.py|. The |session| option replaces the full file name with the name of the session, |mysession.py| in this example. The |genericfile| and |genericscript| options replace the file name with |<file>| and |<script>|, respectively.

%

% \DescribeMacro{pyfuture=none/all/default default:default}

%

% Under Python 2, this determines what is automatically imported from |__future__| for all code. It does not apply to |console| content. |none| imports nothing from |__future__|. |all| imports everything available in Python 2.7 (|absolute_import|, |division|, |print_function|, and |unicode_literals|). |default| imports a default set of features that should be compatible with almost all packages. Everything except |unicode_literals| is imported, since |unicode_literals| can occasionally cause conflicts. Note that imports from |__future__| are also allowed within sessions, so long as they are at the very beginning of the session, as they would have to be in a normal script.

%

% This option has no effect under Python 3.

%

%

% \DescribeMacro{pyconfuture=none/all/default default:none}

%

% This is the equivalent of |pyfuture| for Python |console| content. The two options are separate, because in the |console| context it may be desirable to show explicitly all code that is executed.

%

%

% \DescribeMacro{upquote=\meta{none}/true/false default:true \meta{none}=true}

%

% This option determines whether the |upquote| package is loaded. In general, the |upquote| package should be loaded, because it ensures that quotes within verbatim contexts are ``upquotes,'' that is, \expandafter|\textquotesingle| rather than |'|.

%

% Using |upquote| is important beyond mere presentation. It allows code to be copied directly from the compiled PDF and executed without any errors due to quotes |'| being copied as acute accents \texttt{\'}.

%

% \DescribeMacro{fixlr=\meta{none}/true/false default:false \meta{none}=true}

%

% This option removes ``extra'' spacing around |\left| and |\right| in math mode. This spacing is sometimes undesirable, especially when typesetting functions such as the trig functions. See the implementation for details. Similar functionality is provided by the \href{http://www.ctan.org/pkg/mleftright}{\texttt{mleftright}} package

%

% \DescribeMacro{keeptemps=\meta{none}/all/code/none default:none \meta{none}=all}

%

% When \pytex\ runs, it creates a number of temporary files. By default, none of these are kept. The |none| option keeps no temp files, the |code| option keeps only code temp files (these can be useful for debugging), and the |all| option keeps all temp files (code, stdout and stderr for each code file, etc.). Note that this option does not apply to any user-generated content, since \pytex\ knows very little about that; it only applies to files that \pytex\ automatically creates by itself.

%

% \DescribeMacro{prettyprinter=pygments/fancyvrb default:pygments}

%

% This allows the user to determine at the document level whether code is typeset using Pygments or |fancyvrb|.

%

% The package-level option can be overridden for individual command and environment families, using the |\setpythontexprettyprinter| command. Overriding is never automatic and should generally be avoided, since using Pygments to highlight only some content results in an inconsistent style. Keep in mind that Pygment's |text| lexer and/or |bw| style can be used when content needs little or no syntax highlighting.

%

%

% \DescribeMacro{prettyprintinline=\meta{none}/true/false default:true \meta{none}=true}

%

% This determines whether inline content is pretty printed. If it is turned off, inline content is typeset with |fancyvrb|.

%

%

% \DescribeMacro{pygments=\meta{none}/true/false default:true \meta{none}=true}

%

% This allows the user to determine at the document level whether code is typeset using Pygments rather than |fancyvrb|. It is an alias for |prettyprinter=pygments|.

%

%

% \DescribeMacro{pyginline=\meta{none}/true/false default:true \meta{none}=true}

%

% This option governs whether inline code, not just code in environments, is highlighted when Pygments highlighting is in use. When Pygments is in use, it will highlight everything by default.

%

% It is an alias for |prettyprintinline|.

%

%

% \DescribeMacro{pyglexer=\meta{pygments~lexer} default:\meta{none}}

%

% This allows a Pygments lexer to be set at the document level. In general, this option should \textbf{not} be used. It overrides the default lexer for all commands and environments, for both \pytex\ and Pygments content, and this is usually not desirable. It should be useful primarily when all content uses the same lexer, and multiple lexers are compatible with the content.

%

%

% \DescribeMacro{pygopt=\marg{pygments~options} default:\meta{none}}

%

% This allows Pygments options to be set at the document level. The options must be enclosed in curly braces |{}|. Currently, three options may be passed in this manner: |style=|\meta{style~name}, which sets the formatting style; |texcomments|, which allows \LaTeX\ in code comments to be rendered; and |mathescape|, which allows \LaTeX\ math mode (|$...$|) in comments. The |texcomments| and |mathescape| options may be used with an argument (for example, |texcomments=true/false|); if an argument is not supplied, |true| is assumed. Example: |pygopt={style=colorful, texcomments=true, mathescape=false}|.

%

% Pygments options for individual command and environment families may be set with the |\setpythontexpygopt| macro; for Pygments content, there is |\setpygmentspygopt|. These individual settings are always overridden by the package option.

%

%

% \DescribeMacro{fvextfile=\meta{none}/\meta{integer} default:$\infty$ \meta{none}=25}

%

% This option speeds the typesetting of long blocks of code that are created on the Python side. This includes content highlighted using Pygments and the |console| environment. Typesetting speed is increased at the expense of creating additional external files (in the \pytex\ directory). The \meta{integer} determines the number of lines of code at which the system starts using multiple external files, rather than a single external file. See the implementation for the technical details; basically, an external file is used rather than |fancyvrb|'s |SaveVerbatim|, which becomes increasingly inefficient as the length of the saved verbatim content grows. In most situations, this option should not be needed, or should be fine with the default value or similar ``small'' integers.

%

%

% \DescribeMacro{pyconbanner=none/standard/default/pyversion default:none}

%

% This option governs the appearance (or disappearance) of a banner at the beginning of Python console environments. (A banner only appears in the first environment within each session.) The options |none| (no banner), |standard| (standard Python banner), |default| (default banner for Python's |code| module, standard banner plus interactive console class name), and |pyversion| (banner in the form |Python x.y.z|) are accepted.

%

%

% \DescribeMacro{pyconfilename=stdin/console default:stdin}

%

% This governs the form of the filename that appears in error messages in Python console environments. Python errors messages have a form such as the following:

% \begin{verbatim}

% >>> z = 1 + 34 +

% File "<name>", line 1

% z = 1 + 34 +

% ^

% SyntaxError: invalid syntax

% \end{verbatim}

% The |stdin| option replaces |<name>| with |<stdin>|, as it appears in a standard Python interactive session. The |console| option uses |<console>| instead, which is the default setting for the Python |code| module used by \pytex\ to create Python console environments.

%

% \DescribeMacro{depythontex=\meta{none}/true/false default:false \meta{none}=true}

%

% This option is used to create a version of the \LaTeX\ document that does not require the \pytex\ package. When invoked, it creates an auxiliary file called |<filename>.depytx|. The script |depythontex.py| uses the original document and this auxiliary file to create a new document in which all \pytex\ commands and environments have been replaced by typeset code and code output. For additional information on |depythontex|, see Section~\ref{sec:depythontex}.

%

%

% \subsection{Commands and environments}

%

% \pytex\ provides four types of commands for use with inline code and three environments for use with multiple lines of code, plus special commands and environments for |console| content. All commands and environments are named using a base name and a command- or environment-specific suffix. A complete set of commands and environments with the same base name constitutes a \textbf{command and environment family}. In what follows, the different commands and environments are described using the |py| base name (the |py| family) as an example.

%

% Most commands and environments cannot be used in the preamble, because they typeset material and that is not possible in the preamble. The one exception is the |code| command and environment. These can be used to enter code, but need not typeset anything. This allows you to collect your \pytex\ code in the preamble, if you wish, or even use \pytex\ in package writing. Note that the package option |autoprint| is never active in the preamble, so even if a |code| command or environment did print in the preamble, printed content would never be inputted unless |\printpythontex| or |\stdoutpythontex| were used.

%

% All commands and environments take a session name as an optional argument. The session name determines the session in which the code is executed. This allows code to be executed in multiple independent sessions, increasing speed (sessions run in parallel) and preventing naming conflicts. If a session is not specified, then the |default| session is used. Session names should use the characters a-z, A-Z, 0-9, the hyphen, and the underscore. All characters used \textbf{must} be valid in file names, since session names are used to create temporary files. The colon is also allowed, but it is replaced with a hyphen internally, so the sessions |code:1| and |code-1| are identical.

%

% In addition, all environments take |fancyvrb| settings as a second, optional argument. See the \href{http://www.ctan.org/pkg/fancyvrb}{|fancyvrb| documentation} for an explanation of accepted settings. This second optional argument \textbf{must} be preceeded by the first optional argument (session name). If a named session is not desired, the optional argument can be left empty (|default| session), but the square brackets |[]| must be present so that the second optional argument may be correctly identified:

% \begin{quote}

% |\begin{|\meta{environment}|}[]|\oarg{fancyvrb~settings}

% \end{quote}

%

%

% \subsubsection{Inline commands}

% \pytxtodo{Fix spacing around |\DescribeMacro|!}

% Inline commands are suitable for single lines of code that need to be executed within the body of a paragraph or within a larger body of text. The commands use arbitrary code delimiters (like |\verb| does), which allows the code to contain arbitrary characters. Note that this is only guaranteed to work properly when the inline commands are \textbf{not} inside other macros. If an inline command is used within another macro, the code will be read by the external macro before \pytex\ can read the special code characters (that is, \LaTeX\ will tokenize the code). The inline commands can work properly within other macros, but it is best to stick with curly braces for delimiters in this case and you may have trouble with the hash |#| and percent |%| characters.

%

% \DescribeMacro{\py\oarg{session}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command is used for including variable values or other content that can be converted to a string. It is an alternative to including content via the |print| statement/function within other commands/environments.

%

% The |\py| command sends \meta{code} to Python, and Python returns a string representation of \meta{code}.\pytxtodo{Link to details about Python built-ins} \meta{opening~delim} and \meta{closing~delim} must be either a pair of identical, non-space characters, or a pair of curly braces. If curly braces are used as delimiters, then curly braces may only be used within \meta{code} if they are paired. Thus, |\py{1+1}| sends the code |1+1| to Python, Python evaluates the string representation of this code, and the result is returned to \LaTeX\ and included as |2|. The commands |\py#1+1#| and |\py@1+1@| would have the same effect. The command can also be used to access variable values. For example, if the code |a=1| had been executed previously, then |\py{a}| simply brings the string represantation of |a| back into the document as |1|.

%

% Assignment is \textbf{not} allowed using |\py|. For example, |\py{a=1}| is \textbf{not} valid. This is because assignment cannot be converted to a string.\footnote{It would be simple to allow any code within |\textbackslash py|, including assignment, by using a |try/except| statement. In this way, the functionality of |\textbackslash py| and |\textbackslash pyc| could be merged. While that would be simpler to use, it also has serious drawbacks. If |\textbackslash py| is not exclusively used to typeset string representations of \meta{code}, then it is no longer possible on the \LaTeX\ side to determine whether a command should return a string. Thus, it is harder to determine, from within a \TeX\ editor, whether |pythontex.py| needs to be run; warnings for missing Python content could not be issued, because the system wouldn't know (on the \LaTeX\ side) whether content was indeed missing.}

%

% The text returned by Python must be valid \LaTeX\ code. Verbatim and other special content is allowed. The primary reasons for using |\py| rather than |print| are (1) |\py| is more compact and (2) |print| requires an external file to be created for every command or environment in which it is used, while |\py| and equivalents for other families share a single external file. Thus, use of |\py| minimizes the creation of external files, which is a key design goal for \pytex.\footnote{For |\textbackslash py|, the text returned by Python is stored in macros and thus must be valid \LaTeX\ code, because \LaTeX\ interprets the returned content. The use of macros for storing returned content means that an external file need not be created for each use of |\textbackslash py|. Rather, all macros created by |\textbackslash py| and equivalent commands from other families are stored in a single file that is inputted. Note that even though the content is stored in macros, verbatim content is allowed, through the use of special macro definitions combined with \texttt{\string\scantokens}.} The main reason for using |print| rather than |\py| is if you need to include a very large amount of material; |print|'s use of external files won't use up \TeX's memory, and may give noticeably better performance once the material is sufficiently long.

%

% \DescribeMacro{\pyc\oarg{session}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command is used for executing but not typesetting \meta{code}. The suffix |c| is an abbreviation of |code|. If the |print| statement/function is used within \meta{code}, printed content will be included automatically so long as the package |autoprint| option is set to true (the default setting).

%

% \DescribeMacro{\pys\oarg{session}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command performs variable and expression substitution, or string interpolation, on \meta{code}. Fields of the form |!{|\meta{expr}|}| in \meta{code} are replaced with the evaluated and printed output of \meta{expr}. The suffix |s| is an abbreviation of |sub|, for ``substitute.'' This command is useful for inserting Python-generated content in contexts where the normal |\py| and |\pyc| would not function or would be inconvenient due to the restrictions imposed by \LaTeX. Since Python processes \meta{code} and performs substitutions before the result is passed to \LaTeX, substitution fields may be anywhere.

%

% Literal exclamation points |!| in \meta{code} only need to be escaped when they immediately precede an opening curly brace |{|, or when they precede exclamation points that precede a brace. Escaping is performed by doubling. Thus, |!!{| would indicate a literal exclamation point followed by a literal curly brace (|!{|), not the beginning of a substitution field. And |!!!{| would indicate a literal exclamation point (|!!|) followed by a substitution field (|!{...}|). Because curly braces |{}| only have the meaning of field delimiters when immediately following a non-escaped exclamation point, curly braces never need to be escaped.

%

% The rules for delimiting \meta{expr} depend on the number of curly braces used.

% \begin{description}

% \item[1 pair] If \meta{expr} is delimited by a single pair of braces, then \meta{expr} may contain curly braces so long as the braces only appear in matched pairs and are nested no more than 5 levels deep. This is essentially the same as standard \LaTeX\ tokenization rules except for the nesting limit.

% \item[2--6 pairs] If \meta{expr} is delimited by 2--6 immediately adjacent curly braces (|!{{...}}| to |!{{{{{{...}}}}}}|), then \meta{expr} may contain any combination of braces, paired or unpaired, so long as the longest sequence of identical brace characters is shorter than the delimiters. Thus, |!{{...}}| can only contain single braces |{| and |}| (paired or unpaired); |!{{{...}}}| can contain |{|, |}|, |{{|, or |}}|; and so forth.

% \end{description}

% In both cases, anything more than five identical, immediately adjacent braces will always trigger an error. If a greater level of nesting is needed, then a function should be created within a |pycode| environment and afterward used to assemble the desired result.

%

% Curly braces used for delimiting \meta{expr} must not be immediately adjacent to braces that are part of \meta{expr}, because it would be impossible to distinguish them in the general case. If \meta{expr} begins/ends with a literal curly brace, the brace should be preceded/followed by a space or other whitespace character; leading and trailing whitespace in \meta{expr} is stripped, so this will not affect the output.

%

% Besides braces, \meta{expr} may contain any character except for literal newlines. In some cases, it may be appropriate to represent newlines in escaped form (|\n|). In other cases, it will be more appropriate to perform most calculations within a preceding |pycode| environment, and then access them via a variable or function call.

%

% Because \meta{expr} is evaluated and printed, it must be suitable for insertion in a |print()| function (or the equivalent, for languages besides Python). If string conversion as performed by |print()| is not desirable, then commands for explicit string conversion should be used.

%

% \DescribeMacro{\pyv\oarg{session}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command is used for typesetting but not executing \meta{code}. The suffix |v| is an abbreviation for |verb|.

%

% \DescribeMacro{\pyb\oarg{session}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command both executes and typesets \meta{code}. Since it is unlikely that the user would wish to typeset code and then \textbf{immediately} include any output of the code, printed content is \textbf{not} automatically included, even when the package |autoprint| option is set to true. Rather, any printed content is included at a user-designated location via the |\printpythontex| or |\stdoutpythontex| macros.

%

%

% \subsubsection{Environments}

%

% \DescribeEnv{pycode~\oarg{session}\oarg{fancyvrb~settings}}

%

% This environment encloses code that is executed but not typeset. The second optional argument \meta{fancyvrb~settings} is irrelevant since nothing is typeset, but it is accepted to maintain parallelism with the |verbatim| and |block| environments. If the |print| statement/function is used within the environment, printed content will be included automatically so long as the package |autoprint| option is set to true (the default setting).

%

%

% \DescribeEnv{pysub~\oarg{session}\oarg{fancyvrb~settings}}

%

% This environment performs variable and expression substitution, or string interpolation, on the enclosed code. Fields of the form |!{|\meta{expr}|}| in \meta{code} are replaced with the evaluated and printed output of \meta{expr}. See the description of the |\pys| command for details about substitution field syntax.

%

%

%

%

% \DescribeEnv{pyverbatim~\oarg{session}\oarg{fancyvrb~settings}}

%

% This environment encloses code that is typeset but not executed.

%

%

% \DescribeEnv{pyblock~\oarg{session}\oarg{fancyvrb~settings}}

%

% This environment encloses code that is both executed and typeset. Since it is unlikely that the user would wish to typeset code and then \textbf{immediately} print any output of the code, printed content is \textbf{not} automatically included, even when the package |autoprint| option is set to true. Rather, any printed content is included at a user-designated location via the |\printpythontex| or |\stdoutpythontex| macros.

%

%

% \subsubsection{Console command and environment families}

%

% So far, we have considered the |py| command and environment family. \pytex\ also provides families for |console| content. These emulate the behavior of a Python interactive console. In what follows, the |pycon| family is described

%

% The |pycon| family includes a |\pyconv| and |pyconverbatim| that typeset a console session pasted from an interpreter. It also includes a |\pyconc| and |pyconcode| that execute code but typeset nothing. These should be used with care, since it may often be advisable to show all executed code when working with an interactive console.

%

% The |pycon| family also includes a special environment and command.

%

% \DescribeEnv{pyconsole~\oarg{session}\oarg{fancyvrb~settings}}

%

% This environment treats its contents as a series of commands passed to an interactive Python console. Python's \href{http://docs.python.org/3/library/code.html}{\texttt{code}} module is used to intersperse the commands with their output, to emulate an interactive Python interpreter.

%

% When a multi-line command is entered (for example, a function definition), a blank line after the last line of the command may be necessary.

%

% For example,

% \begin{verbatim}

%a = 1

%b = 2

%a + b

% \end{verbatim}

% produces

% \begin{verbatim}

%>>> a = 1

%>>> b = 2

%>>> a + b

%3

% \end{verbatim}

% \DescribeMacro{\pycon\oarg{session}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command executes \meta{code} using the emulated interpreter, and brings the output back into the document, \textbf{discarding the input}. The output is typeset verbatim (since it will not in general be valid \LaTeX), with the same font used for the |pyconsole| environment.

%

% For example, |\pycon{a + b}| would create |3|.

%

% This command is primarily for use in referencing console variable values.

%

% Notice that there is \textbf{not} a command or environment for |console| content that parallels the |block| command and environment. That is, there is not a command or environment that both typesets and executes code in the console, but does not show the output. This is intentional. In most cases, if you are going to use the console, you should use it consistently, showing input and output together.

%

% \subsubsection{Default families}

%

% By default, three command and environment families are defined, with three corresponding console families.

% \begin{itemize}

% \item Python

% \begin{itemize}

% \item Base name |py|: |\py|, |\pyc|, |\pyv|, |\pyb|, |pycode|, |pyverbatim|, |pyblock|.

% \item Base name |pycon|: |\pycon|, |\pyconc|, |\pyconv|, |pyconsole|, |pyconcode|, |pyconverbatim|.

% \item Imports: None.

% \end{itemize}

% \item Python + pylab (matplotlib module)

% \begin{itemize}

% \item Base name |pylab|: |\pylab|, |\pylabc|, |\pylabv|, |\pylabb|, |pylabcode|, |pylabverbatim|, |pylabblock|.

% \item Base name |pylabcon|: |\pylabcon|, |\pylabconc|, |\pylabconv|, |pylabconsole|, |pylabconcode|, |pylabconverbatim|.

% \item Imports: matplotlib's |pylab| module, which provides access to much of matplotlib and NumPy within a single namespace. pylab content is brought in via |from pylab import *|.

% \item Additional notes: matplotlib added a \href{http://matplotlib.org/users/pgf.html}{\texttt{pgf} backend} in version 1.2. You will probably want to use this for creating most plots. However, this is not currently configured automatically because many users will want to customize font, \TeX\ engine, and other settings. Using \TeX\ to create plots also introduces a performance penalty.

% \end{itemize}

% \item Python + SymPy

% \begin{itemize}

% \item Base name |sympy|: |\sympy|, |\sympyc|, |\sympyv|, |\sympyb|, |sympycode|, |sympyverbatim|, |sympyblock|, |sympyconsole|.

% \item Base name |sympycon|: |\sympycon|, |\sympyconc|, |\sympyconv|, |sympyconsole|, |sympyconcode|, |sympyconverbatim|.

% \item Imports: SymPy via |from sympy import *|.

% \item Additional notes: By default, content brought in via |\sympy| is formatted using a context-sensitive interface to SymPy's |LatexPrinter| class, described below.

% \end{itemize}

% \end{itemize}

%

% Under Python 2.7, all non-|console| families import |absolute_import|, |division|, and |print_function| from |__future__| by default. This may be changed using the package option |pyfuture|. There is an equivalent |pyconfuture| for |console| families. Keep in mind that importing |unicode_literals| from |__future__| may break compatibility with some packages; this is why it is not imported by default. Imports from |__future__| are also possible without using the |pyfuture| option. You may use the |\pythontexcustomc| command or |pythontexcustomcode| environment (described below), or simply enter the import commands immediately at the beginning of a session.

%

%

% \subsubsection{Custom code}

%

% You may wish to customize the behavior of one or more families within a document by adding custom code to the beginning and end of each session. The custom code command and environment make this possible. While the custom code command and environment work with |console| content, most of the discussion below is geared toward the non-|console| case.

%

% If you wish to share these customizations among several documents, you can create your own document class or package containing custom code commands and environments.

%

% While custom code can be added anywhere in a document, it is probably best for organizational reasons to add it in the preamble or near the beginning of the document.

%

% Note that custom code is executed, but never typeset. Only code that is actually entered within a |block| (or |verbatim|) command or environment is ever typeset. This means that you should be careful about how you use custom code. For example, if you are documenting code, you probably want to show absolutely all code that is executed, and in that case using custom code might not be appropriate. If you are using \pytex\ to create figures or automate text, are using many sessions, and require many imports, then custom code could save some typing by centralizing the imports.

%

% Any errors or warnings due to custom code will be correctly synchronized with the document, just like normal errors and warnings. Any errors or warnings will be specifically identified as originating in custom code.