% \iffalse meta-comment

%

% Copyright (C) 2012 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>

[2012/07/17 Version~0.9beta3 PythonTeX]

%</package>

%

%<*driver>

\documentclass{ltxdoc}

\usepackage[T1]{fontenc}

\usepackage[utf8]{inputenc}

\usepackage[svgnames]{xcolor}

\usepackage[fixlr=false]{pythontex} %Need fixlr=false so can demo issue

\usepackage{enumitem}

\usepackage{hyperref}

\hypersetup{colorlinks=true,urlcolor=Green,linkcolor=blue}

\usepackage{textcomp}

\newcommand{\pytxtodo}[1]{}

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

\EnableCrossrefs

\CodelineIndex

\RecordChanges

\begin{document}

\DocInput{pythontex.dtx}

\PrintChanges

\PrintIndex

\end{document}

%</driver>

% \fi

%

% \CheckSum{1982}

%

% \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 \~}

%

%

% \changes{v0.9beta3}{2012/07/17}{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. 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. Improved installation script. Added package options: pyfuture, stderr, upquote, pyglexer, pyginline. Renamed the pygextfile option to fvextfile. Added custom code and workingdir commands. Added the console environment and associated options. Rewrote pythontex\_utils*.py, creating a new, context-aware interface to SymPy's LatexPrinter class. Content brought in via macros no longer uses labels. Rather, long defs are used, which allows line breaks. Pygments highlighting is now default for PythonTeX commands and environments}

% \changes{v0.9beta2}{2012/05/09}{Changed Python output extension to .stdout.}

% \changes{v0.9beta}{2012/04/27}{Initial public beta release.}

%

%

% \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{The \textsf{pythontex} package}

% \author{Geoffrey M.\ Poore \\ \url{[email protected]}}

% \date{\fileversion~from \filedate}

%

% \maketitle

%

% \begin{abstract}

% \pytex\ allows Python code entered within a \LaTeX\ document to be executed, and the output to be included within the original document. This provides access to the full power of Python from within \LaTeX, simplifying Python-\LaTeX\ workflow and making possible a range of document customization and automation. It also allows macro definitions that mix Python and \LaTeX\ code. In addition, \pytex\ provides syntax highlighting for many programming languages via the Pygments Python package.

%

% \pytex\ is fast and user-friendly. Python code is only executed when it has been modified. When code is executed, it automatically attempts to run in parallel. If Python code produces errors, the error message line numbers are synchronized with the \LaTeX\ document line numbers, so that it is easy to find the misbehaving code.

% \end{abstract}

%

%

% \section*{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 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.

%

%

% \section*{Package status}

% \pytex\ is currently in ``beta.'' Almost all features intended for version 0.9 are present, and almost all are fully functional (at least, so far as is known!). Testing is the main task that remains. \pytex\ has been primarily developed and tested under Windows with \TeX\ Live and Python 2.7. It has also been tested with Python 3.2 under Windows, and has been used under OS X (10.7) with MacPort's \TeX\ Live and Python 2.7.

% \vfill

%

%

% \pagebreak

% \tableofcontents

% \pagebreak

%

%

% \section{Introduction}

%

% \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.} Also, in spite of the many packages available for \LaTeX, the libraries and packages of a general-purpose programming language are lacking. For these reasons, there have been multiple attempts to allow other languages to be used within \LaTeX.

% \begin{itemize}

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

% \item \href{http://www.ctan.org/tex-archive/macros/latex/contrib/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://web.archive.org/web/20080728170129/www.imada.sdu.dk/~ehmsen/python.sty }{|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 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 line 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 likely wish 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 package Pygments to perform highlighting. Pygments can provide superior syntax highlighting, but |minted| can be slow because all code must be highlighted at each compilation. We need syntax highlighting via Pygments that saves all highlighted code, only re-highlighting when there are modifications. Ideally, we would also like a solution that overcomes some of |minted|'s longstanding issues.\footnote{http://code.google.com/p/minted/issues/list}

% \item[Context awareness]\hfill\\ It would be nice for the non-\LaTeX\ code to have at least a minimal awareness of its context in the \LaTeX\ document. For example, it would be nice to know whether code is executing within math mode.

% \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 be able 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.

% \item[Printing]\hfill\\ It would be nice for the |print| statement/function,\footnote{In Python, |print| was a statement until Python 3.0, 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 (|# $ % & ~ _ ^ \ { }|), which complicates the entry of code in a non-\LaTeX\ language 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}}

%

% This language hybridization is not terribly difficult to work around in the Sage\TeX\ and Sympy\TeX\ cases, and might even be considered a feature in Lua\TeX\ in some 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.

% \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.\footnote{Unfortunately, Sage can only run under Windows within a virtual machine at present; otherwise, an extension of Sage\TeX\ might have been tempting. Then again, for general computing, an approach that utilizes pure Python is probably superior.}

% \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! Although \pytex\ is written to support Python within \LaTeX, the implementation has been specially crafted so that other languages may be supported in the future. See Section~\ref{sec:future} for more details.

%

%

%

% \section{Installing and running}

%

% \subsection{Installing \pytex}

%

% \pytex\ requires a \TeX\ installation. \href{http://www.tug.org/texlive/}{\TeX\ Live} or \href{http://miktex.org/}{MiK\TeX} are preferred. \pytex\ requires the |Kpathsea| library, which is available in both of these distributions. The following \LaTeX\ packages, with their dependencies, are also required: |fancyvrb|, |etex|, |etoolbox|, |xstring|, |pgfopts|, |newfloat|, and |color| or |xcolor|. If you are creating and importing graphics using Python, you will also need |graphicx|. The |mdframed| package is recommended for enclosing typeset code in boxes with fancy borders and/or background colors.

%

% \pytex\ also requires a \href{http://www.python.org/}{Python} installation. Python 2.7 is recommended for the greatest compatibility with scientific tools. Python 3.1 and later will work as well. Earlier versions of Python 2 and 3 are not compatible, at least not without some modifications to the \pytex\ scripts. 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 or experiment with the \pytex\ gallery file, 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}.

%

% \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 Python scripts |pythontex2.py| and |pythontex3.py|

% \item Helper scripts |pythontex_utils2.py| and |pythontex_types2.py|, and |pythontex_utils3.py| and |pythontex_types3.py|

% \item Installation script |pythontex_install_texlive| (for \TeX\ Live)

% \item README

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

% \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|. Two versions of all of the Python scipts are supplied, one for Python 2 and one for Python 3.\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.}

%

% Until \pytex\ is submitted to CTAN, it must be installed manually. The \pytex\ files should be installed within the \TeX\ directory structure as follows.

% \begin{itemize}

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

% \begin{itemize}

% \item |pythontex.pdf|

% \item |README|

% \end{itemize}

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

% \begin{itemize}

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

% \item |pythontex_types2.py| and |pythontex_types3.py|

% \item |pythontex_utils2.py| and |pythontex_utils3.py|

% \end{itemize}

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

% \begin{itemize}

% \item |pythontex.dtx|

% \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. Run |mktexlsr| or |texhash| to do this. In order for |pythontex*.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/| directory. For \TeX\ Live under Windows, simply copy |bin/win32/runscript.exe| to |bin/win32/pythontex*.exe| to create the wrapper (replace the |*| with the appropriate version).\footnote{See the output of |runscript -h| under Windows for additional details.}

%

% A Python installation script is provided for use with \TeX\ Live. It may need to be slightly modified based on your system. It performs all steps described above, except for creating a symlink under Linux.

%

% \subsection{Compiling documents using \pytex}

%

% To compile a document that uses \pytex, you should run \LaTeX, then run |pythontex*.py| (preferably via a symlink, wrapper, or batch file, as described above), and finally run \LaTeX\ again. |pythontex*.py| requires a single command-line argument, which must be passed to it directly or via symlink/wrapper/batch file: the name of the .tex file. The filename can be passed with or without the .tex extension, but no extension is preferred.\footnote{|pythontex*.py| will be happy to work with a file that does not have the .tex extension, so long as the file cooperates with |pythontex.sty|. In this case, the file extension should \textbf{not} be passed to |pythontex*.py|, because it won't be expecting it and won't be able to determine that it is indeed an extension. |pythontex*.py| just needs to know |\textbackslash jobname|.} The file name should be wrapped 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 |pythontex2.exe|. Then we could run \pytex\ on a file \meta{file~name}.tex using the command |pythontex2.exe "|\meta{file~name}|"|. In practice, you will probably want to configure your \TeX\ editor with a shortcut key for running \pytex.

%

% A second argument specifying the file encoding may also be passed to \pytex: |pythontex*.py| \meta{file} |--encoding| \meta{encoding}. Any encoding supported by Python's \href{http://docs.python.org/library/codecs.html}{codecs} module may be used. If an encoding is not specified, \pytex\ uses UTF-8. Note that the encoding \textbf{must} be used consistently; the .tex source, the \pytex\ output, and any external code files that \pytex\ highlights should all use the same encoding. If support for characters beyond ASCII is required, then the \LaTeX\ packages |fontenc| and |inputenc| should be used.

%

% \pytex\ currently does not provide means to choose between multiple Python installations; it will use the default Python installation. Support for multiple installations is unlikely to be added, since a cross-platform solution would be required. If you need to work with multiple installations, you may wish to modify |pythontex_types*.py| to create additional command and environment families that invoke different versions of Python, based on your system.

%

% \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}

%

% \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, what \meta{none} does is described. Each option lists its default setting, if the option is not invoked when the package is loaded.

%

% \DescribeMacro{autoprint=\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. In that case, the printed content must be included using the |\printpythontex| or |\stdoutpythontex| commands, or one of their variants.

%

% 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 |inlineverb| (|v|) options.

%

% \DescribeMacro{stderr=\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{group}|.|\meta{extension}. For example, an error produced by a |py| command or environment, in the session |mysession|, using the default group (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 imported from |__future__| for all code. |none| imports nothing from |__future__|; |all| imports everything (|absolute_import|, |division|, |print_function|, and |unicode_literals|); and |default| imports everything except |unicode_literals|, since |unicode_literals| can conflict with some packages.

%

% This option has no effect under Python 3.

%

% \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:true \meta{none}=true}

%

% This option fixes extra spacing around |\left| and |\right| in math mode. See the implementation for details.

%

% \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{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|.

%

% Note that the package-level Pygments option can be overridded for individual command and environment families, using the |\setpythontexformatter| macro; the |\setpygmentsformatter| provides equivalent functionality for the Pygments commands and environments. 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{pyglexer=\marg{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{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.

%

% \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.

%

% \pytxtodo{

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

%

% \textbf{This option has not yet been implemented.} This option determines whether \pytex\ attempts to create a version of the .tex file that does not require \pytex. When invoked, it will create a file |depythontex-|\meta{jobname}|.tex|, in which all \pytex\ commands and environments have been replaced by their output and their typeset code (typeset via |fancyvrb|).}

%

%

% \subsection{Code 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 a |console| environment. 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, we describe the different commands and environments, using the |py| base name (the |py| family) as an example.

%

% 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/tex-archive/macros/latex/contrib/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 only works 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 try to expand the code). The inline commands can work properly within other macros, but only when all that they contain is also valid \LaTeX\ code (and you should stick with curly braces for delimiters in this case).

%

% \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. 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 value 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. If you need to include complex text within your document, or if you need to include verbatim text, you should use the |print| statement/function within one of the other commands or environments. The primary reason to use |\py| rather than |print| is that |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.}

%

% \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 (which is the default setting).

%

% \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 |verbatim|.

%

% \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| and |\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 |verb| 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 (which is the default setting).

%

%

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

%

% This environment encloses code that is typeset but not executed. The suffix |verb| is an abbreviation for |verbatim|.

%

%

% \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.

%

%

% \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 |code| module is used to intersperse the commands with their output, to emulate an interactive Python interpreter. Unlike the other environments, |pyconsole| has no inline equivalent. Currently, non-ASCII characters are not supported in |console| environments under Python 2.\pytxtodo{edit?}

%

% 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.

%

%

% \subsubsection{Default families, \pytex\ utilities, and custom code}

%

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

% \begin{itemize}

% \item Python

% \begin{itemize}

% \item Base name |py|: |\py|, |\pyc|, |\pyv|, |\pyb|, |pycode|, |pyverb|, |pyblock|, |pyconsole|

% \item Imports: None.

% \end{itemize}

% \item Python + pylab (matplotlib module)

% \begin{itemize}

% \item Base name |pylab|: |\pylab|, |\pylabc|, |\pylabv|, |\pylabb|, |pylabcode|, |pylabverb|, |pylabblock|, |pylabconsole|

% \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 *|.

% \end{itemize}

% \item Python + SymPy

% \begin{itemize}

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

% \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 families import |absolute_import|, |division|, and |print_function| from |__future__| by default. This may be changed using the package option |pyfuture|. 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 |\setpythontexcustomcode| command (described below), or simply enter the import code immediately at the beginning of a session.

% All families import |pythontex_utils*.py|, and create an instance of the \pytex\ utilities class called |pytex|. This provides various utilities for interfacing with \LaTeX. In particular, it provides an interface for determining how Python objects are converted into strings in commands such as |\py|. The |pytex.set_formatter(|\meta{formatter}|)| method determines the conversion. Two formatters are provided:

% \begin{itemize}

% \item |'str'| converts Python objects to a string, using the |str()| function under Python 3 and the |unicode()| function under Python 2. (The use of |unicode()| under Python 2 should not cause problems, even if you have not imported |unicode_literals| and are not using unicode strings. All encoding issues should be taken care of automatically by the utilities class.)

% \item |'sympy_latex'| uses SymPy's |LatexPrinter| class to return context-sensitive \LaTeX\ representations of SymPy objects. Separate |LatexPrinter| settings may be created for the following contexts: |'display'| (displaystyle math), |'text'| (textstyle math), |'script'| (superscripts and subscripts), and |'scriptscript'| (superscripts and subscripts, of superscripts and subscripts). Settings are created via |pytex.set_sympy_latex(|\meta{context}|,|\meta{settings}|)|. For example, |pytex.set_sympy_latex('display', mul_symbol='times')| sets multiplication to use a multiplication symbol $\times$, but only when math is in displaystyle.\footnote{Internally, the |'sympy\_latex'| formatter uses the |\textbackslash mathchoice| macro to return multiple representations of a SymPy object, if needed by the current settings. Then |\textbackslash mathchoice| typesets the correct representation, based on context.} See the \href{http://docs.sympy.org/dev/modules/printing.html}{SymPy documentation} for a list of possible settings for the |LatexPrinter| class.

%

% By default, |'sympy_latex'| only treats matrices differently based on context. Matrices in displaystyle are typeset using |pmatrix|, while those in all other styles are typeset via |smallmatrix| with parentheses.

% \end{itemize}

%

% The \pytex\ utilities formatter may also be set to a custom function that returns strings, simply by reassigning the |pytex.formatter()| method. For example, define a formatter function |my_func()|, and then |pytex.formatter=my_func|.

%

% The context-sensitive interface to SymPy's |LatexPrinter| is always available via |pytex.sympy_latex()|. If you wish to use it outside the |sympy| command and environment family, you must initialize it before use via the command |pytex.init_sympy_latex()|.

%

% \DescribeMacro{\setpythontexcustomcode\marg{family}\marg{quoted~list}}

%

% \pytxtodo{Look into options for setting custom code for an entire language at a time. It would be possible to have the family be optional, but while that would be good as long as only Python is supported, it would quickly start causing problems as soon as any additional languages are added. Basically, there needs to be a way to set custom code for all sessions sharing a language. Perhaps some kind of keyword system, like language:python being used for family.}

% This macro allows custom code to be added to all sessions within a command and environment family. \meta{quoted~list} should be a comma-separated list of lines of code, each line enclosed in quotes (single or double). For example, |\setpythontexcustomcode{py}{'a=1', 'b=2'}| would create the variables |a| and |b| within all sessions of the |py| family, by invisibly adding the following lines at the beginning of each session:

% \begin{verbatim}

% a=1

% b=2

% \end{verbatim}

% Note that custom code is executed, but never typeset. Only code that is actually entered within a |block| (or |verb|) command or environment is every 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.

%

% \meta{quoted~list} may contain imports from |__future__|. It is best if these are the first elements in the list, since future imports are only possible at the very beginning of a Python script. This is not strictly required, however. When \pytex\ writes the individual scripts that are executed, it checks \meta{quoted~list} for future imports, and automatically moves them to the appropriate location.

%

% \meta{quoted~list} may \textbf{not} contain \LaTeX\ macros. \meta{quoted~list} is interpreted as verbatim content, since in general the custom code will not be valid \LaTeX.

%

%

% \subsubsection{Formatting of typeset code}

%

% \DescribeMacro{\setpythontexfv\oarg{family}\marg{fancyvrb~settings}}

%

% This command sets the |fancyvrb| settings for all command and environment families. Alternatively, if an optional argument \meta{family} is supplied, the settings only apply to the family with that base name. The general command will override family-specific settings.

%

% Each time the command is used, it completely overwrites the previous settings. If you only need to change the settings for a few pieces of code, you should use the second optional argument in |block| and |verb| environments.

%

% Note that |\setpythontexfv| and |\setpygmentsfv| are equivalent when they are used without an optional argument; in that case, either may be used to determine the document-wide |fancyvrb| settings, because both use the same underlying macro.

%

%

% \DescribeMacro{\setpythontexformatter\marg{family}\marg{formatter}}

%

% This should generally not be needed. It allows the formatter used by \meta{family} to be set. Valid options for \meta{formatter} are |auto|, |fancyvrb|, and |pygments|. Using |auto| means that the formatter will be determined based on the package |pygments| option. Using either of the other two options will force \meta{family} to use that formatter, regardless of the package-level options. By default, families use the |auto| formatter.

%

%

% \DescribeMacro{\setpythontexpyglexer\marg{family}\marg{pygments~lexer}}

%

% This allows the Pygments lexer to be set for \meta{family}. \meta{pygments~lexer} should should use a form of the lexer name that does not involve any special characters. For example, you would want to use the lexer name |csharp| rather than |C#|. This will be a consideration primarily when using the Pygments commands and environments to typeset code of an arbitrary language.

%

% \DescribeMacro{\setpythontexpygopt\marg{family}\marg{pygments~options}}

%

% This allows the Pygments options for \meta{family} to be redefined. Note that any previous options are overwritten. The same Pygments options may be passed here as are available via the package |pygopt| option. Note that for each available option, individual family settings will be overridden by the package-level |pygopt| settings, if any are given.

%

%

% \subsubsection{Access to printed content (stdout) and error messages (stderr)}

%

% The macros that allow access to printed content and any additional content written to stdout are provided in two identical forms: one based off of the word |print| and one based off of |stdout|. Macro choice depends on user preference. The |stdout| form provides parallelism with the macros that provide accesss to |stderr|.

%

% \DescribeMacro{\printpythontex\oarg{verbatim~options}\oarg{fancyvrb~options}}

%

% \DescribeMacro{\stdoutpythontex\oarg{verbatim~options}\oarg{fancyvrb~options}}

%

% Unless the package option |autoprint| is true, printed content from |code| commands and environments will not be automatically included. Even when the |autoprint| option is turned on, |block| commands and environments do not automatically include printed content, since we will generally not want printed content immediately after typeset code. This macro brings in any printed content from the \textbf{last} command or environment. It is reset after each command/environment, so its scope for accessing particular printed content is very limited. It will return an error if no printed content exists.

%

% By default, printed content is brought in raw---it is pulled in directly from the external file in which it is saved and interpreted 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 consider the |verb| and |inlineverb| (also accesible as |v|) options, which bring in code verbatim. If code is brought in verbatim, then \meta{fancyvrb~options} are applied to it.

%

%

% \DescribeMacro{\saveprintpythontex\marg{name}}

%

% \DescribeMacro{\savestdoutpythontex\marg{name}}

%

% \DescribeMacro{\useprintpythontex\oarg{verbatim~options}\oarg{fancyvrb~options}\marg{name}}

%

% \DescribeMacro{\usestdoutpythontex\oarg{verbatim~options}\oarg{fancyvrb~options}\marg{name}}

%

% We may wish to be able to access the printed content from a command or environment at any point after the code that prints it, not just before any additional commands or environments are used. In that case, we may save access to the content under \meta{name}, and access it later via |\useprintpythontex|\marg{name}. \meta{verbatim~options} must be either |verb| or |inlineverb| (also accessible as |v|), specifying how content is brought in verbatim. If content is brought in verbatim, then \meta{fancyvrb~options} are applied.

%

% \DescribeMacro{\stderrpythontex\oarg{verbatim~options}\oarg{fancyvrb~options}}

%

% This brings in the stderr produced by the last command or environment. It is intended for typesetting incorrect code next to the errors that it produces. By default, stderr is brought in verbatim. \meta{verbatim~options} may be set to |verb| (default), |inlineverb| (or |v|), and |raw|. In general, bringing in stderr |raw| should be avoided, since stderr will typically include special characters that will make \TeX\ unhappy.

%

% The line number given in the |stderr| message will correctly align with the line numbering of the typeset code. Note that this only applies to |code| and |block| environments. Inline commands do not have line numbers, and as a result, they \textbf{do not} produce stderr content. \pytxtodo{Maybe allow stderr for inline, with line number set to 1?}

%

% By default, the file name given in the message will be in the form

% \begin{quote}

% \meta{family~name}|_|\meta{session}|_|\meta{group}|.|\meta{extension}

% \end{quote}

% For example, an error produced by a |\py| command or environment, in the session |mysession|, using the default group (that is, the default |\restartpythontexsession| treatment), would be reported in |py_mysession_default.py|. The package option |stderrfilename| may be used to change the reported name to the following forms: |mysession.py|, |<file>|, |<script>|.

%

%

% \DescribeMacro{\savestderrpythontex\marg{name}}

%

% \DescribeMacro{\usestderrpythontex\oarg{verbatim~options}\oarg{fancyvrb~options}\marg{name}}

%

%

% Content written to |stderr| may be saved and accessed anywhere later in the document, just as |stdout| content may be. These commands should be used with care. Using Python-generated content at multiple locations within a document may often be appropriate. But an error message will usually be most meaningful in its context, next to the code that produced it.

%

%

% \subsection{Pygments commands and environments}

%

% Although \pytex's goal is primarily the execution and typesetting of Python code from within \LaTeX, it also provides access to syntax highlighting for any language supported by Pygments.

%

% \DescribeMacro{\pygment\marg{lexer}\meta{opening~delim}\meta{code}\meta{closing~delim}}

%

% This command typesets \meta{code} in a suitable form for inline use within a paragraph, using the specified Pygments \meta{lexer}. Internally, it uses the same macros as the \pytex\ inline commands. \meta{opening~delim} and \meta{closing~delim} may be a pair of any characters except for the space character, or a matched set of curly braces |{}|.

%

% As with the inline commands for code typesetting and execution, there is not an optional argument for |fancyvrb| settings, since almost all of them are not relevant for inline usage, and the few that might be should probably be used document-wide if at all.

%

%

% \DescribeEnv{pygments~\oarg{fancyvrb~settings}\marg{lexer}}

%

% This environment typesets its contents using the specified Pygments \meta{lexer} and applying the \meta{fancyvrb~settings}.

%

%

% \DescribeMacro{\inputpygments\oarg{fancyvrb~settings}\marg{lexer}\marg{external~file}}

%

% This command brings in the contents of \meta{external~file}, highlights it using \meta{lexer}, and typesets it using \meta{fancyvrb~settings}.

%

%

% \DescribeMacro{\setpygmentsfv\oarg{lexer}\marg{fancyvrb~settings}}

%

% This command sets the \meta{fancyvrb~settings} for \meta{lexer}. If no \meta{lexer} is supplied, then it sets document-wide \meta{fancyvrb~settings}. In that case, it is equivalent to |\setpythontexfv|\marg{fancyvrb~settings}.

%

%

% \DescribeMacro{\setpygmentspygopt\marg{lexer}\marg{pygments~options}}

%

% This sets \meta{lexer} to use \meta{pygments~options}. If there is any overlap between \meta{pygments~options} and the package-level |pygopt|, the package-level options override the lexer-specific options.

%

%

% \DescribeMacro{\setpygmentsformatter\marg{formatter}}

%

% This usually should not be needed. It allows the formatter for Pygments content to be set. Valid options for \meta{formatter} are |auto|, |fancyvrb|, and |pygments|. Using |auto| means that the formatter will be determined based on the package |pygments| option. Using either of the other two options will force Pygments content to use that formatter, regardless of the package-level options. The |auto| formatter is used by default.

%

%

% \subsection{General code typesetting}

%

% \subsubsection{Listings float}

%

% \DescribeEnv{listing}

%

% \pytex\ will create a float environment |listing| for code listings, unless an environment with that name already exists. The |listing| environment is created using the |newfloat| package. Customization is possible through |newfloat|'s |\SetupFloatingEnvironment| command.

%

% \DescribeMacro{\setpythontexlistingenv\marg{alternate~listing~environment~name}}

%

% In the event that an environment named |listing| already exists for some other purpose, \pytex\ will not override it. Instead, you may set an alternate name for \pytex's |listing| environment, via |\setpythontexlistingenv|.

%

%

% \subsubsection{Background colors}

%

% \pytex\ uses |fancyvrb| internally to typeset all code. Even code that is highlighted with Pygments is typeset afterwards with |fancyvrb|. Using |fancyvrb|, it is possible to set background colors for individual lines of code, but not for entire blocks of code, using |\FancyVerbFormatLine| (you may also wish to consider the |formatcom| option). For example, the following command puts a green background behind all the characters in each line of code:

% \begin{verbatim}

% \renewcommand{\FancyVerbFormatLine}[1]{\colorbox{green}{#1}}

% \end{verbatim}

%

% If you need a completely solid colored background for an environment, or a highly customizable background, you should consider the |mdframed| package. Wrapping \pytex\ environments with |mdframed| frames works quite well. You can even automatically add a particular style of frame to all instances of an environment using the command

% \begin{quote}

% |\surroundwithmdframed|\oarg{frame~options}\marg{environment}

% \end{quote}

% Or you could consider using |etoolbox| to do the same thing with |mdframed| or another framing package of your choice, via |etoolbox|'s |\BeforeBeginEnvironment| and |\AfterEndEnvironment| macros.

%

%

% \subsubsection{Referencing code by line number}

%

% It is possible to reference individual lines of code, by line number. If code is typeset using pure |fancyvrb|, then \LaTeX\ labels can be included within comments. The labels will only operate correctly (that is, be treated as \LaTeX\ rather than verbatim content) if |fancyvrb|'s |commandchars| option is used. For example, |commandchars=\\\{\}| makes the backslash and the curly braces function normally \textbf{within} |fancyvrb| environments, allowing \LaTeX\ macros to work, including label definitions. Once a label is defined within a code comment, then referencing it will return the code line number.

%

% The disadvantage of the pure |fancyvrb| approach is that by making the backslash and curly braces command characters, we can produce conflicts if the code we are typesetting contains these characters for non-\LaTeX\ purposes. In such a case, it might be possible to make alternate characters command characters, but it would probably be better to use Pygments.

%

% If code is typeset using Pygments (which also ties into |fancyvrb|), then this problem is avoided. The Pygments option |texcomments=true| has Pygments look for \LaTeX\ code only within comments. Possible command character conflicts with the language being typeset are thus eliminated.

%

% Note that when references are created within comments, the references themselves will be invisible within the final document but the comment character(s) and any other text within comments will still be visible. For example, the following

% \begin{quote}

% |abc = 123 # An important line of code!\ref{lst:important}|

% \end{quote}

% would appear as

% \begin{quote}

% |abc = 123 # An important line of code!|

% \end{quote}

% If a comment only contains the |\ref| command, then only the comment character |#| would actually be visible in the typeset code.

%

% \subsubsection{Beamer compatibility}

%

% \pytex\ is compatible with \href{http://www.ctan.org/pkg/beamer}{Beamer}. Since \pytex\ typesets code as verbatim content, Beamer's |fragile| option must be used for any frame that contains typeset code. Beamer's |fragile| option involves saving frame contents to an external file and bringing them back in. This use of an external file breaks \pytex's error line number synchronization. A fix is expected in a future version of \pytex.

%

%

% \subsection{Advanced \pytex\ usage}

%

% \DescribeMacro{\restartpythontexsession\marg{counter~value(s)}}

%

% This macro determines when or if sessions are restarted (or ``subdivided''). Whenever \meta{counter~value(s)} change, the session will be restarted.

%

% By default, each session corresponds to a single code file that is executed. But sometimes it might be conventient if the code from each chapter or section or subsection were to run within its own file, as its own session. For example, we might want each chapter to execute separately, so that changing code within one chapter won't require that all the code from all the other chapters be executed. But we might not want to have to go to the bother and extra typing of defining a new session for every chapter (like |\py[ch1]{|\meta{code}|}|). To do that, we could use |\restartpythontexsession{\thechapter}|. This would cause all sessions to restart whenever the chapter counter changes. If we wanted sessions to restart at each section within a chapter, we would use |\restartpythontexsession{\thechapter|\meta{delim}|\thesection}|. \meta{delim} is needed to separate the counter values so that they are not ambiguous (for example, we need to distinguish chapter 11-1 from chapter 1-11). \meta{delim} should be a hyphen or an underscore; it must be a character that is valid in file names.

%

% Note that \textbf{counter values}, and not counters themselves, must be supplied as the argument. Also note that the command applies to \textbf{all} sessions. If it did not, then we would have to keep track of which sessions restarted when, and the lack of uniformity could easily result in errors on the part of the user.

%

% Keep in mind that when a session is restarted, all continuity is lost. It is best not to restart sessions if you need continuity. If you must restart a session, but also need to keep some data, you could save the data before restarting the session and then load the saved data after the restart. This approach should be used with \textbf{extreme} caution, since it can result in unanticipated errors due to sessions not staying synchronized.\footnote{For example, suppose sessions are restarted based on chapter. |session-ch1| saves a data file, and |session-ch2| loads it and uses it. You write the code, and run \pytex. Then you realize that |session-ch1| needs to be modified and make some changes. The next time \pytex\ runs, it will only execute |session-ch1|, since it detects no code changes in |session-ch2|. This means that |session-ch2| is not updated, at least to the extent that it depends on the data from |session-ch1|. Again, saving and loading data between restarted sessions, or just between sessions in general, can produce unexpected behavior and should be avoided.}

%

% This command can only be used in the preamble.

%

% \DescribeMacro{\setpythontexoutputdir\marg{output~directory}}

%

% By default, \pytex\ saves all automatically generated content in a directory called |pythontex-files-|\meta{sanitized jobname}, where \meta{sanitized jobname} is just |\jobname| with any space characters or asterisks replaced with hyphens. This directory will be created by |pythontex*.py|. If we wish to specify another directory (for example, if |\jobname| is long and complex, and there is no danger of two files trying to use the same directory), then we can use the |\setpythontexoutputdir| macro to redefine the output directory.

%

% \DescribeMacro{\setpythontexworkingdir\marg{working~directory}}

%

% The \pytex\ working directory is the current working directory for \pytex\ scripts. This is the directory in which any open or save operations will take place, unless a path is explicitly specified. By default, the working directory is the same as the output directory. For example, if you are writing |my_file.tex| and save a matplotlib figure with |savefig('my_figure.pdf')|, then |my_figure.pdf| will be created in the output directory |pythontex-files-my_file|. But maybe you have a directory called |plots| in your document root directory. In that case, you could leave the working directory unchanged, and simply specify the relative path to |plots|. Or you could set the working directory to |plots| using |\setpythontexworkingdir{plots}|, so that all content would automatically be saved there.

%

% If you want your working directory to be the document root directory, you should use a period (|.|) for \meta{working~directory}: |\setpythontexworkingdir{.}|.

%

%

% \section{Questions and answers}

%

% \begin{description}[style=unboxed]

% \item[Will you add a plot command that automates the saving and inclusion of plots or other graphics created by matplotlib or similar packages?] There are no plans to add a plot command like |\pyplot|. A plot command would add a little convenience, but at the expense of power. Automated saving would give the plot an automatically generated name, making the file harder to find. Automated inclusion would involve collecting a lot of settings and then passing them on to |\includegraphics|, perhaps within |figure| and |center| environments. It is much simpler for the user to choose a meaningful name and then include the file in the desired manner.

% \end{description}

%

%

%

% \section{Troubleshooting}

% \label{sec:troubleshooting}

%

% A more extensive troubleshooting section will be added in the future.\pytxtodo{Extend section}

%

% If a \pytex\ document will not compile, you may want to delete the directory in which \pytex\ content is stored and try compiling from scratch. It is possible for \pytex\ to become stuck in an unrecoverable loop. Suppose you tell Python to print some \LaTeX\ code back to your \LaTeX\ document, but make a fatal \LaTeX\ syntax error in the printed content. This syntax error prevents \LaTeX\ from compiling. Now suppose you realize what happened and correct the syntax error. The problem is that the corrected code cannot be executed until \LaTeX\ correctly compiles and saves the code externally, but \LaTeX\ cannot compile until the corrected code has already been executed. The simplest solution in such cases is to correct the code, delete all files in the \pytex\ directory, compile the \LaTeX\ document, and then run \pytex\ from scratch.

%

% Dollar signs \$ may appear as \textsterling\ in italic code comments typeset by Pygments. This is a font-related issue. One fix is to |\usepackage[T1]{fontenc}|.

%

%

% \section{The future of \pytex}

% \label{sec:future}

%

% This section consists of a To Do list for future development. The To Do list is primarily for the benefit of the author, but also gives users a sense of what changes are in progress or under consideration.

%

% \pytxtodo{

% This section consists of a To Do list and a roadmap for future development. The To Do list is primarily for the benefit of the author, but also gives users a sense of what changes are in progress. The roadmap provides a projected direction for future development.}

%

% \subsection{To Do}

%

% \subsubsection{Modifications to make}

% \begin{itemize}

% \item Fix error line number synchronization with Beamer. The |filehook| and |currfile| packages may be useful in this. One approach may be to patch the macros associated with |\beamer@doframeinput| in |beamerbaseframe.sty|.

% \item User-defined custom commands and environments for general Pygments typesetting.

% \item Testing under Linux.

% \item Additional documentation for the Python code (Sphinx?).

% \item Establish a testing framework.

% \item Keep track of any Pygments errors for future runs, so we know what to run again? How easy is it to get Pygments errors? There don't seem to have been any in any of the testing so far.

% \item It might nice to include some methods in the \pytex\ utilities for formatting numbers (especially with SymPy and Pylab). Also, it would be nice to have shortcuts for \href{https://github.com/nschloe/matplotlib2tikz}{Matplotlib2tikz} integration.

% \end{itemize}

%

% \subsubsection{Modifications to consider}

% \begin{itemize}

% \item Allow \LaTeX\ in code, and expand \LaTeX\ macros before passing code to |pythontex.py|. Maybe create an additional set of inline commands with additional |exp| suffix for |expanded|? This can already be done by creating a macro that contains a \pytex\ macro, though.

% \item Built-in support for background colors for blocks and verbatim, via |mdframed|?

% \item Consider support for executing other languages. It might be nice to support a few additional languages at a basic level by version 1.0. Languages currently under consideration: Perl, MATLAB, Mathematica, Lua, Sage, R. But note that there are ways to interface with many or perhaps all of these from within Python. Also, consider general command line-access, similar to |\write18|. The |bashful| package can do some nice command-line things. But it would probably require some real finesse to get that kind of |bash| access cross-platform. Probably could figure out a way to access Cygwin's bash or GnuWin32 or MSYS.

% \item Support for executing external scripts, not just internal code? It would be nice to be able to typeset an external file, as well as execute it by passing command-line arguments and then pull in its output.

% \item Is there any reason that saved printed content should be allowed to be brought in before the code that caused it has been typeset? Are there any cases in which the output should be typeset \textbf{before} the code that created it? That would require some type of external file for bringing in saved definitions. Maybe there should be a |\typesetpythontex| command that parallels |\printpythontex|?

% \item Consider some type of primitive line-breaking algorithm for use with Pygments. Could break at closest space, indent 8 spaces further than parent line (assuming 4-space indents; could auto-detect the correct size), and use \LaTeX\ counter commands to keep the line numbering from being incorrectly incremented. Such an approach might not be hard and might have some real promise.

% \item Consider allowing names of files into which scripts are saved to be specified. This could allow \pytex\ to be used for literate programming, general code documentation, etc. Also, it could allow writing a document that describes code and also produces the code files, for user modification (see the |bashful| package for the general idea). Doing something like this would probably require a new, slightly modified interface to preexisting macros.

% \item Consider methods of taking \pytex\ documents and removing their dependence on |pythontex.sty|. Something that could convert a \pytex\ document into a document that would be more readily acceptable by a publisher. Sage\TeX\ has something like this.

% \end{itemize}

%

%

% \pytxtodo{

% \subsection{Roadmap}

% \label{sec:future:roadmap}

%

% Under development. For now, see the To Do list.

% }

%

%

%

% \section*{Acknowledgements}

%

% Thanks to Øystein Bjørndal for suggestions and for help with OS X compatibility.

%

%

%

% \PrintChanges

%

% \StopEventually{\PrintIndex}

%

% \section{Implementation}

%

% \iffalse

%<*package>

% \fi

%

% This section describes the technical implementation of the package. Unless you wish to understand all the fine details or need to use the package in extremely sophisticated ways, you should not need to read it.

%

% The prefix |pytx@| is used for all \pytex\ macros, to prevent conflict with other packages. Macros that simply store text or a value for later retrieval are given names completely in lower case. For example, |\pytx@packagename| stores the name of the package, |PythonTeX|. Macros that actually perform some operation in contrast to simple storage are named using CamelCase, with the first letter after the prefix being capitalized. For example, |\pytx@CheckCounter| checks to see if a counter exists, and if not, creates it. Thus, macros are divided into two categories based on their function, and named accordingly.

%

% \subsection{Package opening}

% We begin according to custom by specifying the version of \LaTeX\ that we require and stating the package that we are providing. We also store the name of the package in a macro for later use in warnings and error messages.

% \begin{macrocode}

\NeedsTeXFormat{LaTeX2e}[1999/12/01]

\ProvidesPackage{pythontex}[2012/07/17 v0.9beta3]

\newcommand{\pytx@packagename}{PythonTeX}

% \end{macrocode}

%

% \subsection{Required packages}

% A number of packages are required. |fancyvrb| is used to typeset all code that is not inline, and its internals are used to format inline code as well. |etex| provides extra registers, to avoid the (probably unlikely) possibility that the many counters required by \pytex\ will exhaust the supply. |etoolbox| is used for string comparison and boolean flags. |xstring| provides the |\tokenize| macro. |pgfopts| is used to process package options, via the |pgfkeys| package. |newfloat| allows the creation of a floating environment for code listings. |xcolor| or |color| is needed for syntax highlighting with Pygments.

% \begin{macrocode}

\RequirePackage{fancyvrb}

\RequirePackage{etex}

\RequirePackage{etoolbox}

\RequirePackage{xstring}

\RequirePackage{pgfopts}

\RequirePackage{newfloat}

\AtBeginDocument{\@ifpackageloaded{color}{}{\RequirePackage{xcolor}}}

% \end{macrocode}

%

% \subsection{Package options}

% We now proceed to define package options, using the |pgfopts| package that provides a package-level interface to |pgfkeys|. All keys for package-level options are placed in the key tree under the path |/PYTX/pkgopt/|, to prevent conflicts with any other packages that may be using |pgfkeys|.

%

% \subsubsection{Autoprint}

% \begin{macro}{pytx@opt@autoprint}

% The |autoprint| option determines whether content printed within a code command or environment is automatically included at the location of the command or environment. If the option is not used, |autoprint| is turned on by default. If the option is used, but without a setting (|\usepackage[autoprint]{pythontex}|), it is true by default. We use the key handler \meta{key}|/.is choice| to ensure that only true/false values are allowed. The code for the true branch is redundant, but is included for symmetry.

% \begin{macrocode}

\newbool{pytx@opt@autoprint}

\booltrue{pytx@opt@autoprint}

\pgfkeys{/PYTX/pkgopt/autoprint/.default=true}

\pgfkeys{/PYTX/pkgopt/autoprint/.is choice}

\pgfkeys{/PYTX/pkgopt/autoprint/true/.code=\booltrue{pytx@opt@autoprint}}

\pgfkeys{/PYTX/pkgopt/autoprint/false/.code=\boolfalse{pytx@opt@autoprint}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{stderr}

% \begin{macro}{pytx@opt@stderr}

% The |stderr| option determines whether stderr is saved and may be included in the document via |\stderrpythontex|.

% \begin{macrocode}

\newbool{pytx@opt@stderr}

\pgfkeys{/PYTX/pkgopt/stderr/.default=true}

\pgfkeys{/PYTX/pkgopt/stderr/.is choice}

\pgfkeys{/PYTX/pkgopt/stderr/true/.code=\booltrue{pytx@opt@stderr}}

\pgfkeys{/PYTX/pkgopt/stderr/false/.code=\boolfalse{pytx@opt@stderr}}

% \end{macrocode}

% \end{macro}

%

%

% \subsubsection{stderrfilename}

% \begin{macro}{\pytx@opt@stderrfilename}

% This option determines how the file name appears in |stderr|.

% \begin{macrocode}

\def\pytx@opt@stderrfilename{full}

\pgfkeys{/PYTX/pkgopt/stderrfilename/.default=full}

\pgfkeys{/PYTX/pkgopt/stderrfilename/.is choice}

\pgfkeys{/PYTX/pkgopt/stderrfilename/full/.code=\def\pytx@opt@stderrfilename{full}}

\pgfkeys{/PYTX/pkgopt/stderrfilename/session/.code=\def\pytx@opt@stderrfilename{session}}

\pgfkeys{/PYTX/pkgopt/stderrfilename/genericfile/.code=%

\def\pytx@opt@stderrfilename{genericfile}}

\pgfkeys{/PYTX/pkgopt/stderrfilename/genericscript/.code=%

\def\pytx@opt@stderrfilename{genericscript}}

% \end{macrocode}

% \end{macro}

%

%

% \subsubsection{Python's \texttt{\_\_future\_\_} module}

% \begin{macro}{\pytx@opt@pyfuture}

% The |pyfuture| option determines what is imported from the |__future__| module under Python 2. It has no effect under Python 3.

% \begin{macrocode}

\def\pytx@opt@pyfuture{default}

\pgfkeys{/PYTX/pkgopt/pyfuture/.is choice}

\pgfkeys{/PYTX/pkgopt/pyfuture/default/.code=\def\pytx@opt@pyfuture{default}}

\pgfkeys{/PYTX/pkgopt/pyfuture/all/.code=\def\pytx@opt@pyfuture{all}}

\pgfkeys{/PYTX/pkgopt/pyfuture/none/.code=\def\pytx@opt@pyfuture{none}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{Upquote}

% \begin{macro}{pytx@opt@upquote}

% The |upquote| option determines whether the |upquote| package is loaded. It makes quotes within verbatim contexts \expandafter|\textquotesingle| rather than |'|. This is important, because it means that code may be copied directly from the compiled PDF and executed without any errors due to quotes |'| being copied as acute accents \texttt{\'}.

% \begin{macrocode}

\newbool{pytx@opt@upquote}

\booltrue{pytx@opt@upquote}

\pgfkeys{/PYTX/pkgopt/upquote/.default=true}

\pgfkeys{/PYTX/pkgopt/upquote/.is choice}

\pgfkeys{/PYTX/pkgopt/upquote/true/.code=\booltrue{pytx@opt@upquote}}

\pgfkeys{/PYTX/pkgopt/upquote/false/.code=\boolfalse{pytx@opt@upquote}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{Fix math spacing}

% \begin{macro}{pytx@opt@fixlr}

% The |fixlr| option fixes extra, undesirable spacing in mathematical formulae introduced by the commands |\left| and |\right|. For example, compare the results of |$\sin(x)$| and |$\sin\left(x\right)$|: $\sin(x)$ and $\sin\left(x\right)$. The |fixlr| option fixes this, using a solution proposed by Mateus Ara\'{u}jo, Philipp Stephani, and Heiko Oberdiek.\footnote{ \url{http://tex.stackexchange.com/questions/2607/spacing-around-left-and-right}}

% \begin{macrocode}

\newbool{pytx@opt@fixlr}

\booltrue{pytx@opt@fixlr}

\pgfkeys{/PYTX/pkgopt/fixlr/.default=true}

\pgfkeys{/PYTX/pkgopt/fixlr/.is choice}

\pgfkeys{/PYTX/pkgopt/fixlr/true/.code=\booltrue{pytx@opt@fixlr}}

\pgfkeys{/PYTX/pkgopt/fixlr/false/.code=\boolfalse{pytx@opt@fixlr}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{Keep temporary files}

% \begin{macro}{\pytx@opt@keeptemps}

% By default, \pytex\ tries to be very tidy. It creates many temporary files, but deletes all that are not required to compile the document, keeping the overall file count very low. At times, particularly during debugging, it may be useful to keep these temporary files, so that code, errors, and output may be examined more directly. The |keeptemps| option makes this possible.

% \begin{macrocode}

\def\pytx@opt@keeptemps{none}

\pgfkeys{/PYTX/pkgopt/keeptemps/.default=all}

\pgfkeys{/PYTX/pkgopt/keeptemps/.is choice}

\pgfkeys{/PYTX/pkgopt/keeptemps/all/.code=\def\pytx@opt@keeptemps{all}}

\pgfkeys{/PYTX/pkgopt/keeptemps/code/.code=\def\pytx@opt@keeptemps{code}}

\pgfkeys{/PYTX/pkgopt/keeptemps/none/.code=\def\pytx@opt@keeptemps{none}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{Pygments}

% \begin{macro}{pytx@opt@pygments}

% By default, \pytex\ uses |fancyvrb| to typeset code. This provides nice formatting and font options, but no syntax highlighting. The |pygments| option determines whether Pygments or |fancyvrb| is used to typeset code. Pygments is a generic syntax highlighter written in Python. Since \pytex\ sends code to Python anyway, having Pygments process the code is only a small additional step and in many cases takes little if any extra time to execute.\footnote{Pygments code highlighting is executed as a separate process by |pythontex*.py|, so it runs in parallel on a multicore system. Pygments usage is optimized by saving highlighted code and only reprocessing it when changed.}

%

% Command and environment families obey the |pygments| option by default, but they may be set to override it and always use Pygments or always use |fancyvrb|, via |\setpythontexformatter| and |\setpygmentsformatter|.

%

% Pygments has been used previously to highlight code for \LaTeX, most notably in the |minted| package.

% \begin{macrocode}

\newbool{pytx@opt@pygments}

\booltrue{pytx@opt@pygments}

\pgfkeys{/PYTX/pkgopt/pygments/.default=true}

\pgfkeys{/PYTX/pkgopt/pygments/.is choice}

\pgfkeys{/PYTX/pkgopt/pygments/true/.code=\booltrue{pytx@opt@pygments}}

\pgfkeys{/PYTX/pkgopt/pygments/false/.code=\boolfalse{pytx@opt@pygments}}

% \end{macrocode}

% \end{macro}

%

%

% \begin{macro}{pytx@pyglexer}

% For completeness, we need a way to set the Pygments lexer for all content. Note that in general, resetting the lexers for all content is not desirable.

% \begin{macrocode}

\def\pytx@pyglexer{}

\pgfkeys{/PYTX/pkgopt/pyglexer/.code=\def\pytx@pyglexer{#1}}

% \end{macrocode}

% \end{macro}

%

%

% \begin{macro}{\pytx@pygopt}

% We also need a way to specify Pygments options at the package level. This is accomplished via the |pygopt| option: |pygopt|=\{\meta{options}\}. Note that the options must be enclosed in curly braces since they contain equals signs and thus must be distinguishable from package options.

%

% Currently, three options may be passed in this manner: |style=|\meta{style}, 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 a boolean argument; if an argument is not supplied, true is assumed. As an example of |pygopt| usage, consider the following:

% \begin{verbatim}

% pygopt={style=colorful, texcomments=True, mathescape=False}

% \end{verbatim}

% The usage of capitalized |True| and |False| is more pythonic, but is not strictly require.

%

% While the package-level |pygments| option may be overridden by individual commands and environments (though it is not by default), the package-level Pygments options cannot be overridden by individual commands and environments.

% \begin{macrocode}

\def\pytx@pygopt{}

\pgfkeys{/PYTX/pkgopt/pygopt/.code=\def\pytx@pygopt{#1}}

% \end{macrocode}

% \end{macro}

%

%

% \begin{macro}{pytx@opt@pyginline}

% This option governs whether, when Pygments is in use, it highlights inline content.

% \begin{macrocode}

\newbool{pytx@opt@pyginline}

\booltrue{pytx@opt@pyginline}

\pgfkeys{/PYTX/pkgopt/pyginline/.default=true}

\pgfkeys{/PYTX/pkgopt/pyginline/.is choice}

\pgfkeys{/PYTX/pkgopt/pyginline/true/.code=\booltrue{pytx@opt@pyginline}}

\pgfkeys{/PYTX/pkgopt/pyginline/false/.code=\boolfalse{pytx@opt@pyginline}}

% \end{macrocode}

% \end{macro}

%

%

% \begin{macro}{\pytx@fvextfile}

% By default, code highlighted by Pygments, the |console| environment, and some other content is brought back via |fancyvrb|'s |SaveVerbatim| macro, which saves verbatim content into a macro and then allows it to be restored. This makes it possible for all Pygments content to be brought back in a single file, keeping the total file count low (which is a major priority for \pytex!). This approach does have a disadvantage, though, because |SaveVerbatim| slows down as the length of saved code increases.\footnote{The macro in which code is saved is created by grabbing the code one line at a time, and for each line redefining the macro to be its old value with the additional line tacked on. This is rather inefficient, but apparently there isn't a good alternative.} To deal with this issue, we create the |fvextfile| option. This option takes an integer, |fvextfile|=\meta{integer}. All content that is more than \meta{integer} lines long will be saved to its own external file and inputted from there, rather than saved and restored via |SaveVerbatim| and |UseVerbatim|. This provides a workaround should speed ever become a hindrance for large blocks of code.

%

% A default value of 25 is set. There is nothing special about 25; it is just a relatively reasonably cutoff. If the option is unused, it has a value of $-1$, which is converted to the maximum integer on the Python side.

% \begin{macrocode}

\def\pytx@fvextfile{-1}

\pgfkeys{/PYTX/pkgopt/fvextfile/.default=25}

\pgfkeys{/PYTX/pkgopt/fvextfile/.code=\def\pytx@fvextfile{#1}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{Python console environment}

% \begin{macro}{\pytx@opt@pyconbanner}

% This option governs the appearance (or disappearance) of a banner at the beginning of Python console environments. 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.

% \begin{macrocode}

\def\pytx@opt@pyconbanner{none}

\pgfkeys{/PYTX/pkgopt/pyconbanner/.is choice}

\pgfkeys{/PYTX/pkgopt/pyconbanner/none/.code=\def\pytx@opt@pyconbanner{none}}

\pgfkeys{/PYTX/pkgopt/pyconbanner/standard/.code=\def\pytx@opt@pyconbanner{standard}}

\pgfkeys{/PYTX/pkgopt/pyconbanner/default/.code=\def\pytx@opt@pyconbanner{default}}

\pgfkeys{/PYTX/pkgopt/pyconbanner/pyversion/.code=\def\pytx@opt@pyconbanner{pyversion}}

% \end{macrocode}

% \end{macro}

%

% \begin{macro}{\pytx@opt@pyconfilename}

% This option governs the file name that appears in error messages in the console. The file name may be either |stdin|, as it is in a standard interactive interpreter, or |console|, as it would typically be for the Python |code| module.

% \begin{verbatim}

% Traceback (most recent call last):

% File "<file name>", line <line no>, in <module>

% \end{verbatim}

% \begin{macrocode}

\def\pytx@opt@pyconfilename{stdin}

\pgfkeys{/PYTX/pkgopt/pyconfilename/.is choice}

\pgfkeys{/PYTX/pkgopt/pyconfilename/stdin/.code=\def\pytx@opt@pyconfilename{stdin}}

\pgfkeys{/PYTX/pkgopt/pyconfilename/console/.code=\def\pytx@opt@pyconfilename{console}}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{De-PythonTeX}

% \begin{macro}{pytx@opt@depythontex}

% This option governs whether \pytex\ creates a version of the .tex file that does not require \pytex\ to be compiled. This option should be useful for converting a \pytex\ document into a more standard \TeX\ document when sharing or publishing documents.

% \begin{macrocode}

\newbool{pytx@opt@depythontex}

\pgfkeys{/PYTX/pkgopt/depythontex/.default=true}

\pgfkeys{/PYTX/pkgopt/depythontex/.is choice}

\pgfkeys{/PYTX/pkgopt/depythontex/true/.code=\booltrue{pytx@opt@depythontex}}

\pgfkeys{/PYTX/pkgopt/depythontex/false/.code=\boolfalse{pytx@opt@depythontex}}

% \end{macrocode}

% \end{macro}

%

%

% \subsubsection{Process options}

% Now we process the package options.

% \begin{macrocode}

\ProcessPgfPackageOptions{/PYTX/pkgopt}

% \end{macrocode}

%

% The |fixlr| option only affects one thing, so we go ahead and take care of that.

% \begin{macrocode}

\ifbool{pytx@opt@fixlr}{

\let\originalleft\left

\let\originalright\right

\renewcommand{\left}{\mathopen{}\mathclose\bgroup\originalleft}

\renewcommand{\right}{\aftergroup\egroup\originalright}

}{}

% \end{macrocode}

%

% Likewise, the |upquote| option.

% \begin{macrocode}

\ifbool{pytx@opt@upquote}{\RequirePackage{upquote}}{}

% \end{macrocode}

% \subsection{Utility macros and input/output setup}

% Once options are processed, we proceed to define a number of utility macros and setup the file input/output that is required by \pytex.

%

% \subsubsection{Automatic counter creation}

%

% \begin{macro}{\pytx@CheckCounter}

% We will be using counters to give each command/environment a unique identifier, as well as to manage line numbering of code when desired. We don't know the names of the counters ahead of time (this is actually determined by the user's naming of code sessions), so we need a macro that checks whether a counter exists, and if not, creates it.

% \begin{macrocode}

\def\pytx@CheckCounter#1{%

\ifcsname c@#1\endcsname\else\newcounter{#1}\fi

}

% \end{macrocode}

% \end{macro}

%

% \subsubsection{Code context}

% \begin{macro}{\pytx@context}\begin{macro}{\pytx@SetContext}\begin{macro}{\definepythontexcontext}

% It would be nice if when our code is executed, we could know something about its context, such as the style of its surroundings or information about page size.

%

% By default, no contextual information is passed to \LaTeX. There is a wide variety of information that could be passed, but most use cases would only need a very specific subset. Instead, the user can customize what information is passed to \LaTeX. The |\definepythontexcontext| macro defines what is passed. It creates the |\pytx@SetContext| macro, which creates |\pytx@context|, in which the expanded context information is stored. The context should only be defined in the preamble, so that it is consistent throughout the document.

%

% If you are interested in typesetting mathematics based on math styles, you should use the |\mathchoice| macro rather than attempting to pass contextual information.

% \begin{macrocode}

\newcommand{\definepythontexcontext}[1]{%

\def\pytx@SetContext{%

\edef\pytx@context{#1}%

}%

}

\definepythontexcontext{}

\@onlypreamble\definepythontexcontext

% \end{macrocode}

% \end{macro}\end{macro}\end{macro}

%

% \subsubsection{Code groups}

% By default, \pytex\ executes code based on sessions. All of the code entered within a command and environment family is divided based on sessions, and each session is saved to a single external file and executed. If you have a calculation that will take a while, you can simply give it its own named session, and then the code will only be executed when there is a change within that session.

%

% While this approach is appropriate for many scenarios, it is sometimes inefficient. For example, suppose you are writing a document with multiple chapters, and each chapter needs its own session. You could manually do this, but that would involve a lot of commands like |\py[chapter x]{|\meta{some~code}|}|, which means lots of extra typing and extra session names. So we need a way to subdivide or restart sessions, based on context such as chapter, section, or subsection.

%

% ``Groups'' provide a solution to this problem. Each session is subdivided based on groups behind the scenes. By default, this changes nothing, because each session is put into a single default group. But the user can redefine groups based on chapter, section, and other counters, so that sessions are automatically subdivided accordingly. Note that there is no continuity between sessions thus subdivided. For example, if you set groups to change between chapters, there will be no continuity between the code of those chapters, even if all the code is within the same named session. If you require continuity, the groups approach is probably not appropriate. You could consider saving results at the end of one chapter and loading them at the beginning of the next, but that introduces additional issues in keeping all code properly synchronized, since code is executed only when it changes, not when any data it loads may have changed.

%

%

% \begin{macro}{\restartpythontexsession}

% \begin{macro}{\pytx@group}

% \begin{macro}{\pytx@SetGroup}

% \begin{macro}{\pytx@SetGroupVerb}

% \begin{macro}{\pytx@SetGroupCons}

% We begin by creating the |\restartpythontexsession| macro. It creates the |\pytx@SetGroup*| macros, which create |\pytx@group|, in which the expanded context information is stored. The context should only be defined in the preamble, so that it is consistent throughout the document. Note that groups should be defined so that they will only contain characters that are valid in file names, because groups are used in naming temporary files. It is also a good idea to avoid using periods, since \LaTeX\ input of file names containing multiple periods can sometimes be tricky. For best results, use A-Z, a-z, 0-9, and the hyphen and underscore characters to define groups. If groups contain numbers from multiple sources (for example, chapter and section), the numbers should be separated by a non-numeric character to prevent unexpected collisions (for example, distinguishing chapter 1-11 from 11-1). For example, |\restartpythontexsession{\arabic{chapter}-\arabic{section}}| could be a good approach.

%

% Three forms of |\pytx@SetGroup*| are provided. |\pytx@SetGroup| is for general code use. |\pytx@SetGroupVerb| is for use in verbatim contexts. It splits verbatim content off into its own group. That way, verbatim content does not affect the instance numbers of code that is actually executed. This prevents code from needing to be run every time verbatim content is added or removed; code is only executed when it is actually changed. |pytx@SetGroupCons| is for |console| environments. It separate console content from executed code and from verbatim content, again for efficiency reasons.

% \begin{macrocode}

\newcommand{\restartpythontexsession}[1]{%

\def\pytx@SetGroup{%

\edef\pytx@group{#1}%

}%

\def\pytx@SetGroupVerb{%

\edef\pytx@group{#1verb}%

}%

\def\pytx@SetGroupCons{%

\edef\pytx@group{#1cons}%

}%

\AtBeginDocument{%

\pytx@SetGroup

\IfSubStr{\pytx@group}{verb}{%

\PackageError{\pytx@packagename}%

{String "verb" is not allowed in \string\restartpythontexsession}%

{Use \string\restartpythontexsession with a valid argument}}{}%

\IfSubStr{\pytx@group}{cons}{%

\PackageError{\pytx@packagename}%

{String "cons" is not allowed in \string\restartpythontexsession}%