pyreport is a program that runs a python script and captures its output, compiling it to a pretty report in a pdf or an html file. It can display the output embedded in the code that produced it and can process special comments (literate comments) according to markup languages ( rst or LaTeX ) to compile a very readable document.
This allows for extensive literate progamming  in python, for generating reports out of calculations written in python, and for making nice tutorials.
License pyreport is free software released under a BSD-like license. You can chek out the latest code, submit bugs, ask questions... on the github project page.
pyreport is of course written in python, and needs the python interpreter to run.
It should work on any operating system where python and the other requirements are available.
Under windows make sure they are in the path, elsewhere pyreport cannot find them. All these programs are available with the MikTeX LaTeX distribution.
The easiest way to install pyreport is using setuptools:
Under Linux it is recommended to install to '/usr/local' instead of '/usr':
easy_install --prefix /usr/local pyreport
I use python to write small scripts that can do, for instance, numerical calculations, or simple operations  and I want to have nice print-outs of these scripts to study off-screen or to hand out to colleagues. Having the code with its relevant output is great for code reviewing. This also allows something similar to mathematica's notebook in python without having to use a special IDE.
Second I would like all the plots produced by matplotlib to be captured and displayed too.
Last I would be able to comment these reports, give them titles, sections, ... This can be done via "literate programming": comment lines begin with a special sets of characters are interpreted as rst or LaTeX. I also want these files to still be standard python files, and to be able to run them with the python interpreter.#! Just a title
a = "a"
#! *ooo oo
b = "b"
#$ This is \LaTeX : $c = 2\cdot(a+b)$
c = 2*(a+b)
- Hidding the source code allows to generate nice reports from calculation scripts without worrying about writing document generating code in the script itself. The use of the literal comments and print statements allow your report to be well structured and self-explaining. The major advantage of having the text of the report in the source of the calulation is that the report always discribes the calculation that was actually ran, and not a previous one, with incorrect constants, for instance.
- With a moin-moin syntax and a pdf output this can be a very useful tool for writing tutorials and putting them on scipy.org, with a pdf version.
Here are two examples showing what you can do with pyreport :
A calculation of the bifurcation diagram of the logistic mapping
An exploration of the Julia sets, this example uses a LaTeX equation (LaTeX embedding does not work with html output, so far):
This section could also be called "known bugs", but I do not like such a name :->.
The "sys" module is imported in your code, whether you want it or not. As a general rule, beware of the namespace when running your scripts with pyreport, pyreport injects a few variables in your namespace.
from __future__ import foobar in a script does not work ! This a a big caveat ! This is simply not possible in python, as the from __future__ imports have to be the first statement of a script.
As a consequence I have made the decision to always import division, so that 2/3 = 0.6666.
Some stange bugs can occur depending on the backend you use for matplotlib. WXAgg has played me a few tricks.
Up to release 0.2 putting literate comments in the middle of indented blocks will not work (the execution of the script will fail).
This is not as useful as a well written documentation, but it is better than nothing:
usage: pyreport [options] pythonfile
Processes a python script and pretty prints the results using LateX. If
the script uses "show()" commands (from pylab) they are caught by
pyreport and the resulting graphs are inserted in the output pdf.
Comments lines starting with "#!" are interprated as rst lines
and pretty printed accordingly in the pdf.
By Gael Varoquaux
--version show program's version number and exit
-h, --help show this help message and exit
-o FILE, --outfile=FILE
write report to FILE
-x, --noexecute do not run the code, just extract the literate
-n, --nocode do not display the source code
-d, --double compile to two columns per page (only for pdf or tex
-t TYPE, --type=TYPE output to TYPE, TYPE can be ps, dvi, trac, eps, tex,
html, pdf, rst, moin
-f TYPE, --figuretype=TYPE
output figure type TYPE (TYPE can be of pdf, jpg,
eps, png, ps depending on report output type)
-c CHAR, --commentchar=CHAR
literate comments start with "#CHAR"
-l, --latexliterals allow LaTeX literal comment lines starting with "#$"
-e, --latexescapes allow LaTeX math mode escape in code wih dollar signs
-p, --nopyreport disallow the use of #pyreport lines in the processed
file to specify options
-q, --quiet don't print status messages to stderr
-v, --verbose print all the message, including tex messages
-s, --silent Suppress the display of warning and errors in the
--noecho Turns off the echoing of the output of the script on
the standard out
-a ARGS, --arguments=ARGS
pass the arguments "ARGS" to the script
|||literate programming is a programming style that embeds the documentation of a program in its source code. The documentation is generated in the same time that the program is built. I am using the term in a very loose way, as pyreport is capable of literate programming, but also of much more, as it embeds the documentation, but also weaves the output of the script in the documentation.|
|||scipy provides a very powerful math package to python, and matplotlib is a great plotting interface.|