Update documentation and release info

CHANGELOG.rst

@@ -2,6 +2,12 @@
 CHANGELOG
 *********
 
+`v2.0.3`_ (2022-08-25)
+======================
+* *keep_empty* and *element_hook* options to main `iter_decode()`
+* Fix default namespace mapping in `BadgerFishConverter`
+* Fix type restriction check if restricted particle has `maxOccurs==0` (issue #323)
+
 `v2.0.2`_ (2022-08-12)
 ======================
 * Fix XSD 1.1 assertions effective scope
@@ -564,3 +570,4 @@ v0.9.6 (2017-05-05)
 .. _v2.0.0: https://github.com/brunato/xmlschema/compare/v1.11.3...v2.0.0
 .. _v2.0.1: https://github.com/brunato/xmlschema/compare/v2.0.0...v2.0.1
 .. _v2.0.2: https://github.com/brunato/xmlschema/compare/v2.0.1...v2.0.2
+.. _v2.0.3: https://github.com/brunato/xmlschema/compare/v2.0.2...v2.0.3

doc/api.rst

@@ -104,15 +104,11 @@ Schema level API
     .. automethod:: validate
     .. automethod:: is_valid
     .. automethod:: iter_errors
-    .. automethod:: decode
-
-    .. _schema-iter_decode:
 
+    .. automethod:: decode
     .. automethod:: iter_decode
-    .. automethod:: encode
-
-    .. _schema-iter_encode:
 
+    .. automethod:: encode
     .. automethod:: iter_encode
 
 

doc/usage.rst

@@ -412,8 +412,92 @@ to the method call:
 See the :ref:`converters` section for more information about converters.
 
 
+Control the decoding of XSD atomic datatypes
+--------------------------------------------
+
+XSD datatypes are decoded to Python basic datatypes. Python strings are used
+for all string-based XSD types and others, like *xs:hexBinary* or *xs:QName*.
+Python integers are used for *xs:integer* and derived types, `bool` for *xs:boolean*
+values and `decimal.Decimal` for *xs:decimal* values.
+
+Currently there are three options for variate the decoding of XSD atomic datatypes:
+
+decimal_type
+    decoding type for *xs:decimal* (is `decimal.Decimal` for default)
+
+datetime_types
+    if set to `True` decodes datetime and duration types to their respective XSD
+    atomic types instead of keeping the XML string value
+
+binary_types
+    if set to `True` decodes *xs:hexBinary* and *xs:base64Binary* types to their
+    respective XSD atomic types instead of keeping the XML string value
+
+
+Filling missing values
+----------------------
+
+Incompatible values are decoded with `None` when the *validation* mode is `'lax'`.
+For these situations there are two options for changing the behavior of the decoder:
+
+filler
+    a callback function to fill undecodable data with a typed value. The
+    callback function must accept one positional argument, that can be an
+    XSD Element or an attribute declaration. If not provided undecodable
+    data is replaced by `None`.
+
+fill_missing
+    if set to True the decoder fills also missing attributes. The filling value
+    is None or a typed value if the *filler* callback is provided.
+
+
+Control the decoding of elements
+--------------------------------
+
+These options concern the decoding of XSD elements:
+
+value_hook
+    a function that will be called with any decoded atomic value and the XSD type
+    used for decoding. The return value will be used instead of the original value.
+
+keep_empty
+    if set to `True` empty elements that are valid are decoded with an empty string
+    value instead of `None`.
+
+element_hook
+    an function that is called with decoded element data before calling the converter
+    decode method. Takes an `ElementData` instance plus optionally the XSD element
+    and the XSD type, and returns a new `ElementData` instance.
+
+
+Control the decoding of wildcards
+---------------------------------
+
+These two options are specific for the content processed with an XSD wildcard:
+
+keep_unknown
+    if set to `True` unknown tags are kept and are decoded with *xs:anyType*.
+    For default unknown tags not decoded by a wildcard are discarded.
+
+process_skipped
+    process XML data that match a wildcard with `processContents=’skip’`.
+
+
+Control the decoding depth
+--------------------------
+
+max_depth
+    maximum level of decoding, for default there is no limit. With lazy resources
+    is automatically set to *source.lazy_depth* for managing lazy decoding.
+
+depth_filler
+    a callback function for replacing data over the *max_depth* level. The callback
+    function must accept one positional argument, that can be an XSD Element. For
+    default deeper data is replaced with `None` values when *max_depth* is provided.
+
+
 Decoding to JSON
-----------------
+================
 
 The data structured created by the decoder can be easily serialized to JSON. But if you data
 include `Decimal` values (for *decimal* XSD built-in type) you cannot convert the data to JSON:

publiccode.yml

@@ -6,8 +6,8 @@ publiccodeYmlVersion: '0.2'
 name: xmlschema
 url: 'https://github.com/sissaschool/xmlschema'
 landingURL: 'https://github.com/sissaschool/xmlschema'
-releaseDate: '2022-08-12'
-softwareVersion: v2.0.2
+releaseDate: '2022-08-25'
+softwareVersion: v2.0.3
 developmentStatus: stable
 platforms:
   - linux