Functional tests

Author: tobywf

README.md

@@ -1,9 +1,11 @@
 # XML dataclasses
 
-This is a very rough prototype of how a library might look like for (de)serialising XML into dataclasses. XML dataclasses build on normal dataclasses from the standard library and [`lxml`](https://pypi.org/project/lxml/) elements. Loading and saving these elements is left to the consumer for flexibility of the desired output.
+This is a very rough prototype of how a library might look like for (de)serialising XML into  Python dataclasses. XML dataclasses build on normal dataclasses from the standard library and [`lxml`](https://pypi.org/project/lxml/) elements. Loading and saving these elements is left to the consumer for flexibility of the desired output.
 
 It isn't ready for production if you aren't willing to do your own evaluation/quality assurance. I don't recommend using this library with untrusted content. It inherits all of `lxml`'s flaws with regards to XML attacks, and recursively resolves data structures. Because deserialisation is driven from the dataclass definitions, it shouldn't be possible to execute arbitrary Python code. But denial of service attacks would very likely be feasible.
 
+Requires Python 3.7 or higher.
+
 ## Example
 
 (This is a simplified real world example - the container can also include optional `links` child elements.)
@@ -42,14 +44,16 @@ class Container:
     __ns__ = CONTAINER_NS
     version: str = attr()
     rootfiles: RootFiles = child()
+    # WARNING: this is an incomplete implementation of an OPF container
+    # (it's missing links)
 
 
 if __name__ == "__main__":
     nsmap = {None: CONTAINER_NS}
     lxml_el_in = etree.parse("container.xml").getroot()
     container = load(Container, lxml_el_in, "container")
     lxml_el_out = dump(container, "container", nsmap)
-    print(etree.tounicode(lxml_el_out, pretty_print=True))
+    print(etree.tostring(lxml_el_out, encoding="unicode", pretty_print=True))
 ```
 
 ## Features
@@ -75,3 +79,35 @@ Most of these limitations/assumptions are enforced. They may make this project u
 * Deserialisation is strict; missing required attributes and child elements will cause an error
 * Unions of types aren't yet supported
 * Dataclasses must be written by hand, no tools are provided to generate these from, DTDs, XML schema definitions, or RELAX NG schemas
+
+## Development
+
+This project uses [pre-commit](https://pre-commit.com/) to run some linting hooks when committing. When you first clone the repo, please run:
+
+```
+pre-commit install
+```
+
+You may also run the hooks at any time:
+
+```
+pre-commit run --all-files
+```
+
+Dependencies are managed via [poetry](https://python-poetry.org/). To install all dependencies, use:
+
+```
+poetry install
+```
+
+This will also install development dependencies such as `black`, `isort`, `pylint`, `mypy`, and `pytest`. I've provided a simple script to run these during development called `lint`. You can either run it from a shell session with the poetry-installed virtual environment, or run as follows:
+
+```
+poetry run ./lint
+```
+
+Auto-formatters will be applied, and static analysis/tests are run in order. The script stops on failure to allow quick iteration.
+
+## License
+
+This library is licensed under the Mozilla Public License Version 2.0. For more information, see `LICENSE`.

functional/container.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0"?>
+<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container" version="1.0">
+  <rootfiles>
+    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
+  </rootfiles>
+</container>

functional/container_test.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+from typing import List
+
+from lxml import etree
+
+from xml_dataclasses import attr, child, dump, load, xml_dataclass
+
+BASE = Path(__file__).resolve(strict=True).parent
+
+CONTAINER_NS = "urn:oasis:names:tc:opendocument:xmlns:container"
+
+
+@xml_dataclass
+class RootFile:
+    __ns__ = CONTAINER_NS
+    full_path: str = attr(rename="full-path")
+    media_type: str = attr(rename="media-type")
+
+
+@xml_dataclass
+class RootFiles:
+    __ns__ = CONTAINER_NS
+    rootfile: List[RootFile] = child()
+
+
+@xml_dataclass
+class Container:
+    __ns__ = CONTAINER_NS
+    version: str = attr()
+    rootfiles: RootFiles = child()
+    # WARNING: this is an incomplete implementation of an OPF container
+    # (it's missing links)
+
+
+def lmxl_dump(el):
+    encoded = etree.tostring(
+        el, encoding="utf-8", pretty_print=True, xml_declaration=True
+    )
+    return encoded.decode("utf-8")
+
+
+def test_functional_container():
+    el = etree.parse(str(BASE / "container.xml")).getroot()
+    original = lmxl_dump(el)
+    container = load(Container, el, "container")
+    assert container == Container(
+        version="1.0",
+        rootfiles=RootFiles(
+            rootfile=[
+                RootFile(
+                    full_path="OEBPS/content.opf",
+                    media_type="application/oebps-package+xml",
+                ),
+            ],
+        ),
+    )
+    el = dump(container, "container", {None: CONTAINER_NS})
+    roundtrip = lmxl_dump(el)
+    assert original == roundtrip

lint

@@ -1,10 +1,25 @@
 #!/bin/sh
 set -ex
-isort --recursive src/ tests/
-black src/ tests/
+
+if [ -n "$1" ]; then
+  ISORT_CHECK="--check-only"
+  BLACK_CHECK="--check"
+  PYTEST_DEBUG=""
+else
+  ISORT_CHECK=""
+  BLACK_CHECK=""
+  PYTEST_DEBUG="-s --pdb --pdbcls=IPython.terminal.debugger:Pdb"
+fi
+
+isort --recursive $ISORT_CHECK src/ tests/ functional/
+black $BLACK_CHECK src/ tests/ functional/
 mypy src/xml_dataclasses/ --strict
 pylint src/
-
-set +e
-pytest tests/ --cov=xml_dataclasses -s --pdb --pdbcls=IPython.terminal.debugger:Pdb
-coverage html
+# always output coverage report
+if pytest tests/ --cov=xml_dataclasses --random-order $PYTEST_DEBUG; then
+  coverage html
+else
+  coverage html
+  exit 1
+fi
+pytest functional/ --random-order $PYTEST_DEBUG

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "xml_dataclasses"
-version = "0.0.1"
+version = "0.0.2"
 description = "(De)serialize XML documents into specially-annotated dataclasses"
 authors = ["Toby Fleming <tobywf@users.noreply.github.com>"]
 license = "MPL-2.0"
@@ -31,6 +31,7 @@ pytest-cov = "^2.8.1"
 mypy = "^0.761"
 ipython = "^7.12.0"
 coverage = {extras = ["toml"], version = "^5.0.3"}
+pytest-random-order = "^1.0.4"
 
 [tool.isort]
 # see https://black.readthedocs.io/en/stable/the_black_code_style.html

tests/dump_test.py

@@ -56,7 +56,7 @@ class Foo:
 
     foo = Foo(bar="baz")
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == '<foo bar="baz"/>'
 
 
@@ -68,7 +68,7 @@ class Foo:
 
     foo = Foo(bar="baz")
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == '<foo bar="baz"/>'
 
 
@@ -80,7 +80,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo/>"
 
 
@@ -92,7 +92,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == '<foo bar="baz"/>'
 
 
@@ -104,7 +104,7 @@ class Foo:
 
     foo = Foo(value="bar")
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo>bar</foo>"
 
 
@@ -116,7 +116,7 @@ class Foo:
 
     foo = Foo(value="bar")
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo>bar</foo>"
 
 
@@ -128,7 +128,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo/>"
 
 
@@ -140,7 +140,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo>bar</foo>"
 
 
@@ -152,7 +152,7 @@ class Foo:
 
     foo = Foo(bar=Child())
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo><bar/></foo>"
 
 
@@ -164,7 +164,7 @@ class Foo:
 
     foo = Foo(bar=Child())
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo><bar/></foo>"
 
 
@@ -176,7 +176,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo/>"
 
 
@@ -188,7 +188,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo><bar/></foo>"
 
 
@@ -200,7 +200,7 @@ class Foo:
 
     foo = Foo(bar=[Child()])
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo><bar/></foo>"
 
 
@@ -212,7 +212,7 @@ class Foo:
 
     foo = Foo(bar=[Child(), Child()])
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo><bar/><bar/></foo>"
 
 
@@ -224,7 +224,7 @@ class Foo:
 
     foo = Foo(bar=[Child(), Child()])
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo><bar/><bar/></foo>"
 
 
@@ -236,7 +236,7 @@ class Foo:
 
     foo = Foo()
     el = dump(foo, "foo", None)
-    xml = etree.tounicode(el)
+    xml = etree.tostring(el, encoding="unicode")
     assert xml == "<foo/>"
 
 
@@ -249,6 +249,6 @@ def test_dump_children_multiple_missing_default():
 
     # foo = Foo()
     # el = dump(foo, "foo", None)
-    # xml = etree.tounicode(el)
+    # xml = etree.tostring(el, encoding="unicode")
     # assert xml == "<foo><bar/><bar/></foo>"
     pass