Merge pull request #112 from dapper91/dev

- model level skip_empty parameter added.
- wrapped element extra entities checking bugs fixed.

Author: dapper91

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+2.2.1 (2023-09-12)
+------------------
+
+- model level `skip_empty` parameter added.
+- wrapped element extra entities checking bugs fixed.
+
+
 2.2.0 (2023-09-07)
 ------------------
 

docs/source/pages/misc.rst

@@ -70,6 +70,25 @@ or drop ``None`` fields at all:
     assert company.to_xml(skip_empty=True) == b'<Company/>'
 
 
+Empty entities exclusion
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to exclude all empty entities from the resulting xml document at once. To do that
+just pass ``skip_empty=True`` parameter to :py:meth:`pydantic_xml.BaseXmlModel.to_xml` during serialization.
+That parameter is applied to the root model and all its sub-models by default. But it can be adjusted
+for a particular model during its declaration as illustrated in the following example:
+
+.. literalinclude:: ../../../examples/snippets/skip_empty.py
+    :language: python
+    :start-after: model-start
+    :end-before: model-end
+
+.. literalinclude:: ../../../examples/snippets/skip_empty.py
+    :language: xml
+    :lines: 2-
+    :start-after: xml-start
+    :end-before: xml-end
+
 
 Default namespace
 ~~~~~~~~~~~~~~~~~

examples/snippets/skip_empty.py

@@ -0,0 +1,50 @@
+from typing import Literal, Optional, Tuple
+from xml.etree.ElementTree import canonicalize
+
+from pydantic_xml import BaseXmlModel, attr, element
+
+
+# [model-start]
+class Product(BaseXmlModel, tag='Product', skip_empty=True):
+    status: Optional[Literal['running', 'development']] = attr(default=None)
+    launched: Optional[int] = attr(default=None)
+    title: Optional[str] = element(tag='Title', default=None)
+
+
+class Company(BaseXmlModel, tag='Company'):
+    trade_name: str = attr(name='trade-name')
+    website: str = element(tag='WebSite', default='')
+
+    products: Tuple[Product, ...] = element()
+
+
+company = Company(
+    trade_name="SpaceX",
+    products=[
+        Product(status="running", launched=2013, title="Several launch vehicles"),
+        Product(status="running", title="Starlink"),
+        Product(status="development"),
+        Product(),
+    ],
+)
+# [model-end]
+
+
+# [xml-start]
+xml_doc = '''
+<Company trade-name="SpaceX">
+    <WebSite /><!--Company empty elements are not excluded-->
+
+    <!--Product empty sub-elements and attributes are excluded-->
+    <Product status="running" launched="2013">
+        <Title>Several launch vehicles</Title>
+    </Product>
+    <Product status="running">
+        <Title>Starlink</Title>
+    </Product>
+    <Product status="development"/>
+    <Product />
+</Company>
+'''  # [xml-end]
+
+assert canonicalize(company.to_xml(), strip_text=True) == canonicalize(xml_doc, strip_text=True)

pydantic_xml/element/element.py

@@ -1,6 +1,6 @@
 import abc
 from enum import Enum
-from typing import Any, Callable, Dict, Generic, List, Optional, Sequence, TypeVar
+from typing import Any, Callable, Dict, Generic, List, Optional, Sequence, Tuple, TypeVar
 
 from pydantic_xml.typedefs import NsMap
 
@@ -52,14 +52,6 @@ def find_element(
         :return: xml element
         """
 
-    @abc.abstractmethod
-    def get_text(self) -> Optional[str]:
-        """
-        Returns the element text.
-
-        :return: element text
-        """
-
     @abc.abstractmethod
     def pop_text(self) -> Optional[str]:
         """
@@ -78,14 +70,6 @@ def pop_attrib(self, name: str) -> Optional[str]:
         :return: element attribute
         """
 
-    @abc.abstractmethod
-    def get_attributes(self) -> Optional[Dict[str, str]]:
-        """
-        Returns the element attributes.
-
-        :return: element attributes
-        """
-
     @abc.abstractmethod
     def pop_attributes(self) -> Optional[Dict[str, str]]:
         """
@@ -115,14 +99,6 @@ def find_sub_element(self, path: Sequence[str], search_mode: 'SearchMode') -> Op
         :return: found element or `None`
         """
 
-    @abc.abstractmethod
-    def get_elements(self) -> Optional[List['XmlElement[Any]']]:
-        """
-        Returns the element sub-elements.
-
-        :return: sub-element
-        """
-
     @abc.abstractmethod
     def create_snapshot(self) -> 'XmlElement[Any]':
         """
@@ -145,6 +121,14 @@ def to_native(self) -> Any:
         :return: native element
         """
 
+    @abc.abstractmethod
+    def get_unbound(self) -> List[Tuple[Tuple[str, ...], str]]:
+        """
+        Returns unbound entities.
+
+        :return: list of unbound entities
+        """
+
 
 class XmlElementWriter(abc.ABC):
     """
@@ -251,7 +235,7 @@ def __init__(
             self.elements = elements
             self.next_element_idx = next_element_idx
 
-    __slots__ = ('_tag', '_nsmap')
+    __slots__ = ('_tag', '_nsmap', '_state')
 
     @classmethod
     @abc.abstractmethod
@@ -337,9 +321,6 @@ def append_element(self, element: 'XmlElement[NativeElement]') -> None:
     def get_attrib(self, name: str) -> Optional[str]:
         return self._state.attrib.get(name, None) if self._state.attrib else None
 
-    def get_text(self) -> Optional[str]:
-        return self._state.text
-
     def pop_text(self) -> Optional[str]:
         result, self._state.text = self._state.text, None
 
@@ -348,9 +329,6 @@ def pop_text(self) -> Optional[str]:
     def pop_attrib(self, name: str) -> Optional[str]:
         return self._state.attrib.pop(name, None) if self._state.attrib else None
 
-    def get_attributes(self) -> Optional[Dict[str, str]]:
-        return self._state.attrib
-
     def pop_attributes(self) -> Optional[Dict[str, str]]:
         result, self._state.attrib = self._state.attrib, None
 
@@ -395,8 +373,20 @@ def find_element(
 
         return searcher(self._state, tag, look_behind, step_forward)
 
-    def get_elements(self) -> Optional[List['XmlElement[NativeElement]']]:
-        return self._state.elements[self._state.next_element_idx:]
+    def get_unbound(self, path: Tuple[str, ...] = ()) -> List[Tuple[Tuple[str, ...], str]]:
+        result: List[Tuple[Tuple[str, ...], str]] = []
+
+        if self._state.text and (text := self._state.text.strip()):
+            result.append((path, text))
+
+        if attrs := self._state.attrib:
+            for name, value in attrs.items():
+                result.append((path + (f'@{name}',), value))
+
+        for sub_element in self._state.elements:
+            result.extend(sub_element.get_unbound(path + (sub_element.tag,)))
+
+        return result
 
 
 class SearchMode(str, Enum):

pydantic_xml/model.py

@@ -233,6 +233,7 @@ class BaseXmlModel(BaseModel, __xml_abstract__=True, metaclass=XmlModelMeta):
     __xml_ns__: ClassVar[Optional[str]]
     __xml_nsmap__: ClassVar[Optional[NsMap]]
     __xml_ns_attrs__: ClassVar[bool]
+    __xml_skip_empty__: ClassVar[Optional[bool]]
     __xml_search_mode__: ClassVar[SearchMode]
     __xml_serializer__: ClassVar[Optional[BaseModelSerializer]] = None
 
@@ -242,6 +243,7 @@ def __init_subclass__(
             ns: Optional[str] = None,
             nsmap: Optional[NsMap] = None,
             ns_attrs: Optional[bool] = None,
+            skip_empty: Optional[bool] = None,
             search_mode: Optional[SearchMode] = None,
             **kwargs: Any,
     ):
@@ -261,6 +263,7 @@ def __init_subclass__(
         cls.__xml_ns__ = ns if ns is not None else getattr(cls, '__xml_ns__', None)
         cls.__xml_nsmap__ = nsmap if nsmap is not None else getattr(cls, '__xml_nsmap__', None)
         cls.__xml_ns_attrs__ = ns_attrs if ns_attrs is not None else getattr(cls, '__xml_ns_attrs__', False)
+        cls.__xml_skip_empty__ = skip_empty if skip_empty is not None else getattr(cls, '__xml_skip_empty__', None)
         cls.__xml_search_mode__ = search_mode if search_mode is not None \
             else getattr(cls, '__xml_search_mode__', SearchMode.STRICT)
 

pydantic_xml/serializers/factories/model.py

@@ -31,33 +31,14 @@ def nsmap(self) -> Optional[NsMap]: ...
     def _check_extra(cls, error_title: str, element: XmlElementReader) -> None:
         line_errors: List[pdc.InitErrorDetails] = []
 
-        if (text := element.get_text()) is not None:
-            if text := text.strip():
-                line_errors.append(
-                    pdc.InitErrorDetails(
-                        type='extra_forbidden',
-                        loc=('<text>',),
-                        input=text,
-                    ),
-                )
-        if extra_attrs := element.get_attributes():
-            for name, value in extra_attrs.items():
-                line_errors.append(
-                    pdc.InitErrorDetails(
-                        type='extra_forbidden',
-                        loc=(f'<attr> {name}',),
-                        input=value,
-                    ),
-                )
-        if extra_elements := element.get_elements():
-            for extra_element in extra_elements:
-                line_errors.append(
-                    pdc.InitErrorDetails(
-                        type='extra_forbidden',
-                        loc=(f'<element> {extra_element.tag}',),
-                        input=extra_element.get_text(),
-                    ),
-                )
+        for path, value in element.get_unbound():
+            line_errors.append(
+                pdc.InitErrorDetails(
+                    type='extra_forbidden',
+                    loc=path,
+                    input=value,
+                ),
+            )
 
         if line_errors:
             raise pd.ValidationError.from_exception_data(title=error_title, line_errors=line_errors)
@@ -171,6 +152,9 @@ def serialize(
         if value is None:
             return None
 
+        if self._model.__xml_skip_empty__ is not None:
+            skip_empty = self._model.__xml_skip_empty__
+
         for field_name, field_serializer in self._field_serializers.items():
             if field_name not in self._fields_serialization_exclude:
                 field_serializer.serialize(
@@ -264,6 +248,9 @@ def serialize(
         if value is None:
             return None
 
+        if self._model.__xml_skip_empty__ is not None:
+            skip_empty = self._model.__xml_skip_empty__
+
         self._root_serializer.serialize(element, getattr(value, 'root'), encoded, skip_empty=skip_empty)
 
         return element

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pydantic-xml"
-version = "2.2.0"
+version = "2.2.1"
 description = "pydantic xml extension"
 authors = ["Dmitry Pershin <dapper1291@gmail.com>"]
 license = "Unlicense"