+% \def\fileversion{0.1}
+% \def\filedate{2010/03/03}
+% \iffalse meta-comment
+%<package>\def\fileversion{0.1}
+%<package>\def\filedate{2010/03/03}
+%
+% Copyright (C) 2010 W. Trevor King
+% -------------------------------------------------------
+%
+% This file 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 2003/12/01 or later.
+%
+% Docstrip formatting initially based on Scott Pakin's
+% dtxtut/cskeleton.dtx
+% http://www.ctan.org/tex-archive/info/dtxtut/
+% Shellout calls initially based on Will Robertson's asyfig.sty
+% http://github.com/wspr/asyfig/
+%
+% \fi
+%
+% \iffalse meta-comment
+%<*driver>
+\ProvidesFile{pytex.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesClass{pytex}
+%<package> [\filedate\ \fileversion\ embed Python in LaTeX files]
+%
+% Code for the .ini driver, see section "2.1 The driver file" of doc.dtx.
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[colorlinks=true]{hyperref}
+%</driver>
+% Include some useful commands from |xkeyval|'s |<preamble>|.
+%<*driver>
+\usepackage{xcolor}
+\usepackage{listings}
+\lstnewenvironment{command}{%
+ \lstset{columns=flexible,frame=single,backgroundcolor=\color{blue!20},%
+ xleftmargin=\fboxsep,xrightmargin=\fboxsep,escapeinside=`',gobble=1}}{}
+\lstnewenvironment{example}{%
+ \lstset{basicstyle=\footnotesize\ttfamily,columns=flexible,frame=single,%
+ backgroundcolor=\color{yellow!20},xleftmargin=\fboxsep,%
+ xrightmargin=\fboxsep,gobble=1}}{}
+%</driver>
+% Define a quick and dirty version of |xkeyval|'s |\DescribeOptions|.
+%<*driver>
+\newenvironment{option}[1]{\begin{macro}{#1}}
+ {\end{macro}}
+%</driver>
+% Some commonly used abbreviations from |classes.dtx|.
+%<*driver>
+\newcommand*{\Lopt}[1]{\textsf {#1}}
+\newcommand*{\file}[1]{\texttt {#1}}
+\newcommand*{\Lcount}[1]{\textsl {\small#1}}
+\newcommand*{\pstyle}[1]{\textsl {#1}}
+%</driver>
+%<*driver>
+\makeatletter
+\def\DescribeOption#1{\leavevmode\@bsphack
+ \marginpar{\raggedleft\PrintDescribeOption{#1}}%
+ \SpecialOptionIndex{#1}\@esphack\ignorespaces}
+\def\PrintDescribeOption#1{\strut\emph{option}\\\MacroFont #1\ }
+\def\SpecialOptionIndex#1{\@bsphack
+ \index{#1\actualchar{\protect\ttfamily#1}
+ (option)\encapchar usage}%
+ \index{options:\levelchar#1\actualchar{\protect\ttfamily#1}\encapchar
+ usage}\@esphack}
+\def\DescribeOptions#1{\leavevmode\@bsphack
+ \marginpar{\raggedleft\strut\emph{options}%
+ \@for\@tempa:=#1\do{%
+ \\\strut\MacroFont\@tempa\SpecialOptionIndex\@tempa
+ }}\@esphack\ignorespaces}
+\makeatother
+%</driver>
+%<*driver>
+\EnableCrossrefs
+\RecordChanges
+\EnableCrossrefs
+\begin{document}
+ \DocInput{pytex.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{0}
+%
+% \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{0.1}{2006/01/18}{Initial package}
+%
+% \MakeShortVerb{\|}
+% \newcommand{\pkg}[1]{\textsf{#1}}
+% \newcommand{\cls}[1]{\textsf{#1}}
+% \newcommand{\fixme}[1]{\emph{FIXME: #1}}
+% \newcommand{\python}{Python}
+% \newcommand{\firstPython}{\href{http://www.python.org/}{\python}}
+%
+% \title{The \textsf{pytex} class\thanks{This document
+% corresponds to \textsf{pytex}~\fileversion, dated \filedate.}}
+% \author{W.~Trevor King \\\texttt{wking@drexel.edu}}
+% \date{\filedate}
+%
+% \maketitle
+%
+%
+% \section{Introduction}
+%
+% This package defines a \LaTeX\ package for embedding \firstPython\ in
+% \LaTeX\ files. This is useful, for example, if you want to automate
+% physics problem generation. This is intended for easy transitions
+% from static \LaTeX sources, or for those to whom \LaTeX seems more
+% natural. An alternative approach would be to write \python\ code
+% that built static \LaTeX\ files on the fly.
+%
+%
+% \section{Usage}
+%
+% Include \pkg{pytex} in your preamble (after |\documentclass{}| and
+% before |\begin{document}|).
+% \begin{example}
+% \usepackage{pytex}
+% \end{example}
+%
+% This will give you the |\pytex{}| and |\pytexfile{}| macros.
+% The long names are chosen to reduce the risk of collision with
+% other packages, but feel free to abbreviate.
+% \begin{example}
+% \newcommand{\py}[1]{\pytex{#1}}
+% \end{example}
+%
+% Remember to use |-shell-escape| option or its equivalent for your
+% flavor of \LaTeX, since \pkg{pytex} works by shelling out to
+% \python. Obviously, you'll have to trust the user writing whatever
+% goes into the |\pytex| macro because (1) no shell escaping is done
+% on the argument and (2) even if it were, you can do whatever you
+% want through \python's |os.system| etc.
+%
+%
+% \subsection{Macros}
+%
+% \begin{command}
+% `\cs{pytexfile}\marg{path}'
+% \end{command}
+% \DescribeMacro{\pytexfile}
+% Set the working pickle file to \meta{path}. \pkg{pytex} keeps track
+% of your environment by
+% \href{http://docs.python.org/library/pickle.html}{pickling}
+% everything in a pickle file. By default, this will be
+% |./\jobname.pkl|, but feel free to use whatever name you want, or to
+% switch back an forth between names.
+% \begin{example}
+% \pytexfile{problem1}
+% \end{example}
+% The pickle file is \emph{not} cleared at the start of each
+% \LaTeX\ run (but it could be, perhaps via a |\newpytexfile{}|).
+%
+% \begin{command}
+% `\cs{pytex}\marg{python-code}'
+% \end{command}
+% \DescribeMacro{\pytex}
+% Here's where the fun begins.
+% \begin{example}
+% If $a=\pytex{p.a=1; print p.a}$ and $b=\pytex{p.b=2; print p.b}$,
+% then $a\cdot b = \pytex{print p.a*p.b}$.
+% \end{example}
+% |p| is a |PyTeX_Storage| instance that handles saving to and loading
+% from the current pytex file.
+%
+%
+% \section{Implementation}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% Use \pkg{ifplatform} to detect Linux / Mac / MS Windows \ldots.
+% \begin{macrocode}
+\RequirePackage{ifplatform}
+% \end{macrocode}
+%
+% Use \pkg{catchfile} for reading in files.
+% \begin{macrocode}
+\RequirePackage{catchfile}
+% \end{macrocode}
+%
+% \begin{macro}{\pytex@currentfile}
+% Keep track of the current pytex file, making |\jobname| the default.
+% \begin{macrocode}
+\newcommand\pytex@currentfile{\jobname}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\pytexfile}
+% Give the user a way to change the current pytex file.
+% \begin{macrocode}
+\newcommand\pytexfile[1]{\renewcommand\pytex@currentfile{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\pytex@stdout}
+% \begin{macro}{\pytex@stderr}
+% Temporary files for capturing stdout and stderr from a |\pytex|
+% call.
+% \begin{macrocode}
+\newcommand\pytex@stdout{pytex.stdout}
+\newcommand\pytex@stderr{pytex.stderr}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\pytex@par}
+% We will be using |^^J| for line breaks on our input stderr to
+% preserve line wrapping. Here we give |^^J| a name to make
+% the stderr comparison more clear.
+% \begin{macrocode}
+\newcommand\pytex@par{^^J}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\pytex@qt}
+% Surround an argument with escaped quotes.
+% For wrapping strings in the python shellout.
+% \fixme{doesn't actually work.}
+% ^^A echo '\write16{"hi \"there"}\bye' | tex
+% ^^A echo '\write16{"hi \ "there"}\bye' | tex
+% \begin{macrocode}
+\newcommand{\pytex@qt}[1]{\char"22 #1\char"22}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\pytex}
+% Here's the meat. Use the pytex file to provide a persitent
+% environment for \python\ execution.
+% \begin{macrocode}
+\newcommand\pytex[1]{%
+ \immediate\write18{%
+ python -c "import pytex;
+ p = pytex.PyTeX_Storage('\pytex@currentfile');
+ p.load();
+ #1;
+ p.save();"
+ 1> \pytex@stdout\space 2> \pytex@stderr}%
+% \end{macrocode}
+% Read stdout and stderr files into |\@tempa| and |\@tempb|
+% respectively. \fixme{How do we know the command is complete? wait
+% call?}. We preserve linebreaks while reading stderr so that
+% they will show up if we have to |\typeout| them later.
+% \begin{macrocode}
+ \CatchFileEdef{\@tempa}{\pytex@stdout}{}%
+ \CatchFileEdef{\@tempb}{\pytex@stderr}{\let\par\pytex@par\obeylines}%
+% \end{macrocode}
+% Remove the temporary files.
+% \begin{macrocode}
+ \immediate\write18{\ifwindows del \else rm \fi \pytex@stdout}
+ \immediate\write18{\ifwindows del \else rm \fi \pytex@stderr}
+% \end{macrocode}
+% If stderr is blank (equivalent to a single endline?)\ldots
+% \begin{macrocode}
+ \if\@tempb\pytex@par
+% \end{macrocode}
+% \ldots the \python\ code ran cleanly. Put stdout in the token
+% stream.
+% \begin{macrocode}
+ \@tempa
+ \else
+% \end{macrocode}
+% \ldots otherwise, the \python\ code failed. Put stderr in the token
+% stream and raise an error.
+% \begin{macrocode}
+ \errorstopmode
+ \typeout{%
+ ------------------------------------^^J%
+ ----------- PYTHON ERROR -----------^^J}
+ %\typeout{\expandafter\strip@prefix\meaning\@tempb}
+ \typeout{\@tempb}
+ \typeout{^^J%
+ ----------- PYTHON ERROR -----------^^J%
+ ------------------------------------}%
+ \batchmode
+ \end{document}
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+%
+% \section{Module}
+% \label{sec:module}
+%
+% \begin{macrocode}
+%<*module>
+# See pytex.pdf for details.
+
+import os
+import pickle
+
+class PyTeX_Storage (object):
+ """
+ >>> test_file = 'test.pkl'
+ >>> p = PyTeX_Storage(test_file)
+ >>> p.a = 1
+ >>> p.b = 2
+ >>> p.save()
+ >>> del p
+ >>> p = PyTeX_Storage(test_file)
+ >>> p.a
+ Traceback (most recent call last):
+ ...
+ AttributeError: 'PyTeX_Storage' object has no attribute 'a'
+ >>> p.load()
+ >>> p.a
+ 1
+ >>> p.b
+ 2
+ >>> p.cleanup()
+ """
+ def __init__(self, pytexfile):
+ self._pytexfile = self._pytexfile_path(pytexfile)
+ self._hidden = dir(self)
+ self._hidden.append('_hidden')
+
+ def _pytexfile_path(self, pytexfile):
+ """
+ >>> p = PyTeX_Storage('dummy')
+ >>> p._pytexfile_path('test')
+ 'test.pkl'
+ >>> p._pytexfile_path('test.pkl')
+ 'test.pkl'
+ """
+ if not pytexfile.endswith('.pkl'):
+ pytexfile += '.pkl'
+ return pytexfile
+
+ def load(self):
+ try:
+ f = open(self._pytexfile, 'r')
+ except IOError: # [Errno 2] No such file or directory
+ return
+ saved = pickle.load(f)
+ for key,value in saved.items():
+ setattr(self, key, value)
+
+ def save(self, protocol=-1):
+ saved = {}
+ for key in dir(self):
+ if key in self._hidden:
+ continue
+ saved[key] = getattr(self, key)
+ f = open(self._pytexfile, 'w')
+ pickle.dump(saved, f, protocol=protocol)
+ f.close()
+
+ def cleanup(self):
+ os.remove(self._pytexfile)
+
+def test() :
+ import doctest
+ doctest.testmod()
+
+if __name__ == '__main__':
+ test()
+%</module>
+% \end{macrocode}
+%
+%
+% \section{Examples}
+% \label{sec:example}
+%
+% \begin{macrocode}
+%<*example>
+%% See pytex.pdf for details.
+\documentclass{article}
+\usepackage{pytex}
+\begin{document}
+
+\section{Problem 1}
+\pytexfile{problem1}
+
+If $a=\pytex{p.a=1; print p.a}$ and $b=\pytex{p.b=2; print p.b}$, then
+what is $a\cdot b$? [Answer: $\pytex{p.ans=p.a*p.b; print p.ans}$]
+
+\section{Problem 2}
+\pytexfile{problem2}
+
+If $a=\pytex{p.a=1; print p.a}$ and $b=\pytex{p.b=3; print p.b}$, then
+what is $a\cdot b$? [Answer: $\pytex{p.ans=p.a*p.b; print p.ans}$]
+
+\section{Discussion}
+\pytexfile{problem3}
+
+Comparing our answers for Problems 1 and 2, we see that the answer to
+1 (\pytexfile{problem1}$\pytex{print p.ans}$) is smaller than the answer
+to 2 (\pytexfile{problem2}$\pytex{print p.ans}$). This is to be expected,
+since $a$ is the same in both problems, and $b$ is larger in Problem 2
+($\pytexfile{problem1}\pytex{print p.b} <
+ \pytexfile{problem2}\pytex{print p.b}$).
+% \end{macrocode}
+% We can explicitly check our statement. \LaTeX\ compilation will
+% fail if the |\pytex| call returns a non-zero status code, as it
+% does for Exceptions.
+% \begin{macrocode}
+\pytex{p1 = pytex.PyTeX_Storage('problem1'); p1.load();
+ assert p.b > p1.b, ('b2 = '+str(p.b)+' > '+str(p1.b)+' = b1')}
+
+\end{document}
+%</example>
+% \end{macrocode}
+%
+%
+% \Finale
+\endinput
projects / pytex.git / commitdiff