+
Py3o Report Engine
+
+

+
The py3o reporting engine is a reporting engine for Odoo based on
+[Libreoffice](http://www.libreoffice.org/):
+
+- the report is created with Libreoffice (ODT or ODS),
+- the report is stored on the server in OpenDocument format (.odt or
+.ods file)
+- the report is sent to the user in OpenDocument format or in any output
+format supported by Libreoffice (PDF, HTML, DOC, DOCX, Docbook, XLS,
+etc.)
+
+
The key advantages of a Libreoffice based reporting engine are:
+
+- no need to be a developer to create or modify a report: the report is
+created and modified with Libreoffice. So this reporting engine has a
+full WYSIWYG report development tool!
+- For a PDF report in A4/Letter format, it’s easier to develop it with a
+tool such as Libreoffice that is designed to create A4/Letter
+documents than to develop it in HTML/CSS, also some print
+peculiarities (backgrounds, margin boxes) are not very well supported
+by the HTML/CSS based solutions.
+- If you want your users to be able to modify the document after its
+generation by Odoo, just configure the document with ODT output (or
+DOC or DOCX) and the user will be able to modify the document with
+Libreoffice (or Word) after its generation by Odoo.
+- Easy development of spreadsheet reports in ODS format (XLS output
+possible).
+
+
This module report_py3o is the base module for the Py3o reporting
+engine. If used alone, it will spawn a libreoffice process for each ODT
+to PDF (or ODT to DOCX, ..) document conversion. This is slow and can
+become a problem if you have a lot of reports to convert from ODT to
+another format. In this case, you should consider the additionnal module
+report_py3o_fusion_server which is designed to work with a libreoffice
+daemon. With report_py3o_fusion_server, the technical environnement is
+more complex to setup because you have to install additionnal software
+components and run 2 daemons, but you have much better performances and
+you can configure the libreoffice PDF export options in Odoo (allows to
+generate PDF forms, PDF/A documents, password-protected PDFs,
+watermarked PDFs, etc.).
+
This reporting engine is an alternative to
+[Aeroo](https://github.com/aeroo-community/aeroo_reports): these two
+reporting engines have similar features but their implementation is
+entirely different. You cannot use aeroo templates as drop in
+replacement though, you’ll have to change a few details.
+
Table of contents
+
+
+
+
Install the required python libs:
+
:literal:`` pip install py3o.template pip install py3o.formats``
+
To allow the conversion of ODT or ODS reports to other formats (PDF,
+DOC, DOCX, etc.), install libreoffice:
+
:literal:`` apt-get –no-install-recommends install libreoffice``
+
+
+
+
For example, to replace the native invoice report by a custom py3o
+report, add the following XML file in your custom module:
+
:literal:`` <?xml version=”1.0” encoding=”utf-8”?> <odoo> <record id=”account.account_invoices” model=”ir.actions.report”> <field name=”report_type”>py3o</field> <field name=”py3o_filetype”>odt</field> <field name=”module”>my_custom_module_base</field> <field name=”py3o_template_fallback”>report/account_invoice.odt</field> </record> </odoo>``
+
where my_custom_module_base is the name of the custom Odoo module. In
+this example, the invoice ODT file is located in
+my_custom_module_base/report/account_invoice.odt.
+
It’s also possible to reference a template located in a trusted path of
+your Odoo server. In this case you must let the module entry empty and
+specify the path to the template as py3o_template_fallback.
+
:literal:`` <?xml version=”1.0” encoding=”utf-8”?> <odoo> <record id=”account.account_invoices” model=”ir.actions.report”> <field name=”report_type”>py3o</field> <field name=”py3o_filetype”>odt</field> <field name=”py3o_template_fallback”>/odoo/templates/py3o/report/account_invoice.odt</field> </record> </odoo>``
+
Moreover, you must also modify the Odoo server configuration file to
+declare the allowed root directory for your py3o templates. Only
+templates located into this directory can be loaded by py3o report.
+
:literal:`` [options] … [report_py3o] root_tmpl_path=/odoo/templates/py3o``
+
If you want an invoice in PDF format instead of ODT format, the XML file
+should look like:
+
:literal:`` <?xml version=”1.0” encoding=”utf-8”?> <odoo> <record id=”account.account_invoices” model=”ir.actions.report”> <field name=”report_type”>py3o</field> <field name=”py3o_filetype”>pdf</field> <field name=”module”>my_custom_module_base</field> <field name=”py3o_template_fallback”>report/account_invoice.odt</field> </record> </odoo>``
+
If you want to add a new py3o PDF report (and not replace a native
+report), the XML file should look like this:
+
:literal:`` <?xml version=”1.0” encoding=”utf-8”?> <odoo> <record id=”partner_summary_report” model=”ir.actions.report”> <field name=”name”>Partner Summary</field> <field name=”model”>res.partner</field> <field name=”report_name”>res.partner.summary</field> <field name=”report_type”>py3o</field> <field name=”py3o_filetype”>pdf</field> <field name=”module”>my_custom_module_base</field> <field name=”py3o_template_fallback”>report/partner_summary.odt</field> <!– Add entry in “Print” drop-down list –> <field name=”binding_type”>report</field> <field name=”binding_model_id” ref=”base.model_res_partner”/> </record> </odoo>``
+
## Configuration parameters
+
py3o.conversion_command The command to be used to run the conversion,
+libreoffice by default. If you change this, whatever you set here must
+accept the parameters –headless –convert-to $ext $file and put the
+resulting file into $file’s directory with extension $ext. The command
+will be started in $file’s directory.
+
+
+
+
The templating language is [extensively
+documented](http://py3otemplate.readthedocs.io/en/latest/templating.html),
+the records are exposed in libreoffice as objects, on which you can also
+call functions.
+
## Available functions and objects
+
user Browse record of current user
+
lang The user’s company’s language as string (ISO code)
+
b64decode base64.b64decode
+
format_multiline_value(string) Generate the ODF equivalent of <br/> and
+ for multiline fields (ODF is XML internally, so those would be skipped
+otherwise)
+
html_sanitize(string) Sanitize HTML string
+
time Python’s time module
+
display_address(partner) Return a formatted string of the partner’s
+address
+
o_format_lang(value, lang_code=False, digits=None, grouping=True,
+monetary=False, dp=False, currency_obj=False, no_break_space=True)
+Return a formatted numeric or monetary value according to the context
+language and timezone
+
o_format_date(value, lang_code=False, date_format=False) Return a
+formatted date or time value according to the context language and
+timezone
+
## Sample report templates
+
Sample py3o report templates for the main Odoo native reports (invoice,
+sale order, purchase order, picking, etc.) are available on the Github
+project
+[odoo-py3o-report-templates](https://github.com/akretion/odoo-py3o-report-templates).
+
+
+
+
+- generate barcode ?
+- add more detailed example in demo file to showcase features
+- add migration guide aeroo -> py3o
+
+
+
+
+
Bugs are tracked on GitHub Issues.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+feedback.
+
Do not contact contributors directly about support or help with technical issues.
+
+
+
+
+
+
+- XCG Consulting
+- ACSONE SA/NV
+
+
+
+
+
+
This module is maintained by the OCA.
+
+
+
+
OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
This module is part of the OCA/reporting-engine project on GitHub.
+
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
+
+
+