Merge pull request #104 from dapper91/dev

- raw element typed fields support added. See #14.
- pydantic field exclude flag bug fixed (works only for serialization now).

Author: dapper91

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+2.1.0 (2023-08-24)
+------------------
+
+- raw element typed fields support added. See https://github.com/dapper91/pydantic-xml/issues/14.
+- pydantic field exclude flag bug fixed (works only for serialization now).
+
+
 2.0.0 (2023-08-19)
 ------------------
 

README.rst

@@ -44,7 +44,6 @@ ______________________
 
 - `dynamic model creation <https://docs.pydantic.dev/usage/models/#dynamic-model-creation>`_
 - `dataclasses <https://docs.pydantic.dev/usage/dataclasses/>`_
-- `discriminated unions <https://docs.pydantic.dev/usage/types/#discriminated-unions-aka-tagged-unions>`_
 
 Getting started
 ---------------

docs/source/pages/data-binding/index.rst

@@ -17,3 +17,4 @@ Data binding
    generics
    wrapper
    aliases
+   raw

docs/source/pages/data-binding/raw.rst

@@ -0,0 +1,49 @@
+.. _raw_fields:
+
+
+Raw fields
+__________
+
+Raw element typed fields
+************************
+
+The library supports raw xml elements. It is helpful when the element schema is unknown or its schema is too complex
+to define a model describing it.
+
+To declare a raw element field annotate it with :py:class:`xml.etree.ElementTree.Element`
+(or :py:class:`lxml.etree._Element` for ``lxml``).
+
+Since ``pydantic`` doesn't support arbitrary types by default it is necessary to allow them
+by setting ``arbitrary_types_allowed`` attribute.
+See `documentation <https://docs.pydantic.dev/latest/usage/model_config/#arbitrary-types-allowed>`_ for more details.
+
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/element_raw.py
+            :language: python
+            :start-after: model-start
+            :end-before: model-end
+
+    .. grid-item-card:: Document
+
+        .. tab-set::
+
+            .. tab-item:: input XML
+
+                .. literalinclude:: ../../../../examples/snippets/element_raw.py
+                    :language: xml
+                    :lines: 2-
+                    :start-after: xml-start-1
+                    :end-before: xml-end-1
+
+            .. tab-item:: output XML
+
+                .. literalinclude:: ../../../../examples/snippets/element_raw.py
+                    :language: xml
+                    :lines: 2-
+                    :start-after: xml-start-2
+                    :end-before: xml-end-2

examples/snippets/element_raw.py

@@ -0,0 +1,63 @@
+from typing import List
+from xml.etree.ElementTree import canonicalize
+
+from pydantic import HttpUrl
+
+from pydantic_xml import BaseXmlModel, computed_element, element
+from pydantic_xml.element.native import ElementT as Element
+
+
+# [model-start]
+class Contact(BaseXmlModel, tag='contact'):
+    url: HttpUrl
+
+
+class Contacts(
+    BaseXmlModel,
+    tag='contacts',
+    arbitrary_types_allowed=True,
+):
+    contacts_raw: List[Element] = element(tag='contact', exclude=True)
+
+    @computed_element
+    def parse_raw_contacts(self) -> List[Contact]:
+        contacts: List[Contact] = []
+        for contact_raw in self.contacts_raw:
+            if url := contact_raw.attrib.get('url'):
+                contact = Contact(url=url)
+            elif (link := contact_raw.find('link')) is not None:
+                contact = Contact(url=link.text)
+            else:
+                contact = Contact(url=contact_raw.text.strip())
+
+            contacts.append(contact)
+
+        return contacts
+# [model-end]
+
+
+# [xml-start-1]
+src_doc = '''
+<contacts>
+    <contact url="https://www.linkedin.com/company/spacex" />
+    <contact>
+        <link>https://twitter.com/spacex</link>
+    </contact>
+    <contact>https://www.youtube.com/spacex</contact>
+</contacts>
+'''  # [xml-end-1]
+
+
+contacts = Contacts.from_xml(src_doc)
+
+
+# [xml-start-2]
+dst_doc = '''
+<contacts>
+    <contact>https://www.linkedin.com/company/spacex</contact>
+    <contact>https://twitter.com/spacex</contact>
+    <contact>https://www.youtube.com/spacex</contact>
+</contacts>
+'''  # [xml-end-2]
+
+assert canonicalize(contacts.to_xml(), strip_text=True) == canonicalize(dst_doc, strip_text=True)

pydantic_xml/element/element.py

@@ -34,7 +34,7 @@ def find_element(
             search_mode: 'SearchMode',
             look_behind: bool = True,
             step_forward: bool = True,
-    ) -> Optional['XmlElement[Any]']:
+    ) -> Optional['XmlElementReader']:
         """
         Searches for an element with the provided tag.
 
@@ -73,7 +73,7 @@ def pop_attributes(self) -> Optional[Dict[str, str]]:
         """
 
     @abc.abstractmethod
-    def pop_element(self, tag: str, search_mode: 'SearchMode') -> Optional['XmlElement[Any]']:
+    def pop_element(self, tag: str, search_mode: 'SearchMode') -> Optional['XmlElementReader']:
         """
         Extracts a sub-element from the xml element matching `tag`.
 
@@ -83,7 +83,7 @@ def pop_element(self, tag: str, search_mode: 'SearchMode') -> Optional['XmlEleme
         """
 
     @abc.abstractmethod
-    def find_sub_element(self, path: Sequence[str], search_mode: 'SearchMode') -> Optional['XmlElement[Any]']:
+    def find_sub_element(self, path: Sequence[str], search_mode: 'SearchMode') -> Optional['XmlElementReader']:
         """
         Searches for an element at the provided path. If the element is not found returns `None`.
 
@@ -106,6 +106,14 @@ def apply_snapshot(self, snapshot: 'XmlElement[Any]') -> None:
         Applies a snapshot to the current element.
         """
 
+    @abc.abstractmethod
+    def to_native(self) -> Any:
+        """
+        Transforms current element to a native one.
+
+        :return: native element
+        """
+
 
 class XmlElementWriter(abc.ABC):
     """
@@ -165,7 +173,7 @@ def make_element(self, tag: str, nsmap: Optional[NsMap]) -> 'XmlElement[Any]':
         """
 
     @abc.abstractmethod
-    def find_element_or_create(self, tag: str, search_mode: 'SearchMode', nsmap: Optional[NsMap]) -> 'XmlElement[Any]':
+    def find_element_or_create(self, tag: str, search_mode: 'SearchMode', nsmap: Optional[NsMap]) -> 'XmlElementWriter':
         """
         Searches for an element with the provided tag.
         If the element is found returns it otherwise creates a new one.
@@ -176,6 +184,16 @@ def find_element_or_create(self, tag: str, search_mode: 'SearchMode', nsmap: Opt
         :return: xml element
         """
 
+    @classmethod
+    @abc.abstractmethod
+    def from_native(cls, element: Any) -> 'XmlElement[Any]':
+        """
+        Creates a instance of `XmlElement` from native element.
+
+        :param element: native element
+        :return: `XmlElement`
+        """
+
 
 NativeElement = TypeVar('NativeElement')
 

pydantic_xml/element/native/__init__.py

@@ -4,6 +4,7 @@
 from pydantic_xml.element import XmlElement as BaseXmlElement
 
 XmlElement: Type[BaseXmlElement[Any]]
+ElementT: Type[Any]
 
 if config.FORCE_STD_XML:
     from .std import *  # noqa: F403

pydantic_xml/element/native/lxml.py

@@ -6,14 +6,17 @@
 from pydantic_xml.typedefs import NsMap
 
 __all__ = (
+    'ElementT',
     'XmlElement',
     'etree',
 )
 
+ElementT = etree._Element
 
-class XmlElement(BaseXmlElement[etree._Element]):
+
+class XmlElement(BaseXmlElement[ElementT]):
     @classmethod
-    def from_native(cls, element: etree._Element) -> 'XmlElement':
+    def from_native(cls, element: ElementT) -> 'XmlElement':
         return cls(
             tag=element.tag,
             text=element.text,
@@ -28,7 +31,7 @@ def from_native(cls, element: etree._Element) -> 'XmlElement':
             ],
         )
 
-    def to_native(self) -> etree._Element:
+    def to_native(self) -> ElementT:
         element = etree.Element(
             self._tag,
             attrib=self._state.attrib,
@@ -51,5 +54,5 @@ def force_str(val: Union[str, bytes]) -> str:
         return val
 
 
-def is_xml_comment(element: etree._Element) -> bool:
+def is_xml_comment(element: ElementT) -> bool:
     return isinstance(element, etree._Comment)

pydantic_xml/element/native/std.py

@@ -5,14 +5,17 @@
 from pydantic_xml.typedefs import NsMap
 
 __all__ = (
+    'ElementT',
     'XmlElement',
     'etree',
 )
 
+ElementT = etree.Element
 
-class XmlElement(BaseXmlElement[etree.Element]):
+
+class XmlElement(BaseXmlElement[ElementT]):
     @classmethod
-    def from_native(cls, element: etree.Element) -> 'XmlElement':
+    def from_native(cls, element: ElementT) -> 'XmlElement':
         return cls(
             tag=element.tag,
             text=element.text,
@@ -24,7 +27,7 @@ def from_native(cls, element: etree.Element) -> 'XmlElement':
             ],
         )
 
-    def to_native(self) -> etree.Element:
+    def to_native(self) -> ElementT:
         element = etree.Element(self._tag, attrib=self._state.attrib or {})
         element.text = self._state.text
         element.extend([element.to_native() for element in self._state.elements])
@@ -35,5 +38,5 @@ def make_element(self, tag: str, nsmap: Optional[NsMap]) -> 'XmlElement':
         return XmlElement(tag)
 
 
-def is_xml_comment(element: etree.Element) -> bool:
+def is_xml_comment(element: ElementT) -> bool:
     return element.tag is etree.Comment  # type: ignore[comparison-overlap]

pydantic_xml/model.py

@@ -9,7 +9,7 @@
 
 from . import config, errors, utils
 from .element import SearchMode
-from .element.native import XmlElement, etree
+from .element.native import ElementT, XmlElement, etree
 from .serializers.factories.model import BaseModelSerializer
 from .serializers.serializer import Serializer, XmlEntityInfoP
 from .typedefs import EntityLocation
@@ -354,7 +354,11 @@ def to_xml_tree(self, *, skip_empty: bool = False) -> etree.Element:
 
         root = XmlElement(tag=self.__xml_serializer__.element_name, nsmap=self.__xml_serializer__.nsmap)
         self.__xml_serializer__.serialize(
-            root, self, pdc.to_jsonable_python(self, by_alias=False), skip_empty=skip_empty,
+            root, self, pdc.to_jsonable_python(
+                self,
+                by_alias=False,
+                fallback=lambda obj: obj if not isinstance(obj, ElementT) else None,  # for raw fields support
+            ), skip_empty=skip_empty,
         )
 
         return root.to_native()