Optionally ignore unknown attributes and children (#8)

Author: tobywf

README.md

@@ -27,7 +27,6 @@ Requires Python 3.7 or higher.
 
 * Whitespace and comments aren't supported in the data model. They must be stripped when loading the XML
 * So far, I haven't found any examples where XML can't be mapped to a dataclass, but it's likely possible given how complex XML is
-* Strict mapping. Currently, if an unknown element is encountered, an error is raised (see [#3](https://github.com/tobywf/xml_dataclasses/issues/3), pull requests welcome)
 * No typing/type conversions. Since XML is untyped, only string values are currently allowed. Type conversions are tricky to implement in a type-safe and extensible manner.
 * Dataclasses must be written by hand, no tools are provided to generate these from, DTDs, XML schema definitions, or RELAX NG schemas
 
@@ -54,6 +53,8 @@ class Foo:
 
 For now, you can work around this limitation with properties that do the conversion, and perform post-load validation.
 
+By default, unknown attributes raise an error. This can be disabled by passing `Options` to `load` with `ignore_unknown_attributes`.
+
 ### Defining text
 
 Like attributes, text can be either `str` or `Optional[str]`. You must declare text content with the `text` function. Similar to `rename`, this function can use an existing field definition, or take the `default` argument. Text cannot be renamed or namespaced. Every class can only have one field defining text content. If a class has text content, it cannot have any children.
@@ -87,6 +88,8 @@ If a class has children, it cannot have text content.
 
 Children can be renamed via the `rename` function. However, attempting to set a namespace is invalid, since the namespace is provided by the child type's XML dataclass. Also, unions of XML dataclasses must have the same namespace (you can use different fields with renaming if they have different namespaces, since the XML names will be resolved as a combination of namespace and name).
 
+By default, unknown children raise an error. This can be disabled by passing `Options` to `load` with `ignore_unknown_children`.
+
 ### Defining post-load validation
 
 Simply implement an instance method called `xml_validate` with no parameters, and no return value (if you're using type hints):
@@ -216,6 +219,7 @@ This makes sense in many cases, but possibly not every case.
 ### [0.0.7] - unreleased
 
 * Warn if comments are found/don't treat comments as child elements in error messages
+* Allow lenient loading of undeclared attributes or children
 
 ### [0.0.6] - 2020-03-25
 

src/xml_dataclasses/__init__.py

@@ -2,6 +2,7 @@
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
+from .options import Options  # isort:skip
 from .modifiers import rename, text, ignored  # isort:skip
 from .resolve_types import (  # isort:skip
     is_xml_dataclass,

src/xml_dataclasses/options.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Options:
+    ignore_unknown_attributes: bool = False
+    ignore_unknown_children: bool = False

src/xml_dataclasses/serde.py

@@ -7,6 +7,7 @@
 from lxml.etree import _Comment as Comment  # type: ignore
 
 from .lxml_utils import strip_ns
+from .options import Options
 from .resolve_types import (
     ChildInfo,
     TextInfo,
@@ -18,7 +19,9 @@
 _T = TypeVar("_T")
 
 
-def _load_attributes(cls: Type[XmlDataclass], el: Any) -> Mapping[str, str]:
+def _load_attributes(
+    cls: Type[XmlDataclass], el: Any, options: Options
+) -> Mapping[str, str]:
     values = {}
     processed = set()
 
@@ -37,7 +40,7 @@ def _load_attributes(cls: Type[XmlDataclass], el: Any) -> Mapping[str, str]:
         values[attr.dt_name] = attr_value
 
     unprocessed = set(el.attrib.keys()) - processed
-    if unprocessed:
+    if unprocessed and not options.ignore_unknown_attributes:
         readable = ", ".join(f"'{v}'" for v in unprocessed)
         raise ValueError(f"Found undeclared attributes on '{el.tag}': {readable}")
 
@@ -60,7 +63,9 @@ def _load_text(info: TextInfo, el: Any) -> Mapping[str, str]:
     return {info.dt_name: text}
 
 
-def _load_children(cls: Type[XmlDataclass], el: Any) -> Mapping[str, XmlDataclass]:
+def _load_children(
+    cls: Type[XmlDataclass], el: Any, options: Options
+) -> Mapping[str, XmlDataclass]:
     if el.text and el.text.strip():
         raise ValueError(f"Element '{el.tag}' has text (expected child elements only)")
 
@@ -126,7 +131,7 @@ def _get_one_child_value(child: ChildInfo) -> Any:
         values[child.dt_name] = child_value
 
     unprocessed = el_children.keys() - processed
-    if unprocessed:
+    if unprocessed and not options.ignore_unknown_children:
         readable = ", ".join(f"'{v}'" for v in unprocessed)
         raise ValueError(f"Found undeclared child elements on '{el.tag}': {readable}")
 
@@ -144,20 +149,26 @@ def _validate_name(cls: Type[XmlDataclass], el: Any, name: str) -> None:
 
 
 def load(
-    cls: Type[XmlDataclassInstance], el: Any, name: Optional[str] = None
+    cls: Type[XmlDataclassInstance],
+    el: Any,
+    name: Optional[str] = None,
+    options: Optional[Options] = None,
 ) -> XmlDataclassInstance:
     if not is_xml_dataclass(cls):
         raise ValueError(f"Class '{cls!r}' is not an XML dataclass")
 
+    if not options:
+        options = Options()
+
     if name:
         _validate_name(cls, el, name)
 
-    attr_values = _load_attributes(cls, el)
+    attr_values = _load_attributes(cls, el, options)
     # are we just looking for text content?
     if cls.__text_field__:
         text_values = _load_text(cls.__text_field__, el)
     else:
-        child_values = _load_children(cls, el)
+        child_values = _load_children(cls, el, options)
 
     if cls.__text_field__:
         child_values = {}

tests/load_test.py

@@ -5,7 +5,7 @@
 from lxml import etree
 
 # test public exports
-from xml_dataclasses import load, text, xml_dataclass
+from xml_dataclasses import Options, load, text, xml_dataclass
 
 NS = "https://tobywf.com"
 
@@ -135,7 +135,7 @@ class Foo:
     assert foo.bar == "baz"
 
 
-def test_load_attributes_undeclared():
+def test_load_attributes_undeclared_strict():
     @xml_dataclass
     class Foo:
         __ns__ = None
@@ -150,6 +150,16 @@ class Foo:
     assert "'bar'" in msg
 
 
+def test_load_attributes_undeclared_lenient():
+    @xml_dataclass
+    class Foo:
+        __ns__ = None
+
+    el = etree.fromstring('<foo bar="baz" />')
+    options = Options(ignore_unknown_attributes=True)
+    load(Foo, el, "foo", options)
+
+
 def test_load_text_present_required():
     @xml_dataclass
     class Foo:
@@ -290,7 +300,7 @@ class Foo:
     assert foo.bar is None
 
 
-def test_load_children_single_undeclared():
+def test_load_children_single_undeclared_strict():
     @xml_dataclass
     class Foo:
         __ns__ = None
@@ -305,6 +315,16 @@ class Foo:
     assert "'bar'" in msg
 
 
+def test_load_children_single_undeclared_lenient():
+    @xml_dataclass
+    class Foo:
+        __ns__ = None
+
+    el = etree.fromstring("<foo><bar /></foo>")
+    options = Options(ignore_unknown_children=True)
+    load(Foo, el, "foo", options)
+
+
 def test_load_children_single_multiple_els():
     @xml_dataclass
     class Foo: