Support for unions

Author: tobywf

README.md

@@ -65,6 +65,19 @@ if __name__ == "__main__":
 * Lists of child elements are supported
 * Inheritance does work, but has the same limitations as dataclasses. Inheriting from base classes with required fields and declaring optional fields doesn't work due to field order. This isn't recommended
 * Namespace support is decent as long as correctly declared. I've tried on several real-world examples, although they were known to be valid. `lxml` does a great job at expanding namespace information when loading and simplifying it when saving
+* Union child types are supported. When loading XML, they are attempted to be parsed in order
+
+## Gotchas
+
+### Whitespace
+
+If you are able to, it is strongly recommended you strip whitespace from the input via `lxml`:
+
+```python
+parser = etree.XMLParser(remove_blank_text=True)
+```
+
+By default, `lxml` preserves whitespace. This can cause a problem when checking if elements have no text. The library does attempt to strip these; literally via Python's `strip()`. But `lxml` is likely faster and more robust.
 
 ## Limitations and Assumptions
 
@@ -77,8 +90,8 @@ Most of these limitations/assumptions are enforced. They may make this project u
 * It isn't possible to pass any parameters to the wrapped `@dataclass` decorator
 * Some properties of dataclass `field`s are not exposed: `default_factory`, `repr`, `hash`, `init`, `compare`. For most, it is because I don't understand the implications fully or how that would be useful for XML. `default_factory` is hard only because of [the overloaded type signatures](https://github.com/python/typeshed/blob/master/stdlib/3.7/dataclasses.pyi), and getting that to work with `mypy`
 * Deserialisation is strict; missing required attributes and child elements will cause an error. I want this to be the default behaviour, but it should be straightforward to add a parameter to `load` for lenient operation
-* 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
+* Union types must have the same element/tag name and namespace. Otherwise, two different dataclass attributes (XML child fields) may be used
 
 ## Development
 

functional/__init__.py

@@ -1,10 +1,12 @@
 from pathlib import Path
 from typing import List
-
+import pytest
 from lxml import etree
 
 from xml_dataclasses import attr, child, dump, load, xml_dataclass
 
+from .utils import lmxl_dump
+
 BASE = Path(__file__).resolve(strict=True).parent
 
 CONTAINER_NS = "urn:oasis:names:tc:opendocument:xmlns:container"
@@ -32,15 +34,10 @@ class 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()
+@pytest.mark.parametrize("remove_blank_text", [True, False])
+def test_functional_container_no_whitespace(remove_blank_text):
+    parser = etree.XMLParser(remove_blank_text=remove_blank_text)
+    el = etree.parse(str(BASE / "container.xml"), parser).getroot()
     original = lmxl_dump(el)
     container = load(Container, el, "container")
     assert container == Container(

functional/container_test.py

@@ -0,0 +1,65 @@
+<?xml version='1.0' encoding='utf-8'?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0" unique-identifier="13b2938e-05ad-4096-abde-0f377b895d61" xml:lang="en">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="13b2938e-05ad-4096-abde-0f377b895d61">13b2938e-05ad-4096-abde-0f377b895d61</dc:identifier>
+    <dc:title>XML dataclass test</dc:title>
+    <dc:language>en</dc:language>
+    <meta content="cover-image" name="cover"/>
+    <meta property="dcterms:modified">2020-02-02T12:00:00Z</meta>
+  </metadata>
+  <manifest>
+    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
+    <item id="cover" href="xhtml/cover.html" media-type="application/xhtml+xml"/>
+    <item id="title" href="xhtml/title.html" media-type="application/xhtml+xml"/>
+    <item id="dedication" href="xhtml/dedication.html" media-type="application/xhtml+xml"/>
+    <item id="contents" href="xhtml/contents.html" media-type="application/xhtml+xml"/>
+    <item id="intro" href="xhtml/intro.html" media-type="application/xhtml+xml"/>
+    <item id="ch01" href="xhtml/ch01.html" media-type="application/xhtml+xml"/>
+    <item id="ch02" href="xhtml/ch02.html" media-type="application/xhtml+xml"/>
+    <item id="ch03" href="xhtml/ch03.html" media-type="application/xhtml+xml"/>
+    <item id="ch04" href="xhtml/ch04.html" media-type="application/xhtml+xml"/>
+    <item id="ch05" href="xhtml/ch05.html" media-type="application/xhtml+xml"/>
+    <item id="ch06" href="xhtml/ch06.html" media-type="application/xhtml+xml"/>
+    <item id="ch07" href="xhtml/ch07.html" media-type="application/xhtml+xml"/>
+    <item id="ch08" href="xhtml/ch08.html" media-type="application/xhtml+xml"/>
+    <item id="ch09" href="xhtml/ch09.html" media-type="application/xhtml+xml"/>
+    <item id="ch10" href="xhtml/ch10.html" media-type="application/xhtml+xml"/>
+    <item id="ch11" href="xhtml/ch11.html" media-type="application/xhtml+xml"/>
+    <item id="ch12" href="xhtml/ch12.html" media-type="application/xhtml+xml"/>
+    <item id="ch13" href="xhtml/ch13.html" media-type="application/xhtml+xml"/>
+    <item id="ch14" href="xhtml/ch14.html" media-type="application/xhtml+xml"/>
+    <item id="ch15" href="xhtml/ch15.html" media-type="application/xhtml+xml"/>
+    <item id="ch16" href="xhtml/ch16.html" media-type="application/xhtml+xml"/>
+    <item id="ch17" href="xhtml/ch17.html" media-type="application/xhtml+xml"/>
+    <item id="ch18" href="xhtml/ch18.html" media-type="application/xhtml+xml"/>
+    <item id="ch19" href="xhtml/ch19.html" media-type="application/xhtml+xml"/>
+    <item id="ch20" href="xhtml/ch20.html" media-type="application/xhtml+xml"/>
+  </manifest>
+  <spine toc="ncx">
+    <itemref idref="cover"/>
+    <itemref idref="title"/>
+    <itemref idref="dedication"/>
+    <itemref idref="contents"/>
+    <itemref idref="intro"/>
+    <itemref idref="ch01"/>
+    <itemref idref="ch02"/>
+    <itemref idref="ch03"/>
+    <itemref idref="ch04"/>
+    <itemref idref="ch05"/>
+    <itemref idref="ch06"/>
+    <itemref idref="ch07"/>
+    <itemref idref="ch08"/>
+    <itemref idref="ch09"/>
+    <itemref idref="ch10"/>
+    <itemref idref="ch11"/>
+    <itemref idref="ch12"/>
+    <itemref idref="ch13"/>
+    <itemref idref="ch14"/>
+    <itemref idref="ch15"/>
+    <itemref idref="ch16"/>
+    <itemref idref="ch17"/>
+    <itemref idref="ch18"/>
+    <itemref idref="ch19"/>
+    <itemref idref="ch20"/>
+  </spine>
+</package>

functional/package.xml

@@ -0,0 +1,108 @@
+from enum import Enum
+from pathlib import Path
+from typing import List, Mapping, Optional, Union
+
+from lxml import etree
+
+from xml_dataclasses import attr, child, dump, load, text, xml_dataclass
+
+from .utils import lmxl_dump
+
+BASE = Path(__file__).resolve(strict=True).parent
+
+
+class NsMap(Enum):
+    xml = "http://www.w3.org/XML/1998/namespace"
+    opf = "http://www.idpf.org/2007/opf"
+    dc = "http://purl.org/dc/elements/1.1/"
+    dcterms = "http://purl.org/dc/terms/"
+
+    @classmethod
+    def to_dict(cls, default_ns: Optional[str] = None) -> Mapping[Optional[str], str]:
+        nsmap = dict(cls.__members__)
+        if default_ns:
+            nsmap[None] = default_ns
+        return nsmap
+
+
+@xml_dataclass
+class DublinCoreMd:
+    __ns__ = NsMap.dc.value
+    value: str = text()
+    id: Optional[str] = attr(default=None)
+
+
+@xml_dataclass
+class MdMeta3:
+    __ns__ = NsMap.opf.value
+
+    property: str = attr()
+    value: str = text()
+
+
+@xml_dataclass
+class MdMeta2:
+    __ns__ = NsMap.opf.value
+    content: str = attr()
+    name: str = attr()
+
+
+@xml_dataclass
+class Metadata3:
+    __ns__ = NsMap.opf.value
+
+    identifier: List[DublinCoreMd] = child()
+    title: List[DublinCoreMd] = child()
+    language: List[DublinCoreMd] = child()
+    meta: List[Union[MdMeta3, MdMeta2]] = child()
+
+
+@xml_dataclass
+class Item3:
+    __ns__ = NsMap.opf.value
+    id: str = attr()
+    href: str = attr()
+    media_type: str = attr(rename="media-type")
+
+
+@xml_dataclass
+class Manifest3:
+    __ns__ = NsMap.opf.value
+    item: List[Item3] = child()
+
+
+@xml_dataclass
+class ItemRef3:
+    __ns__ = NsMap.opf.value
+    idref: str = attr()
+    properties: Optional[str] = attr(default=None)
+
+
+@xml_dataclass
+class Spine3:
+    __ns__ = NsMap.opf.value
+    itemref: List[ItemRef3] = child()
+    toc: Optional[str] = attr(default=None)
+
+
+@xml_dataclass
+class Package3:
+    __ns__ = NsMap.opf.value
+    version: str = attr()
+    unique_identifier: str = attr(rename="unique-identifier")
+    metadata: Metadata3 = child()
+    manifest: Manifest3 = child()
+    spine: Spine3 = child()
+    id: Optional[str] = attr(default=None)
+    lang: Optional[str] = attr(default=None, namespace=NsMap.xml.value)
+    dir: Optional[str] = attr(default=None)
+
+
+def test_functional_package():
+    parser = etree.XMLParser(remove_blank_text=True)
+    el = etree.parse(str(BASE / "package.xml"), parser).getroot()
+    original = lmxl_dump(el)
+    package = load(Package3, el, "package")
+    el = dump(package, "package", NsMap.to_dict(NsMap.opf.value))
+    roundtrip = lmxl_dump(el)
+    assert original == roundtrip

functional/package_test.py

@@ -0,0 +1,8 @@
+from lxml import etree
+
+
+def lmxl_dump(el):
+    encoded = etree.tostring(
+        el, encoding="utf-8", pretty_print=True, xml_declaration=True
+    )
+    return encoded.decode("utf-8")

functional/utils.py

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "xml_dataclasses"
-version = "0.0.2"
+version = "0.0.3"
 description = "(De)serialize XML documents into specially-annotated dataclasses"
 authors = ["Toby Fleming <tobywf@users.noreply.github.com>"]
 license = "MPL-2.0"

pyproject.toml

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import Any, Dict, List, Mapping, Optional, Type, TypeVar
+from typing import Any, Dict, List, Mapping, Optional, Type, TypeVar, Union
 
 from lxml.builder import ElementMaker  # type: ignore
 
@@ -11,16 +11,6 @@
 _T = TypeVar("_T")
 
 
-def _unpack_child(info: ChildInfo[_T], value: Any, el_tag: str) -> Any:
-    if info.is_list:
-        return [load(info.base_type, v) for v in value]
-
-    if len(value) != 1:
-        raise ValueError(f"Multiple child elements '{info.xml_name}' in '{el_tag}'")
-
-    return load(info.base_type, value[0])
-
-
 def _load_attributes(cls: Type[XmlDataclass], el: Any) -> Mapping[str, str]:
     values = {}
     processed = set()
@@ -62,6 +52,9 @@ def _load_text(info: TextInfo[Any], el: Any) -> Mapping[str, str]:
 
 
 def _load_children(cls: Type[XmlDataclass], el: Any) -> Mapping[str, XmlDataclass]:
+    if el.text and el.text.strip():
+        raise ValueError(f"Element '{el.tag}' has text (expected child elements only)")
+
     # child elements can be duplicated
     el_children: Dict[str, List[Any]] = defaultdict(list)
     for e in el.iterchildren():
@@ -70,16 +63,54 @@ def _load_children(cls: Type[XmlDataclass], el: Any) -> Mapping[str, XmlDataclas
     values = {}
     processed = set()
 
-    for child in cls.__children__:
+    def _unpack_union_child(
+        child: ChildInfo[Any], value: Any
+    ) -> Union[XmlDataclass, List[XmlDataclass]]:
+        exceptions = []
+        # try to find one matching type
+        for base_type in child.base_types:
+            try:
+                return load(base_type, value)
+            except ValueError as e:
+                exceptions.append(e)
+
+        raise ValueError(
+            f"Invalid child elements found for '{child.dt_name}' in '{el.tag}':\n"
+            + "\n".join(str(e) for e in exceptions)
+        )
+
+    def _get_one_child_value(child: ChildInfo[Any]) -> Any:
         # defaultdict can't raise KeyError
         if child.xml_name in el_children:
-            child_value = _unpack_child(child, el_children[child.xml_name], el.tag)
+            value = el_children[child.xml_name]
         else:
-            if child.is_required:
+            if not child.is_required:
+                return child.field.default
+
+            raise ValueError(
+                f"Required child element '{child.xml_name}' not found in '{el.tag}'"
+            )
+
+        if not child.is_list:
+            if len(value) != 1:
                 raise ValueError(
-                    f"Required child element '{child.xml_name}' not found in '{el.tag}'"
+                    f"Multiple child elements '{child.xml_name}' in '{el.tag}'"
                 )
-            child_value = child.field.default
+            value = value[0]
+
+        if len(child.base_types) == 1:
+            # nice path for default use-case
+            base_type = child.base_types[0]
+            if child.is_list:
+                return [load(base_type, v) for v in value]
+            return load(base_type, value)
+
+        if child.is_list:
+            return [_unpack_union_child(child, v) for v in value]
+        return _unpack_union_child(child, value)
+
+    for child in cls.__children__:
+        child_value = _get_one_child_value(child)
         processed.add(child.xml_name)
         values[child.dt_name] = child_value