Merge pull request #651 from tefra/docs

Update docs
tefra · Jan 29, 2022 · fcc10b1 · fcc10b1
2 parents ab2269d + 0b2a085
commit fcc10b1
Show file tree

Hide file tree

Showing 4 changed files with 131 additions and 40 deletions.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -1,43 +1,10 @@
-**************************
-Frequently Asked Questions
-**************************
+FAQ
+===
 
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Frequently asked questions:
+    :glob:
 
-Why are all properties marked as optional?
-------------------------------------------
-
-We rely on the fields ordering for all binding procedures and due to the following
-limitation we have to mark even required fields as optional.
-
-..
-
-    TypeError will be raised if a field without a default value follows a field
-    with a default value. This is true whether this occurs in a single class, or as
-    a result of class inheritance.
-
-    Source: :mod:`python:dataclasses`
-
-In Python 3.10 dataclasses introduced a new directive `kw_only` that resolves the above
-limitation and xsdata handling. Read :ref:`more <Dataclasses Features>`
-
-If you can't update just yet please check the `attrs <https://pypi.org/project/xsdata-attrs/>`_ plugin!
-
-
-Why are elements out of order?
-------------------------------
-
-There are a few cases when elements can appear in any order. The default simplified
-models don't have a way to store the original order of the elements in a document.
-
-Repeatable choice elements is one of them.
-
-.. literalinclude:: /../tests/fixtures/compound/schema.xsd
-   :language: xml
-   :lines: 1-9
-
-In order to maintain the original order between roundtrip conversions you need to
-enable compound fields. Compound fields are group fields and can be used to wrap
-mixed context elements, repeatable choice elements or complex sequential elements.
-
-Read :ref:`more <Compound Fields>`
+    faq/*
diff --git a/docs/faq/how-to-work-with-wildcard-fields.rst b/docs/faq/how-to-work-with-wildcard-fields.rst
@@ -0,0 +1,89 @@
+How to work with wildcard fields?
+==================================
+
+One of the xml schema traits is to support any extensions with wildcards.
+
+.. code-block:: xml
+
+    <xs:complexType name="MetadataType" mixed="false">
+        <xs:sequence>
+            <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
+        </xs:sequence>
+        <xs:anyAttribute namespace="##other" processContents="lax"/>
+    </xs:complexType>
+
+The generator will roughly create this class for you.
+
+.. doctest::
+
+    >>> from dataclasses import dataclass
+    >>> from dataclasses import field
+    >>> from typing import Dict
+    >>> from typing import List
+    ...
+    >>> @dataclass
+    ... class MetadataType:
+    ...     any_element: List[object] = field(
+    ...         default_factory=list,
+    ...         metadata={
+    ...              "type": "Wildcard",
+    ...              "namespace": "##any",
+    ...          }
+    ...     )
+    ...     other_attributes: Dict[str, str] = field(
+    ...          default_factory=dict,
+    ...          metadata={
+    ...              "type": "Attributes",
+    ...              "namespace": "##other",
+    ...          }
+    ...      )
+
+
+xsdata comes with two generic models that are used during parsing and you can also use
+to generate any custom xml element.
+
+.. list-table::
+   :widths: 20 250
+   :header-rows: 1
+
+   * - Model
+     - Description
+   * - :class:`~xsdata.formats.dataclass.models.generics.AnyElement`
+     - Used to represent any xml structure, resembles a DOM Element
+   * - :class:`~xsdata.formats.dataclass.models.generics.DerivedElement`
+     - Wrapper for type substitution elements eg `<b xsi:type="a">...</b>`
+
+
+.. doctest::
+
+    >>> from xsdata.formats.dataclass.models.generics import AnyElement
+    >>> from xsdata.formats.dataclass.models.generics import DerivedElement
+    >>> from xsdata.formats.dataclass.serializers import XmlSerializer
+    >>> from xsdata.formats.dataclass.serializers.config import SerializerConfig
+    ...
+    >>> obj = MetadataType(
+    ...     any_element=[
+    ...         AnyElement(
+    ...             qname="bar",
+    ...             children=[
+    ...                 AnyElement(qname="first", text="1st", attributes={"a": "1"}),
+    ...                 AnyElement(qname="second", text="2nd", attributes={"b": "2"}),
+    ...                 DerivedElement(
+    ...                     qname="third",
+    ...                     value=MetadataType(other_attributes={"c": "3"})
+    ...                 )
+    ...             ]
+    ...         )
+    ...     ]
+    ... )
+    >>> config = SerializerConfig(pretty_print=True, xml_declaration=False)
+    >>> serializer = XmlSerializer(config=config)
+    >>> print(serializer.render(obj))
+    <MetadataType>
+      <bar>
+        <first a="1">1st</first>
+        <second b="2">2nd</second>
+        <third xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" c="3" xsi:type="MetadataType"/>
+      </bar>
+    </MetadataType>
+    <BLANKLINE>
diff --git a/docs/faq/why-are-elements-out-of-order.rst b/docs/faq/why-are-elements-out-of-order.rst
@@ -0,0 +1,17 @@
+Why are elements out of order?
+------------------------------
+
+There are a few cases when elements can appear in any order. The default simplified
+models don't have a way to store the original order of the elements in a document.
+
+Repeatable choice elements is one of them.
+
+.. literalinclude:: /../tests/fixtures/compound/schema.xsd
+   :language: xml
+   :lines: 1-9
+
+In order to maintain the original order between roundtrip conversions you need to
+enable compound fields. Compound fields are group fields and can be used to wrap
+mixed context elements, repeatable choice elements or complex sequential elements.
+
+Read :ref:`more <Compound Fields>`
diff --git a/docs/faq/why-non-nullable-fields-are-marked-as-optional.rst b/docs/faq/why-non-nullable-fields-are-marked-as-optional.rst
@@ -0,0 +1,18 @@
+Why non-nullable fields are marked as optional?
+===============================================
+
+We rely on the fields ordering for all binding procedures and due to the following
+limitation we have to mark even required fields as optional.
+
+..
+
+    TypeError will be raised if a field without a default value follows a field
+    with a default value. This is true whether this occurs in a single class, or as
+    a result of class inheritance.
+
+    Source: :mod:`python:dataclasses`
+
+In Python 3.10 dataclasses introduced a new directive `kw_only` that resolves the above
+limitation and xsdata handling. Read :ref:`more <Dataclasses Features>`
+
+If you can't update just yet please check the `attrs <https://pypi.org/project/xsdata-attrs/>`_ plugin!