Merge pull request #74 from dapper91/minor-fixes

dapper91 · web-flow · commit 39f835420973 · 2023-07-14T19:46:15.000+05:00
- custom root type serialization format changed
- doc typos fixed
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -25,13 +25,13 @@ repos:
         args:
           - --fix=no
   - repo: https://github.com/asottile/add-trailing-comma
-    rev: v2.4.0
+    rev: v3.0.0
     hooks:
       - id: add-trailing-comma
         stages:
           - commit
   - repo: https://github.com/pre-commit/mirrors-autopep8
-    rev: v2.0.1
+    rev: v2.0.2
     hooks:
       - id: autopep8
         stages:
@@ -63,7 +63,7 @@ repos:
           - --multi-line=9
           - --project=pydantic_xml
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.991
+    rev: v1.4.1
     hooks:
       - id: mypy
         stages:
@@ -72,5 +72,5 @@ repos:
         pass_filenames: false
         args: ["--package", "pydantic_xml"]
         additional_dependencies:
-          - pydantic
-          - lxml-stubs
+          - pydantic==1.9
+          - lxml-stubs==0.4.0
diff --git a/README.rst b/README.rst
@@ -22,7 +22,7 @@ pydantic-xml extension
    :target: https://pydantic-xml.readthedocs.io/en/stable/
 
 
-``pydantic-xml`` is a `pydantic <https://docs.pydantic.dev>`_ extension providing model fields xml binding
+``pydantic-xml`` is a `pydantic <https://docs.pydantic.dev/1.10/>`_ extension providing model fields xml binding
 and xml serialization / deserialization.
 It is closely integrated with ``pydantic`` which means it supports most of its features.
 
@@ -33,16 +33,16 @@ Features
 - flexable attributes, elements and text binding
 - python collection types support (``Dict``, ``List``, ``Set``, ``Tuple``, ...)
 - ``Union`` type support
-- pydantic `generic <https://pydantic-docs.helpmanual.io/usage/models/#generic-models>`_ models support
+- pydantic `generic <https://docs.pydantic.dev/1.10/usage/models/#generic-models>`_ models support
 - `lxml <https://lxml.de/>`_ xml parser support
 - ``xml.etree.ElementTree`` standard library xml parser support
 
 What is not supported?
 ______________________
 
-- `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>`_
+- `dynamic model creation <https://docs.pydantic.dev/1.10/usage/models/#dynamic-model-creation>`_
+- `dataclasses <https://docs.pydantic.dev/1.10/usage/dataclasses/>`_
+- `discriminated unions <https://docs.pydantic.dev/1.10/usage/types/#discriminated-unions-aka-tagged-unions>`_
 
 Getting started
 ---------------
@@ -74,4 +74,4 @@ defines the XML document:
    </Company>
 
 
-Check `documentation <https://pydantic-xml.readthedocs.io/en/latest/>`_ for more information.
+See `documentation <https://pydantic-xml.readthedocs.io/en/latest/>`_ for more details.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -40,7 +40,7 @@ Links
 -----
 
 - `Source code <https://github.com/dapper91/pydantic-xml>`_
-- `Pydantic documentation <https://docs.pydantic.dev>`_
+- `Pydantic documentation <https://docs.pydantic.dev/1.10/>`_
 
 
 Indices and tables
diff --git a/docs/source/pages/data-binding/aliases.rst b/docs/source/pages/data-binding/aliases.rst
@@ -45,7 +45,7 @@ Template models
 
 ``pydantic`` aliases make it possible to declare so-called template models.
 The base model implements all data-validation and data-processing logic and
-fields mapping is described in inherited classes:
+fields mapping is described in the inherited classes:
 
 .. grid:: 2
     :gutter: 2
diff --git a/docs/source/pages/data-binding/attributes.rst b/docs/source/pages/data-binding/attributes.rst
@@ -7,7 +7,7 @@ __________
 Primitive types
 ***************
 
-Field of a primitive type marked as :py:func:`pydantic_xml.attr` is bound to a  local element attribute.
+Field of a primitive type marked as :py:func:`pydantic_xml.attr` is bound to a local element attribute.
 Parameter ``name`` is used to declare the attribute name from which the data is extracted.
 If it is omitted field name is used (respecting ``pydantic`` field aliases).
 
diff --git a/docs/source/pages/data-binding/elements.rst b/docs/source/pages/data-binding/elements.rst
@@ -120,7 +120,8 @@ where ``ns`` is the element namespace alias and ``nsmap`` is a namespace mapping
                     :start-after: json-start
                     :end-before: json-end
 
-Namespace mapping can be declared for a model. In that case all fields inherit that mapping:
+Namespace and namespace mapping can be declared for a model. In that case all fields
+:ref:`except attributes <pages/data-binding/attributes:namespace inheritance>` inherit them:
 
 .. grid:: 2
     :gutter: 2
diff --git a/docs/source/pages/data-binding/generics.rst b/docs/source/pages/data-binding/generics.rst
@@ -4,7 +4,7 @@
 Generic models
 ______________
 
-``pydantic`` library supports `generic-models <https://pydantic-docs.helpmanual.io/usage/models/#generic-models>`_.
+``pydantic`` library supports `generic-models <https://docs.pydantic.dev/1.10/usage/models/#generic-models>`_.
 To declare one inherit your model from :py:class:`pydantic_xml.BaseGenericXmlModel`,
 the rest is the same as ``pydantic`` generic model declaration:
 
diff --git a/docs/source/pages/data-binding/homogeneous.rst b/docs/source/pages/data-binding/homogeneous.rst
@@ -51,7 +51,7 @@ Model homogeneous collection
 
 Field of a model homogeneous collection type is bound to sub-elements. Then the sub-element is used
 as a root for that sub-model. For more information see :ref:`model data binding <pages/data-binding/models:model>`.
-Parameter ``tag`` is used to declare a sub-elements tag to which the sub-models are bound.
+Parameter ``tag`` is used to declare sub-elements tag to which the sub-models are bound.
 If it is omitted the sub-model ``tag`` parameter is used.
 If it is omitted too field name is used (respecting ``pydantic`` field aliases).
 
diff --git a/docs/source/pages/data-binding/models.rst b/docs/source/pages/data-binding/models.rst
@@ -7,7 +7,7 @@ _____
 Root model
 **********
 
-Root model is bound the root xml element with the tag matching the model ``tag`` or class name.
+Root model is bound to the root xml element with the tag matching the model ``tag`` or class name.
 If the corresponding element not found :py:class:`pydantic_xml.ParsingError` exception is raised.
 
 .. grid:: 2
@@ -88,7 +88,7 @@ Namespace mapping is inherited by all the model field:
 Custom root type
 ****************
 
-``Pydantic`` supports so-called `custom root type <https://docs.pydantic.dev/usage/models/#custom-root-types>`_.
+``Pydantic`` supports so-called `custom root type <https://docs.pydantic.dev/1.10/usage/models/#custom-root-types>`_.
 
 It works for primitive types:
 
@@ -192,7 +192,7 @@ and model types:
 Self-referencing models
 ***********************
 
-``pydantic`` library supports `self-referencing models <https://pydantic-docs.helpmanual.io/usage/postponed_annotations/#self-referencing-models>`_.
+``pydantic`` library supports `self-referencing models <https://docs.pydantic.dev/1.10/usage/postponed_annotations/#self-referencing-models>`_.
 Within the model, you can refer to a not-yet-constructed model using a string.
 
 .. grid:: 2
diff --git a/docs/source/pages/data-binding/wrapper.rst b/docs/source/pages/data-binding/wrapper.rst
@@ -4,7 +4,7 @@ Wrapper
 _______
 
 Some XML documents have deep element hierarchy which requires to declare a lot of "dumb" sub-models
-to extract the deepest element data. In such cases :py:func:`pydantic_xml.wrapped` can help.
+to extract the deepest element data. :py:func:`pydantic_xml.wrapped` helps to get rid of that.
 
 
 Wrapped entities
diff --git a/docs/source/pages/misc.rst b/docs/source/pages/misc.rst
@@ -9,7 +9,7 @@ Custom type encoding
 ____________________
 
 ``pydantic-xml`` uses ``pydantic`` default encoder to encode fields data during xml serialization. To alter the default
-behaviour ``pydantic`` provides a mechanism to `customize <https://docs.pydantic.dev/usage/exporting_models/#json_encoders>`_
+behaviour ``pydantic`` provides a mechanism to `customize <https://docs.pydantic.dev/1.10/usage/exporting_models/#json_encoders>`_
 the default json encoding format for a particular type. ``pydantic-xml`` allows to do the same for xml serialization.
 The api is similar to the json one:
 
diff --git a/docs/source/pages/quickstart.rst b/docs/source/pages/quickstart.rst
@@ -11,7 +11,7 @@ To declare an xml serializable / deserializable model inherit it
 from :py:class:`pydantic_xml.BaseXmlModel` base class. It collects
 data binding meta-information and generates xml serializer for the model.
 
-To serializes the object to an xml string use :py:meth:`pydantic_xml.BaseXmlModel.to_xml` method,
+To serialize the object into an xml string use :py:meth:`pydantic_xml.BaseXmlModel.to_xml` method,
 :py:meth:`pydantic_xml.BaseXmlModel.from_xml` to deserialize it.
 For more information see :ref:`XML serialization <pages/misc:xml serialization>`.
 
@@ -123,7 +123,7 @@ For more information see :ref:`mappings <pages/data-binding/mappings:mappings>`.
 4. Primitive collection
 ***********************
 
-field of a primitive collection type (``List[str]``, ``Set[int]``, ``Tuple[flaot, float]`` ...) is bound to
+field of a primitive collection type (``List[str]``, ``Set[int]``, ``Tuple[float, float]`` ...) is bound to
 sub-elements text if the field is marked as :py:func:`pydantic_xml.element`:
 
 .. literalinclude:: ../../../examples/snippets/homogeneous_primitives.py
@@ -167,7 +167,7 @@ For more information see
 **********
 
 wrapped field (marked as :py:func:`pydantic_xml.wrapped`) is bound to a sub-element located
-at the provided path. Then depending on the field type rules are the same as described above:
+at the provided path. Then depending on the field type the rules are the same as described above:
 
 .. literalinclude:: ../../../examples/snippets/wrapper.py
   :language: xml
diff --git a/examples/snippets/model_root_type.py b/examples/snippets/model_root_type.py
@@ -1,35 +1,40 @@
-from pydantic_xml import BaseXmlModel, attr, element
+from typing import List
 
+from pydantic import HttpUrl
 
-# [model-start]
-class CompanyInfo(BaseXmlModel):
-    trade_name: str = attr(name='trade-name')
-    website: str = element()
+from pydantic_xml import BaseXmlModel, element
 
-    ...  # data validation logic
 
+# [model-start]
+class Socials(BaseXmlModel, tag='socials'):
+    __root__: List[HttpUrl] = element(tag='social')
 
-class Company(BaseXmlModel, tag='company'):
-    __root__: CompanyInfo
 
-    ...  # business logic
+class Contacts(BaseXmlModel, tag='contacts'):
+    __root__: Socials
 # [model-end]
 
 
 # [xml-start]
 xml_doc = '''
-<company trade-name="SpaceX">
-    <website>https://www.spacex.com</website>
-</company>
+<contacts>
+    <socials>
+        <social>https://www.linkedin.com/company/spacex</social>
+        <social>https://twitter.com/spacex</social>
+        <social>https://www.youtube.com/spacex</social>
+    </socials>
+</contacts>
 '''  # [xml-end]
 
 # [json-start]
 json_doc = '''
-{
-    "trade_name": "SpaceX",
-    "website": "https://www.spacex.com"
-}
+[
+    "https://www.linkedin.com/company/spacex",
+    "https://twitter.com/spacex",
+    "https://www.youtube.com/spacex"
+]
 '''  # [json-end]
 
-env = Company.from_xml(xml_doc)
-assert env == Company.parse_raw(json_doc)
+contacts = Contacts.from_xml(xml_doc)
+
+assert contacts == Contacts.parse_raw(json_doc)
diff --git a/pydantic_xml/element/element.py b/pydantic_xml/element/element.py
@@ -273,7 +273,7 @@ def pop_attributes(self) -> Optional[Dict[str, str]]:
         return result
 
     def pop_element(self, tag: str, search_mode: 'SearchMode') -> Optional['XmlElement[NativeElement]']:
-        searcher = get_searcher(search_mode)
+        searcher: Searcher[NativeElement] = get_searcher(search_mode)
 
         return searcher(self._state, tag, False)
 
@@ -301,7 +301,7 @@ def find_element_or_create(
         return sub_element
 
     def _find_element(self, tag: str, search_mode: 'SearchMode') -> Optional['XmlElement[NativeElement]']:
-        searcher = get_searcher(search_mode)
+        searcher: Searcher[NativeElement] = get_searcher(search_mode)
 
         return searcher(self._state, tag, True)
 
@@ -320,10 +320,10 @@ class SearchMode(str, Enum):
     UNORDERED = 'unordered'
 
 
-Searcher = Callable[[XmlElement.State[Any], str, bool], Optional[XmlElement]]
+Searcher = Callable[[XmlElement.State[NativeElement], str, bool], Optional[XmlElement]]
 
 
-def get_searcher(search_mode: SearchMode) -> Searcher:
+def get_searcher(search_mode: SearchMode) -> Searcher[NativeElement]:
     if search_mode == SearchMode.STRICT:
         return strict_search
     elif search_mode == SearchMode.ORDERED:
@@ -334,7 +334,11 @@ def get_searcher(search_mode: SearchMode) -> Searcher:
         raise AssertionError('unreachable')
 
 
-def strict_search(state: XmlElement.State[Any], tag: str, look_behind: bool = False) -> Optional[XmlElement[Any]]:
+def strict_search(
+        state: XmlElement.State[NativeElement],
+        tag: str,
+        look_behind: bool = False,
+) -> Optional[XmlElement[NativeElement]]:
     """
     Searches for a sub-element sequentially one by one.
 
@@ -344,7 +348,7 @@ def strict_search(state: XmlElement.State[Any], tag: str, look_behind: bool = Fa
     :return: found element or `None` if the element not found
     """
 
-    result: Optional[XmlElement[Any]] = None
+    result: Optional[XmlElement[NativeElement]] = None
 
     if look_behind and (result := _look_behind(state, tag)) is not None:
         return result
@@ -356,7 +360,11 @@ def strict_search(state: XmlElement.State[Any], tag: str, look_behind: bool = Fa
     return result
 
 
-def ordered_search(state: XmlElement.State[Any], tag: str, look_behind: bool = False) -> Optional[XmlElement[Any]]:
+def ordered_search(
+        state: XmlElement.State[NativeElement],
+        tag: str,
+        look_behind: bool = False,
+) -> Optional[XmlElement[NativeElement]]:
     """
     Searches for an element sequentially skipping unmatched ones.
 
@@ -366,7 +374,7 @@ def ordered_search(state: XmlElement.State[Any], tag: str, look_behind: bool = F
     :return: found element or `None` if the element not found
     """
 
-    result: Optional[XmlElement[Any]] = None
+    result: Optional[XmlElement[NativeElement]] = None
 
     if look_behind and (result := _look_behind(state, tag)) is not None:
         return result
@@ -385,10 +393,10 @@ def ordered_search(state: XmlElement.State[Any], tag: str, look_behind: bool = F
 
 
 def unordered_search(
-        state: XmlElement.State[Any],
+        state: XmlElement.State[NativeElement],
         tag: str,
         look_behind: bool = False,
-) -> Optional[XmlElement[Any]]:
+) -> Optional[XmlElement[NativeElement]]:
     """
     Searches search for an element ignoring elements order.
 
@@ -398,7 +406,7 @@ def unordered_search(
     :return: found element or `None` if the requested element not found
     """
 
-    result: Optional[XmlElement[Any]] = None
+    result: Optional[XmlElement[NativeElement]] = None
 
     if look_behind and (result := _look_behind(state, tag)) is not None:
         return result
@@ -415,7 +423,7 @@ def unordered_search(
     return result
 
 
-def _look_behind(state: XmlElement.State[Any], tag: str) -> Optional[XmlElement[Any]]:
+def _look_behind(state: XmlElement.State[NativeElement], tag: str) -> Optional[XmlElement[NativeElement]]:
     if state.next_element_idx != 0:
         candidate = state.elements[state.next_element_idx - 1]
         if candidate.tag == tag:
diff --git a/pydantic_xml/element/native/lxml.py b/pydantic_xml/element/native/lxml.py
@@ -18,7 +18,7 @@ def from_native(cls, element: etree._Element) -> 'XmlElement':
             tag=element.tag,
             text=element.text,
             attributes={
-                force_str(name): force_str(value)  # str transformation safe since lxml byte values are ASCII compatible
+                force_str(name): force_str(value)  # transformation is safe since lxml bytes values are ASCII compatible
                 for name, value in element.attrib.items()
             },
             elements=[
diff --git a/pydantic_xml/serializers/factories/mapping.py b/pydantic_xml/serializers/factories/mapping.py
@@ -25,7 +25,12 @@ def __init__(
             self._ns_attrs = model.__xml_ns_attrs__
 
         def serialize(
-                self, element: XmlElementWriter, value: Dict[str, Any], *, encoder: XmlEncoder, skip_empty: bool = False
+                self,
+                element: XmlElementWriter,
+                value: Dict[str, Any],
+                *,
+                encoder: XmlEncoder,
+                skip_empty: bool = False,
         ) -> Optional[XmlElementWriter]:
             if value is None:
                 return element
@@ -62,7 +67,12 @@ def __init__(
             self._search_mode = ctx.search_mode
 
         def serialize(
-                self, element: XmlElementWriter, value: Dict[str, Any], *, encoder: XmlEncoder, skip_empty: bool = False
+                self,
+                element: XmlElementWriter,
+                value: Dict[str, Any],
+                *,
+                encoder: XmlEncoder,
+                skip_empty: bool = False,
         ) -> Optional[XmlElementWriter]:
             if skip_empty and len(value) == 0:
                 return element
diff --git a/pydantic_xml/serializers/factories/model.py b/pydantic_xml/serializers/factories/model.py
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tests/test_encoder.py b/tests/test_encoder.py
diff --git a/tests/test_forward_ref.py b/tests/test_forward_ref.py
diff --git a/tests/test_generics.py b/tests/test_generics.py
diff --git a/tests/test_submodels.py b/tests/test_submodels.py
