Developer Interface#

Main Interface#

Examples for the most relevant api functions can be viewed in the test file. fattura_elettronica_reader’s API uses type hints instead of assertions to check input and output types.

fattura_elettronica_reader.is_xml_file_conforming_to_schema(xml_file: str, xml_schema_file: str) → bool#

Check that the XML file follows its schema.

Parameters

  • xml_file (str) – the path of the XML file.

  • xml_schema_file (str) – the path of the schema file.

Returns

True if the schema is followed, False otherwise.

Return type

bool

Raises

an lxml or a built-in exception.

fattura_elettronica_reader.parse_xml_file(xml_file: str)#

Parse the XML file.

Parameters

xml_file (str) – the input XML file.

Returns

the XML root as a data structure

Return type

ET.parse.getroot

Raises

an lxml or a built-in exception.

fattura_elettronica_reader.get_invoice_filename(metadata_file_xml_root, metadata_file_invoice_filename_xml_tag: str, metadata_file_xml_namespace: str) → str#

Return the file name of the invoice file.

Parameters

  • metadata_file_xml_root (lxml.etree._Element) – the root of the metadata XML tree.

  • metadata_file_invoice_filename_xml_tag (str) – the tag name corresponding to the invoice filename.

  • metadata_file_xml_namespace (str) – the XML namespace of the metadata file.

Returns

the element or None, if no match is found.

Return type

str

Raises

an lxml or a built-in exception.

fattura_elettronica_reader.is_p7m_file_signed(p7m_file: str) → bool#

Check if the invoice file is signed with a PKCS#7 signature.

Parameters

p7m_file (str) – the path of the invoice file.

Returns

True if the file is signed, False otherwise.

Return type

bool

Raises

a fpyutils or a built-in exception.

fattura_elettronica_reader.invoice_file_checksum_matches(metadata_file_xml_root, invoice_file: str, metadata_file_invoice_checksum_xml_tag: str, metadata_file_xml_namespace: str) → bool#

Check if the invoice checksum matches the one in the metadata file.

Parameters

  • metadata_file_xml_root (lxml.etree._Element) – the root of the metadata XML tree.

  • invoice_file (str) – the path of the invoice file.

  • metadata_file_invoice_checksum_xml_tag (str) – the XML tag name corresponding to the invoice file checksum.

  • metadata_file_xml_namespace (str) – the XML namespace of the metadata file.

Returns

True if the checksum matches, False otherwise. The expected checksum is also returned.

Return type

tuple

Raises

a hashlib, lxml or a built-in exception.

fattura_elettronica_reader.get_remote_file(destination: str, url: str)#

Download and save a remote file.

Parameters

  • destination (str) – the local path of the downloaded file.

  • url (str) – the remote path of the file.

Returns

None

Return type

None

Raises

ValueError or a built-in exception.

fattura_elettronica_reader.get_ca_certificates(trusted_list_xml_root: str, ca_certificate_pem_file: str, trusted_list_file_xml_namespace: str, trusted_list_file_xml_certificate_tag: str, eol: str = '\n')#

Write the CA certificates file using the trusted list file.

Parameters

  • trusted_list_file – the input file.

  • ca_certificate_pem_file (str) – the destination file.

  • trusted_list_file_xml_namespace (str) – the XML namespace of the trusted list file.

  • trusted_list_file_xml_certificate_tag (str) – the XML tag name corresponding to the certificates in the trusted list file.

  • eol (str) – the end of line character to be used in the PEM file.

Returns

None

Return type

None

Raises

an atomicwrites, an lxml or a built-in exception.

fattura_elettronica_reader.is_p7m_file_authentic(p7m_file: str, ca_certificate_pem_file: str, ignore_signature_check: bool = False, ignore_signers_certificate_check: bool = False) → bool#

Check authenticity of the invoice file on various levels.

Parameters

  • p7m_file (str) – the path of the signed invoice file.

  • ca_certificate_pem_file (str) – the certificates file in PEM format.

  • ignore_signature_check (bool) – avoid checking the signature. Defaults to False.

  • ignore_signers_certificate_check (bool) – avoid checking the signer’s certificate. Defaults to False.

Returns

True if the operation is successful, False otherwise.

Return type

bool

Raises

a fpyutils or built-in exception.

fattura_elettronica_reader.remove_signature_from_p7m_file(p7m_file: str, output_file: str) → bool#

Remove signature from the signed invoice file and save the original one.

Parameters

  • p7m_file (str) – the path of the invoice file.

  • output_file (str) – the path of the destination file.

Returns

True if the operation is successful, False otherwise.

Return type

bool

Raises

a fpyutils or built-in exception.

fattura_elettronica_reader.extract_attachments_from_invoice_file(invoice_file_xml_root, invoice_file_xml_attachment_xpath: str, invoice_file_xml_attachment_tag: str, invoice_file_xml_attachment_filename_tag: str, invoice_file_text_encoding: str, ignore_attachment_extension_whitelist: bool = False, ignore_attachment_filetype_whitelist: bool = False, attachment_extension_whitelist: list = [], attachment_filetype_whitelist: list = [], destination_directory: str = '.')#

Extract, decode and save possible attachments within the invoice file.

Parameters

  • invoice_file_xml_root (str) – the original invoice file.

  • invoice_file_xml_attachment_xpath (str) – the full path, from the XML root, corresponding to the attachments.

  • invoice_file_xml_attachment_tag (str) – the XML tag name corresponding to the attachment content.

  • invoice_file_xml_attachment_filename_tag (str) – the XML tag name corresponing to the attachment filename.

  • invoice_file_text_encoding (str) – the text encoding used for the invoice file.

  • ignore_attachment_extension_whitelist (bool) – avoid cheking file extensions. Defaults to False.

  • ignore_attachment_filetype_whitelist (bool) – avoid cheking file types. Defaults to False.

  • attachment_extension_whitelist (list) – allowed attachment extensions. Defaults to list().

  • attachment_filetype_whitelist (list) – allowed attachment file types. Defaults to list().

  • destination_directory (str) – the output directory for the attachments. Defaults to ..

Returns

None

Return type

None

Raises

base64.binascii.Error, filetype, atomicwrites, or a built-in exception.

fattura_elettronica_reader.get_invoice_as_html(invoice_file_xml_root, invoice_file_xml_stylesheet_root, html_output_file: str, invoice_file_text_encoding: str, destination_directory: str = '.')#

Transform the XML invoice file into a styled HTML file.

Parameters

  • invoice_file_xml_root (lxml.etree._Element) – the XML tree root of the invoice file

  • invoice_file_xml_stylesheet_root (lxml.etree._Element) – the XML tree root of the stylesheet file

  • html_output_file (str) – the destination file.

  • invoice_file_text_encoding (str) – the text encoding used for the invoice file.

  • destination_directory (str) – the output directory for the html file. Defaults to ..

Returns

None

Return type

None

Raises

an lxml or a built-in exception.

fattura_elettronica_reader.patch_invoice_schema_file(invoice_schema_file: str, offending_line: str, fix_line: str)#

Fix the error in the schema file.

Parameters

  • invoice_schema_file (str) – the path of the schema file.

  • offending_line (str) – the string in the schema file that needs to be changed.

  • fix_line (str) – a string that replaces the offending line.

Returns

None

Return type

None

Raises

an atomicwrites, or a built-in exception.

fattura_elettronica_reader.create_appdirs(program_name: str, destination_directory: str = '.')#

Create user data, configuration and destination directories.

Parameters

  • program_name (str) – the name of the software.

  • destination_directory (str) – the output directory for the files. Defaults to .

Raises

a pathlib or a built-in exception.

Returns

None

Return type

None

fattura_elettronica_reader.define_appdirs_user_data_dir_file_path(program_name: str, relative_path: str)#

Get the full path of the input file in the users’s data directory.

Parameters

  • program_name (str) – the name of the software.

  • relative_path (str) – the relative path of the file, i.e: the file name.

Returns

a full path.

Return type

str

fattura_elettronica_reader.define_appdirs_user_config_dir_file_path(program_name: str, relative_path: str) → str#

Get the full path of the input file in the user’s cofiguration directory.

Parameters

  • program_name (str) – the name of the software.

  • relative_path (str) – the relative path of the file, i.e: the file name.

Returns

a path.

Return type

str

fattura_elettronica_reader.write_configuration_file(configuration_file: str)#

Write the default configuration file.

Parameters

configuration_file (str) – the path of the configuration file.

Returns

None

Return type

None

Raises

a configparser or a built-in exception.

fattura_elettronica_reader.assert_data_structure(source: str, file_type: str, data: dict)#

Check the data structure.

Parameters

  • source (str) – the type of document to be considered. Choose between invoice and generic.

  • considered (file_type the type of file to be) – Choose between p7m and plain, depending on the source parameter.

  • data (dict) – a data structure containing all the fields.

Returns

None

Return type

None

Raises

ValueError or TypeError

fattura_elettronica_reader.asset_checksum_matches(file: str) → bool#

Check that the asset file is the expected one.

Parameters

file (str) – the file name that needs to be checked.

Returns

matches

Return type

str

Raises

a built-in exception.

fattura_elettronica_reader.pipeline(source: str, file_type: str, data: dict)#

Run the pipeline.

Parameters

  • source (str) – the type of document to be considered. Choose between invoice and generic.

  • file_type (str) – the type of file to be considered. Choose between p7m and plain, depending on the source parameter.

  • data (dict) – a data structure containing all the fields. See the cli.py file.

Returns

None

Return type

None

Exceptions#

exception fattura_elettronica_reader.P7MFileDoesNotHaveACoherentCryptographicalSignature#

Not a PKCS#7 signature.

exception fattura_elettronica_reader.InvoiceFileChecksumFailed#

Checksum of the invoice file does not match the one in the metadata file.

exception fattura_elettronica_reader.P7MFileNotAuthentic#

An error with the signature or the signers certificate of the invoice.

exception fattura_elettronica_reader.CannotExtractOriginalP7MFile#

The cryptographical signature from the invoice file cannot be removed.

exception fattura_elettronica_reader.MissingTagInMetadataFile#

A necessary element is missing from the metadata file.

exception fattura_elettronica_reader.XMLFileNotConformingToSchema#

XML file is not-conforming to the XML schema.

exception fattura_elettronica_reader.ExtractedAttachmentNotInExtensionWhitelist#

An extracted attachment is not in the extension whitelist.

exception fattura_elettronica_reader.ExtractedAttachmentNotInFileTypeWhitelist#

An extracted attachment is not in the filetype whitelist.

exception fattura_elettronica_reader.AssetsChecksumDoesNotMatch#

A downloaded file might make this program malfuncioning.