drafthorse


Namedrafthorse JSON
Version 2.4.0 PyPI version JSON
download
home_pagehttps://github.com/pretix/python-drafthorse
SummaryPython ZUGFeRD XML implementation
upload_time2024-03-10 15:57:01
maintainer
docs_urlNone
authorRaphael Michel
requires_python
licenseApache License
keywords xml banking sepa
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            drafthorse -- Basic ZUGFeRD implementation in Python
====================================================

.. image:: https://travis-ci.com/pretix/python-drafthorse.svg?branch=master
   :target: https://travis-ci.com/pretix/python-drafthorse

.. image:: https://codecov.io/gh/pretix/python-drafthorse/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/pretix/drafthorse

.. image:: http://img.shields.io/pypi/v/drafthorse.svg
   :target: https://pypi.python.org/pypi/drafthorse

This is a low-level python implementation of the ZUGFeRD XML format. ZUGFeRD is a German
format for sending digital invoices. ZUGFeRD XML files are to be attached to a PDF
file. This library can be used to generate or parse the contents of this XML file as well as
attach it to a PDF. We do not support parsing PDF files (for now).

By low-level, we mean that this library tries to model the ZUGFeRD data model 1:1 without any
further abstractions or simplifications. You can set and parse all parameters defined in ZUGFeRD
2.2. To see which parameters are defined, please refer to the official ZUGFeRD specification,
there is no documentation for this library that reiterates it.

All output is validated against the official XSDs, but no validation of profile levels
(basic, comfort, extended) is performed.

The profile level is detected automatically based on the XML data and added to the PDF metadata.

Maintenance note
----------------

With the possibly upcoming legal obligation to use digital formats for all B2B invoices in
Germany, interest in this library is increasing. We built this library to ble able to use it
in the [pretix-zugferd](https://github.com/pretix/pretix-zugferd) module and we are planning
to keep maintaining the library. However, it is not our core business and turnaround time on
issus or PR reviews might be longer than usual due to other priorities. We do not offer paid
consulting services around this library.

Usage
-----

Parsing::

    from drafthorse.models.document import Document
    samplexml = open("sample.xml", "rb").read()
    doc = Document.parse(samplexml)
    print(doc.trade.agreement.seller.name)

Generating::

    import os
    from datetime import date, datetime, timezone
    from decimal import Decimal

    from drafthorse.models.accounting import ApplicableTradeTax
    from drafthorse.models.document import Document
    from drafthorse.models.note import IncludedNote
    from drafthorse.models.tradelines import LineItem
    from drafthorse.pdf import attach_xml

    # Build data structure
    doc = Document()
    doc.context.guideline_parameter.id = "urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended"
    doc.header.id = "RE1337"
    doc.header.type_code = "380"
    doc.header.name = "RECHNUNG"
    doc.header.issue_date_time = date.today()
    doc.header.languages.add("de")

    note = IncludedNote()
    note.content.add("Test Node 1")
    doc.header.notes.add(note)

    doc.trade.agreement.seller.name = "Lieferant GmbH"
    doc.trade.settlement.payee.name = "Kunde GmbH"

    doc.trade.agreement.buyer.name = "Kunde GmbH"
    doc.trade.settlement.invoicee.name = "Kunde GmbH"

    doc.trade.settlement.currency_code = "EUR"
    doc.trade.settlement.payment_means.type_code = "ZZZ"

    doc.trade.agreement.seller.address.country_id = "DE"
    doc.trade.agreement.seller.address.country_subdivision = "Bayern"

    doc.trade.agreement.seller_order.issue_date_time = datetime.now(timezone.utc)
    doc.trade.agreement.buyer_order.issue_date_time = datetime.now(timezone.utc)
    doc.trade.settlement.advance_payment.received_date = datetime.now(timezone.utc)
    doc.trade.agreement.customer_order.issue_date_time = datetime.now(timezone.utc)

    li = LineItem()
    li.document.line_id = "1"
    li.product.name = "Rainbow"
    li.agreement.gross.amount = Decimal("999.00")
    li.agreement.gross.basis_quantity = (Decimal("1.0000"), "C62")  # C62 == pieces
    li.agreement.net.amount = Decimal("999.00")
    li.agreement.net.basis_quantity = (Decimal("999.00"), "EUR")
    li.delivery.billed_quantity = (Decimal("1.0000"), "C62")  # C62 == pieces
    li.settlement.trade_tax.type_code = "VAT"
    li.settlement.trade_tax.category_code = "E"
    li.settlement.trade_tax.rate_applicable_percent = Decimal("0.00")
    li.settlement.monetary_summation.total_amount = Decimal("999.00")
    doc.trade.items.add(li)

    trade_tax = ApplicableTradeTax()
    trade_tax.calculated_amount = Decimal("0.00")
    trade_tax.basis_amount = Decimal("999.00")
    trade_tax.type_code = "VAT"
    trade_tax.category_code = "AE"
    trade_tax.exemption_reason_code = 'VATEX-EU-AE'
    trade_tax.rate_applicable_percent = Decimal("0.00")
    doc.trade.settlement.trade_tax.add(trade_tax)

    doc.trade.settlement.monetary_summation.line_total = Decimal("999.00")
    doc.trade.settlement.monetary_summation.charge_total = Decimal("0.00")
    doc.trade.settlement.monetary_summation.allowance_total = Decimal("0.00")
    doc.trade.settlement.monetary_summation.tax_basis_total = Decimal("999.00")
    doc.trade.settlement.monetary_summation.tax_total = Decimal("0.00")
    doc.trade.settlement.monetary_summation.grand_total = Decimal("999.00")
    doc.trade.settlement.monetary_summation.due_amount = Decimal("999.00")

    # Generate XML file
    xml = doc.serialize(schema="FACTUR-X_EXTENDED")

    # Attach XML to an existing PDF.
    # Note that the existing PDF should be compliant to PDF/A-3!
    # You can validate this here: https://www.pdf-online.com/osa/validate.aspx
    with open("input.pdf", "rb") as original_file:
        new_pdf_bytes = attach_xml(original_file.read(), xml)

    with open("output.pdf", "wb") as f:
        f.write(new_pdf_bytes)


Development
-----------

To run the included tests::

    pip install -r requirements_dev.txt
    py.test tests

To automatically sort your Imports as required by CI::

    pip install isort
    isort -rc .

To validate files using mustang::

    git clone https://github.com/ZUGFeRD/mustangproject.git
    cd mustangproject
    git checkout core-2.9.0
    ./mvnw clean package
    java -jar Mustang-CLI/target/Mustang-CLI-2.7.4-SNAPSHOT.jar --action validate --source invoice.pdf


Credits and License
-------------------

Maintainer: Raphael Michel <michel@rami.io>

License of the Python code: Apache License 2.0

The PDF handling (drafthorse/pdf.py) was originally based on the code of factur-x, Copyright 2016-2018, Alexis de Lattre <alexis.delattre@akretion.com>,
released under a BSD license.

The packages includes schemas and samples of the ZUGFeRD specification (.xsd and .xml files) which are owned by the *Forum für elektronische Rechnungen bei der AWV e.V („FeRD“)* and are released under a proprietary license that allows bundling them together with other software for free.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/pretix/python-drafthorse",
    "name": "drafthorse",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "xml banking sepa",
    "author": "Raphael Michel",
    "author_email": "michel@rami.io",
    "download_url": "https://files.pythonhosted.org/packages/3e/26/8c43afe4abbfcc0c60fc5c598754b747b68a7652afbe0f608bff3ac35bd7/drafthorse-2.4.0.tar.gz",
    "platform": null,
    "description": "drafthorse -- Basic ZUGFeRD implementation in Python\n====================================================\n\n.. image:: https://travis-ci.com/pretix/python-drafthorse.svg?branch=master\n   :target: https://travis-ci.com/pretix/python-drafthorse\n\n.. image:: https://codecov.io/gh/pretix/python-drafthorse/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/pretix/drafthorse\n\n.. image:: http://img.shields.io/pypi/v/drafthorse.svg\n   :target: https://pypi.python.org/pypi/drafthorse\n\nThis is a low-level python implementation of the ZUGFeRD XML format. ZUGFeRD is a German\nformat for sending digital invoices. ZUGFeRD XML files are to be attached to a PDF\nfile. This library can be used to generate or parse the contents of this XML file as well as\nattach it to a PDF. We do not support parsing PDF files (for now).\n\nBy low-level, we mean that this library tries to model the ZUGFeRD data model 1:1 without any\nfurther abstractions or simplifications. You can set and parse all parameters defined in ZUGFeRD\n2.2. To see which parameters are defined, please refer to the official ZUGFeRD specification,\nthere is no documentation for this library that reiterates it.\n\nAll output is validated against the official XSDs, but no validation of profile levels\n(basic, comfort, extended) is performed.\n\nThe profile level is detected automatically based on the XML data and added to the PDF metadata.\n\nMaintenance note\n----------------\n\nWith the possibly upcoming legal obligation to use digital formats for all B2B invoices in\nGermany, interest in this library is increasing. We built this library to ble able to use it\nin the [pretix-zugferd](https://github.com/pretix/pretix-zugferd) module and we are planning\nto keep maintaining the library. However, it is not our core business and turnaround time on\nissus or PR reviews might be longer than usual due to other priorities. We do not offer paid\nconsulting services around this library.\n\nUsage\n-----\n\nParsing::\n\n    from drafthorse.models.document import Document\n    samplexml = open(\"sample.xml\", \"rb\").read()\n    doc = Document.parse(samplexml)\n    print(doc.trade.agreement.seller.name)\n\nGenerating::\n\n    import os\n    from datetime import date, datetime, timezone\n    from decimal import Decimal\n\n    from drafthorse.models.accounting import ApplicableTradeTax\n    from drafthorse.models.document import Document\n    from drafthorse.models.note import IncludedNote\n    from drafthorse.models.tradelines import LineItem\n    from drafthorse.pdf import attach_xml\n\n    # Build data structure\n    doc = Document()\n    doc.context.guideline_parameter.id = \"urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended\"\n    doc.header.id = \"RE1337\"\n    doc.header.type_code = \"380\"\n    doc.header.name = \"RECHNUNG\"\n    doc.header.issue_date_time = date.today()\n    doc.header.languages.add(\"de\")\n\n    note = IncludedNote()\n    note.content.add(\"Test Node 1\")\n    doc.header.notes.add(note)\n\n    doc.trade.agreement.seller.name = \"Lieferant GmbH\"\n    doc.trade.settlement.payee.name = \"Kunde GmbH\"\n\n    doc.trade.agreement.buyer.name = \"Kunde GmbH\"\n    doc.trade.settlement.invoicee.name = \"Kunde GmbH\"\n\n    doc.trade.settlement.currency_code = \"EUR\"\n    doc.trade.settlement.payment_means.type_code = \"ZZZ\"\n\n    doc.trade.agreement.seller.address.country_id = \"DE\"\n    doc.trade.agreement.seller.address.country_subdivision = \"Bayern\"\n\n    doc.trade.agreement.seller_order.issue_date_time = datetime.now(timezone.utc)\n    doc.trade.agreement.buyer_order.issue_date_time = datetime.now(timezone.utc)\n    doc.trade.settlement.advance_payment.received_date = datetime.now(timezone.utc)\n    doc.trade.agreement.customer_order.issue_date_time = datetime.now(timezone.utc)\n\n    li = LineItem()\n    li.document.line_id = \"1\"\n    li.product.name = \"Rainbow\"\n    li.agreement.gross.amount = Decimal(\"999.00\")\n    li.agreement.gross.basis_quantity = (Decimal(\"1.0000\"), \"C62\")  # C62 == pieces\n    li.agreement.net.amount = Decimal(\"999.00\")\n    li.agreement.net.basis_quantity = (Decimal(\"999.00\"), \"EUR\")\n    li.delivery.billed_quantity = (Decimal(\"1.0000\"), \"C62\")  # C62 == pieces\n    li.settlement.trade_tax.type_code = \"VAT\"\n    li.settlement.trade_tax.category_code = \"E\"\n    li.settlement.trade_tax.rate_applicable_percent = Decimal(\"0.00\")\n    li.settlement.monetary_summation.total_amount = Decimal(\"999.00\")\n    doc.trade.items.add(li)\n\n    trade_tax = ApplicableTradeTax()\n    trade_tax.calculated_amount = Decimal(\"0.00\")\n    trade_tax.basis_amount = Decimal(\"999.00\")\n    trade_tax.type_code = \"VAT\"\n    trade_tax.category_code = \"AE\"\n    trade_tax.exemption_reason_code = 'VATEX-EU-AE'\n    trade_tax.rate_applicable_percent = Decimal(\"0.00\")\n    doc.trade.settlement.trade_tax.add(trade_tax)\n\n    doc.trade.settlement.monetary_summation.line_total = Decimal(\"999.00\")\n    doc.trade.settlement.monetary_summation.charge_total = Decimal(\"0.00\")\n    doc.trade.settlement.monetary_summation.allowance_total = Decimal(\"0.00\")\n    doc.trade.settlement.monetary_summation.tax_basis_total = Decimal(\"999.00\")\n    doc.trade.settlement.monetary_summation.tax_total = Decimal(\"0.00\")\n    doc.trade.settlement.monetary_summation.grand_total = Decimal(\"999.00\")\n    doc.trade.settlement.monetary_summation.due_amount = Decimal(\"999.00\")\n\n    # Generate XML file\n    xml = doc.serialize(schema=\"FACTUR-X_EXTENDED\")\n\n    # Attach XML to an existing PDF.\n    # Note that the existing PDF should be compliant to PDF/A-3!\n    # You can validate this here: https://www.pdf-online.com/osa/validate.aspx\n    with open(\"input.pdf\", \"rb\") as original_file:\n        new_pdf_bytes = attach_xml(original_file.read(), xml)\n\n    with open(\"output.pdf\", \"wb\") as f:\n        f.write(new_pdf_bytes)\n\n\nDevelopment\n-----------\n\nTo run the included tests::\n\n    pip install -r requirements_dev.txt\n    py.test tests\n\nTo automatically sort your Imports as required by CI::\n\n    pip install isort\n    isort -rc .\n\nTo validate files using mustang::\n\n    git clone https://github.com/ZUGFeRD/mustangproject.git\n    cd mustangproject\n    git checkout core-2.9.0\n    ./mvnw clean package\n    java -jar Mustang-CLI/target/Mustang-CLI-2.7.4-SNAPSHOT.jar --action validate --source invoice.pdf\n\n\nCredits and License\n-------------------\n\nMaintainer: Raphael Michel <michel@rami.io>\n\nLicense of the Python code: Apache License 2.0\n\nThe PDF handling (drafthorse/pdf.py) was originally based on the code of factur-x, Copyright 2016-2018, Alexis de Lattre <alexis.delattre@akretion.com>,\nreleased under a BSD license.\n\nThe packages includes schemas and samples of the ZUGFeRD specification (.xsd and .xml files) which are owned by the *Forum f\u00fcr elektronische Rechnungen bei der AWV e.V (\u201eFeRD\u201c)* and are released under a proprietary license that allows bundling them together with other software for free.\n",
    "bugtrack_url": null,
    "license": "Apache License",
    "summary": "Python ZUGFeRD XML implementation",
    "version": "2.4.0",
    "project_urls": {
        "Homepage": "https://github.com/pretix/python-drafthorse"
    },
    "split_keywords": [
        "xml",
        "banking",
        "sepa"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2455dd1f0c643da379a89501b9887619f74bf104175849d8800051650aba2cfd",
                "md5": "fe3528fb59d5a19973fabcdf2eebabfe",
                "sha256": "e67d9f21bbada2282e5f63257c01cc56f8cb2667000f67e68bbddf6956484375"
            },
            "downloads": -1,
            "filename": "drafthorse-2.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fe3528fb59d5a19973fabcdf2eebabfe",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 70858,
            "upload_time": "2024-03-10T15:56:59",
            "upload_time_iso_8601": "2024-03-10T15:56:59.860683Z",
            "url": "https://files.pythonhosted.org/packages/24/55/dd1f0c643da379a89501b9887619f74bf104175849d8800051650aba2cfd/drafthorse-2.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3e268c43afe4abbfcc0c60fc5c598754b747b68a7652afbe0f608bff3ac35bd7",
                "md5": "144a8c0138f36e44515c37453e418a13",
                "sha256": "4d16a6dd60708676465e63ac7ff1b5f140e8c1c58be7d0eda66bc309814fc5c5"
            },
            "downloads": -1,
            "filename": "drafthorse-2.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "144a8c0138f36e44515c37453e418a13",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 59821,
            "upload_time": "2024-03-10T15:57:01",
            "upload_time_iso_8601": "2024-03-10T15:57:01.468769Z",
            "url": "https://files.pythonhosted.org/packages/3e/26/8c43afe4abbfcc0c60fc5c598754b747b68a7652afbe0f608bff3ac35bd7/drafthorse-2.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-10 15:57:01",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "pretix",
    "github_project": "python-drafthorse",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "lcname": "drafthorse"
}
        
Elapsed time: 5.02087s