pybill.lib.xmlwriters package

pybill.lib.xmlwriters package contains the classes and functions that PyBill accounting entities in XML files.

Currently, PyBill just knows how to dump the entities in the PyBill Document 1.0 format. There is no support for writing the entities in the old formats.

The write_accounting_doc() is the public function that should be used from the outside of this package. The ENCODING constant is also public and contains the default encoding used for all the XML files written by PyBill. They are both imported and available in the namespace of this package.

accdoc module

pybill.lib.xmlwriters.accdoc module contains the function used for saving PyBill accounting documents into XML files.

The XML files are built thanks to lxml library. All the type of accountind documents (bill, claim-form, debit, downpayment, pro-forma) can be saved by this function.

Currently, it is only possible to save the entities in the latest PyBill Document 1.0 format.

pybill.lib.xmlwriters.accdoc.write_accounting_doc(acc_doc, xml_file, format=u'PBD-1.0', encoding=u'UTF-8')

Writes an accounting entity into an XML file in format PyBill format.

If the entity is linked to a configuration object that has a reference, a processing instruction will be added in the XML in order to specify the configuration to be used.

This function relies on the other functions defined in this package that know how to write the XML corresponding to a given format.

Parameters:
  • acc_doc (GenericAccountingDoc) – PyBill entity describing the accounting document to be saved in XML. Can be a Bill, a ClaimForm, a Debit, a Downpayment or a ProForma object.
  • xml_file (unicode) – Name of the file where the XML has to be saved.
  • format (unicode) – name of the PyBill format used for the XML. Currently, only PyBill Document 1.0 format is supported; therefore the only possible value for this parameter is u"PBD-1.0".
  • encoding (str) – Encoding used to write the XML file.

utils module

pybill.lib.xmlwriters.utils module defines constants and common functions used to write accounting entities in XML.

These functions mainly concern opening an XML file and writing an address object into an XML element with a DocBook-like structure.

This module defines a constant that will be widely used in PyBill.

pybill.lib.xmlwriters.utils.ENCODING = u'UTF-8'

Constant specifying the default encoding used for the XML files written in this package.

type: unicode

It also defines the following utilitary functions.

pybill.lib.xmlwriters.utils.open_xml_outfile(xml_file, encoding=u'UTF-8')

Opens an XML file in write mode, and writes the XML declaration.

Parameters:
  • xml_file (unicode) – Name of the XML file. Also works if this parameter is an opened file.
  • encoding (str) – Encoding used to write the XML file.
Returns:

opened file in write mode where the XML declaration has already been written.

Return type:

file

pybill.lib.xmlwriters.utils.build_address_xml_element(address, xml_ns=u'')

Transforms the address object in an XML element whose structure is inspired by DocBook.

This type of XML element is used in several PyBill formats ( PyBill Document 0.X or PyBill Document 1.0). The XML element is built thanks to lxml library.

Parameters:
  • address (PersonAddress) – Address object to be turned into an XML element.
  • xml_ns (unicode) – XML namespace where the address XML elements will be defined in. The default value u"" corresponds to an empty namespace.
Returns:

An XML element built with lxml library that contains the information from the address object.

Return type:

:class:lxml.etree.Element

pybill.lib.xmlwriters.utils.write_address_xml_elements(address, xml_elt, xml_ns=u'')

Writes the elements of the address object inside the xml_elt XML element, using a structure inspired by DocBook.

This function can be used to dump the elements of a PersonAddress or an OrganisationAddress. The dumped elements are street, postcode, etc. that are common to both addresses.

Parameters:
  • address (Address) – Address object whose elements must be written in XML into the XML element. This object is either a PersonAddress or an OrganisationAddress.
  • xml_elt (lxml.etree.Element) – XML element in which the XML elements representing the address elements will be written. This XML element is built with the lxml library and will be modified by this function (addition of new child elements).
  • xml_ns (unicode) – XML namespace where the address XML elements will be defined in. The default value u"" corresponds to an empty namespace.

accdoc_format_1_0 module

pybill.lib.xmlwriters.accdoc_format_1_0 module defines the function that can write the accounting entities in an XML element in PyBill Document 1.0 format.

The function can write any accounting entities such as bills, claim-forms, debits, downpayments, or pro-formas.

pybill.lib.xmlwriters.accdoc_format_1_0.write_accdoc_1_0_xml(acc_doc)

Writes an accounting entity into an XML element in PyBill Document 1.0 format.

The XML element is built thanks to lxml library.

Parameters:acc_doc (GenericAccountingDoc) – PyBill entity describing the accounting document to be turned in XML. Can be a Bill, a ClaimForm, a Debit, a Downpayment or a ProForma object.
Returns:an XML element describing the accounting document in PyBill Document 1.0 format.
Return type:lxml.etree.Element