============
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.5 [*]_ to 2.7.

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

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

    **Warning**: The ``wx`` front-end has never been checked
    with `wxPython Phoenix`_, and has known issues with
    print preview on earlier wxPython_ versions.
  * Tk-based report preview requires Tkinter
    (part of the Python Standard Library).
    Reports containing images additionally require
    `Python Imaging Library`_ 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_.

`QR`_ barcodes (introduced in v0.8.0) require qrcode_.

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
.. _qrcode: https://pypi.python.org/pypi/qrcode
.. _QR: https://en.wikipedia.org/wiki/QR_code
.. _rsonlite: https://pypi.python.org/pypi/rsonlite
.. _wxPython: http://www.wxpython.org/
.. _wxPython Phoenix: https://wxpython.org/Phoenix/docs/html/index.html
.. _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 :
