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

PythonReports_ is a toolkit aimed to build database reports
in |Python(r)| programs.  The toolkit includes the report builder
and printout_ renderer for PDF 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 to PDF.

It is possible to render printouts for other presentation formats
such as a specific printer language or a GUI toolkit display.
There used to be printing output for wxPython_ and screen
display for Tkinter and wxPython_, but they fell out of use
and their support is discontinued.

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

Current version of PythonReports_ has only been tested with Python v3.12.
Earlier versions of Python3 may or may not work; Python2 is not supported
starting from PythonReports v1.0.0.

Report building and printout_ rendering require the ReportLab_ Toolkit.
Reports containing images additionally require
`Python Imaging Library`_: Pillow_ (preferred) or PIL_.

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

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

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

A report is built from a list of data dictionaries or data objects
having uniform structure.  An example of such data is a list of rows
fetched from an SQL server.

Report layout is defined by a template_ file which can have
either XML format or a textual format based on rsonlite_.

Report builder applies loaded template to a list of data
objects and produces a printout_ structure.  Printout can
be saved in XML format.

PDF writer creates an output file from a printout structure.

There are example templates in the `package sources`_:
`sakila.prt` is in XML format, and `sakila.prtr` is the
same template in RSON format.  The data file for those
templates can be found in the `project downloads`_.

This is an example of building a PDF from that data::

    import pickle
    from PythonReports.api import Builder, parse_rson, write_pdf

    with open("sakila.dat", "rb") as data_file:
        data = pickle.load(data_file, encoding="latin1")[:200]
    template = parse_rson("sakila.prtr")
    build = Builder(template)
    printout = build.run(data)
    with open("sakila.prp", "wb") as printout_file:
        printout.write(printout_file)
    # It is necessary to call .validate() on built or loaded printout
    # before creating PDF output.
    printout.validate()
    write_pdf(printout, "sakila.pdf")

.. _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/
.. _ReportLab: https://www.reportlab.com/software/opensource/rl-toolkit/
.. _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/
.. _package sources: https://sourceforge.net/p/pythonreports/code/
.. _project downloads: https://sourceforge.net/projects/pythonreports/files/Sample%20Data%20file/

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

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