# Package API

API includes classes and methods imported at package level and others included in subpackages. Only the modules, classes and methods imported within the top-level package are in fact to be considered as public API.

## Errors and exceptions

exception XMLSchemaException

  The base exception that let you catch all the errors generated by the library.

exception XMLResourceError

  A generic error on an XML resource that catches all the errors generated by an XML resource/loader instance on accessing XML data.

exception XMLSchemaNamespaceError

  Raised when a wrong runtime condition is found with a namespace.

exception XMLSchemaValidatorError(validator: XsdValidator | Callable[[Any], None], message: str, elem: Element | None = None, source: Any | None = None, namespaces: MutableMapping[str, str] | None = None)

  Base class for XSD validator errors.

  Parameters:

    - validator – the XSD validator.

    - message – the error message.

    - elem – the element that contains the error.

    - source – the XML resource or the decoded data that contains the error.

    - namespaces – is an optional mapping from namespace prefix to URI.

exception XMLSchemaNotBuiltError(validator: XsdValidator, message: str, namespaces: MutableMapping[str, str] | None = None)

  Raised when there is an improper usage attempt of a not built XSD validator.

  Parameters:

    - validator – the XSD validator.

    - message – the error message.

    - namespaces – is an optional mapping from namespace prefix to URI.

exception XMLSchemaParseError(validator: XsdValidator, message: str, elem: Element | None = None, namespaces: MutableMapping[str, str] | None = None)

  Raised when an error is found during the building of an XSD validator.

  Parameters:

    - validator – the XSD validator.

    - message – the error message.

    - elem – the element that contains the error.

    - namespaces – is an optional mapping from namespace prefix to URI.

exception XMLSchemaModelError(group: XsdGroup, message: str)

  Raised when a model error is found during the checking of a model group.

  Parameters:

    - group – the XSD model group.

    - message – the error message.

exception XMLSchemaModelDepthError(group: XsdGroup)

  Raised when recursion depth is exceeded while iterating a model group.

exception XMLSchemaValidationError(validator: XsdValidator | Callable[[Any], None], obj: Any, reason: str | None = None, source: Any | None = None, namespaces: MutableMapping[str, str] | None = None)

  Raised when the XML data is not validated with the XSD component or schema. It’s used by decoding and encoding methods. Encoding validation errors do not include XML data element and source, so the error is limited to a message containing object representation and a reason.

  Parameters:

    - validator – the XSD validator.

    - obj – the not validated XML data.

    - reason – the detailed reason of failed validation.

    - source – the XML resource that contains the error.

    - namespaces – is an optional mapping from namespace prefix to URI.

exception XMLSchemaDecodeError(validator: XsdValidator | Callable[[Any], None], obj: Any, decoder: Any, reason: str | None = None, source: Any | None = None, namespaces: MutableMapping[str, str] | None = None)

  Raised when an XML data string is not decodable to a Python object.

  Parameters:

    - validator – the XSD validator.

    - obj – the not validated XML data.

    - decoder – the XML data decoder.

    - reason – the detailed reason of failed validation.

    - source – the XML resource that contains the error.

    - namespaces – is an optional mapping from namespace prefix to URI.

exception XMLSchemaEncodeError(validator: XsdValidator | Callable[[Any], None], obj: Any, encoder: Any, reason: str | None = None, source: Any | None = None, namespaces: MutableMapping[str, str] | None = None)

  Raised when an object is not encodable to an XML data string.

  Parameters:

    - validator – the XSD validator.

    - obj – the not validated XML data.

    - encoder – the XML encoder.

    - reason – the detailed reason of failed validation.

    - source – the XML resource that contains the error.

    - namespaces – is an optional mapping from namespace prefix to URI.

exception XMLSchemaChildrenValidationError(validator: XsdValidator, elem: Element, index: int, particle: XsdElement | XsdAnyElement | XsdGroup, occurs: int = 0, expected: Iterable[XsdElement | XsdAnyElement] | None = None, source: Any | None = None, namespaces: MutableMapping[str, str] | None = None)

  Raised when a child element is not validated.

  Parameters:

    - validator – the XSD validator.

    - elem – the not validated XML element.

    - index – the child index.

    - particle – the model particle that generated the error. Maybe the validator itself.

    - occurs – the particle occurrences.

    - expected – the expected element tags/object names.

    - source – the XML resource that contains the error.

    - namespaces – is an optional mapping from namespace prefix to URI.

  invalid_tag: str | None = None

    The tag of the invalid child element, None in case of an incomplete content.

  invalid_child

    The invalid child element, if any, None otherwise. It’s None in case of incomplete content or if the parent has been cleared during lazy validation.

exception XMLSchemaStopValidation

  Stops the validation process.

exception XMLSchemaIncludeWarning

  A schema include fails.

exception XMLSchemaImportWarning

  A schema namespace import fails.

exception XMLSchemaTypeTableWarning

  Not equivalent type table found in model.

## Document level API

validate(xml_document: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, schema: XMLSchemaBase | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, schema_path: str | None = None, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, **kwargs: Any) → None

  Validates an XML document against a schema instance. This function builds an `XMLSchema` object for validating the XML document. Raises an `XMLSchemaValidationError` if the XML document is not validated against the schema.

  Parameters:

    - xml_document – can be an `XMLResource` instance, a file-like object a path to a file or a URI of a resource or an Element instance or an ElementTree instance or a string containing the XML data. If the passed argument is not an `XMLResource` instance a new one is built using this and defuse, timeout and lazy arguments.

    - schema – can be a schema instance or a file-like object or a file path or a URL of a resource or a string containing the schema.

    - cls – class to use for building the schema instance (for default `XMLSchema10` is used).

    - path – is an optional XPath expression that matches the elements of the XML data that have to be decoded. If not provided the XML root element is used.

    - schema_path – an XPath expression to select the XSD element to use for decoding. If not provided the path argument or the source root tag are used.

    - use_defaults – defines when to use element and attribute defaults for filling missing required values.

    - namespaces – is an optional mapping from namespace prefix to URI.

    - locations – additional schema location hints, used if a schema instance has to be built.

    - use_location_hints – for default, in case a schema instance has to be built, uses also schema locations hints provided within XML data. set this option to False to ignore these schema location hints.

    - kwargs – other optional arguments for building `XMLResource` or `XMLSchema` instances provided as keyword arguments.

is_valid(xml_document: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, schema: XMLSchemaBase | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, schema_path: str | None = None, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, **kwargs: Any) → bool

  Like `validate()` except that do not raise an exception but returns `True` if the XML document is valid, `False` if it’s invalid.

iter_errors(xml_document: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, schema: XMLSchemaBase | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, schema_path: str | None = None, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, **kwargs: Any) → Iterator[XMLSchemaValidationError]

  Creates an iterator for the errors generated by the validation of an XML document. Takes the same arguments of the function `validate()`.

iter_decode(xml_document: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, schema: XMLSchemaBase | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, validation: str = 'lax', locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, **kwargs: Any) → Iterator[Any | XMLSchemaValidationError]

  Creates an iterator for decoding an XML source to a data structure. For default the document is validated during the decoding phase and if it’s invalid then one or more `XMLSchemaValidationError` instances are yielded before the decoded data.

  Parameters:

    - xml_document – can be an `XMLResource` instance, a file-like object a path to a file or a URI of a resource or an Element instance or an ElementTree instance or a string containing the XML data. If the passed argument is not an `XMLResource` instance a new one is built using this and defuse, timeout and lazy arguments.

    - schema – can be a schema instance or a file-like object or a file path or a URL of a resource or a string containing the schema.

    - cls – class to use for building the schema instance (for default uses `XMLSchema10`).

    - path – is an optional XPath expression that matches the elements of the XML data that have to be decoded. If not provided the XML root element is used.

    - validation – defines the XSD validation mode to use for decode, can be ‘strict’, ‘lax’ or ‘skip’.

    - locations – additional schema location hints, in case a schema instance has to be built.

    - use_location_hints – for default, in case a schema instance has to be built, uses also schema locations hints provided within XML data. set this option to False to ignore these schema location hints.

    - kwargs – other optional arguments of `XMLSchemaBase.iter_decode()` or for building `XMLResource` or `XMLSchema` instances provided as keyword arguments.

  Raises:

    `XMLSchemaValidationError` if the XML document is invalid and `validation='strict'` is provided.

to_dict(xml_document: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, schema: XMLSchemaBase | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, validation: str = 'strict', locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, **kwargs: Any) → Any | None | tuple[Any | None, list[XMLSchemaValidationError]]

  Decodes an XML document to a Python’s nested dictionary. Takes the same arguments of the function `iter_decode()`, but validation mode defaults to ‘strict’.

  Returns:

    an object containing the decoded data. If `validation='lax'` is provided validation errors are collected and returned in a tuple with the decoded data.

  Raises:

    `XMLSchemaValidationError` if the XML document is invalid and `validation='strict'` is provided.

to_json(xml_document: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, fp: IO[str] | None = None, schema: XMLSchemaBase | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, validation: str = 'strict', locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, json_options: dict[str, Any] | None = None, **kwargs: Any) → str | None | tuple[XMLSchemaValidationError, ...] | tuple[str | None, tuple[XMLSchemaValidationError, ...]]

  Serialize an XML document to JSON. For default the XML data is validated during the decoding phase. Raises an `XMLSchemaValidationError` if the XML document is not validated against the schema.

  Parameters:

    - xml_document – can be an `XMLResource` instance, a file-like object a path to a file or a URI of a resource or an Element instance or an ElementTree instance or a string containing the XML data. If the passed argument is not an `XMLResource` instance a new one is built using this and defuse, timeout and lazy arguments.

    - fp – can be a `write()` supporting file-like object.

    - schema – can be a schema instance or a file-like object or a file path or a URL of a resource or a string containing the schema.

    - cls – schema class to use for building the instance (for default uses `XMLSchema10`).

    - path – is an optional XPath expression that matches the elements of the XML data that have to be decoded. If not provided the XML root element is used.

    - validation – defines the XSD validation mode to use for decode, can be ‘strict’, ‘lax’ or ‘skip’.

    - locations – additional schema location hints, in case the schema instance has to be built.

    - use_location_hints – for default, in case a schema instance has to be built, uses also schema locations hints provided within XML data. set this option to False to ignore these schema location hints.

    - json_options – a dictionary with options for the JSON serializer.

    - kwargs – optional arguments of `XMLSchemaBase.iter_decode()` as keyword arguments to variate the decoding process.

  Returns:

    a string containing the JSON data if fp is None, otherwise doesn’t return anything. If `validation='lax'` keyword argument is provided the validation errors are collected and returned, eventually coupled in a tuple with the JSON data.

  Raises:

    `XMLSchemaValidationError` if the object is not decodable by the XSD component, or also if it’s invalid when `validation='strict'` is provided.

to_etree(obj: Any, schema: XMLSchemaBase | str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, validation: str = 'strict', namespaces: MutableMapping[str, str] | None = None, use_defaults: bool = True, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, unordered: bool = False, **kwargs: Any) → Element | tuple[Element, list[XMLSchemaValidationError]]

  Encodes a data structure/object to an ElementTree’s Element.

  Parameters:

    - obj – the Python object that has to be encoded to XML data.

    - schema – can be a schema instance or a file-like object or a file path or a URL of a resource or a string containing the schema. If not provided a dummy schema is used.

    - cls – class to use for building the schema instance (for default uses `XMLSchema10`).

    - path – is an optional XPath expression for selecting the element of the schema that matches the data that has to be encoded. For default the first global element of the schema is used.

    - validation – the XSD validation mode. Can be ‘strict’, ‘lax’ or ‘skip’.

    - namespaces – is an optional mapping from namespace prefix to URI.

    - use_defaults – whether to use default values for filling missing data.

    - converter – an `XMLSchemaConverter` subclass or instance to use for the encoding.

    - unordered – a flag for explicitly activating unordered encoding mode for content model data. This mode uses content models for a reordered-by-model iteration of the child elements.

    - kwargs – other optional arguments of `XMLSchemaBase.iter_encode()` and options for the converter.

  Returns:

    An element tree’s Element instance. If `validation='lax'` keyword argument is provided the validation errors are collected and returned coupled in a tuple with the Element instance.

  Raises:

    `XMLSchemaValidationError` if the object is not encodable by the schema, or also if it’s invalid when `validation='strict'` is provided.

from_json(source: str | bytes | IO[str], schema: XMLSchemaBase | str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource | None = None, cls: Type[XMLSchemaBase] | None = None, path: str | None = None, validation: str = 'strict', namespaces: MutableMapping[str, str] | None = None, use_defaults: bool = True, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, unordered: bool = False, json_options: dict[str, Any] | None = None, **kwargs: Any) → Element | tuple[Element, list[XMLSchemaValidationError]]

  Deserialize JSON data to an XML Element.

  Parameters:

    - source – can be a string or a `read()` supporting file-like object containing the JSON document.

    - schema – an `XMLSchema10` or an `XMLSchema11` instance.

    - cls – class to use for building the schema instance (for default uses `XMLSchema10`).

    - path – is an optional XPath expression for selecting the element of the schema that matches the data that has to be encoded. For default the first global element of the schema is used.

    - validation – the XSD validation mode. Can be ‘strict’, ‘lax’ or ‘skip’.

    - namespaces – is an optional mapping from namespace prefix to URI.

    - use_defaults – whether to use default values for filling missing data.

    - converter – an `XMLSchemaConverter` subclass or instance to use for the encoding.

    - unordered – a flag for explicitly activating unordered encoding mode for content model data. This mode uses content models for a reordered-by-model iteration of the child elements.

    - json_options – a dictionary with options for the JSON deserializer.

    - kwargs – other optional arguments of `XMLSchemaBase.iter_encode()` and options for converter.

  Returns:

    An element tree’s Element instance. If `validation='lax'` keyword argument is provided the validation errors are collected and returned coupled in a tuple with the Element instance.

  Raises:

    `XMLSchemaValidationError` if the object is not encodable by the schema, or also if it’s invalid when `validation='strict'` is provided.

## Schema level API

class XMLSchema10(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource | list[str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource], namespace: str | None = None, validation: str = 'strict', global_maps: XsdGlobals | None = None, parent: XMLSchemaBase | None = None, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, base_url: str | None = None, allow: str = 'all', defuse: str = 'remote', timeout: int = 300, uri_mapper: MutableMapping[str, str] | Callable[[str], str] | None = None, opener: OpenerDirector | None = None, iterparse: Callable[[IOProtocol[str] | IOProtocol[bytes], Sequence[str] | None], Iterator[tuple[str, Any]]] | None = None, loader_class: Type[SchemaLoader] | None = None, use_fallback: bool = True, use_xpath3: bool = False, use_meta: bool = True, loglevel: str | int | None = None, build: bool = True, partial: bool = False)

  XSD 1.0 schema class.

class XMLSchema11(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource | list[str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource], namespace: str | None = None, validation: str = 'strict', global_maps: XsdGlobals | None = None, parent: XMLSchemaBase | None = None, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, base_url: str | None = None, allow: str = 'all', defuse: str = 'remote', timeout: int = 300, uri_mapper: MutableMapping[str, str] | Callable[[str], str] | None = None, opener: OpenerDirector | None = None, iterparse: Callable[[IOProtocol[str] | IOProtocol[bytes], Sequence[str] | None], Iterator[tuple[str, Any]]] | None = None, loader_class: Type[SchemaLoader] | None = None, use_fallback: bool = True, use_xpath3: bool = False, use_meta: bool = True, loglevel: str | int | None = None, build: bool = True, partial: bool = False)

  XSD 1.1 schema class.

  The classes for XSD v1.0 and v1.1 schema instances. They are both generated by the meta-class `XMLSchemaMeta` and take the same API of `xmlschema.XMLSchemaBase`.

XMLSchema

  alias of `XMLSchema10`

class XMLSchemaMeta(name: str, bases: tuple[Type[Any]], dict_: dict[str, Any])

class XMLSchemaBase(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource | list[str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource], namespace: str | None = None, validation: str = 'strict', global_maps: XsdGlobals | None = None, parent: XMLSchemaBase | None = None, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, base_url: str | None = None, allow: str = 'all', defuse: str = 'remote', timeout: int = 300, uri_mapper: MutableMapping[str, str] | Callable[[str], str] | None = None, opener: OpenerDirector | None = None, iterparse: Callable[[IOProtocol[str] | IOProtocol[bytes], Sequence[str] | None], Iterator[tuple[str, Any]]] | None = None, loader_class: Type[SchemaLoader] | None = None, use_fallback: bool = True, use_xpath3: bool = False, use_meta: bool = True, loglevel: str | int | None = None, build: bool = True, partial: bool = False)

  Base class for an XML Schema instance.

  Parameters:

    - source – a URI that reference to a resource or a file path or a file-like object or a string containing the schema or an Element or an ElementTree document or an `XMLResource` instance. A multi source initialization is supported providing a not empty list of XSD sources.

    - namespace – is an optional argument that contains the URI of the namespace that has to used in case the schema has no namespace (chameleon schema). For other cases, when specified, it must be equal to the targetNamespace of the schema.

    - validation – the XSD validation mode to use for build the schema, that can be ‘strict’ (default), ‘lax’ or ‘skip’.

    - global_maps – is an optional argument containing an `XsdGlobals` instance, a mediator object for sharing declaration data between dependents schema instances.

    - parent – optional `XMLSchema` instance to use as parent if a new `XsdGlobals` is created, ignored otherwise.

    - loader_class – an optional subclass of `SchemaLoader` to use for creating the loader instance.

    - converter – is an optional argument that can be an `XMLSchemaConverter` subclass or instance, used for defining the default XML data converter for XML Schema instance.

    - locations – schema extra location hints, that can include custom resource locations (e.g. local XSD file instead of remote resource) or additional namespaces to import after processing schema’s import statements. Can be a dictionary or a sequence of couples (namespace URI, resource URL). Extra locations passed using a tuple container are not normalized.

    - base_url – is an optional base URL, used for the normalization of relative paths when the URL of the schema resource can’t be obtained from the source argument.

    - allow – the security mode for accessing resource locations. Can be ‘all’, ‘remote’, ‘local’ or ‘sandbox’. Default is ‘all’ that means all types of URLs are allowed. With ‘remote’ only remote resource URLs are allowed. With ‘local’ only file paths and URLs are allowed. With ‘sandbox’ only file paths and URLs that are under the directory path identified by source or by the base_url argument are allowed.

    - defuse – defines when to defuse XML data using a SafeXMLParser. Can be ‘always’, ‘remote’ or ‘never’. For default defuses only remote XML data.

    - timeout – the timeout in seconds for fetching resources. Default is 300.

    - uri_mapper – an optional URI mapper for using relocated or URN-addressed resources. Can be a dictionary or a function that takes the URI string and returns a URL, or the argument if there is no mapping for it.

    - opener – an optional `OpenerDirector` instance used for opening XML resources. For default uses the opener installed globally for urlopen.

    - iterparse – an optional callable that returns an iterator parser instance used for building the XML trees. For default ElementTree.iterparse is used.

    - use_fallback – if True the schema processor uses the validator fallback location hints to load well-known namespaces (e.g. xhtml).

    - use_xpath3 – if True an XSD 1.1 schema instance uses the XPath 3 processor for assertions. For default a full XPath 2.0 processor is used.

    - use_meta – if True the schema processor uses the validator meta-schema as parent schema. Ignored if either global_maps or parent argument is provided.

    - loglevel – for setting a different logging level for schema initialization and building. For default is WARNING (30). For INFO level set it with 20, for DEBUG level with 10. The default loglevel is restored after schema building, when exiting the initialization method.

    - build – defines whether build the schema maps. Default is True.

    - partial – if True, the schema is initialized without processing imports/inclusions and the build phase is skipped.

  Variables:

    - XSD_VERSION – store the XSD version (1.0 or 1.1).

    - BASE_SCHEMAS – a dictionary from namespace to schema resource for meta-schema bases.

    - meta_schema – the XSD meta-schema instance.

    - attribute_form_default – the schema’s attributeFormDefault attribute. Default is ‘unqualified’.

    - element_form_default – the schema’s elementFormDefault attribute. Default is ‘unqualified’.

    - block_default – the schema’s blockDefault attribute. Default is ‘’.

    - final_default – the schema’s finalDefault attribute. Default is ‘’.

    - default_attributes – the XSD 1.1 schema’s defaultAttributes attribute. Default is `None`.

    - target_namespace – is the targetNamespace of the schema, the namespace to which belong the declarations/definitions of the schema. If it’s empty no namespace is associated with the schema. In this case the schema declarations can be reused from other namespaces as chameleon definitions.

    - maps – XSD global declarations/definitions maps. This is an instance of `XsdGlobals`, that stores the global_maps argument or a new object when this argument is not provided.

    - namespaces – a dictionary that maps from the prefixes used by the schema into namespace URI.

    - imports – a dictionary of namespace imports of the schema, that maps namespace URI to imported schema object, or None in case of unsuccessful import.

    - includes – a dictionary of included schemas, that maps a schema location to an included schema. It also comprehends schemas included by “xs:redefine” or “xs:override” statements.

    - warnings – warning messages about failure of import and include elements.

    - notations (NamespaceView) – xsd:notation declarations.

    - types (NamespaceView) – xsd:simpleType and xsd:complexType global declarations.

    - attributes (NamespaceView) – xsd:attribute global declarations.

    - attribute_groups (NamespaceView) – xsd:attributeGroup definitions.

    - groups (NamespaceView) – xsd:group global definitions.

    - elements (NamespaceView) – xsd:element global declarations.

  meta_schema: XMLSchemaBase | None = None
  builders: XsdBuilders
  root

    Root element of the schema.

  get_text() → str

    Returns the source text of the XSD schema.

  name: str | None = None
  url

    Schema resource URL, is None if the schema is built from an Element or a string.

  base_url

    The base URL of the source of the schema.

  tag

    Schema root tag. For compatibility with the ElementTree API.

  id

    The schema’s id attribute, defaults to `None`.

  version

    The schema’s version attribute, defaults to `None`.

  schema_location

    A list of location hints extracted from the xsi:schemaLocation attribute of the schema.

  no_namespace_schema_location

    A location hint extracted from the xsi:noNamespaceSchemaLocation attribute of the schema.

  target_prefix

    The prefix associated to the targetNamespace.

  default_namespace

    The namespace associated to the empty prefix ‘’.

  root_elements

    The list of global elements that are not used by reference in any model of the schema. This is implemented as lazy property because it’s computationally expensive to build when the schema model is complex.

  simple_types

    Returns a list containing the global simple types.

  complex_types

    Returns a list containing the global complex types.

  classmethod builtin_types() → NamespaceView[XsdSimpleType | XsdComplexType]

    Returns the XSD built-in types of the meta-schema.

  classmethod create_meta_schema(source: str | None = None, base_schemas: dict[str, str] | None = None, global_maps: XsdGlobals | None = None) → XMLSchemaBase

    Creates a new meta-schema instance.

    Parameters:

      - source – location of the XSD meta-schema file/resource.

      - base_schemas – a dictionary that contains namespace URIs and locations of base schemas.

      - global_maps – an optional XsdGlobals instance where include the meta-schema.

  get_locations(namespace: str) → list[str]

    Get a list of location hints for a namespace.

  include_schema(location: str, base_url: str | None = None, build: bool = False, partial: bool = False) → XMLSchemaBase

    Includes a schema for the same namespace, from a specific URL.

    Parameters:

      - location – is the URL of the schema.

      - base_url – is an optional base URL for fetching the schema resource.

      - build – defines when to build the imported schema, the default is to not build.

      - partial – if True, the included schema is initialized without processing imports/inclusions and the build phase is skipped.

    Returns:

      the included `XMLSchema` instance.

    Returns:

      the included `XMLSchema` instance.

  import_schema(namespace: str, location: str, base_url: str | None = None, force: bool = False, build: bool = False, partial: bool = False) → XMLSchemaBase | None

    Imports a schema for an external namespace from a specific location.

    Parameters:

      - namespace – is the URI of the external namespace.

      - location – is the URL of the schema.

      - base_url – is an optional base URL for fetching the schema resource.

      - force – if set to True imports the schema also if the namespace is already imported.

      - build – defines when to build the imported schema, the default is to not build.

      - partial – if True, the imported schema is initialized without processing imports/inclusions and the build phase is skipped.

    Returns:

      the imported `XMLSchema` instance or None if a schema can’t be imported from that location.

  add_schema(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource, namespace: str | None = None, base_url: str | None = None, build: bool = False, partial: bool = False) → XMLSchemaBase

    Add another schema source to the maps of the instance without affecting imports or includes registrations.

    Parameters:

      - source – a URI that reference to a resource or a file path or a file-like object or a string containing the schema or an Element or an ElementTree document.

      - namespace – is an optional argument that contains the URI of the namespace that has to used in case the schema has no namespace (chameleon schema). It must be equal to the targetNamespace of the schema. If not provided, the resource is examined and if the schema has no namespace it’s added as a chameleon schema.

      - base_url – is an optional base URL for fetching the schema resource.

      - build – defines when to build the imported schema, the default is to not build.

      - partial – if True, the added schema is initialized without processing imports/inclusions and the build phase is skipped.

    Returns:

      the added `XMLSchema` instance.

  export(target: str | Path, save_remote: bool = False, remove_residuals: bool = True, exclude_locations: list[str] | None = None, loglevel: str | int | None = None) → dict[str, str]

    Exports a schema instance. The schema instance is exported to a directory with also the hierarchy of imported/included schemas.

    Parameters:

      - target – a path to a local empty directory.

      - save_remote – if True is provided saves also remote schemas.

      - remove_residuals – for default removes residual remote schema locations from redundant import statements.

      - exclude_locations – explicitly exclude schema locations from substitution or removal.

      - loglevel – for setting a different logging level for schema export.

    Returns:

      a dictionary containing the map of modified locations.

  resolve_qname(qname: str, namespace_imported: bool = True) → str

    QName resolution for a schema instance.

    Parameters:

      - qname – a string in xs:QName format.

      - namespace_imported – if this argument is True raises an XMLSchemaNamespaceError if the namespace of the QName is not the targetNamespace and the namespace is not imported by the schema.

    Returns:

      an expanded QName in the format “{namespace-URI}*local-name*”.

    Raises:

      XMLSchemaValueError for an invalid xs:QName is found, XMLSchemaKeyError if the namespace prefix is not declared in the schema instance.

  iter_globals() → Iterator[XsdNotation | XsdSimpleType | XsdComplexType | XsdElement | XsdAttribute | XsdAttributeGroup | XsdGroup]

    Iterates XSD global definitions/declarations of the schema.

  iter_components(xsd_classes: None | type[XsdComponent] | tuple[type[XsdComponent], ...] = None) → Iterator[XsdComponent | XMLSchemaBase]

    Iterates yielding the schema and its components. For default includes all the relevant components of the schema, excluding only facets and empty attribute groups. The first returned component is the schema itself.

    Parameters:

      xsd_classes – provide a class or a tuple of classes to restrict the range of component types yielded.

  build() → None

    Builds the schema’s XSD global maps.

  clear() → None

    Clears the schema cache.

  built
  validation_attempted
  validity
  all_errors

    A list with all the building errors of the XSD validator and its components.

  get_converter(converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, **kwargs: Any) → XMLSchemaConverter

    Returns a new converter instance.

    Parameters:

      - converter – can be a converter class or instance. If not provided the converter attribute of the schema instance is used.

      - kwargs – optional arguments for initialize the converter instance.

    Returns:

      a converter instance.

  validate(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, path: str | None = None, schema_path: str | None = None, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, max_depth: int | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None, allow_empty: bool = True, use_location_hints: bool = False) → None

    Validates an XML data against the XSD schema/component instance.

    Parameters:

      - source – the source of XML data. Can be an `XMLResource` instance, a path to a file or a URI of a resource or an opened file-like object or an Element instance or an ElementTree instance or a string containing the XML data.

      - path – is an optional XPath expression that matches the elements of the XML data that have to be decoded. If not provided the XML root element is selected.

      - schema_path – an alternative XPath expression to select the XSD element to use for decoding. Useful if the root of the XML data doesn’t match an XSD global element of the schema.

      - use_defaults – Use schema’s default values for filling missing data.

      - namespaces – is an optional mapping from namespace prefix to URI.

      - max_depth – maximum level of validation, for default there is no limit. With lazy resources is set to source.lazy_depth for managing lazy validation.

      - extra_validator – an optional function for performing non-standard validations on XML data. The provided function is called for each traversed element, with the XML element as 1st argument and the corresponding XSD element as 2nd argument. It can be also a generator function and has to raise/yield `XMLSchemaValidationError` exceptions.

      - validation_hook – an optional function for stopping or changing validation at element level. The provided function must accept two arguments, the XML element and the matching XSD element. If the value returned by this function is evaluated to false then the validation process continues without changes, otherwise the validation process is stopped or changed. If the value returned is a validation mode the validation process continues changing the current validation mode to the returned value, otherwise the element and its content are not processed. The function can also stop validation suddenly raising a XmlSchemaStopValidation exception.

      - allow_empty – for default providing a path argument empty selections of XML data are allowed. Provide False to generate a validation error.

      - use_location_hints – for default schema locations hints provided within XML data are ignored in order to avoid the change of schema instance. Set this option to True to activate dynamic schema loading using schema location hints.

    Raises:

      `XMLSchemaValidationError` if the XML data instance is invalid.

  is_valid(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, path: str | None = None, schema_path: str | None = None, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, max_depth: int | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None, allow_empty: bool = True, use_location_hints: bool = False) → bool

    Like `validate()` except that does not raise an exception but returns `True` if the XML data instance is valid, `False` if it is invalid.

  iter_errors(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, path: str | None = None, schema_path: str | None = None, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, max_depth: int | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None, allow_empty: bool = True, use_location_hints: bool = False, validation: str = 'lax') → Iterator[XMLSchemaValidationError]

    Creates an iterator for the errors generated by the validation of an XML data against the XSD schema/component instance. Accepts the same arguments of `validate()`.

  decode(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, path: str | None = None, schema_path: str | None = None, validation: str = 'strict', *args: Any, **kwargs: Any) → Any | None | tuple[Any | None, list[XMLSchemaValidationError]]

    Decodes XML data. Takes the same arguments of the method `iter_decode()`.

  iter_decode(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol | XMLResource, path: str | None = None, schema_path: str | None = None, validation: str = 'lax', process_namespaces: bool = True, namespaces: MutableMapping[str, str] | None = None, use_defaults: bool = True, use_location_hints: bool = False, decimal_type: Type[Any] | None = None, datetime_types: bool = False, binary_types: bool = False, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, filler: Callable[[XsdElement | XsdAttribute], None | str | bytes | int | float | Decimal | bool | Integer | Float10 | NormalizedString | AnyURI | QName | Duration | AbstractDateTime | AbstractBinary | list[str | bytes | int | float | Decimal | bool | Integer | Float10 | NormalizedString | AnyURI | QName | Duration | AbstractDateTime | AbstractBinary | None]] | None = None, fill_missing: bool = False, keep_empty: bool = False, keep_unknown: bool = False, process_skipped: bool = False, max_depth: int | None = None, depth_filler: Callable[[XsdElement], Any] | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None, value_hook: Callable[[str | bytes | int | float | Decimal | bool | Integer | Float10 | NormalizedString | AnyURI | QName | Duration | AbstractDateTime | AbstractBinary | None, BaseXsdType], None | str | bytes | int | float | Decimal | bool | Integer | Float10 | NormalizedString | AnyURI | QName | Duration | AbstractDateTime | AbstractBinary | list[str | bytes | int | float | Decimal | bool | Integer | Float10 | NormalizedString | AnyURI | QName | Duration | AbstractDateTime | AbstractBinary | None]] | None = None, element_hook: Callable[[ElementData, XsdElement | None, BaseXsdType | None], ElementData] | None = None, errors: list[XMLSchemaValidationError] | None = None, **kwargs: Any) → Iterator[Any | XMLSchemaValidationError]

    Creates an iterator for decoding an XML source to a data structure.

    Parameters:

      - source – the source of XML data. Can be an `XMLResource` instance, a path to a file or a URI of a resource or an opened file-like object or an Element instance or an ElementTree instance or a string containing the XML data.

      - path – is an optional XPath expression that matches the elements of the XML data that have to be decoded. If not provided the XML root element is selected.

      - schema_path – an alternative XPath expression to select the XSD element to use for decoding. Useful if the root of the XML data doesn’t match an XSD global element of the schema.

      - validation – defines the XSD validation mode to use for decode, can be ‘strict’, ‘lax’ or ‘skip’.

      - process_namespaces – whether to use namespace information in the decoding process, using the map provided with the argument namespaces and the namespace declarations extracted from the XML document.

      - namespaces – is an optional mapping from namespace prefix to URI that integrate/override the root namespace declarations of the XML source. In case of prefix collision an alternate prefix is used for the root XML namespace declaration.

      - use_defaults – whether to use default values for filling missing data.

      - use_location_hints – for default schema locations hints provided within XML data are ignored in order to avoid the change of schema instance. Set this option to True to activate dynamic schema loading using schema location hints.

      - decimal_type – conversion type for Decimal objects (generated by xs:decimal built-in and derived types), useful if you want to generate a JSON-compatible data structure.

      - datetime_types – if set to True the datetime and duration XSD types are kept decoded, otherwise their origin XML string is returned.

      - binary_types – if set to True xs:hexBinary and xs:base64Binary types are kept decoded, otherwise their origin XML string is returned.

      - converter – an `XMLSchemaConverter` subclass or instance to use for decoding.

      - filler – an optional 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.

      - keep_empty – if set to True empty elements that are valid are decoded with an empty string value instead of a None.

      - 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’.

      - max_depth – maximum level of decoding, for default there is no limit. With lazy resources is set to source.lazy_depth for managing lazy decoding.

      - depth_filler – an optional callback function to replace data over the max_depth level. The callback function must accept one positional argument, that can be an XSD Element. If not provided deeper data are replaced with None values.

      - extra_validator – an optional function for performing non-standard validations on XML data. The provided function is called for each traversed element, with the XML element as 1st argument and the corresponding XSD element as 2nd argument. It can be also a generator function and has to raise/yield `XMLSchemaValidationError` exceptions.

      - validation_hook – an optional function for stopping or changing validated decoding at element level. The provided function must accept two arguments, the XML element and the matching XSD element. If the value returned by this function is evaluated to false then the decoding process continues without changes, otherwise the decoding process is stopped or changed. If the value returned is a validation mode the decoding process continues changing the current validation mode to the returned value, otherwise the element and its content are not decoded.

      - value_hook – an optional 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.

      - element_hook – an optional 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.

      - errors – optional internal collector for validation errors.

      - kwargs – keyword arguments with other options for building converter instances.

    Returns:

      yields a decoded data object, eventually preceded by a sequence of validation or decoding errors.

  encode(obj: Any, path: str | None = None, validation: str = 'strict', *args: Any, **kwargs: Any) → Any | tuple[Any, list[XMLSchemaValidationError]]

    Encodes to XML data. Takes the same arguments of the method `iter_encode()`.

    Returns:

      An ElementTree’s Element or a list containing a sequence of ElementTree’s elements if the argument path matches multiple XML data chunks. If validation argument is ‘lax’ a 2-items tuple is returned, where the first item is the encoded object and the second item is a list containing the errors.

  iter_encode(obj: Any, path: str | None = None, validation: str = 'lax', namespaces: MutableMapping[str, str] | None = None, use_defaults: bool = True, converter: Type[XMLSchemaConverter] | XMLSchemaConverter | None = None, unordered: bool = False, process_skipped: bool = False, max_depth: int | None = None, untyped_data: bool = False, **kwargs: Any) → Iterator[Element | XMLSchemaValidationError]

    Creates an iterator for encoding a data structure to an ElementTree’s Element.

    Parameters:

      - obj – the data that has to be encoded to XML data.

      - path – is an optional XPath expression for selecting the element of the schema that matches the data that has to be encoded. For default the first global element of the schema is used.

      - validation – the XSD validation mode. Can be ‘strict’, ‘lax’ or ‘skip’.

      - namespaces – is an optional mapping from namespace prefix to URI.

      - use_defaults – whether to use default values for filling missing data.

      - converter – an `XMLSchemaConverter` subclass or instance to use for the encoding.

      - unordered – a flag for explicitly activating unordered encoding mode for content model data. This mode uses content models for a reordered-by-model iteration of the child elements.

      - process_skipped – process XML decoded data that match a wildcard with processContents=’skip’.

      - max_depth – maximum level of encoding, for default there is no limit.

      - untyped_data – for default xs:untypedAtomic datatype is not accepted as a decoded value, set to true to extend the compatibility of with string and untyped values to all builtin datatypes.

      - kwargs – keyword arguments with other options for building the converter instance.

    Returns:

      yields an Element instance/s or validation/encoding errors.

## Global maps API

class XsdGlobals(validator: XMLSchemaBase, validation: str = 'strict', parent: XMLSchemaBase | None = None, loader_class: Type[SchemaLoader] | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_fallback: bool = True, use_xpath3: bool = False)

  Mediator collection class for composing XML schema instances and provides lookup maps. It stores the global declarations defined in the registered schemas. Register a schema to add its declarations to the global maps.

  Parameters:

    - validator – the origin schema class/instance used for creating the global maps.

    - validation – deprecated argument for the validation mode, now it takes the validation mode of the validator.

    - parent – an optional parent schema, that is required to be built and with no use of the target namespace of the validator.

    - loader_class – an optional subclass of `SchemaLoader` to use for creating the loader instance.

    - locations – schema extra location hints, that can include custom resource locations or additional namespaces to import after processing schema’s import statements.

    - use_fallback – if True the schema processor uses the validator fallback location hints to load well-known namespaces (e.g. xhtml).

    - use_xpath3 – if True an XSD 1.1 schema instance uses the XPath 3 processor for assertions. For default a full XPath 2.0 processor is used.

  build() → None

    Build the maps of XSD global definitions/declarations. The global maps are updated adding and building the globals of not built registered schemas.

  check(schemas: Iterable[XMLSchemaBase] | None = None) → None

    Checks the components of provided schemas. Used after the build of the global maps. For default checks all schemas and raises an exception at first error.

    Parameters:

      schemas – optional argument with the set of the schemas to check.

    Raise:

      XMLSchemaParseError

  clear(remove_schemas: bool = False) → None

    Clears the instance maps and schemas.

    Parameters:

      remove_schemas – removes also the schema instances, keeping only the validator that created the global maps instance and schemas and namespaces inherited from ancestors.

  iter_globals() → Iterator[XsdNotation | XsdSimpleType | XsdComplexType | XsdElement | XsdAttribute | XsdAttributeGroup | XsdGroup]

    Creates an iterator for the built XSD global components.

  iter_schemas() → Iterator[XMLSchemaBase]

    Creates an iterator for the registered schemas.

  lookup(tag: str, qname: str) → XsdNotation | XsdSimpleType | XsdComplexType | XsdElement | XsdAttribute | XsdAttributeGroup | XsdGroup

    General lookup method for XSD global components.

    Parameters:

      - tag – the expanded QName of the XSD the global declaration/definition (e.g. ‘{http://www.w3.org/2001/XMLSchema}element’), that is used to select the global map for lookup.

      - qname – the expanded QName of the component to be looked-up.

    Returns:

      an XSD global component.

    Raises:

      an XMLSchemaValueError if the tag argument is not appropriate for a global component, an XMLSchemaKeyError if the qname argument is not found in the global map.

  register(schema: XMLSchemaBase) → None

    Registers an XMLSchema instance.

  property unbuilt: list[XsdComponent]

    Property that returns a list with unbuilt components.

## Converters API

The base class XMLSchemaConverter is used for defining generic converters. The subclasses implement some of the most used conventions for converting XML to JSON data.

class ElementData(tag, text, content, attributes, xmlns)

  Namedtuple for Element data interchange between decoders and converters. The field tag is a string containing the Element’s tag, text can be None or a string representing the Element’s text, content can be None, a list containing the Element’s children or a dictionary containing element name to list of element contents for the Element’s children (used for unordered input data), attributes can be None or a dictionary containing the Element’s attributes, xmlns can be None or a list of couples containing namespace declarations.

class XMLSchemaConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, etree_element_class: Type[Element] | None = None, text_key: str | None = '$', attr_prefix: str | None = '@', cdata_prefix: str | None = None, indent: int = 4, process_namespaces: bool = True, strip_namespaces: bool = False, xmlns_processing: str | None = None, source: XMLResource | None = None, preserve_root: bool = False, force_dict: bool = False, force_list: bool = False, **kwargs: Any)

  Generic XML Schema based converter class. A converter is used to compose decoded XML data for an Element into a data structure and to build an Element from encoded data structure. There are two methods for interfacing the converter with the decoding/encoding process. The method element_decode accepts an ElementData tuple, containing the element parts, and returns a data structure. The method element_encode accepts a data structure and returns an ElementData tuple. For default character data parts are ignored. Prefixes and text key can be changed also using alphanumeric values but ambiguities with schema elements could affect XML data re-encoding.

  Parameters:

    - namespaces – map from namespace prefixes to URI.

    - dict_class – dictionary class to use for decoded data. Default is dict.

    - list_class – list class to use for decoded data. Default is list.

    - etree_element_class – the class that has to be used to create new XML elements, if not provided uses the ElementTree’s Element class.

    - text_key – is the key to apply to element’s decoded text data.

    - attr_prefix – controls the mapping of XML attributes, to the same name or with a prefix. If None the converter ignores attributes.

    - cdata_prefix – is used for including and prefixing the character data parts of a mixed content, that are labeled with an integer instead of a string. Character data parts are ignored if this argument is None.

    - indent – number of spaces for XML indentation (default is 4).

    - process_namespaces – whether to use namespace information in name mapping methods. If set to False then the name mapping methods simply return the provided name.

    - strip_namespaces – if set to True removes namespace declarations from data and namespace information from names, during decoding or encoding. Defaults to False.

    - xmlns_processing – defines the processing mode of XML namespace declarations. Can be ‘stacked’, ‘collapsed’, ‘root-only’ or ‘none’, with the meaning defined for the NamespaceMapper base class. For default the xmlns processing mode is chosen between ‘stacked’, ‘collapsed’ and ‘none’, depending on the provided XML source and the capabilities and the settings of the converter instance.

    - source – the origin of XML data. Con be an XMLResource instance or None.

    - preserve_root – if set to True the root element is preserved, wrapped into a single-item dictionary. Applicable only to default converter, to `UnorderedConverter` and to `ParkerConverter`.

    - force_dict – if set to True complex elements with simple content are decoded with a dictionary also if there are no decoded attributes. Applicable only to default converter and to `UnorderedConverter`. Defaults to False.

    - force_list – if set to True child elements are decoded within a list in any case. Applicable only to default converter and to `UnorderedConverter`. Defaults to False.

  Variables:

    - dict – dictionary class to use for decoded data.

    - list – list class to use for decoded data.

    - etree_element_class – Element class to use

    - text_key – key for decoded Element text

    - attr_prefix – prefix for attribute names

    - cdata_prefix – prefix for character data parts

    - indent – indentation to use for rebuilding XML trees

    - preserve_root – preserve the root element on decoding

    - force_dict – force dictionary for complex elements with simple content

    - force_list – force list for child elements

  lossy

    The converter ignores some kind of XML data during decoding/encoding.

  losslessly

    The XML data is decoded without loss of quality, neither on data nor on data model shape. Only losslessly converters can be always used to encode to an XML data that is strictly conformant to the schema.

  copy(keep_namespaces: bool = True, **kwargs: Any) → XMLSchemaConverter

    Creates a new converter instance from the existing, replacing options provided with keyword arguments.

    Parameters:

      keep_namespaces – whether to keep the namespaces of the converter if they are not replaced by a keyword argument.

  map_attributes(attributes: Iterable[tuple[str, Any]]) → Iterator[tuple[str, Any]]

    Creates an iterator for converting decoded attributes to a data structure with appropriate prefixes.

    Parameters:

      attributes – A sequence or an iterator of couples with the name of the attribute and the decoded value. Default is None (for simpleType elements, that don’t have attributes).

  map_content(content: Iterable[tuple[str, Any, Any]]) → Iterator[tuple[str, Any, Any]]

    A generator function for converting the decoded content to a data structure.

    Parameters:

      content – A sequence or an iterator of tuples with the name of the element, the decoded value and the XsdElement instance associated.

  etree_element(tag: str, text: str | None = None, children: list[Element] | None = None, attrib: dict[str, str] | Iterable[tuple[str, str]] | None = None, level: int = 0) → Element

    Builds an ElementTree’s Element using arguments and the element class and the indent spacing stored in the converter instance.

    Parameters:

      - tag – the Element tag string.

      - text – the Element text.

      - children – the list of Element children/subelements.

      - attrib – a dictionary with Element attributes.

      - level – the level related to the encoding process (0 means the root).

    Returns:

      an instance of the Element class is set for the converter instance.

  element_decode(data: ElementData, xsd_element: XsdElement, xsd_type: XsdSimpleType | XsdComplexType | None = None, level: int = 0) → Any

    Converts a decoded element data to a data structure.

    Parameters:

      - data – ElementData instance decoded from an Element node.

      - xsd_element – the XsdElement associated to decode the data.

      - xsd_type – optional XSD type for supporting dynamic type through xsi:type or xs:alternative.

      - level – the level related to the decoding process (0 means the root).

    Returns:

      a data structure containing the decoded data.

  element_encode(obj: Any, xsd_element: XsdElement, level: int = 0) → ElementData

    Extracts XML decoded data from a data structure for encoding into an ElementTree.

    Parameters:

      - obj – the decoded object.

      - xsd_element – the XsdElement associated to the decoded data structure.

      - level – the level related to the encoding process (0 means the root).

    Returns:

      an ElementData instance.

  map_qname(qname: str) → str

    Converts an extended QName to the prefixed format. Only registered namespaces are mapped.

    Parameters:

      qname – a QName in extended format or a local name.

    Returns:

      a QName in prefixed format or a local name.

  unmap_qname(qname: str, name_table: Container[str | None] | None = None, xmlns: list[tuple[str, str]] | None = None) → str

    Converts a QName in prefixed format or a local name to the extended QName format. Local names are converted only if a default namespace is included in the instance. If a name_table is provided a local name is mapped to the default namespace only if not found in the name table.

    Parameters:

      - qname – a QName in prefixed format or a local name

      - name_table – an optional lookup table for checking local names.

      - xmlns – an optional list of namespace declarations that integrate or override the namespace map.

    Returns:

      a QName in extended format or a local name.

class UnorderedConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, etree_element_class: Type[Element] | None = None, text_key: str | None = '$', attr_prefix: str | None = '@', cdata_prefix: str | None = None, indent: int = 4, process_namespaces: bool = True, strip_namespaces: bool = False, xmlns_processing: str | None = None, source: XMLResource | None = None, preserve_root: bool = False, force_dict: bool = False, force_list: bool = False, **kwargs: Any)

  Same as `XMLSchemaConverter` but `XMLSchemaConverter.element_encode()` returns a dictionary for the content of the element, that can be used directly for unordered encoding mode. In this mode the order of the elements in the encoded output is based on the model visitor pattern rather than the order in which the elements were added to the input dictionary. As the order of the input dictionary is not preserved, character data between sibling elements are interleaved between tags.

class ParkerConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, preserve_root: bool = False, **kwargs: Any)

  XML Schema based converter class for Parker convention.

  ref: http://wiki.open311.org/JSON_and_XML_Conversion/#the-parker-convention ref: https://developer.mozilla.org/en-US/docs/Archive/JXON#The_Parker_Convention

  Parameters:

    - namespaces – Map from namespace prefixes to URI.

    - dict_class – dictionary class to use for decoded data. Default is dict.

    - list_class – list class to use for decoded data. Default is list.

    - preserve_root – If True the root element will be preserved. For default the Parker convention remove the document root element, returning only the value.

class BadgerFishConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, **kwargs: Any)

  XML Schema based converter class for Badgerfish convention.

  ref: http://www.sklar.com/badgerfish/ ref: https://badgerfish.ning.com/

  Parameters:

    - namespaces – Map from namespace prefixes to URI.

    - dict_class – dictionary class to use for decoded data. Default is dict.

    - list_class – list class to use for decoded data. Default is list.

class AbderaConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, **kwargs: Any)

  XML Schema based converter class for Abdera convention.

  ref: https://wiki.open311.org/JSON_and_XML_Conversion/#the-abdera-convention ref: https://cwiki.apache.org/confluence/display/ABDERA/JSON+Serialization

  Parameters:

    - namespaces – Map from namespace prefixes to URI.

    - dict_class – dictionary class to use for decoded data. Default is dict.

    - list_class – list class to use for decoded data. Default is list.

class JsonMLConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, **kwargs: Any)

  XML Schema based converter class for JsonML (JSON Mark-up Language) convention.

  ref: http://www.jsonml.org/ ref: https://www.ibm.com/developerworks/library/x-jsonml/

  Parameters:

    - namespaces – Map from namespace prefixes to URI.

    - dict_class – dictionary class to use for decoded data. Default is dict.

    - list_class – list class to use for decoded data. Default is list.

class ColumnarConverter(namespaces: MutableMapping[str, str] | None = None, dict_class: Type[dict[str, Any]] | None = None, list_class: Type[list[Any]] | None = None, attr_prefix: str | None = '', **kwargs: Any)

  XML Schema based converter class for columnar formats.

  Parameters:

    - namespaces – map from namespace prefixes to URI.

    - dict_class – dictionary class to use for decoded data. Default is dict.

    - list_class – list class to use for decoded data. Default is list.

    - attr_prefix – used as separator string for renaming the decoded attributes. Can be the empty string (the default) or a single/double underscore.

## Data objects API

class DataElement(tag: str, value: Any | None = None, attrib: dict[str, Any] | None = None, nsmap: MutableMapping[str, str] | None = None, xmlns: list[tuple[str, str]] | None = None, xsd_element: XsdElement | None = None, xsd_type: XsdSimpleType | XsdComplexType | None = None)

  Data Element, an Element like object with decoded data and schema bindings.

  Parameters:

    - tag – a string containing a QName in extended format.

    - value – the simple typed value of the element.

    - attrib – the typed attributes of the element.

    - nsmap – an optional map from prefixes to namespaces.

    - xsd_element – an optional XSD element association.

    - xsd_type – an optional XSD type association. Can be provided also if the instance is not bound with an XSD element.

class DataElementConverter(namespaces: MutableMapping[str, str] | None = None, data_element_class: Type[DataElement] | None = None, map_attribute_names: bool = True, **kwargs: Any)

  XML Schema based converter class for DataElement objects.

  Parameters:

    - namespaces – a dictionary map from namespace prefixes to URI.

    - data_element_class – MutableSequence subclass to use for decoded data. Default is DataElement.

    - map_attribute_names – define if map the names of attributes to prefixed form. Defaults to True. If False the names are kept to extended format.

class DataBindingConverter(namespaces: MutableMapping[str, str] | None = None, data_element_class: Type[DataElement] | None = None, map_attribute_names: bool = True, **kwargs: Any)

  A `DataElementConverter` that uses XML data binding classes for decoding. Takes the same arguments of its parent class but the argument data_element_class is used for define the base for creating the missing XML binding classes.

## URL normalization API

normalize_url(url: str, base_url: str | None = None, keep_relative: bool = False, method: str = 'xml') → str

  Returns a normalized URL eventually joining it to a base URL if it’s a relative path. Path names are converted to ‘file’ scheme URLs and unsafe characters are encoded. Query and fragments parts are kept only for non-local URLs

  Parameters:

    - url – a relative or absolute URL.

    - base_url – a reference base URL.

    - keep_relative – if set to True keeps relative file paths, which would not strictly conformant to specification (RFC 8089), because urlopen() doesn’t accept a simple pathname.

    - method – method used to encode query and fragment parts. If set to html the whitespaces are replaced with + characters.

  Returns:

    a normalized URL string.

normalize_locations(locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str], base_url: str | None = None, keep_relative: bool = False) → list[tuple[str, str]]

  Returns a list of normalized locations. The locations are normalized using the base URL of the instance.

  Parameters:

    - locations – a dictionary or a list of couples containing namespace location hints.

    - base_url – the reference base URL for construct the normalized URL from the argument.

    - keep_relative – if set to True keeps relative file paths, which would not strictly conformant to URL format specification.

  Returns:

    a list of couples containing normalized namespace location hints.

## XML resources API

fetch_resource(location: str, base_url: str | None = None, timeout: int = 30) → str

  Fetches a resource by trying to access it. If the resource is accessible returns its normalized URL, otherwise raises an XMLResourceOSError.

  Parameters:

    - location – a URL or a file path.

    - base_url – reference base URL for normalizing local and relative URLs.

    - timeout – the timeout in seconds for the connection attempt in case of remote data.

  Returns:

    a normalized URL.

fetch_schema_locations(source: XMLResource | str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, base_url: str | None = None, allow: str = 'all', defuse: str = 'remote', timeout: int = 30, uri_mapper: MutableMapping[str, str] | Callable[[str], str] | None = None, root_only: bool = True, **_kwargs: Any) → tuple[str, list[tuple[str, str]]]

  Fetches schema location hints from an XML data source and a list of location hints. If an accessible schema location is not found raises a ValueError.

  Parameters:

    - source – can be an `XMLResource` instance, a file-like object a path to a file or a URI of a resource or an Element instance or an ElementTree instance or a string containing the XML data. If the passed argument is not an `XMLResource` instance a new one is built using this and defuse, timeout and lazy arguments.

    - locations – a dictionary or dictionary items with additional schema location hints.

    - base_url – the same argument of the `XMLResource`.

    - allow – the same argument of the `XMLResource`, applied to location hints only.

    - defuse – the same argument of the `XMLResource`.

    - timeout – the same argument of the `XMLResource` but with a reduced default.

    - uri_mapper – an optional argument for building the schema from location hints.

    - root_only – if True extracts from the XML source only the location hints of the root element.

    - _kwargs – unused keyword arguments.

  Returns:

    A 2-tuple with the URL referring to the first reachable schema resource and a list of dictionary items with normalized location hints.

fetch_schema(source: XMLResource | str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, base_url: str | None = None, allow: str = 'all', defuse: str = 'remote', timeout: int = 30, uri_mapper: MutableMapping[str, str] | Callable[[str], str] | None = None, root_only: bool = True, **_kwargs: Any) → str

  Like `fetch_schema_locations()` but returns only the URL of a loadable XSD schema from location hints fetched from the source or provided by argument.

download_schemas(url: str, target: str | Path, save_remote: bool = True, save_locations: bool = True, modify: bool = False, defuse: str = 'remote', timeout: int = 300, exclude_locations: list[str] | None = None, loglevel: str | int | None = None) → dict[str, str]

  Download one or more schemas from a URL and save them in a target directory. All the referred locations in schema sources are downloaded and stored in the target directory.

  Parameters:

    - url – The URL of the schema to download, usually a remote one.

    - target – the target directory to save the schema.

    - save_remote – if to save remote schemas, defaults to True.

    - save_locations – for default save a LOCATION_MAP dictionary to a __init__.py, that can be imported in your code to provide a uri_mapper argument for build the schema instance. Provide False to skip the package file creation in the target directory.

    - modify – provide True to modify original schemas, defaults to False.

    - defuse – when to defuse XML data before loading, defaults to ‘remote’.

    - timeout – the timeout in seconds for the connection attempt in case of remote data.

    - exclude_locations – provide a list of locations to skip.

    - loglevel – for setting a different logging level for schema downloads call.

  Returns:

    a dictionary containing the map of modified locations.

class XMLResource(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol, base_url: None | str | Path | bytes = None, allow: str = 'all', defuse: str = 'remote', timeout: int = 300, lazy: bool | int = False, thin_lazy: bool = True, uri_mapper: MutableMapping[str, str] | Callable[[str], str] | None = None, opener: OpenerDirector | None = None, iterparse: Callable[[IOProtocol[str] | IOProtocol[bytes], Sequence[str] | None], Iterator[tuple[str, Any]]] | None = None, selector: type[ElementSelector] | None = None)

  XML resource manager based on ElementTree and urllib.

  Parameters:

    - source – a string containing the XML document or file path or a URL or a file like object or an ElementTree or an Element.

    - base_url – is an optional base URL, used for the normalization of relative paths when the URL of the resource can’t be obtained from the source argument. For security the access to a local file resource is always denied if the base_url is a remote URL.

    - allow – defines the security mode for accessing resource locations. Can be ‘all’, ‘remote’, ‘local’, ‘sandbox’ or ‘none’. Default is ‘all’, which means all types of URLs are allowed. With ‘remote’ only remote resource URLs are allowed. With ‘local’ only file paths and URLs are allowed. With ‘sandbox’ only file paths and URLs that are under the directory path identified by the base_url argument are allowed. If you provide ‘none’, no resources will be allowed from any location.

    - defuse – defines when to defuse XML data using a SafeXMLParser. Can be ‘always’, ‘remote’, ‘nonlocal’ or ‘never’. For default defuses only remote XML data. With ‘always’ all the XML data that is not already parsed is defused. With ‘nonlocal’ it defuses unparsed data except local files. With ‘never’ no XML data source is defused.

    - timeout – the timeout in seconds for the connection attempt in case of remote data.

    - lazy – if a value False or 0 is provided the XML data is fully loaded into and processed from memory. When a resource is lazy only the root element of the source is loaded. A positive integer also defines the depth at which the lazy resource can be better iterated (True means 1).

    - thin_lazy – for default, in order to reduce the memory usage, during the iteration of a lazy resource at lazy_depth level, deletes also the preceding elements after the use.

    - uri_mapper – an optional URI mapper for using relocated or URN-addressed resources. Can be a dictionary or a function that takes the URI string and returns a URL, or the argument if there is no mapping for it.

    - opener – an optional `OpenerDirector` to use for open the resource. For default use the opener installed globally for urlopen.

    - iterparse – an optional callable that returns an iterator parser instance used for building the XML tree. For default that callable is ElementTree.iterparse, provide lxml.etree.iterparse to build lxml trees or another callable if a different parsing of your data.

  root: ElementType

    The XML tree root Element.

  text: str | None = None

    The XML text source, None if it’s not loaded or available.

  name

    The source name, is None if the instance is created from an Element or a string.

  url: str | None = None

    An URL if the source is an URL or a file-like object with a remote url.

  base_url

    The effective base URL used for completing relative locations.

  filepath

    The resource filepath if the instance is created from a local file, None otherwise.

  namespace

    The namespace of the XML resource.

  parse(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol, lazy: bool | int = False) → None

    Parse another XML resource and load it into the instance.

  tostring(namespaces: MutableMapping[str, str] | None = None, indent: str = '', max_lines: int | None = None, spaces_for_tab: int = 4, xml_declaration: bool = False, encoding: str = 'unicode', method: str = 'xml') → str

    Serialize an XML resource to a string.

    Parameters:

      - namespaces – is an optional mapping from namespace prefix to URI. Provided namespaces are registered before serialization. Ignored if the provided elem argument is a lxml Element instance.

      - indent – the baseline indentation.

      - max_lines – if truncate serialization after a number of lines (default: do not truncate).

      - spaces_for_tab – number of spaces for replacing tab characters. For default tabs are replaced with 4 spaces, provide None to keep tab characters.

      - xml_declaration – if set to True inserts the XML declaration at the head.

      - encoding – if “unicode” (the default) the output is a string, otherwise it’s binary.

      - method – is either “xml” (the default), “html” or “text”.

    Returns:

      a Unicode string.

  open(use_loaded: bool = False) → IOProtocol[str] | IOProtocol[bytes]

    Returns an opened resource reader object for the instance URL. If the source attribute is a seekable file-like object rewind the source and return it. If required by configuration the XML resource is defused before returning if to the caller.

  load() → None

    Loads the XML text from the data source. If the data source is an Element the source XML text can’t be retrieved.

  is_lazy() → bool

    Returns True if the XML resource is lazy.

  lazy_depth

    The depth at which the XML tree of the resource is fully loaded during iterations methods. Is a positive integer for lazy resources and 0 for fully loaded XML trees.

  is_remote() → bool

    Returns True if the resource is related with remote XML data.

  is_local() → bool

    Returns True if the resource is related with local XML data.

  is_loaded() → bool

    Returns True if the XML text of the data source is loaded.

  iter(tag: str | None = None) → Iterator[Element]

    XML resource tree iterator. If tag is not None or ‘*’, only elements whose tag equals tag are returned from the iterator. In a lazy resource the yielded elements are full over or at lazy_depth level, otherwise are incomplete and thin for default.

  iter_depth(mode: int = 1, ancestors: list[Element] | None = None) → Iterator[Element]

    Iterates XML subtrees. For fully loaded resources yields the root element. On lazy resources the argument mode can change the sequence and the completeness of yielded elements. There are four possible modes, that generate different sequences of elements:

    > 1. Only the elements at depth_level level of the tree

    > 2. Only the elements at depth_level level of the tree removing

    >    the preceding elements of ancestors (thin lazy tree)

    > 3. Only a root element pruned at depth_level

    > 4. The elements at depth_level and then a pruned root

    > 5. An incomplete root at start, the elements at depth_level and a pruned root

    Parameters:

      - mode – an integer in range [1..5] that defines the iteration mode.

      - ancestors – provide a list for tracking the ancestors of yielded elements.

  iterfind(path: str, namespaces: MutableMapping[str, str] | None = None, ancestors: list[Element] | None = None) → Iterator[Element]

    Apply XPath selection to XML resource that yields full subtrees.

    Parameters:

      - path – an XPath 2.0 expression that selects element nodes. Selecting other values or nodes raise an error.

      - namespaces – an optional mapping from namespace prefixes to URIs used for parsing the XPath expression.

      - ancestors – provide a list for tracking the ancestors of yielded elements.

  find(path: str, namespaces: MutableMapping[str, str] | None = None, ancestors: list[Element] | None = None) → Element | None
  findall(path: str, namespaces: MutableMapping[str, str] | None = None) → list[Element]
  iter_location_hints(tag: str | None = None) → Iterator[tuple[str, str]]

    Yields all schema location hints of the XML resource. If tag is not None or ‘*’, only location hints of elements whose tag equals tag are returned from the iterator.

  get_namespaces(namespaces: MutableMapping[str, str] | None = None, root_only: bool = True) → MutableMapping[str, str]

    Extracts namespaces with related prefixes from the XML resource. If a duplicate prefix is encountered in a xmlns declaration, and this is mapped to a different namespace, adds the namespace using a different generated prefix. The empty prefix ‘’ is used only if it’s declared at root level to avoid erroneous mapping of local names. In other cases it uses the prefix ‘default’ as substitute.

    Parameters:

      - namespaces – is an optional mapping from namespace prefix to URI that integrate/override the namespace declarations of the root element.

      - root_only – if True extracts only the namespaces declared in the root element, otherwise scan the whole tree for further namespace declarations. A full namespace map can be useful for cases where the element context is not available.

    Returns:

      a dictionary for mapping namespace prefixes to full URI.

  get_locations(locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, root_only: bool = True) → list[tuple[str, str]]

    Extracts a list of schema location hints from the XML resource. The locations are normalized using the base URL of the instance.

    Parameters:

      - locations – a sequence of schema location hints inserted before the ones extracted from the XML resource. Locations passed within a tuple container are not normalized.

      - root_only – if True extracts only the location hints of the root element.

    Returns:

      a list of couples containing normalized location hints.

class XmlDocument(source: str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | ElementProtocol | DocumentProtocol, schema: XMLSchemaBase | str | bytes | Path | IO[str] | IO[bytes] | Element | ElementTree | XMLResource | None = None, cls: Type[XMLSchemaBase] | None = None, validation: str = 'strict', namespaces: MutableMapping[str, str] | None = None, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_location_hints: bool = True, **kwargs: Any)

  An XML document bound with its schema. If no schema is get from the provided context and validation argument is ‘skip’ the XML document is associated with a generic schema, otherwise a ValueError is raised.

  Parameters:

    - source – a string containing XML data or a file path or a URL or a file like object or an ElementTree or an Element.

    - schema – can be a `xmlschema.XMLSchema` instance or a file-like object or a file path or a URL of a resource or a string containing the XSD schema.

    - cls – class to use for building the schema instance (for default `XMLSchema10` is used).

    - validation – the XSD validation mode to use for validating the XML document, that can be ‘strict’ (default), ‘lax’ or ‘skip’.

    - namespaces – is an optional mapping from namespace prefix to URI.

    - locations – resource location hints, that can be a dictionary or a sequence of couples (namespace URI, resource URL).

    - use_location_hints – for default, in case a schema instance has to be built, uses also schema locations hints provided within XML data. set this option to False to ignore these schema location hints.

    - kwargs – other optional arguments for building `XMLResource` or `XMLSchema` instances provided as keyword arguments.

## Loaders API

SchemaLoader(maps: XsdGlobals, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_fallback: bool = True, use_xpath3: bool = False)

  The default schema loader, that processes an import statement only if the referred namespace is not imported yet.

LocationSchemaLoader(maps: XsdGlobals, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_fallback: bool = True, use_xpath3: bool = False)

  A schema loader that processes an import statement if the referred location is not already loaded.

SafeSchemaLoader(maps: XsdGlobals, locations: tuple[tuple[str, str], ...] | dict[str, str] | list[tuple[str, str]] | NamespaceResourcesMap[str] | None = None, use_fallback: bool = True, use_xpath3: bool = False)

  A schema loader that processes an import statement if the referred location is not already loaded and after checking if there aren’t collisions with loaded schemas.

## Translation API

activate(localedir: None | str | Path = None, languages: Iterable[str] | None = None, fallback: bool = True, install: bool = False) → None

  Activate translation of xmlschema parsing/validation error messages.

  Parameters:

    - localedir – a string or Path-like object to locale directory

    - languages – list of language codes

    - fallback – for default fallback mode is activated

    - install – if True installs function _() in Python’s builtins namespace

deactivate() → None

  Deactivate translation of xmlschema parsing/validation error messages.

## Namespaces API

Classes for converting namespace representation or for accessing namespace objects:

class NamespaceResourcesMap(*args: Any, **kwargs: Any)

  Dictionary for storing information about namespace resources. Values are lists of objects. Setting an existing value appends the object to the value. Setting a value with a list sets/replaces the value.

class NamespaceMapper(namespaces: MutableMapping[str, str] | None = None, process_namespaces: bool = True, strip_namespaces: bool = False, xmlns_processing: str | None = None, source: Any | None = None)

  A class to map/unmap namespace prefixes to URIs. An internal reverse mapping from URI to prefix is also maintained for keep name mapping consistent within updates.

  Parameters:

    - namespaces – initial data with mapping of namespace prefixes to URIs.

    - process_namespaces – whether to use namespace information in name mapping methods. If set to False then the name mapping methods simply return the provided name.

    - strip_namespaces – if set to True then the name mapping methods return the local part of the provided name.

    - xmlns_processing – defines the processing mode of XML namespace declarations. The preferred mode is ‘stacked’, the mode that processes the namespace declarations using a stack of contexts related with elements and levels. This is the processing mode that always matches the XML namespace declarations defined in the XML document. Provide ‘collapsed’ for loading all namespace declarations of the XML source in a single map, renaming colliding prefixes. Provide ‘root-only’ to use only the namespace declarations of the XML document root. Provide ‘none’ to not use any namespace declaration of the XML document. For default the xmlns processing mode is ‘stacked’ if the XML source is an XMLResource instance, otherwise is ‘none’.

    - source – the origin of XML data. Con be an XMLResource instance, an XML decoded data or None.

class NamespaceView(target_dict: Mapping[str, CT], namespace: str)

  A mapping for filtered access to a dictionary that stores objects by FQDN.

## XPath API

Implemented through a mixin class on XSD schemas and elements.

class ElementPathMixin

  Mixin abstract class for enabling ElementTree and XPath 2.0 API on XSD components.

  Variables:

    - text – the Element text, for compatibility with the ElementTree API.

    - tail – the Element tail, for compatibility with the ElementTree API.

  tag

    Alias of the name attribute. For compatibility with the ElementTree API.

  attrib

    Returns the Element attributes. For compatibility with the ElementTree API.

  get(key: str, default: Any = None) → Any

    Gets an Element attribute. For compatibility with the ElementTree API.

  iter(tag: str | None = None) → Iterator[E_co]

    Creates an iterator for the XSD element and its subelements. If tag is not None or ‘*’, only XSD elements whose matches tag are returned from the iterator. Local elements are expanded without repetitions. Element references are not expanded because the global elements are not descendants of other elements.

  iterchildren(tag: str | None = None) → Iterator[E_co]

    Creates an iterator for the child elements of the XSD component. If tag is not None or ‘*’, only XSD elements whose name matches tag are returned from the iterator.

  find(path: str, namespaces: MutableMapping[str, str] | None = None) → E_co | None

    Finds the first XSD subelement matching the path.

    Parameters:

      - path – an XPath expression that considers the XSD component as the root element.

      - namespaces – an optional mapping from namespace prefix to namespace URI.

    Returns:

      the first matching XSD subelement or `None` if there is no match.

  findall(path: str, namespaces: MutableMapping[str, str] | None = None) → list[E_co]

    Finds all XSD subelements matching the path.

    Parameters:

      - path – an XPath expression that considers the XSD component as the root element.

      - namespaces – an optional mapping from namespace prefix to full name.

    Returns:

      a list containing all matching XSD subelements in document order, an empty list is returned if there is no match.

  iterfind(path: str, namespaces: MutableMapping[str, str] | None = None) → Iterator[E_co]

    Creates and iterator for all XSD subelements matching the path.

    Parameters:

      - path – an XPath expression that considers the XSD component as the root element.

      - namespaces – is an optional mapping from namespace prefix to full name.

    Returns:

      an iterable yielding all matching XSD subelements in document order.

class ElementSelector(path: str, namespaces: MutableMapping[str, str] | None = None)

  An XPath selector for selecting ElementTree elements. Raises an error if the path parse fails or is incompatible with the selector type.

  Parameters:

    - path – the XPath expression.

    - namespaces – an optional namespace mapping.

  path: str

    The normalized XPath expression of the path provided by argument.

  namespaces: dict[str, str] | None

    The namespaces mapping associated with the XPath expression path.

  parts

    Return a list with the parts of the parsed path.

  relative_path

    The equivalent path expression relative to root element.

  depth

    Path depth, 0 means a self axis selector, -1 means an unlimited depth.

  select_all

    Returns True if the path is composed only by wildcards or path steps.

  select(root: Element | XMLResource) → list[Element]
  iter_select(root: Element | XMLResource) → Iterator[Element]
  classmethod cached_selector(path: str, namespaces: MutableMapping[str, str] | None = None) → ElementSelector

    A builder of ElementSelector instances based on a cache.

class ElementPathSelector(path: str, namespaces: MutableMapping[str, str] | None = None)

  An XPath selector that uses xml.etree.ElementPath.iterfind() for selecting elements.

## Validation API

Implemented for XSD schemas, elements, attributes, types, attribute groups and model groups.

class ValidationMixin

  Mixin for implementing XML data validators/decoders on XSD components. A derived class must implement the methods raw_decode and raw_encode.

  is_valid(obj: ST, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, max_depth: int | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None) → bool

    Like `validate()` except that does not raise an exception but returns `True` if the XML data instance is valid, `False` if it is invalid.

  validate(obj: ST, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, max_depth: int | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None) → None

    Validates XML data against the XSD schema/component instance.

    Parameters:

      - obj – the XML data. Can be a string for an attribute or a simple type validators, or an ElementTree’s Element otherwise.

      - use_defaults – indicates whether to use default values for filling missing data.

      - namespaces – is an optional mapping from namespace prefix to URI.

      - max_depth – maximum level of validation, for default there is no limit.

      - extra_validator – an optional function for performing non-standard validations on XML data. The provided function is called for each traversed element, with the XML element as 1st argument and the corresponding XSD element as 2nd argument. It can be also a generator function and has to raise/yield `xmlschema.XMLSchemaValidationError` exceptions.

      - validation_hook – an optional function for stopping or changing validation at element level. The provided function must accept two arguments, the XML element and the matching XSD element. If the value returned by this function is evaluated to false then the validation process continues without changes, otherwise the validation process is stopped or changed. If the value returned is a validation mode the validation process continues changing the current validation mode to the returned value, otherwise the element and its content are not processed. The function can also stop validation suddenly raising a XmlSchemaStopValidation exception.

    Raises:

      `xmlschema.XMLSchemaValidationError` if the XML data instance is invalid.

  decode(obj: ST, validation: str = 'strict', **kwargs: Any) → DT | None | tuple[DT | None, list[XMLSchemaValidationError]]

    Decodes XML data.

    Parameters:

      - obj – the XML data. Can be a string for an attribute or for simple type components or a dictionary for an attribute group or an ElementTree’s Element for other components.

      - validation – the validation mode. Can be ‘lax’, ‘strict’ or ‘skip.

      - kwargs – optional keyword arguments for the method `iter_decode()`.

    Returns:

      a dictionary like object if the XSD component is an element, a group or a complex type; a list if the XSD component is an attribute group; a simple data type object otherwise. If validation argument is ‘lax’ a 2-items tuple is returned, where the first item is the decoded object and the second item is a list containing the errors.

    Raises:

      `xmlschema.XMLSchemaValidationError` if the object is not decodable by the XSD component, or also if it’s invalid when `validation='strict'` is provided.

  iter_decode(obj: ST, validation: str = 'lax', **kwargs: Any) → Iterator[DT | XMLSchemaValidationError]

    Creates an iterator for decoding an XML source to a Python object.

    Parameters:

      - obj – the XML data.

      - validation – the validation mode. Can be ‘lax’, ‘strict’ or ‘skip’.

      - kwargs – keyword arguments for the decoder API.

    Returns:

      Yields a decoded object, eventually preceded by a sequence of validation or decoding errors.

  iter_encode(obj: Any, validation: str = 'lax', **kwargs: Any) → Iterator[Any | XMLSchemaValidationError]

    Creates an iterator for encoding data to an Element tree.

    Parameters:

      - obj – The data that has to be encoded.

      - validation – The validation mode. Can be ‘lax’, ‘strict’ or ‘skip’.

      - kwargs – keyword arguments for the encoder API.

    Returns:

      Yields an Element, eventually preceded by a sequence of validation or encoding errors.

  iter_errors(obj: ST, use_defaults: bool = True, namespaces: MutableMapping[str, str] | None = None, max_depth: int | None = None, extra_validator: Callable[[Element, XsdElement], Iterator[XMLSchemaValidationError] | None] | None = None, validation_hook: Callable[[Element, XsdElement], bool | str] | None = None) → Iterator[XMLSchemaValidationError]

    Creates an iterator for the errors generated by the validation of an XML data against the XSD schema/component instance. Accepts the same arguments of `validate()`.

  encode(obj: Any, validation: str = 'strict', **kwargs: Any) → Any | tuple[Any, list[XMLSchemaValidationError]]

    Encodes data to XML.

    Parameters:

      - obj – the data to be encoded to XML.

      - validation – the validation mode. Can be ‘lax’, ‘strict’ or ‘skip.

      - kwargs – optional keyword arguments for the method `iter_encode()`.

    Returns:

      An element tree’s Element if the original data is a structured data or a string if it’s simple type datum. If validation argument is ‘lax’ a 2-items tuple is returned, where the first item is the encoded object and the second item is a list containing the errors.

    Raises:

      `xmlschema.XMLSchemaValidationError` if the object is not encodable by the XSD component, or also if it’s invalid when `validation='strict'` is provided.

  iter_encode(obj: Any, validation: str = 'lax', **kwargs: Any) → Iterator[Any | XMLSchemaValidationError]

    Creates an iterator for encoding data to an Element tree.

    Parameters:

      - obj – The data that has to be encoded.

      - validation – The validation mode. Can be ‘lax’, ‘strict’ or ‘skip’.

      - kwargs – keyword arguments for the encoder API.

    Returns:

      Yields an Element, eventually preceded by a sequence of validation or encoding errors.

## Particles API

Implemented for XSD model groups, elements and element wildcards.

class ParticleMixin(min_occurs: int = 1, max_occurs: int | None = 1)

  Mixin for objects related to XSD Particle Schema Components:

  > https://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/structures.html#p https://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/structures.html#t

  Variables:

    - min_occurs – the minOccurs property of the XSD particle. Defaults to 1.

    - max_occurs – the maxOccurs property of the XSD particle. Defaults to 1, a None value means ‘unbounded’.

    - oid – an optional secondary unique identifier for tracking occurs. Is set to a unique tuple for XsdGroup instances for tracking higher occurrence in choice and choice-compatible models.

    - skip – a flag that is set to True for wildcards that have processContents=’skip’.

  is_empty() → bool

    Tests if max_occurs == 0. A zero-length model group is considered empty.

  is_emptiable() → bool

    Tests if min_occurs == 0. A model group that can have zero-length is considered emptiable. For model groups the test outcome depends also on nested particles.

  is_single() → bool

    Tests if the particle has max_occurs == 1. For elements the test outcome depends also on parent group. For model groups the test outcome depends also on nested model groups.

  is_multiple() → bool

    Tests the particle can have multiple occurrences.

  is_ambiguous() → bool

    Tests if min_occurs != max_occurs.

  is_univocal() → bool

    Tests if min_occurs == max_occurs.

  is_missing(occurs: Counter[ParticleMixin | XsdElement | XsdAnyElement | XsdGroup | tuple[XsdGroup] | None]) → bool

    Tests if the particle occurrences are under the minimum.

  is_over(occurs: Counter[ParticleMixin | XsdElement | XsdAnyElement | XsdGroup | tuple[XsdGroup] | None]) → bool

    Tests if particle occurrences are equal or over the maximum.

## Main XSD components

class XsdComponent(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD components. See: https://www.w3.org/TR/xmlschema-ref/

  Parameters:

    - elem – ElementTree’s node containing the definition.

    - schema – the XMLSchema object that owns the definition.

    - parent – the XSD parent, None means that is a global component that has the schema as parent.

    - name – name of the component, maybe overwritten by the parse of the elem argument.

  target_namespace
  qualified: bool = True

    For name matching, unqualified matching may be admitted only for elements and attributes

  local_name

    The local part of the name of the component, or None if the name is None.

  qualified_name

    The name of the component in extended format, or None if the name is None.

  prefixed_name

    The name of the component in prefixed format, or None if the name is None.

  is_global() → bool

    Returns True if the instance is a global component, False if it’s local.

  is_matching(name: str | None, default_namespace: str | None = None, **kwargs: Any) → bool

    Returns True if the component name is matching the name provided as argument, False otherwise. For XSD elements the matching is extended to substitutes.

    Parameters:

      - name – a local or fully-qualified name.

      - default_namespace – used by the XPath processor for completing the name argument in case it’s a local name.

      - kwargs – additional options that can be used by certain components.

  tostring(indent: str = '', max_lines: int | None = None, spaces_for_tab: int = 4) → str | bytes

    Serializes the XML elements that declare or define the component to a string.

class XsdType(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Common base class for XSD types.

  content_type_label

    The content type classification. Can be ‘simple’, ‘mixed’, ‘element-only’ or ‘empty’.

  sequence_type

    The XPath sequence type associated with the content.

  root_type

    The root type of the type definition hierarchy. For an atomic type is the primitive type. For a list is the primitive type of the item. For a union is the base union type. For a complex type is xs:anyType.

  simple_type

    Property that is the instance itself for a simpleType. For a complexType is the instance’s content if this is a simpleType or None if the instance’s content is a model group.

  model_group

    Property that is None for a simpleType. For a complexType is the instance’s content if this is a model group or None if the instance’s content is a simpleType.

  has_complex_content() → bool

    Returns True if the instance is a complexType with mixed or element-only content, False otherwise.

  has_mixed_content() → bool

    Returns True if the instance is a complexType with mixed content, False otherwise.

  has_simple_content() → bool

    Returns True if the instance has a simple content, False otherwise.

  is_atomic() → bool

    Returns True if the instance is an atomic simpleType, False otherwise.

  is_blocked(xsd_element: XsdElement) → bool

    Returns True if the base type derivation is blocked, False otherwise.

  static is_complex() → bool

    Returns True if the instance is a complexType, False otherwise.

  is_datetime() → bool

    Returns True if the instance is a datetime/duration XSD builtin-type, False otherwise.

  is_derived(other: XsdSimpleType | XsdComplexType, derivation: str | None = None) → bool

    Returns True if the instance is derived from other, False otherwise. The optional argument derivation can be a string containing the words ‘extension’ or ‘restriction’ or both.

  is_element_only() → bool

    Returns True if the instance is a complexType with element-only content, False otherwise.

  is_emptiable() → bool

    Returns True if the instance has an emptiable value or content, False otherwise.

  is_empty() → bool

    Returns True if the instance has an empty content, False otherwise.

  is_list() → bool

    Returns True if the instance is a list simpleType, False otherwise.

  is_primitive() → bool

    Returns True if the type is an XSD primitive builtin type, False otherwise.

  static is_simple() → bool

    Returns True if the instance is a simpleType, False otherwise.

  is_union() → bool

    Returns True if the instance is a union simpleType, False otherwise.

  overall_max_occurs(particle: XsdElement | XsdAnyElement | XsdGroup) → int | None

    Returns the overall maximum for occurrences of a content model particle.

  overall_min_occurs(particle: XsdElement | XsdAnyElement | XsdGroup) → int

    Returns the overall minimum for occurrences of a content model particle.

class XsdElement(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD 1.0 element declarations.

  type: XsdSimpleType | XsdComplexType

    The XSD simpleType or complexType of the element.

  attributes: XsdAttributeGroup

    The group of the attributes associated with the element.

  min_occurs: int

    The minOccurs property of the XSD particle. Defaults to 1.

  max_occurs: int | None

    The maxOccurs property of the XSD particle. Defaults to 1, a None value means ‘unbounded’.

  abstract: bool = False

    Defines whether the element can be used in an instance document. An abstract element must be global and can still be the head of a substitution group.

  block

    The effective value for blocking the derivation of the element. Can be empty, ‘#all’ or containing a subset of words (extension|restrictions|substitution) separated by a space.

  final

    The effective value for prevent the usage of derived elements. Can be empty, ‘#all’ or containing a subset of words (extension|restrictions) separated by a space.

  default: str | None = None

    The default value of the element if its content is a simple type.

  fixed: str | None = None

    The fixed value of the element if its content is a simple type.

  qualified: bool = False

    The effective form for the element. If True the element name is qualified by a braced namespace URI as prefix. The name of a global element is always qualified.

  get_binding(*bases: Type[Any], replace_existing: bool = False, **attrs: Any) → Type[DataElement]

    Gets data object binding for XSD element, creating a new one if it doesn’t exist.

    Parameters:

      - bases – base classes to use for creating the binding class.

      - replace_existing – provide True to replace an existing binding class.

      - attrs – attribute and method definitions for the binding class body.

  get_path(ancestor: XsdComponent | None = None, reverse: bool = False) → str | None

    Returns the XPath expression of the element. The path is relative to the schema instance in which the element is contained or is relative to a specific ancestor passed as argument. In the latter case returns None if the argument is not an ancestor.

    Parameters:

      - ancestor – optional XSD component of the same schema, that maybe an ancestor of the element.

      - reverse – if set to True returns the reverse path, from the element to ancestor.

  overall_max_occurs(particle: XsdElement | XsdAnyElement | XsdGroup) → int | None

    Returns the overall maximum for occurrences of a content model particle. The content type of the element must be ‘element-only’ or ‘mixed’.

  overall_min_occurs(particle: XsdElement | XsdAnyElement | XsdGroup) → int

    Returns the overall minimum for occurrences of a content model particle. The content type of the element must be ‘element-only’ or ‘mixed’.

class XsdAttribute(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD 1.0 attribute declarations.

  type: XsdSimpleType

    The XSD simpleType of the attribute.

  default: str | None = None

    The default value of the attribute.

  fixed: str | None = None

    The fixed value of the attribute.

  use: str = 'optional'

    Defines the use of the attribute. Can be ‘optional’, ‘prohibited’ or ‘required’.

  inheritable: bool = False

    Defines whether the attribute can be inherited by descendant elements. XSD 1.1 only, it’s always False for XSD 1.0 attributes.

  qualified: bool = False

    The effective form for the attribute. If True the attribute name is qualified by a braced namespace URI as prefix. The name of a global attribute is always qualified.

## Other XSD components

### Elements and attributes

class Xsd11Element(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD 1.1 element declarations.

class Xsd11Attribute(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD 1.1 attribute declarations.

### Types

class Xsd11ComplexType(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None, **kwargs: Any)

  Class for XSD 1.1 complexType definitions.

class XsdComplexType(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None, **kwargs: Any)

  Class for XSD 1.0 complexType definitions.

  Variables:

    - attributes – the attribute group related with the complexType.

    - content – the content of the complexType can be a model group or a simple type.

    - mixed – if True the complex type has mixed content.

  content: XsdGroup | XsdSimpleType

class XsdSimpleType(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None, facets: dict[str | None, XsdFacet | Callable[[Any], None] | list[XsdAssertionFacet]] | None = None)

  Base class for simpleTypes definitions. Generally used only for instances of xs:anySimpleType.

  enumeration
  max_value
  min_value

class XsdAtomicBuiltin(elem: Element, schema: XMLSchemaBase, name: str, datatype: Type[AnyAtomicType], python_type: Type[Any] | tuple[Type[Any]], base_type: XsdAtomicBuiltin | None = None, admitted_facets: set[str] | None = None, facets: dict[str | None, XsdFacet | Callable[[Any], None] | list[XsdAssertionFacet]] | None = None, to_python: Callable[[Any], str | bytes | int | float | Decimal | bool | Integer | Float10 | NormalizedString | AnyURI | QName | Duration | AbstractDateTime | AbstractBinary] | None = None, from_python: Callable[[Any], str] | None = None)

  Class for defining XML Schema built-in simpleType atomic datatypes. An instance contains a Python’s type transformation and a list of validator functions. The ‘base_type’ is not used for validation, but only for reference to the XML Schema restriction hierarchy.

  Type conversion methods:

    - to_python(value): Decoding from XML

    - from_python(value): Encoding to XML

class XsdList(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None, name: str | None = None)

  Class for ‘list’ definitions. A list definition has an item_type attribute that refers to an atomic or union simpleType definition.

class Xsd11Union(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None, name: str | None = None)

class XsdUnion(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None, name: str | None = None)

  Class for ‘union’ definitions. A union definition has a member_types attribute that refers to a ‘simpleType’ definition.

class Xsd11AtomicRestriction(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None, facets: dict[str | None, XsdFacet | Callable[[Any], None] | list[XsdAssertionFacet]] | None = None, base_type: XsdSimpleType | XsdComplexType | None = None)

  Class for XSD 1.1 atomic simpleType and complexType’s simpleContent restrictions.

class XsdAtomicRestriction(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None, facets: dict[str | None, XsdFacet | Callable[[Any], None] | list[XsdAssertionFacet]] | None = None, base_type: XsdSimpleType | XsdComplexType | None = None)

  Class for XSD 1.0 atomic simpleType and complexType’s simpleContent restrictions.

### Attribute and model groups

class XsdAttributeGroup(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, derivation: str | None = None, base_attributes: XsdAttributeGroup | None = None)

  Class for XSD attributeGroup definitions.

class Xsd11Group(elem: Element, schema: XMLSchemaBase, parent: XsdComplexType | XsdGroup | None = None)

  Class for XSD 1.1 model group definitions.

class XsdGroup(elem: Element, schema: XMLSchemaBase, parent: XsdComplexType | XsdGroup | None = None)

  Class for XSD 1.0 model group definitions.

### Wildcards

class Xsd11AnyElement(elem: Element, schema: XMLSchemaBase, parent: XsdComponent)

  Class for XSD 1.1 any declarations.

class XsdAnyElement(elem: Element, schema: XMLSchemaBase, parent: XsdComponent)

  Class for XSD 1.0 any wildcards.

class Xsd11AnyAttribute(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD 1.1 anyAttribute declarations.

class XsdAnyAttribute(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD 1.0 anyAttribute wildcards.

class XsdOpenContent(elem: Element, schema: XMLSchemaBase, parent: XsdComponent)

  Class for XSD 1.1 openContent model definitions.

class XsdDefaultOpenContent(elem: Element, schema: XMLSchemaBase)

  Class for XSD 1.1 defaultOpenContent model definitions.

### Identity constraints

class XsdIdentity(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

  Common class for XSD identity constraints.

  Variables:

    - selector – the XPath selector of the identity constraint.

    - fields – a list containing the XPath field selectors of the identity constraint.

class XsdSelector(elem: Element, schema: XMLSchemaBase, parent: XsdIdentity | None)

  Class for defining an XPath selector for an XSD identity constraint.

class XsdFieldSelector(elem: Element, schema: XMLSchemaBase, parent: XsdIdentity | None)

  Class for defining an XPath field selector for an XSD identity constraint.

class Xsd11Unique(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

class XsdUnique(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

class Xsd11Key(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

class XsdKey(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

class Xsd11Keyref(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

class XsdKeyref(elem: Element, schema: XMLSchemaBase, parent: XsdElement | None)

  Implementation of xs:keyref.

  Variables:

    refer – reference to a xs:key declaration that must be in the same element or in a descendant element.

### Facets

class XsdFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XML Schema constraining facets base class.

class XsdWhiteSpaceFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD whiteSpace facet.

class XsdLengthFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD length facet.

class XsdMinLengthFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD minLength facet.

class XsdMaxLengthFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD maxLength facet.

class XsdMinInclusiveFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD minInclusive facet.

class XsdMinExclusiveFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD minExclusive facet.

class XsdMaxInclusiveFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD maxInclusive facet.

class XsdMaxExclusiveFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD maxExclusive facet.

class XsdTotalDigitsFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD totalDigits facet.

class XsdFractionDigitsFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType)

  XSD fractionDigits facet.

class XsdExplicitTimezoneFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD 1.1 explicitTimezone facet.

class XsdAssertionFacet(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicBuiltin | XsdList | XsdUnion | XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  XSD 1.1 assertion facet for simpleType definitions.

class XsdEnumerationFacets(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType)

  Sequence of XSD enumeration facets. Values are validates if match any of enumeration values.

class XsdPatternFacets(elem: Element, schema: XMLSchemaBase, parent: XsdAtomicRestriction, base_type: XsdSimpleType | XsdComplexType | None)

  Sequence of XSD pattern facets. Values are validates if match any of patterns.

### Others

class XsdAssert(elem: Element, schema: XMLSchemaBase, parent: XsdComplexType, base_type: XsdComplexType)

  Class for XSD assert constraint definitions.

class XsdAlternative(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  XSD 1.1 type alternative definitions.

class XsdNotation(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, name: str | None = None)

  Class for XSD notation declarations.

class XsdAnnotation(elem: Element, schema: XMLSchemaBase, parent: XsdComponent | None = None, parent_elem: Element | None = None)

  Class for XSD annotation definitions.

  Variables:

    - appinfo – a list containing the xs:appinfo children.

    - documentation – a list containing the xs:documentation children.

## Extra features API

### Code generators

class AbstractGenerator(schema, searchpath=None, types_map=None)

  Abstract base class for code generators based on Jinja2 template engine.

  Parameters:

    - schema – the source or the instance of the XSD schema.

    - searchpath – additional search path for custom templates. If provided the search path has priority over searchpaths defined in generator class.

    - types_map – a dictionary with custom mapping for XSD types.

  map_type(obj)

    Maps an XSD type to a type declaration of the target language. This method is registered as filter with a name dependant from the language name (eg. c_type).

    Parameters:

      obj – an XSD type or another type-related declaration as an attribute or an element.

    Returns:

      an empty string for non-XSD objects.

  list_templates(extensions=None, filter_func=None)
  matching_templates(name)
  get_template(name, parent=None, global_vars=None)
  select_template(names, parent=None, global_vars=None)
  render(names, parent=None, global_vars=None)
  render_to_files(names, parent=None, global_vars=None, output_dir='.', force=False)

class PythonGenerator(schema, searchpath=None, types_map=None)

  A Python code generator for XSD schemas.

### WSDL 1.1 documents

class Wsdl11Document(source, schema=None, cls=None, validation='strict', namespaces=None, maps=None, locations=None, base_url=None, **kwargs)

  Class for WSDL 1.1 documents.

  Parameters:

    - source – a string containing XML data or a file path or a URL or a file like object or an ElementTree or an Element.

    - schema – additional schema for providing XSD types and elements to the WSDL document. Can be a `xmlschema.XMLSchema` instance or a file-like object or a file path or a URL of a resource or a string containing the XSD schema.

    - cls – class to use for building the schema instance (for default `xmlschema.XMLSchema10` is used).

    - validation – the XSD validation mode to use for validating the XML document, that can be ‘strict’ (default), ‘lax’ or ‘skip’.

    - maps – WSDL definitions shared maps.

    - namespaces – is an optional mapping from namespace prefix to URI.

    - locations – resource location hints, that can be a dictionary or a sequence of couples (namespace URI, resource URL).

    - kwargs – other optional arguments for initializing `xmlschema.XMLResource` base class or building `xmlschema.XMLSchema` instances provided as keyword arguments.

  messages

    WSDL 1.1 messages.

  port_types

    WSDL 1.1 port types.

  bindings

    WSDL 1.1 bindings.

  services

    WSDL 1.1 services.