From: Raphael Michel <mail@raphaelmichel.de>
Date: Tue, 16 Oct 2018 05:49:33 +0000 (+0200)
Subject: Add a README
X-Git-Tag: 1.0.0~10
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=01c3bdb9741c0dc8719b7d83afde4b87338807b5;p=thirdparty%2Fpython-drafthorse.git

Add a README
---

diff --git a/README.rst b/README.rst
index bed8409..899b150 100644
--- a/README.rst
+++ b/README.rst
@@ -1,36 +1,55 @@
 drafthorse -- Basic ZUGFeRD implementation in Python
 ====================================================
 
-.. image:: https://travis-ci.org/pretix/drafthorse.svg?branch=master
-   :target: https://travis-ci.org/pretix/drafthorse
+.. image:: https://travis-ci.org/pretix/python-drafthorse.svg?branch=master
+   :target: https://travis-ci.org/pretix/python-drafthorse
 
-.. image:: https://codecov.io/gh/pretix/drafthorse/branch/master/graph/badge.svg
+.. 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 python implementation to generate the required XML for ZUGFeRD files
+This is a low-level python implementation of the ZUGFeRD XML format. ZUGFeRD is a German
+format for sending digital invoices. ZUGFeRD XML files can are to be attached to a PDF
+file, which can be done using the ``factur-x`` Python library. This library can be used to generate or parse the contents of this XML file.
 
-Limitations
------------
-
-Currently write-only.
-
-Supported standards:
+By low-level, we mean that this library models the ZUGFeRD data model 1:1 without any further
+abstractions or simplifications. You can set and parse all parameters defined in ZUGFeRD 1.0.
 
-* ZUGFeRD 1.0
-
-Supported profiles:
-
-* Basic
+All output is validated against the official XSDs, but no validation of profile levels (basic, comfort, extended) is performed.
 
 Usage
 -----
 
-Example:
-
-TBD
+Parsing::
+
+    >>> from drafthorse.models.document import Document
+    >>> samplexml = open("sample.xml", "rb").read()
+    >>> doc = Document.parse(samplexml)
+    >>> str(doc.trade.agreement.seller.name)
+    'Lieferant GmbH'
+
+Generating::
+
+    >>> from datetime import Date
+    >>> from drafthorse.models.document import Document
+    >>> from drafthorse.models.note import IncludedNote
+
+    >>> doc = Document()
+    >>> doc.context.guideline_parameter.id = "urn:ferd:CrossIndustryDocument:invoice:1p0:comfort"
+    >>> doc.header.id = "RE1337"
+    >>> doc.header.name = "RECHNUNG"
+    >>> doc.header.type_code = "380"
+    >>> doc.header.issue_date_time.value = date.today()
+    >>> doc.header.languages.add("de")
+    >>> note = IncludedNote()
+    >>> note.content.add("Test Node 1")
+    >>> doc.header.notes.add(n)
+    >>> doc.trade.agreement.seller.name = "Lieferant GmbH"
+
+    >>> doc.serialize()
+    b'<?xml version="1.0" encoding="UTF-8"?><rsm:CrossIndustryDocument …'
 
 
 Development
diff --git a/drafthorse/models/elements.py b/drafthorse/models/elements.py
index 6525fa2..8ffd4ab 100644
--- a/drafthorse/models/elements.py
+++ b/drafthorse/models/elements.py
@@ -100,6 +100,9 @@ class StringElement(Element):
         self.tag = tag
         self.text = text
 
+    def __repr__(self):
+        return '<{}: {}>'.format(type(self).__name__, str(self))
+
     def __str__(self):
         return self.text
 
diff --git a/setup.py b/setup.py
index d6d2e25..be93887 100644
--- a/setup.py
+++ b/setup.py
@@ -38,5 +38,5 @@ setup(
                          'lxml'
                      ] + (['isoweek'] if sys.version_info < (3, 6) else []),
 
-    packages=find_packages(include=['sepadd', 'sepadd.*']),
+    packages=find_packages(include=['drafthorse', 'drafthorse.*']),
 )