pybill.lib.xmlreaders package¶
pybill.lib.xmlreaders package contains the classes and functions used to read the XML files describing the accounting documents and to build the corresponding entity objects.
This package contains classes to read XML files either in the PyBill Document 0.X old format or in the PyBill Document 1.0 latest format. It also defines the public AccDocXMLReader class that manages the reading of an XML file whatever its PBD format is. This public class is the only class that should be used from the outside of this package. It is imported and available in the namespace of this package.
accdoc module¶
pybill.lib.xmlreaders.utils module defines the public class used for reading accounting XML files ans building the corresponding entity objects.
The XML files are read with lxml library. They contain an accounting document that can be a bill, a claim form, a debit, a downpayment or a pro-forma. The information read from these files is stored in Bill, ClaimForm, Debit, Downpayment or ProForma objects.
- class pybill.lib.xmlreaders.accdoc.AccDocXMLReader(config_register)¶
Class reading an XML file containing an accounting document.
After opening the XML file thanks to lxml XML parser, this class finds a processing instruction that specifies the name of the configuration file to be used for turning the accounting document in PDF, instanciates a specialized reader object matching the format of the accounting document, and asks it to read the data. Then, it returns the entity object built by the specialized reader. This entity object is, eventually, linked to the configuration object.
Variables: - format_readers – Dictionary of specialized format readers that can read a given format of accounting document; these readers are indexed by the name of the format they can read. This dictionary contains all the specialized format readers supported by this reader.
- cfg_register – Configuration register that returns a ConfigData object matching a configuration name. This register searches and reads the configuration file. If this file is not found, returns a default configuration object. The configuration is used here to convert accounting documents from older formats.
- __init__(config_register)¶
Initializes a new AccDocXMLReader object.
Parameters: config_register (ConfigRegister) – Register containing the various configurations read by PyBill. This register is used to get the configuration used by the accounting documents read by this object (the configurations can be useful to convert data from older formats).
- load_data(xml_file, config_ref=None)¶
Loads the accounting document contained in the file xml_file.
If the accounting document contains a pybill processing instruction giving the name of the configuration file to be used for document transformation in PDF, reads it and linkks it to the accounting entity.
Parameters: - xml_file (unicode) – name of the XML file containing the accounting document to be read.
- config_ref (unicode) – reference of the XML configuration file that has been manually specified and that will override any configuration specification in the accounting document.
Returns: the entity object containing the accounting document. This object contains also a link towards the configuration object that shall be used for its further process.
Return type:
utils module¶
pybill.lib.xmlreaders.utils module defines various classes and functions used in the different specialized format readers.
It also defines the base class for the format readers, or functions to read the addresses defined in an XML element inspired by the DocBook standard, or dump adress objects into XML elements.
- class pybill.lib.xmlreaders.utils.AccDocFormatAbstractReader¶
Base class for the various specialized format readers. A format reader can read the XML data in a given format and build the corresponding accounting document.
- filename¶
Attribute containing the name of the file that the XML data is read from. This file name is mostly used when reporting errors.
type: unicode
- __init__()¶
Initializes a new AccDocFormatAbstractReader object.
As this class is abstract, raises an exception if the object class is not one of the child classes.
- read_accounting_doc(xml_root, filename='', cfg=None)¶
Reads the data contained in the XML under the element xml_root and builds an accounting entity object.
The class of the accounting entity object (Bill, ClaimForm, Debit, Downpayment, ProForma) depends on the data read in the XML.
This abstract polymorphic method will be implemented in the child classes.
Parameters: - xml_root (lxml.etree.Element) – root element of the XML tree containing the accounting document. The XML has already been read with lxml parser.
- filename (unicode) – name of the file where the XML root element was read from. This name is used to display nicest errors.
- cfg (ConfigData) – Configuration object that might be useful for format conversion. This object contains the configuration read from a configuration XML file.
Returns: entity object containing the accounting document.
Return type:
- _select_from_xpaths(xml_elt, xpaths)¶
Utilitary function that selects XML elements from an XPath pointer.
More precisely, the XPath pointer is a list of several XPath that will be tried in the order of the list until one of them selects something. If none of them selects something, an empty result is returned.
In the XPaths, you can use the pbd: prefix that is automatically binded to the PyBill document XML namespace (defined in PBD_XMLNS).
The result of the selection is returned as a list of XML nodes.
Parameters: - xml_elt (lxml.etree.Element) – XML element where the selection will be started from (especially if the XPath are relative paths). This element has been read in a file thanks to lxml parser.
- xpaths (:list of class:unicode) – List of relative XPaths that points to the piece of information that must be selected in the XML element. If nothing is selected by the first XPath, tries the second one, and so on until something is selected.
Returns: List of XML nodes (element, attribute, text, etc.) selected by one of the XPaths. If no piece of information was found, returns an empty list.
Return type: list of object
- _read_number_from_xpaths(xml_elt, xpaths, converted_type, def_value=None, infoname=u'')¶
Utilitary function that reads a piece of information in an XML element and tries to convert it to a float or an integer.
If the information doesn’t exist, returns a default value. If several pieces of information exist, uses the first one. If there is an error during the numeric conversion, returns a nice error message.
In the XPaths, you can use the pbd: prefix that is automatically binded to the PyBill document XML namespace (defined in PBD_XMLNS).
Parameters: - xml_elt (lxml.etree.Element) – XML element where the piece of information will be read. This element has been read in a file thanks to lxml parser.
- xpaths (:list of class:unicode) – List of relative XPaths that points to the piece of information that must be read in the XML element. If nothing is selected by the first XPath, tries the second one, and so on until something is selected.
- converted_type (type) – Type of number that the information must be converted to. Can be float or int
- def_value (float) – Default value that is returned if the piece of information can’t be read in the XML element.
- infoname (unicode) – Name of the information that must be read in the XML element. Only used to display nice error messages.
Returns: Piece of information read in the XML element and converted to a float or an integer. If no piece of information was found, returns the default value.
Return type: float
- _read_date_from_xpaths(xml_elt, xpaths, infoname=u'')¶
Utilitary function that reads a piece of information in an XML element and tries to convert it to a date.
If the information doesn’t exist, returns None. If several pieces of information exist, uses the first one. If there is an error in the conversion, returns a nice error message.
In the XPaths, you can use the pbd: prefix that is automatically binded to the PyBill document XML namespace (defined in PBD_XMLNS).
Parameters: - xml_elt (lxml.etree.Element) – XML element where the piece of information will be read. This element has been read in a file thanks to lxml parser.
- xpaths (:list of class:unicode) – List of relative XPaths that points to the piece of information that must be read in the XML element. If nothing is selected by the first XPath, tries the second one, and so on until something is selected.
- infoname (unicode) – Name of the information that must be read in the XML element. Only used to display nice error messages.
Returns: Piece of information read in the XML element and converted to a date object. If no piece of information was found, returns None.
Return type: datetime.date
- _read_text_from_xpaths(xml_elt, xpaths)¶
Utilitary function that reads a piece of information in an XML element and returns it as an unicode string.
If the information doesn’t exist, returns u"". If several pieces of information exist, uses the first one.
In the XPaths, you can use the pbd: prefix that is automatically binded to the PyBill document XML namespace (defined in PBD_XMLNS).
Parameters: - xml_elt (lxml.etree.Element) – XML element where the piece of information will be read. This element has been read in a file thanks to lxml parser.
- xpaths (:list of class:unicode) – List of relative XPaths that points to the piece of information that must be read in the XML element. If nothing is selected by the first XPath, tries the second one, and so on until something is selected.
Returns: Piece of information read in the XML element as an unicode string. If no piece of information was found, returns u"".
Return type: unicode
- pybill.lib.xmlreaders.utils.read_person_address(xml_addr, xml_ns=u'')¶
Utilitary function that reads an address defined in an XML element ( xml_addr) and stores it in an entity object.
Hence, the XML defining an address was inspired by DocBook format and is the same in several PyBill formats and in the configuration files.
Parameters: - xml_addr (lxml.etree.Element) – XML element containing the definition of an address in a DocBook-like format. This element was read thanks to lxml parser.
- xml_ns (unicode) – XML namespace where the XML address elements are defined. Default value is u"" (no namespace).
Returns: An entity object storing the address information read from the XML element.
Return type:
- pybill.lib.xmlreaders.utils.fill_address_from_address_block(addr, xml_addr, xml_ns=u'')¶
Reads data from an address XML element and fills it in an address object.
The XML defining an address was inspired by DocBook format.
Parameters: - addr (Address) – An entity object that will be filled with the address information read from the XML element. This object can be a person address or an organisation address. It is modified by this function.
- xml_addr (lxml.etree.Element) – XML element containing the definition of an address in a DocBook-like format. This element was read thanks to lxml parser.
- xml_ns (unicode) – XML namespace where the XML address elements are defined. Default value is u"" (no namespace).
- pybill.lib.xmlreaders.utils.read_text_from_xml_elt(xml_startpoint, elt_name, def_value=u'')¶
Utilitary private function that returns the text contained in an XML element named elt_name selected from an XML start point.
This function is mainly used by the functions reading the addresses from XML elements.
Parameters: - xml_startpoint – XML element where the selection starts from.
- elt_name – Name of the XML element (most of the times, a child of the XML startpoint) containing the text we want to get. The name is given in lxml format: {namespace}elt_name/{namespace}elt_name.
- def_value (unicode) – Default value to be returned if no XML element is selected with elt_name.
Returns: The text contained in the XML element selected by elt_name from xml_startpoint element. If the XML element is empty, returns u"". If the XML element doesn’t exist, returns def_value.
Return type: unicode
accdoc_format_1_0 module¶
pybill.lib.xmlreaders.accdoc_format_1_0 module defines the specialized format reader used to build an accounting document from XML data in PyBill Document 1.0 format.
- class pybill.lib.xmlreaders.accdoc_format_1_0.AccDocFormat_1_0_Reader¶
Bases: pybill.lib.xmlreaders.utils.AccDocFormatAbstractReader
Class reading the XML data contained in an accounting document in PyBill Document 1.0 format.
This class instanciates and fills the accounting object corresponding to the document described in the XML data.
- __init__()¶
Initializes a new AccDocFormat_1_0_Reader object.
- read_accounting_doc(xml_root, filename='', cfg=None)¶
Reads the data contained in the XML and builds an accounting object.
The class of the object (Bill, ClaimForm, Debit, Downpayment, or ProForma) depends on the data contained in the XML.
Parameters: - xml_root (lxml.etree.Element) – root element of the XML tree containing the accounting document. The XML has already been read with lxml parser.
- filename (unicode) – name of the file the XML root element was read from. This name is used to display nicest errors.
- cfg (ConfigData) – Configuration object that might be useful for format conversion. For reading format PDB-1.0, the configuration object is not needed.
Returns: entity object containing the accounting document.
Return type:
accdoc_format_0_X module¶
pybill.lib.xmlreaders.accdoc_format_0_X module defines the specialized format reader used to build an accounting document from XML data in PyBill Document 0.X format.
The PyBill Document 0.X format is the format of the oldest versions of PyBill.
- class pybill.lib.xmlreaders.accdoc_format_0_X.AccDocFormat_0_X_Reader¶
Bases: pybill.lib.xmlreaders.utils.AccDocFormatAbstractReader
Class reading the XML data contained in an accounting document in PyBill Document 0.X format.
This class instanciates and fills the accounting object corresponding to the document described in the XML data.
- __init__()¶
Initializes a new AccDocFormat_0_X_Reader object.
- read_accounting_doc(xml_root, filename='', cfg=None)¶
Reads the data contained in the XML and builds an accounting object.
The class of the object (Bill, ClaimForm, Debit, Downpayment, or ProForma) depends on the data contained in the XML.
Parameters: - xml_root (lxml.etree.Element) – root element of the XML tree containing the accounting document. The XML has already been read with lxml parser.
- filename (unicode) – name of the file the XML root element was read from. This name is used to display nicest errors.
- cfg (ConfigData) – Configuration object that is useful for converting the data in 0.X format.
Returns: entity object containing the accounting document.
Return type: