Merge pull request #163 from dapper91/dev

- mypy plugin added. See https://pydantic-xml.readthedocs.io/en/latest/pages/misc.html#mypy.
- optional raw element bug fixed. See #158.

Author: dapper91

.coveragerc

@@ -0,0 +1,3 @@
+[run]
+omit =
+    pydantic_xml/mypy.py

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+2.8.0 (2024-01-13)
+------------------
+
+- mypy plugin added. See https://pydantic-xml.readthedocs.io/en/latest/pages/misc.html#mypy.
+- optional raw element bug fixed. See https://github.com/dapper91/pydantic-xml/issues/158.
+
+
 2.7.0 (2023-12-18)
 ------------------
 

docs/source/pages/contribute.rst

@@ -14,14 +14,14 @@ Initialize the development environment installing dev dependencies:
 Code style
 __________
 
-After any code changes make sure that code style is followed.
+After any code changes made make sure that the code style is followed.
 To control that automatically install pre-commit hooks:
 
 .. code-block:: console
 
     $ pre-commit install
 
-It will be checking your changes for coding conventions used in the project before any commit.
+They will be checking your changes for the coding conventions used in the project before any commit.
 
 
 Pull Requests
@@ -40,7 +40,7 @@ To make a PR to version 1 checkout branch ``v1`` and create a new branch impleme
 Version 2
 *********
 
-To contribute to version 2 checkout branch ``dev``, create a feature branch and make pull request setting
+To contribute to version 2 checkout branch ``dev``, create a feature branch and make a pull request setting
 ``dev`` as a target.
 
 

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

@@ -6,8 +6,8 @@ ________________
 Aliased fields
 **************
 
-``pydantic`` library allows to set an alias for a field that is used during serialization/deserialization
-instead of field name. ``pydantic-xml`` respects field aliases too:
+``pydantic`` library allows to set the alias for a field that is used during serialization/deserialization
+instead of the field name. ``pydantic-xml`` respects field aliases too:
 
 .. grid:: 2
     :gutter: 2
@@ -44,8 +44,8 @@ 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 the inherited classes:
+The base model implements the data-validation and data-processing logic but
+the fields mapping is described in the inherited classes:
 
 .. grid:: 2
     :gutter: 2

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

@@ -7,9 +7,9 @@ __________
 Primitive types
 ***************
 
-Field of a primitive type marked as :py:func:`pydantic_xml.attr` is bound to a local element attribute.
+A 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).
+If it is omitted the field name is used (respecting ``pydantic`` field aliases).
 
 .. grid:: 2
     :gutter: 2
@@ -45,8 +45,8 @@ If it is omitted field name is used (respecting ``pydantic`` field aliases).
 Namespaces
 **********
 
-Namespace can be defined for attributes. To bind a model field to a namespaced attribute
-pass parameter ``ns`` to a :py:func:`pydantic_xml.attr` and define namespace map for the model.
+The namespace can be defined for attributes as well. To bind a model field to a namespaced attribute
+pass parameter ``ns`` to a :py:func:`pydantic_xml.attr` and define a namespace map for the model.
 
 .. grid:: 2
     :gutter: 2
@@ -82,9 +82,9 @@ pass parameter ``ns`` to a :py:func:`pydantic_xml.attr` and define namespace map
 Namespace inheritance
 *********************
 
-Attribute namespace can be inherited from the model.
-To make attributes inherit the model namespace define model-level namespace and namespace map
-and set parameter ``ns_attrs``.
+The attribute namespace can be inherited from the model.
+To make attributes inherit the model namespace define the model-level namespace and namespace map
+and set ``ns_attrs`` flag.
 
 .. grid:: 2
     :gutter: 2

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

@@ -7,9 +7,9 @@ ________
 Primitive types
 ***************
 
-Field of a primitive type marked as :py:func:`pydantic_xml.element` is bound to a sub-element text.
-Parameter ``tag`` is used to declare a sub-element tag from which the text is extracted.
-If it is omitted field name is used (respecting ``pydantic`` field aliases).
+A field of a primitive type marked as :py:func:`pydantic_xml.element` is bound to the sub-element text.
+Parameter ``tag`` is used to declare the sub-element tag to which the field is bound.
+If it is omitted the field name is used (respecting ``pydantic`` field aliases).
 
 .. grid:: 2
     :gutter: 2
@@ -45,12 +45,12 @@ If it is omitted field name is used (respecting ``pydantic`` field aliases).
 Model types
 ***********
 
-Field of a model type marked as :py:func:`pydantic_xml.element` is bound to a sub-element.
-Then the sub-element is used as a root for that sub-model. For more information
+A field of a model type marked as :py:func:`pydantic_xml.element` is bound to a sub-element.
+Then the sub-element is used as the 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-element tag to which the sub-model is bound.
 If it is omitted the sub-model ``tag`` setting is used.
-If it is omitted too field name is used (respecting ``pydantic`` field aliases).
+If it is omitted too the field name is used (respecting ``pydantic`` field aliases).
 So the order is the following: element tag, model tag, field alias, field name.
 
 .. grid:: 2
@@ -87,7 +87,7 @@ So the order is the following: element tag, model tag, field alias, field name.
 Namespaces
 **********
 
-You can declare an element namespace passing parameters ``ns`` and ``nsmap`` to :py:func:`pydantic_xml.element`
+You can declare the element namespace passing parameters ``ns`` and ``nsmap`` to :py:func:`pydantic_xml.element`
 where ``ns`` is the element namespace alias and ``nsmap`` is a namespace mapping:
 
 .. grid:: 2
@@ -120,7 +120,7 @@ where ``ns`` is the element namespace alias and ``nsmap`` is a namespace mapping
                     :start-after: json-start
                     :end-before: json-end
 
-Namespace and namespace mapping can be declared for a model. In that case all fields
+The 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
@@ -154,8 +154,8 @@ Namespace and namespace mapping can be declared for a model. In that case all fi
                     :end-before: json-end
 
 
-Namespace and namespace mapping can be also applied to model types passing ``ns`` and ``nsmap``
-to :py:func:`pydantic_xml.element`. If they are omitted model namespace and namespace mapping is used:
+The namespace and namespace mapping can be also applied to model types passing ``ns`` and ``nsmap``
+to :py:func:`pydantic_xml.element`. If they are omitted the model namespace and namespace mapping is used:
 
 .. grid:: 2
     :gutter: 2
@@ -198,7 +198,7 @@ Strict (default)
 
 The element to which a field will be bound is searched sequentially one by one (without skipping unknown elements).
 If the tag of a next element doesn't match the field tag that field is considered unbound.
-This mode is used when strong document validation is required. If you parse a large document it is the best
+This mode is used when the strong document validation is required. If you parse a large document it is the best
 choice because it works in predictable time since it doesn't require any look-ahead operations.
 
 .. grid:: 2
@@ -212,7 +212,7 @@ choice because it works in predictable time since it doesn't require any look-ah
             :end-before: model-end
 
         .. error::
-              code raises an exception because of incorrect field order
+              code raises an exception because of the incorrect field order
 
     .. grid-item-card:: Document
 
@@ -239,7 +239,7 @@ Ordered
 .......
 
 The element to which a field will be bound is searched sequentially skipping unknown elements.
-If the tag of a next element doesn't match the field tag that element is skipped and the search continues.
+If the tag of the next element doesn't match the field tag that element is skipped and the search continues.
 This mode is used when the elements order matters but unexpected (or irrelevant) elements could appear in a document.
 
 .. grid:: 2
@@ -282,7 +282,7 @@ This mode is used when the elements order matters but unexpected (or irrelevant)
            field2: str = element(tag='element2')
            field3: str = element(tag='element1')
 
-    will fail for the following document:
+    fails for the following document:
 
     .. code-block:: xml
 

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

@@ -5,5 +5,5 @@ Heterogeneous collections
 _________________________
 
 Heterogeneous collections are similar to :ref:`homogeneous collections <homogeneous>`
-except that the number of elements is predefined which means they follow the same binding rules.
+except that the number of the elements is predefined which means they follow the same binding rules.
 The most common heterogeneous collection is :py:obj:`typing.Tuple` (like ``Tuple[int, int, int]``)

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

@@ -12,8 +12,8 @@ variable-length tuple :py:obj:`typing.Tuple` (like ``Tuple[int, ...]``)
 Primitive homogeneous collection
 ********************************
 
-Field of a primitive homogeneous collection type marked as :py:func:`pydantic_xml.element` is bound
-to sub-elements text.
+A field of a primitive homogeneous collection type marked as :py:func:`pydantic_xml.element` is bound
+to the sub-elements texts.
 
 .. grid:: 2
     :gutter: 2
@@ -49,9 +49,9 @@ to sub-elements text.
 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 sub-elements tag to which the sub-models are bound.
+A field of a model homogeneous collection type is bound to sub-elements. Then the sub-element is used
+as the root for that sub-model. For more information see :ref:`model data binding <pages/data-binding/models:model>`.
+The ``tag`` parameter 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).
 
@@ -89,7 +89,7 @@ If it is omitted too field name is used (respecting ``pydantic`` field aliases).
 Dict homogeneous collection
 ***************************
 
-Field of a mapping homogeneous collection type is bound to sub-elements attributes:
+A field of a mapping homogeneous collection type is bound to sub-elements attributes:
 
 .. grid:: 2
     :gutter: 2

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

@@ -7,7 +7,7 @@ ________
 Local attributes
 ****************
 
-Field of a mapping type is bound to a local element attributes.
+A field of a mapping type is bound to local element attributes.
 
 .. grid:: 2
     :gutter: 2
@@ -43,9 +43,9 @@ Field of a mapping type is bound to a local element attributes.
 Sub-element attributes
 **********************
 
-Field of a mapping type marked as :py:func:`pydantic_xml.element` is bound to a sub-element attributes.
-Parameter ``tag`` of :py:func:`pydantic_xml.element` is used as a sub-element tag to which attributes
-the field is bound. If it is omitted field name is used (respecting ``pydantic`` field aliases).
+A field of a mapping type marked as :py:func:`pydantic_xml.element` is bound to sub-element attributes.
+The ``tag`` parameter of :py:func:`pydantic_xml.element` is used as a sub-element tag to which attributes
+the field is bound. If it is omitted the field name is used (respecting ``pydantic`` field aliases).
 
 .. grid:: 2
     :gutter: 2

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

@@ -7,7 +7,7 @@ _____
 Root model
 **********
 
-Root model is bound to the root xml element with the tag matching the model ``tag`` or class name.
+A 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
@@ -52,7 +52,7 @@ Namespaces
 
 You can declare the root model namespace by setting parameters ``ns`` and ``nsmap``.
 where ``ns`` is the element namespace alias and ``nsmap`` is a namespace mapping.
-Namespace mapping is inherited by all the model field:
+The namespace mapping is inherited by all the model field:
 
 .. grid:: 2
     :gutter: 2