============
Introduction
============

PythonReports_ is a toolkit aimed to build database reports
in |Python(r)| programs.  The toolkit includes report template_
designer, report builder and several printout_ renderers for
GUI and graphic file output.

Report builder applies a template_ to a sequence of uniform data
objects and produces a printout_ structure that can be saved in
a file and/or rendered by one of the front-end drivers to screen,
printer, HTML [*]_, PDF etc.

.. [*] HTML output is not implemented yet.

============
Requirements
============

PythonReports_ require Python_ version 2.4 [*]_ to 2.7.

.. [*] Later versions have been tested only with Python 2.7 and 2.6.
       Compatibility with Python 2.4 and 2.5 may be unintentionally
       broken.  Please file an issue if you encounter errors.

All parts of the PythonReports_ toolkit require the ElementTree_
module.  Python includes this module as part of the standard
library since version 2.5.  Python 2.4 users can download
separate distribution package from http://effbot.org/downloads/
(cElementTree_ add-on is highly recommended too).

Requirements for printout_ rendering depend on selected frontend:
  * PDF output requires the ReportLab_ Toolkit.
    Reports containing images additionally require
    `Python Imaging Library`_ (PIL_ or Pillow_).
  * wx-based preview and printing require wxPython_.
  * Tk-based report preview requires Tkinter
    (part of the Python Standard Library).
    Reports containing images additionally require
    PIL_ or wxPython_.

Report building can utilize any of the above options.
In other words, if your system is able to display or print
a report then it should be able to build a report too.

Templates in RSON format (introduced in v0.7.0) require rsonlite_.

Report template designer requires Tkinter with Tix_ support
(standard Python installer for Windows includes Tix; on some
platforms Tix must be installed separately).

WYSIWIG template editor requires wxPython_.  For wxPython versions
prior to 2.9 wxPropertyGrid_ must be installed as a separate module [*]_.

.. [*] **Note**: the first Windows installer on the `wxPropertyGrid
   download page`_ installs source code only; scroll down for binaries.

===========
Quick Start
===========

No documentation yet.  Please look at the `test script`_
for report building example.  All printout rendering modules
(``pdf``, ``Tk`` and ``wxPrint``) have command line interface
that can serve as their API usage example.

.. _External hyperlink targets:

.. _PythonReports: http://pythonreports.sourceforge.net/
.. _template: http://pythonreports.sourceforge.net/prt.shtml
.. _printout: http://pythonreports.sourceforge.net/prp.shtml
.. _Python: http://www.python.org/
.. _ElementTree: http://effbot.org/zone/element-index.htm
.. _cElementTree: http://effbot.org/zone/celementtree.htm
.. _ReportLab: http://www.reportlab.org/rl_toolkit.html
.. _PIL: http://www.pythonware.com/products/pil/
.. _Python Imaging Library:
.. _Pillow: https://pypi.python.org/pypi/Pillow
.. _rsonlite: https://pypi.python.org/pypi/rsonlite
.. _wxPython: http://www.wxpython.org/
.. _wxPropertyGrid: http://wxpropgrid.sourceforge.net/
.. _wxPropertyGrid download page: http://wxpropgrid.sourceforge.net/cgi-bin/index?page=download
.. _Tix: http://tix.sourceforge.net/
.. _test script: http://pythonreports.bzr.sourceforge.net/bzr/pythonreports/annotate/head%3A/test/test_build.py

.. |Python(r)| unicode:: Python U+00AE

.. vim: set et ft=rst sts=2 sw=2 :
