Releasing v21.8 (#577)

* Updated changelog

* Update docs

CHANGES.rst

@@ -1,6 +1,38 @@
-21.7 (2021-07-01)
+21.8 (2021-08-03)
 -----------------
+- Deprecated JsonSerializer indent property, use SerializerConfig instead
+- Fixed SchemaMapper assigning wrong namespace for imported unqualified elements
+- Fixed AttributeTypeHandler to maintain occurs between any flattening
+- Fixed missing required field metadata property
+- Fixed nillable fields not being marked as optional
+- Fixed fields ordering during class reduce process (Codegen from xml/json)
+- Added support for xs:defaultOpenContent:appliesToEmpty attribute
+- Added ParserConfig class factory option `#549 <https://github.com/tefra/xsdata/pull/549>`_
+- Added SerializerConfig option to ignore optional default attributes `#555 <https://github.com/tefra/xsdata/pull/555>`_
+- Added warning on unexpected duplicate types `#564 <https://github.com/tefra/xsdata/pull/564>`_
+- Added GeneratorConfig support for kw_only and slots for python >= 3.10
+- Added structure style namespace-clusters `#573 <https://github.com/tefra/xsdata/pull/573>`_
+- Updated text fields default value to empty string and marked as required `#570 <https://github.com/tefra/xsdata/pull/570>`_
+- Updated fields derived from xs:substitutionGroups to optional
+- Updated fields derived from xs:any to optional
+- Updated AttributeDefaultValueHandler to preserve acceptable default values
+- Updated AttributeDefaultValueHandler to mark as optional any xsi:type attribute
+- Updated xs:alternative handling to resemble xs:choice
+- Updated mixed content handler to group all elements under wildcard
+- Updated ElementMapper to detect nillable types
+- Updated DictMapper to generate list of xs:anySimpleType for empty list nodes
+- Updated the compatibility layer for dataclass style plugins
+- Updated namespaces structure style to convert namespaces similar to jaxb
+
+  - `http://www.w3.org/XML/1998/namespace` to `org.w3.XML.1998.namespace`
+
+- Update binding process for nillable types and fields
+
+  - nillable types can be initialized
+  - nillable fields are initialized with None values
 
+21.7 (2021-07-01)
+-----------------
 - Fixed docstrings backslash escaping `#518 <https://github.com/tefra/xsdata/pull/518>`_
 - Fixed analyzer flattening bare types `#541 <https://github.com/tefra/xsdata/pull/541>`_
 - Fixed multiple issues with compound fields and override fields `#533 <https://github.com/tefra/xsdata/pull/533>`_
@@ -382,12 +414,10 @@ deserved.
 
 20.1.1 (2020-01-09)
 -------------------
-
 - Change print mode to print rendered output
 - Added new format PlantUML class diagram to replace the old print/debug mode
 
 
 20.1 (2020-01-07)
 -----------------
-
 - Initial release

README.rst

@@ -96,23 +96,35 @@ Features
   - Customize behaviour through config
 
 
-Changelog: 21.7 (2021-07-01)
+Changelog: 21.8 (2021-08-03)
 ----------------------------
-
-- Fixed docstrings backslash escaping `#518 <https://github.com/tefra/xsdata/pull/518>`_
-- Fixed analyzer flattening bare types `#541 <https://github.com/tefra/xsdata/pull/541>`_
-- Fixed multiple issues with compound fields and override fields `#533 <https://github.com/tefra/xsdata/pull/533>`_
-- Fixed missing derived elements types during xml parsing `#541 <https://github.com/tefra/xsdata/pull/541>`_
-- Added structure style: clusters for smaller packages `#509 <https://github.com/tefra/xsdata/pull/509>`_
-- Added configuration to generate relative imports `#519 <https://github.com/tefra/xsdata/pull/519>`_
-- Added configuration to toggle all dataclasses features `#529 <https://github.com/tefra/xsdata/pull/529>`_
-- Added binding support for tuple typing annotations (frozen dataclasses) `#529 <https://github.com/tefra/xsdata/pull/529>`_
-- Added support to bind data directly from xml/lxml Element and ElementTree `#531 <https://github.com/tefra/xsdata/pull/531>`_ `#546 <https://github.com/tefra/xsdata/pull/546>`_
-- Updated analyzer to avoid same name for outer-inner classes `#511 <https://github.com/tefra/xsdata/pull/511>`_
-- Updated cli to fail early if config file is invalid `#514 <https://github.com/tefra/xsdata/pull/514>`_
-- Updated cli to remove setuptools from runtime dependencies `#515 <https://github.com/tefra/xsdata/pull/515>`_
-- Updated analyzer to relax override field validations completely `#516 <https://github.com/tefra/xsdata/pull/516>`_
-- Updated analyzer to sort classes before class name conflict resolution `#517 <https://github.com/tefra/xsdata/pull/517>`_
-- Updated JSON parser to attempt binding against subclasses `#527 <https://github.com/tefra/xsdata/pull/527>`_
-- Updated analyzer to guard against multiple substitution group runs `#538 <https://github.com/tefra/xsdata/pull/538>`_
-- Updated code generation to use case sensitive reserved words `#545 <https://github.com/tefra/xsdata/pull/545>`_
+- Deprecated JsonSerializer indent property, use SerializerConfig instead
+- Fixed SchemaMapper assigning wrong namespace for imported unqualified elements
+- Fixed AttributeTypeHandler to maintain occurs between any flattening
+- Fixed missing required field metadata property
+- Fixed nillable fields not being marked as optional
+- Fixed fields ordering during class reduce process (Codegen from xml/json)
+- Added support for xs:defaultOpenContent:appliesToEmpty attribute
+- Added ParserConfig class factory option `#549 <https://github.com/tefra/xsdata/pull/549>`_
+- Added SerializerConfig option to ignore optional default attributes `#555 <https://github.com/tefra/xsdata/pull/555>`_
+- Added warning on unexpected duplicate types `#564 <https://github.com/tefra/xsdata/pull/564>`_
+- Added GeneratorConfig support for kw_only and slots for python >= 3.10
+- Added structure style namespace-clusters `#573 <https://github.com/tefra/xsdata/pull/573>`_
+- Updated text fields default value to empty string and marked as required `#570 <https://github.com/tefra/xsdata/pull/570>`_
+- Updated fields derived from xs:substitutionGroups to optional
+- Updated fields derived from xs:any to optional
+- Updated AttributeDefaultValueHandler to preserve acceptable default values
+- Updated AttributeDefaultValueHandler to mark as optional any xsi:type attribute
+- Updated xs:alternative handling to resemble xs:choice
+- Updated mixed content handler to group all elements under wildcard
+- Updated ElementMapper to detect nillable types
+- Updated DictMapper to generate list of xs:anySimpleType for empty list nodes
+- Updated the compatibility layer for dataclass style plugins
+- Updated namespaces structure style to convert namespaces similar to jaxb
+
+  - `http://www.w3.org/XML/1998/namespace` to `org.w3.XML.1998.namespace`
+
+- Update binding process for nillable types and fields
+
+  - nillable types can be initialized
+  - nillable fields are initialized with None values

docs/api/codegen.rst

@@ -5,7 +5,7 @@ Generator Config
 The configuration offers more advance options to further tail the output to your needs,
 like naming conventions and aliases.
 
-.. literalinclude:: /_static/config.sample.xml
+.. literalinclude:: /_build/config.sample.xml
    :language: xml
 
 .. currentmodule:: xsdata.models.config

docs/faq.rst

@@ -0,0 +1,43 @@
+**************************
+Frequently Asked Questions
+**************************
+
+
+
+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>`

docs/index.rst

@@ -25,6 +25,7 @@
     examples
     data-types
     api
+    faq
     changelog
 
 

docs/models.rst

@@ -379,12 +379,26 @@ Wildcards can have a normal uri namespace or use one of xml schema generics.
         metadata={
             "type": "Wildcard",
             "namespace": "##any",
+            "choices": (
+                {
+                    "name": "DSAKeyValue",
+                    "type": DsakeyValue,
+                    "namespace": "http://www.w3.org/2000/09/xmldsig#",
+                },
+                {
+                    "name": "RSAKeyValue",
+                    "type": RsakeyValue,
+                    "namespace": "http://www.w3.org/2000/09/xmldsig#",
+                },
+            ),
         }
     )
 
 This type of field accepts any primitive value or an another dataclass instance or a
 generic :class:`~xsdata.formats.dataclass.models.generics.AnyElement` instance.
 
+This type optionally can have a list of acceptable elements similar to compound fields,
+otherwise during binding the parsers will try to find a suitable model automatically.
 
 Type: Attributes
 ~~~~~~~~~~~~~~~~

tests/fixtures/stripe/.xsdata.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<Config xmlns="http://pypi.org/project/xsdata" version="21.6">
+<Config xmlns="http://pypi.org/project/xsdata" version="21.8">
   <Output maxLineLength="79">
     <Package>tests.fixtures.stripe.models.balance</Package>
-    <Format repr="true" eq="true" order="true" unsafeHash="false" frozen="true">dataclasses</Format>
+    <Format repr="true" eq="true" order="true" unsafeHash="false" frozen="true" slots="false" kwOnly="false">dataclasses</Format>
     <Structure>single-package</Structure>
     <DocstringStyle>reStructuredText</DocstringStyle>
     <RelativeImports>true</RelativeImports>
@@ -15,6 +15,5 @@
     <ModuleName case="snakeCase" safePrefix="mod"/>
     <PackageName case="snakeCase" safePrefix="pkg"/>
   </Conventions>
-  <Aliases>
-  </Aliases>
+  <Aliases/>
 </Config>

tests/integration/test_stripe.py

@@ -1,5 +1,6 @@
 import json
 import os
+import sys
 
 from click.testing import CliRunner
 
@@ -15,9 +16,7 @@
 
 
 def test_json_documents():
-
     filepath = fixtures_dir.joinpath("stripe")
-    package = "tests.fixtures.series"
     runner = CliRunner()
     result = runner.invoke(
         cli,

tox.ini

@@ -16,7 +16,7 @@ basepython = python3.8
 extras = docs,cli
 changedir = docs
 commands =
-    xsdata init-config _static/config.sample.xml
+    xsdata init-config _build/config.sample.xml
     sphinx-build -b html . _build
 
 [testenv:build]

xsdata/__init__.py

@@ -1 +1 @@
-__version__ = "21.7"
+__version__ = "21.8"