Merge pull request #205 from dapper91/dev

- exclude_none and exclude_unset serialization flags support added.

Author: dapper91

CHANGELOG.rst

@@ -1,14 +1,20 @@
 Changelog
 =========
 
+2.12.0 (2024-08-24)
+-------------------
+
+- exclude_none and exclude_unset serialization flags support added. See https://github.com/dapper91/pydantic-xml/pull/204.
+
+
 2.11.0 (2024-05-11)
-------------------
+-------------------
 
 - named tuple support added. See https://github.com/dapper91/pydantic-xml/issues/172
 
 
 2.10.0 (2024-05-09)
-------------------
+-------------------
 
 - dynamic model creation support added. See https://pydantic-xml.readthedocs.io/en/latest/pages/misc.html#dynamic-model-creation
 

docs/source/pages/misc.rst

@@ -97,6 +97,33 @@ for a particular model during its declaration as illustrated in the following ex
     :start-after: xml-start
     :end-before: xml-end
 
+It is also possible to exclude ``None`` values:
+
+.. literalinclude:: ../../../examples/snippets/exclude_none.py
+    :language: python
+    :start-after: model-start
+    :end-before: model-end
+
+.. literalinclude:: ../../../examples/snippets/exclude_none.py
+    :language: xml
+    :lines: 2-
+    :start-after: xml-start
+    :end-before: xml-end
+
+
+... or unset values:
+
+.. literalinclude:: ../../../examples/snippets/exclude_unset.py
+    :language: python
+    :start-after: model-start
+    :end-before: model-end
+
+.. literalinclude:: ../../../examples/snippets/exclude_unset.py
+    :language: xml
+    :lines: 2-
+    :start-after: xml-start
+    :end-before: xml-end
+
 
 Default namespace
 ~~~~~~~~~~~~~~~~~

examples/snippets/exclude_none.py

@@ -0,0 +1,26 @@
+from typing import Literal, Optional
+from xml.etree.ElementTree import canonicalize
+
+from pydantic_xml import BaseXmlModel, element
+
+
+# [model-start]
+class Product(BaseXmlModel, tag='Product'):
+    title: Optional[str] = element(tag='Title', default=None)
+    status: Optional[Literal['running', 'development']] = element(tag='Status', default=None)
+    launched: Optional[int] = element(tag='Launched', default=None)
+
+
+product = Product(title="Starlink", status=None)
+xml = product.to_xml(exclude_none=True)
+# [model-end]
+
+
+# [xml-start]
+xml_doc = '''
+<Product>
+    <Title>Starlink</Title>
+</Product>
+'''  # [xml-end]
+
+assert canonicalize(xml, strip_text=True) == canonicalize(xml_doc, strip_text=True)

examples/snippets/exclude_unset.py

@@ -0,0 +1,27 @@
+from typing import Literal, Optional
+from xml.etree.ElementTree import canonicalize
+
+from pydantic_xml import BaseXmlModel, element
+
+
+# [model-start]
+class Product(BaseXmlModel, tag='Product'):
+    title: Optional[str] = element(tag='Title', default=None)
+    status: Optional[Literal['running', 'development']] = element(tag='Status', default=None)
+    launched: Optional[int] = element(tag='Launched', default=None)
+
+
+product = Product(title="Starlink", status=None)
+xml = product.to_xml(exclude_unset=True)
+# [model-end]
+
+
+# [xml-start]
+xml_doc = '''
+<Product>
+    <Title>Starlink</Title>
+    <Status />
+</Product>
+'''  # [xml-end]
+
+assert canonicalize(xml, strip_text=True) == canonicalize(xml_doc, strip_text=True)

pydantic_xml/model.py

@@ -469,11 +469,15 @@ def from_xml(cls: Type[ModelT], source: Union[str, bytes], context: Optional[Dic
 
         return cls.from_xml_tree(etree.fromstring(source), context=context)
 
-    def to_xml_tree(self, *, skip_empty: bool = False) -> etree.Element:
+    def to_xml_tree(
+            self, *, skip_empty: bool = False, exclude_none: bool = False, exclude_unset: bool = False,
+    ) -> etree.Element:
         """
         Serializes the object to an xml tree.
 
         :param skip_empty: skip empty elements (elements without sub-elements, attributes and text, Nones)
+        :param exclude_none: exclude `None` values
+        :param exclude_unset: exclude values that haven't been explicitly set
         :return: object xml representation
         """
 
@@ -485,21 +489,31 @@ def to_xml_tree(self, *, skip_empty: bool = False) -> etree.Element:
                 self,
                 by_alias=False,
                 fallback=lambda obj: obj if not isinstance(obj, ElementT) else None,  # for raw fields support
-            ), skip_empty=skip_empty,
+            ),
+            skip_empty=skip_empty,
+            exclude_none=exclude_none,
+            exclude_unset=exclude_unset,
         )
 
         return root.to_native()
 
-    def to_xml(self, *, skip_empty: bool = False, **kwargs: Any) -> Union[str, bytes]:
+    def to_xml(
+            self, *, skip_empty: bool = False, exclude_none: bool = False, exclude_unset: bool = False, **kwargs: Any,
+    ) -> Union[str, bytes]:
         """
         Serializes the object to an xml string.
 
         :param skip_empty: skip empty elements (elements without sub-elements, attributes and text, Nones)
+        :param exclude_none: exclude `None` values
+        :param exclude_unset: exclude values that haven't been explicitly set
         :param kwargs: additional xml serialization arguments
         :return: object xml representation
         """
 
-        return etree.tostring(self.to_xml_tree(skip_empty=skip_empty), **kwargs)
+        return etree.tostring(
+            self.to_xml_tree(skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset),
+            **kwargs,
+        )
 
 
 @te.dataclass_transform(kw_only_default=True, field_specifiers=(attr, element, wrapped, pd.Field))

pydantic_xml/serializers/factories/heterogeneous.py

@@ -26,7 +26,14 @@ def __init__(self, model_name: str, computed: bool, inner_serializers: Tuple[Ser
         self._inner_serializers = inner_serializers
 
     def serialize(
-            self, element: XmlElementWriter, value: List[Any], encoded: List[Any], *, skip_empty: bool = False,
+            self,
+            element: XmlElementWriter,
+            value: List[Any],
+            encoded: List[Any],
+            *,
+            skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         if value is None:
             return element
@@ -38,7 +45,9 @@ def serialize(
             raise errors.SerializationError("value length is incorrect")
 
         for serializer, val, enc in zip(self._inner_serializers, value, encoded):
-            serializer.serialize(element, val, enc, skip_empty=skip_empty)
+            serializer.serialize(
+                element, val, enc, skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset,
+            )
 
         return element
 

pydantic_xml/serializers/factories/homogeneous.py

@@ -38,7 +38,14 @@ def __init__(self, model_name: str, computed: bool, inner_serializer: Serializer
         self._inner_serializer = inner_serializer
 
     def serialize(
-            self, element: XmlElementWriter, value: List[Any], encoded: List[Any], *, skip_empty: bool = False,
+            self,
+            element: XmlElementWriter,
+            value: List[Any],
+            encoded: List[Any],
+            *,
+            skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         if value is None:
             return element
@@ -50,7 +57,9 @@ def serialize(
             if skip_empty and val is None:
                 continue
 
-            self._inner_serializer.serialize(element, val, enc, skip_empty=skip_empty)
+            self._inner_serializer.serialize(
+                element, val, enc, skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset,
+            )
 
         return element
 

pydantic_xml/serializers/factories/mapping.py

@@ -32,6 +32,8 @@ def serialize(
             encoded: Dict[str, Any],
             *,
             skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         if value is None:
             return element
@@ -100,12 +102,16 @@ def serialize(
             encoded: Dict[str, Any],
             *,
             skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         if skip_empty and len(value) == 0:
             return element
 
         sub_element = element.make_element(self._element_name, nsmap=self._nsmap)
-        super().serialize(sub_element, value, encoded, skip_empty=skip_empty)
+        super().serialize(
+            sub_element, value, encoded, skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset,
+        )
         if skip_empty and sub_element.is_empty():
             return None
         else:

pydantic_xml/serializers/factories/model.py

@@ -158,6 +158,8 @@ def serialize(
             encoded: Dict[str, Any],
             *,
             skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         if value is None:
             return None
@@ -166,10 +168,17 @@ def serialize(
             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(
-                    element, getattr(value, field_name), encoded[field_name], skip_empty=skip_empty,
-                )
+            if field_name in self._fields_serialization_exclude:
+                continue
+            if exclude_unset and field_name not in value.__pydantic_fields_set__:
+                continue
+
+            field_serializer.serialize(
+                element, getattr(value, field_name), encoded[field_name],
+                skip_empty=skip_empty,
+                exclude_none=exclude_none,
+                exclude_unset=exclude_unset,
+            )
 
         return element
 
@@ -269,14 +278,24 @@ def serialize(
             encoded: Dict[str, Any],
             *,
             skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         if value is None:
             return None
 
+        if exclude_unset and 'root' not in value.__pydantic_fields_set__:
+            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)
+        self._root_serializer.serialize(
+            element, getattr(value, 'root'), encoded,
+            skip_empty=skip_empty,
+            exclude_none=exclude_none,
+            exclude_unset=exclude_unset,
+        )
 
         return element
 
@@ -362,9 +381,14 @@ def serialize(
             encoded: Dict[str, Any],
             *,
             skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
         assert self._model.__xml_serializer__ is not None, f"model {self._model.__name__} is partially initialized"
 
+        if exclude_none and value is None:
+            return None
+
         if self._nillable and value is None:
             sub_element = element.make_element(self._element_name, nsmap=self._nsmap)
             make_element_nill(sub_element)
@@ -375,7 +399,9 @@ def serialize(
             return None
 
         sub_element = element.make_element(self._element_name, nsmap=self._nsmap)
-        self._model.__xml_serializer__.serialize(sub_element, value, encoded, skip_empty=skip_empty)
+        self._model.__xml_serializer__.serialize(
+            sub_element, value, encoded, skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset,
+        )
         if skip_empty and sub_element.is_empty():
             return None
         else:

pydantic_xml/serializers/factories/named_tuple.py

@@ -26,9 +26,18 @@ def __init__(self, model_name: str, computed: bool, inner_serializers: Tuple[Ser
         self._inner_serializer = heterogeneous.ElementSerializer(model_name, computed, inner_serializers)
 
     def serialize(
-            self, element: XmlElementWriter, value: List[Any], encoded: List[Any], *, skip_empty: bool = False,
+            self,
+            element: XmlElementWriter,
+            value: List[Any],
+            encoded: List[Any],
+            *,
+            skip_empty: bool = False,
+            exclude_none: bool = False,
+            exclude_unset: bool = False,
     ) -> Optional[XmlElementWriter]:
-        return self._inner_serializer.serialize(element, value, encoded, skip_empty=skip_empty)
+        return self._inner_serializer.serialize(
+            element, value, encoded, skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset,
+        )
 
     def deserialize(
             self,