pyxb package

PyXB stands for Python U{W3C XML Schema<http://www.w3.org/XML/Schema>} Bindings, and is pronounced “pixbee”. It enables translation between XML instance documents and Python objects following rules specified by an XML Schema document.

This is the top-level entrypoint to the PyXB system. Importing this gets you all the exceptions, and pyxb.namespace. For more functionality, delve into these submodules:

  • pyxb.xmlschema Module holding the structures that convert XMLSchema from a DOM model to a Python class model based on the XMLSchema components. Use this when you need to operate on the component model.
  • pyxb.binding Module used to generate the bindings and at runtime to support the generated bindings. Use this if you need to use the binding model or content model.
  • pyxb.utils Common utilities used in parsing, generating, and executing. The submodules must be imported separately.
class pyxb.BIND(*args, **kw)

Bases: object

Bundle data for automated binding generation.

Instances of this class capture positional and keyword arguments that are used to create binding instances based on context. For example, if w is an instance of a complex type whose option element is declared to be an anonymous class with simple content of type integer and an attribute of units, a correct assignment to that element could be achieved with:

w.option = BIND(54, units="m")
_BIND__args = None
_BIND__kw = None
createInstance(factory, **kw)

Invoke the given factory method.

Position arguments to the factory are those cached in this instance. Keyword arguments are the ones on the command line, updated from the ones in this instance.

pyxb.NonElementContent(instance)

Return an iterator producing the non-element content of the provided instance.

The catenated text of the non-element content of an instance can be obtained with:

text = six.u('').join(pyxb.NonElementContent(instance))
Parameters:instance – An instance of pyxb.binding.basis.complexTypeDefinition.
Returns:an iterator producing text values
pyxb.PreserveInputTimeZone(value=None)

Control whether time values are converted to UTC during input.

The specification <http://www.w3.org/TR/xmlschema-2/#dateTime> makes clear that timezoned times are in UTC and that times in other timezones are to be translated to UTC when converted from literal to value form. Provide an option to bypass this step, so the input timezone is preserved.

Note:Naive processing of unnormalized times–i.e., ignoring the

tzinfo field–may result in errors.

pyxb.RequireValidWhenGenerating(value=None)

Query or set a flag that controls validation checking in XML generation.

Normally any attempts to convert a binding instance to a DOM or XML representation requires that the binding validate against the content model, since only in this way can the content be generated in the correct order. In some cases it may be necessary or useful to generate a document from a binding that is incomplete. If validation is not required, the generated documents may not validate even if the content validates, because ordering constraints will be ignored.

Parameters:value – If absent or None, no change is made; otherwise, this

enables (True) or disables (False) the requirement that instances validate before being converted to XML. :type value: bool

Returns:True iff attempts to generate XML for a binding that does not

validate should raise an exception.

pyxb.RequireValidWhenParsing(value=None)

Query or set a flag that controls validation checking in XML parsing.

Normally any attempts to convert XML to a binding instance to a binding instance requires that the document validate against the content model. In some cases it may be necessary or useful to process a document that is incomplete. If validation is not required, the generated documents may not validate even if the content validates, because ordering constraints will be ignored.

Parameters:value – If absent or None, no change is made; otherwise, this

enables (True) or disables (False) the requirement that documents validate when being converted to bindings. :type value: bool

Returns:True iff attempts to generate bindings for a document that

does not validate should raise an exception.

class pyxb.ValidationConfig

Bases: object

Class holding configuration related to validation.

pyxb.GlobalValidationConfig is available to influence validation in all contexts. Each binding class has a reference to an instance of this class, which can be inspected using pyxb.binding.basis._TypeBinding_mixin._GetValidationConfig and changed using pyxb.binding.basis._TypeBinding_mixin._SetValidationConfig. Each binding instance has a reference inherited from its class which can be inspected using pyxb.binding.basis._TypeBinding_mixin._validationConfig and changed using pyxb.binding.basis._TypeBinding_mixin._setValidationConfig.

This allows fine control on a per class and per-instance basis.

forBinding replaces RequireValidWhenParsing.

forDocument replaces RequireValidWhenGenerating.

contentInfluencesGeneration, orphanElementInContent, and invalidElementInContent control how pyxb.binding.basis.complexTypeDefinition.orderedContent affects generated documents.

ALWAYS = -1

Always do it.

GIVE_UP = 2

If an error occurs ignore it and stop using whatever provided the cause of the error. (E.g., if an element in a content list fails stop processing the content list and execute as though it was absent).

IGNORE_ONCE = 1

If an error occurs ignore it and continue with the next one. (E.g., if an element in a content list fails skip it and continue with the next element in the list.)

MIXED_ONLY = 4

Only when content type is mixed.

NEVER = 0

Never do it.

RAISE_EXCEPTION = 3

If an error occurs, raise an exception.

_ValidationConfig__contentInfluencesGeneration = 4
_ValidationConfig__forBinding = True
_ValidationConfig__forDocument = True
_ValidationConfig__getContentInfluencesGeneration()

Determine whether complex type content influences element order in document generation.

The value is one of ALWAYS, NEVER, MIXED_ONLY (default).

_ValidationConfig__getInvalidElementInContent()

How to handle invalid elements in content lists.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

_ValidationConfig__getOrphanElementInContent()

How to handle unrecognized elements in content lists.

This is used when consulting a complex type instance content list to influence the generation of documents from a binding instance.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

_ValidationConfig__invalidElementInContent = 1
_ValidationConfig__orphanElementInContent = 1
_getForBinding()

True iff validation should be performed when manipulating a binding instance.

This includes parsing a document or DOM tree, using a binding instance class constructor, or assigning to an element or attribute field of a binding instance.

_getForDocument()

True iff validation should be performed when creating a document from a binding instance.

This applies at invocation of toDOM(). toxml() invokes toDOM().

_setContentInfluencesGeneration(value)

Set the value of contentInfluencesGeneration.

_setForBinding(value)

Configure whether validation should be performed when manipulating a binding instance.

_setForDocument(value)

Configure whether validation should be performed when generating a document from a binding instance.

_setInvalidElementInContent(value)

Set the value of invalidElementInContent.

_setOrphanElementInContent(value)

Set the value of orphanElementInContent.

contentInfluencesGeneration

Determine whether complex type content influences element order in document generation.

The value is one of ALWAYS, NEVER, MIXED_ONLY (default).

copy()

Make a copy of this instance.

Use this to get a starting point when you need to customize validation on a per-instance/per-class basis.

forBinding

True iff validation should be performed when manipulating a binding instance.

This includes parsing a document or DOM tree, using a binding instance class constructor, or assigning to an element or attribute field of a binding instance.

forDocument

True iff validation should be performed when creating a document from a binding instance.

This applies at invocation of toDOM(). toxml() invokes toDOM().

invalidElementInContent

How to handle invalid elements in content lists.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

orphanElementInContent

How to handle unrecognized elements in content lists.

This is used when consulting a complex type instance content list to influence the generation of documents from a binding instance.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

pyxb.XMLStyle_minidom = 0

Use xml.dom.minidom for XML processing. This is the fastest, but does not provide location information. It produces DOM instances.

pyxb.XMLStyle_saxdom = 1

Use pyxb.utils.saxdom for XML processing. This is the slowest, but both provides location information and generates a DOM instance.

pyxb.XMLStyle_saxer = 2

Use pyxb.binding.saxer when converting documents to binding instances. This style supports location information in the bindings. It produces binding instances directly, without going through a DOM stage, so is faster than XMLStyle_saxdom. However, since the pyxb.xmlschema.structures classes require a DOM model, XMLStyle_saxdom will be used for pyxb.utils.domutils.StringToDOM if this style is selected.

pyxb._SetXMLStyle(style=None)

Set the interface used to parse XML content.

This can be invoked within code. The system default of XMLStyle_saxer can also be overridden at runtime by setting the environment variable PYXB_XML_STYLE to one of minidom, saxdom, or saxer.

Parameters:style – One of XMLStyle_minidom, XMLStyle_saxdom,

XMLStyle_saxer. If not provided, the system default is used.

class pyxb.cscRoot(*args, **kw)

Bases: object

This little bundle of joy exists because in Python 2.6 it became an error to invoke object.__init__ with parameters (unless you also override __new__, in which case it’s only a warning. Whatever.). Since I’m bloody not going to check in every class whether super(Myclass,self) refers to object (even if I could figure out how to do that, ‘cuz the obvious solutions don’t work), we’ll just make this thing the root of all U{cooperative super calling<http://www.geocities.com/foetsch/python/new_style_classes.htm#super>} hierarchies. The standard syntax in PyXB for this pattern is:

def method_csc (self, *args, **kw):
  self_fn = lambda *_args, **_kw: self
  super_fn = getattr(super(ThisClass, self), 'method_csc', self_fn)
  return super_fn(*args, **kw)

Submodules

pyxb.exceptions_ module

Extensions of standard exceptions for PyXB events.

Yeah, I’d love this module to be named exceptions.py, but it can’t because the standard library has one of those, and we need to reference it below.

exception pyxb.exceptions_.AbstractElementError(element, location, value=None)

Bases: pyxb.exceptions_.ElementValidationError

Attempt to create an instance of an abstract element.

Raised when an element is created and the identified binding is abstract. Such elements cannot be created directly; instead the creation must derive from an instance of the abstract element’s substitution group.

Since members of the substitution group self-identify using the substitutionGroup attribute, there is no general way to find the set of elements which would be acceptable in place of the abstract element.

element = None

The abstract pyxb.binding.basis.element in question

value = None

The value proposed for the element. This is usually going to be a xml.dom.Node used in the attempt to create the element, None if the abstract element was invoked without a node, or another type if pyxb.binding.content.ElementDeclaration.toDOM is mis-used.

exception pyxb.exceptions_.AbstractInstantiationError(type, location, node)

Bases: pyxb.exceptions_.ComplexTypeValidationError

Attempt to create an instance of an abstract complex type.

These types are analogous to abstract base classes, and cannot be created directly. A type should be used that extends the abstract class.

When an incoming document is missing the xsi:type attribute which redirects an element with an abstract type to the correct type, the node attribute is provided so the user can get a clue as to where the problem occured. When this exception is a result of constructor mis-use in Python code, the traceback will tell you where the problem lies.

node = None

The xml.dom.Element from which instantiation was attempted, if available.

type = None

The abstract pyxb.binding.basis.complexTypeDefinition subclass used.

exception pyxb.exceptions_.AttributeChangeError(type, tag, instance=None, location=None)

Bases: pyxb.exceptions_.AttributeValidationError

Attempt to change an attribute that has a fixed value constraint.

exception pyxb.exceptions_.AttributeOnSimpleTypeError(instance, tag, value, location=None)

Bases: pyxb.exceptions_.ComplexTypeValidationError

Attempt made to set an attribute on an element with simple type.

Note that elements with complex type and simple content may have attributes; elements with simple type must not.

instance = None

The simple type binding instance on which no attributes exist.

tag = None

The name of the proposed attribute.

value = None

The value proposed to be assigned to the non-existent attribute.

exception pyxb.exceptions_.AttributeValidationError(type, tag, instance=None, location=None)

Bases: pyxb.exceptions_.ValidationError

Raised when an attribute requirement is not satisfied.

instance = None

The binding instance, if available.

tag = None

The name of the attribute.

type = None

The pyxb.binding.basis.complexTypeDefinition subclass of the instance.

exception pyxb.exceptions_.BadDocumentError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when processing document content and an error is encountered.

exception pyxb.exceptions_.BatchElementContentError(instance, fac_configuration, symbols, symbol_set)

Bases: pyxb.exceptions_.ContentValidationError

Element/wildcard content cannot be reconciled with the required content model.

This exception occurs in post-construction validation using a fresh validating automaton.

details()
fac_configuration = None

The pyxb.utils.fac.Configuration representing the current state of the instance automaton.

instance = None

The binding instance being constructed.

symbol_set = None

The leftovers from pyxb.binding.basis.complexTypeDefinition._symbolSet that could not be reconciled with the content model.

symbols = None

The sequence of symbols that were accepted as content prior to the error.

exception pyxb.exceptions_.BindingError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when the bindings are mis-used.

These are not validation errors, but rather structural errors. For example, attempts to extract complex content from a type that requires simple content, or vice versa.

exception pyxb.exceptions_.BindingGenerationError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when something goes wrong generating the binding classes

exception pyxb.exceptions_.ComplexTypeValidationError(*args, **kw)

Bases: pyxb.exceptions_.ValidationError

Raised when a validation requirement for a complex type is not satisfied.

exception pyxb.exceptions_.ContentInNilInstanceError(instance, content, location=None)

Bases: pyxb.exceptions_.ElementValidationError

Raised when an element that is marked to be nil is assigned content.

content = None

The content that was to be assigned to the instance.

instance = None

The binding instance which is xsi:nil

exception pyxb.exceptions_.ContentNondeterminismExceededError(instance)

Bases: pyxb.exceptions_.ContentValidationError

Content validation exceeded the allowed limits of nondeterminism.

instance = None

The binding instance being validated.

exception pyxb.exceptions_.ContentValidationError(*args, **kw)

Bases: pyxb.exceptions_.ComplexTypeValidationError

Violation of a complex type content model.

exception pyxb.exceptions_.DOMGenerationError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

A non-validation error encountered converting bindings to DOM.

exception pyxb.exceptions_.ElementChangeError(element, value, location=None)

Bases: pyxb.exceptions_.ElementValidationError

Attempt to change an element that has a fixed value constraint.

element = None

The pyxb.binding.basis.element that has a fixed value.

value = None

The value that was to be assigned to the element.

exception pyxb.exceptions_.ElementValidationError(*args, **kw)

Bases: pyxb.exceptions_.ValidationError

Raised when a validation requirement for an element is not satisfied.

exception pyxb.exceptions_.ExtraSimpleContentError(instance, value, location=None)

Bases: pyxb.exceptions_.ContentValidationError

A complex type with simple content was provided too much content.

instance = None

The binding instance that already has simple content assigned.

value = None

The proposed addition to that simple content.

exception pyxb.exceptions_.IncompleteElementContentError(instance, fac_configuration, symbols, symbol_set)

Bases: pyxb.exceptions_.BatchElementContentError

Validation of an instance failed to produce an accepting state.

This exception occurs in batch-mode validation.

exception pyxb.exceptions_.IncompleteImplementationError

Bases: pyxb.exceptions_.LogicError

Raised when required capability has not been implemented.

This is only used where it is reasonable to expect the capability to be present, such as a feature of XML schema that is not supported (e.g., the redefine directive).

exception pyxb.exceptions_.IncrementalElementContentError(instance, automaton_configuration, value, location=None)

Bases: pyxb.exceptions_.ContentValidationError

Element or element-like content could not be validly associated with an sub-element in the content model.

This exception occurs when content is added to an element during incremental validation, such as when positional arguments are used in a constructor or material is appended either explicitly or through parsing a DOM instance.

_valueDescription()
automaton_configuration = None

The pyxb.binding.content.AutomatonConfiguration representing the current state of the instance content.

instance = None

The binding for which the value could not be associated with an element.

value = None

The value that could not be associated with allowable content.

exception pyxb.exceptions_.InvalidPreferredElementContentError(instance, fac_configuration, symbols, symbol_set, preferred_symbol)

Bases: pyxb.exceptions_.BatchElementContentError

Use of a preferred element led to inability to generate a valid document

preferred_symbol = None

The element symbol which was not accepted.

exception pyxb.exceptions_.LogicError

Bases: pyxb.exceptions_.PyXBError

Raised when the code detects an implementation problem.

exception pyxb.exceptions_.MissingAttributeError(type, tag, instance=None, location=None)

Bases: pyxb.exceptions_.AttributeValidationError

Raised when an attribute that is required is missing in an element.

exception pyxb.exceptions_.MixedContentError(instance, value, location=None)

Bases: pyxb.exceptions_.ContentValidationError

Non-element content added to a complex type instance that does not support mixed content.

instance = None

The binding instance.

value = None

The non-element content.

exception pyxb.exceptions_.NamespaceArchiveError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Problem related to namespace archives

exception pyxb.exceptions_.NamespaceError(namespace, *args, **kw)

Bases: pyxb.exceptions_.PyXBException

Violation of some rule relevant to XML Namespaces

namespace()
exception pyxb.exceptions_.NamespaceUniquenessError(namespace, *args, **kw)

Bases: pyxb.exceptions_.NamespaceError

Raised when an attempt is made to record multiple objects of the same name in the same namespace category.

exception pyxb.exceptions_.NoNillableSupportError(instance, location=None)

Bases: pyxb.exceptions_.ElementValidationError

Raised when invoking _setIsNil on a type that does not support nillable.

instance = None

The binding instance on which an inappropriate operation was invoked.

exception pyxb.exceptions_.NonElementValidationError(element, location=None)

Bases: pyxb.exceptions_.ValidationError

Raised when an element (or a value bound to an element) appears in context that does not permit an element.

element = None

The content that is not permitted. This may be an element, or a DOM representation that would have been made into an element had matters progressed further.

exception pyxb.exceptions_.NonPluralAppendError(instance, element_declaration, value)

Bases: pyxb.exceptions_.ContentValidationError

Attempt to append to an element which does not accept multiple instances.

element_declaration = None

The pyxb.binding.content.ElementDeclaration contained in instance that does not accept multiple instances

instance = None

The binding instance containing the element

value = None

The proposed addition to the element in the instance

exception pyxb.exceptions_.NotComplexContentError(instance)

Bases: pyxb.exceptions_.BindingError

An operation that requires a content model was invoked on a complex type instance that has empty or simple content.

instance = None

The binding instance which should have had a content model.

exception pyxb.exceptions_.NotInNamespaceError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when a name is referenced that is not defined in the appropriate namespace.

_NotInNamespaceError__namespace = None
_NotInNamespaceError__ncName = None
exception pyxb.exceptions_.NotSimpleContentError(instance)

Bases: pyxb.exceptions_.BindingError

An operation that requires simple content was invoked on a complex type instance that does not have simple content.

instance = None

The binding instance which should have had simple content.

exception pyxb.exceptions_.OrphanElementContentError(instance, preferred)

Bases: pyxb.exceptions_.ContentValidationError

An element expected to be used in content is not present in the instance.

This exception occurs in batch-mode validation when pyxb.ValidationConfig.contentInfluencesGeneration applies, pyxb.ValidationConfig.orphanElementInContent is set to pyxb.ValidationConfig.RAISE_EXCEPTION, and the content list includes an element that is not in the binding instance content.

instance = None

The binding instance.

preferred = None

An element value from the instance content list which was not found in the instance.

exception pyxb.exceptions_.ProhibitedAttributeError(type, tag, instance=None, location=None)

Bases: pyxb.exceptions_.AttributeValidationError

Raised when an attribute that is prohibited is set or referenced in an element.

exception pyxb.exceptions_.PyXBError

Bases: exceptions.Exception

Base class for exceptions that indicate a problem that the user probably can’t fix.

exception pyxb.exceptions_.PyXBException(*args, **kw)

Bases: exceptions.Exception

Base class for exceptions that indicate a problem that the user should fix.

_args = None

The keywords passed to the exception constructor.

Note:Do not pop values from the keywords array in subclass

constructors that recognize and extract values from them. They should be kept around so they’re accessible generically.

_kw = None
_str_from_unicode()
exception pyxb.exceptions_.PyXBVersionError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised on import of a binding generated with a different version of PYXB

exception pyxb.exceptions_.QNameResolutionError(message, qname, xmlns_context)

Bases: pyxb.exceptions_.NamespaceError

Raised when a QName cannot be associated with a namespace.

namespaceContext = None
qname = None
exception pyxb.exceptions_.ReservedNameError(instance, name)

Bases: pyxb.exceptions_.BindingError

Reserved name set in binding instance.

instance = None

The binding instance.

name = None

The name that was caught being assigned

exception pyxb.exceptions_.SchemaUniquenessError(namespace, schema_location, existing_schema, *args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when somebody tries to create a schema component using a schema that has already been used in that namespace. Import and include processing would have avoided this, so somebody asked for it specifically.

existingSchema()
namespace()
schemaLocation()
exception pyxb.exceptions_.SchemaValidationError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when the XML hierarchy does not appear to be valid for an XML schema.

exception pyxb.exceptions_.SimpleContentAbsentError(instance, location)

Bases: pyxb.exceptions_.ContentValidationError

An instance with simple content was not provided with a value.

instance = None

The binding instance for which simple content is missing.

exception pyxb.exceptions_.SimpleFacetValueError(type, value, facet, location=None)

Bases: pyxb.exceptions_.SimpleTypeValueError

Raised when a simple type value does not satisfy a facet constraint.

This extends SimpleTypeValueError with the facet field which can be used to determine why the value is unacceptable.

facet = None

The specific facet that is violated by the value.

type = None

The pyxb.binding.basis.simpleTypeDefinition that constrains values.

value = None

The value that violates the constraints of type. In some cases this is a tuple of arguments passed to a constructor that failed with a built-in exception like:py:obj:ValueError or OverflowError.

exception pyxb.exceptions_.SimpleListValueError(type, value, location=None)

Bases: pyxb.exceptions_.SimpleTypeValueError

Raised when a list simple type contains a member that does not satisfy its constraints.

In this case, type is the type of the list, and value type._ItemType is the type for which the value is unacceptable.

exception pyxb.exceptions_.SimplePluralValueError(type, value, location=None)

Bases: pyxb.exceptions_.SimpleTypeValueError

Raised when context requires a plural value.

Unlike SimpleListValueError, in this case the plurality is external to type, for example when an element has simple content and allows multiple occurrences.

exception pyxb.exceptions_.SimpleTypeValueError(type, value, location=None)

Bases: pyxb.exceptions_.ValidationError

Raised when a simple type value does not satisfy its constraints.

type = None

The pyxb.binding.basis.simpleTypeDefinition that constrains values.

value = None

The value that violates the constraints of type. In some cases this is a tuple of arguments passed to a constructor that failed with a built-in exception like:py:obj:ValueError or OverflowError.

exception pyxb.exceptions_.SimpleUnionValueError(type, value, location=None)

Bases: pyxb.exceptions_.SimpleTypeValueError

Raised when a union simple type contains a member that does not satisfy its constraints.

In this case, type is the type of the union, and the value type._MemberTypes is the set of types for which the value is unacceptable.

The value itself is the tuple of arguments passed to the constructor for the union.

exception pyxb.exceptions_.StructuralBadDocumentError(*args, **kw)

Bases: pyxb.exceptions_.BadDocumentError

Raised when processing document and the content model is not satisfied.

container

The pyxb.binding.basis.complexTypeDefinition instance to which the content would belong, if available.

content

The value which could not be reconciled with the content model.

element_use

The pyxb.binding.content.ElementDeclaration instance to which the content should conform, if available.

exception pyxb.exceptions_.UnboundElementError(instance)

Bases: pyxb.exceptions_.DOMGenerationError

An instance converting to DOM had no bound element.

instance = None

The binding instance. This is missing an element binding (via pyxb.binding.basis._TypeBinding_mixin._element) and no element_name was passed.

exception pyxb.exceptions_.UnprocessedElementContentError(instance, fac_configuration, symbols, symbol_set)

Bases: pyxb.exceptions_.BatchElementContentError

Validation of an instance produced an accepting state but left element material unconsumed.

This exception occurs in batch-mode validation.

exception pyxb.exceptions_.UnprocessedKeywordContentError(instance, keywords, location=None)

Bases: pyxb.exceptions_.ContentValidationError

A complex type constructor was provided with keywords that could not be recognized.

instance = None

The binding instance being constructed.

keywords = None

The keywords that could not be recognized. These may have been intended to be attributes or elements, but cannot be identified as either.

exception pyxb.exceptions_.UnrecognizedAttributeError(type, tag, instance=None, location=None)

Bases: pyxb.exceptions_.AttributeValidationError

Attempt to reference an attribute not sanctioned by content model.

exception pyxb.exceptions_.UnrecognizedContentError(instance, automaton_configuration, value, location=None)

Bases: pyxb.exceptions_.IncrementalElementContentError

Element or element-like content could not be validly associated with an sub-element in the content model.

This exception occurs when content is added to an element during incremental validation.

details()
exception pyxb.exceptions_.UnrecognizedDOMRootNodeError(node)

Bases: pyxb.exceptions_.StructuralBadDocumentError

A root DOM node could not be resolved to a schema element

_UnrecognizedDOMRootNodeError__get_node_name()

The QName of the node as a pyxb.namespace.ExpandedName

node = None

The xml.dom.Element instance that could not be recognized

node_name

The QName of the node as a pyxb.namespace.ExpandedName

exception pyxb.exceptions_.UsageError

Bases: pyxb.exceptions_.PyXBError

Raised when the code detects user violation of an API.

exception pyxb.exceptions_.ValidationError(*args, **kw)

Bases: pyxb.exceptions_.PyXBException

Raised when something in the infoset fails to satisfy a content model or attribute requirement.

All validation errors include a location attribute which shows where in the original XML the problem occurred. The attribute may be None if the content did not come from an XML document, or the underlying XML infrastructure did not provide a location.

More refined validation error exception classes add more attributes.

details()

Provide information describing why validation failed.

In many cases, this is simply the informal string content that would be obtained through the str built-in function. For certain errors this method gives more details on what would be acceptable and where the descriptions can be found in the original schema.

Returns:a string description of validation failure
location = None

Where the error occurred in the document being parsed, if available. This will be None, or an instance of pyxb.utils.utility.Location.

Module contents

PyXB stands for Python U{W3C XML Schema<http://www.w3.org/XML/Schema>} Bindings, and is pronounced “pixbee”. It enables translation between XML instance documents and Python objects following rules specified by an XML Schema document.

This is the top-level entrypoint to the PyXB system. Importing this gets you all the exceptions, and pyxb.namespace. For more functionality, delve into these submodules:

  • pyxb.xmlschema Module holding the structures that convert XMLSchema from a DOM model to a Python class model based on the XMLSchema components. Use this when you need to operate on the component model.
  • pyxb.binding Module used to generate the bindings and at runtime to support the generated bindings. Use this if you need to use the binding model or content model.
  • pyxb.utils Common utilities used in parsing, generating, and executing. The submodules must be imported separately.
class pyxb.BIND(*args, **kw)

Bases: object

Bundle data for automated binding generation.

Instances of this class capture positional and keyword arguments that are used to create binding instances based on context. For example, if w is an instance of a complex type whose option element is declared to be an anonymous class with simple content of type integer and an attribute of units, a correct assignment to that element could be achieved with:

w.option = BIND(54, units="m")
_BIND__args = None
_BIND__kw = None
createInstance(factory, **kw)

Invoke the given factory method.

Position arguments to the factory are those cached in this instance. Keyword arguments are the ones on the command line, updated from the ones in this instance.

pyxb.NonElementContent(instance)

Return an iterator producing the non-element content of the provided instance.

The catenated text of the non-element content of an instance can be obtained with:

text = six.u('').join(pyxb.NonElementContent(instance))
Parameters:instance – An instance of pyxb.binding.basis.complexTypeDefinition.
Returns:an iterator producing text values
pyxb.PreserveInputTimeZone(value=None)

Control whether time values are converted to UTC during input.

The specification <http://www.w3.org/TR/xmlschema-2/#dateTime> makes clear that timezoned times are in UTC and that times in other timezones are to be translated to UTC when converted from literal to value form. Provide an option to bypass this step, so the input timezone is preserved.

Note:Naive processing of unnormalized times–i.e., ignoring the

tzinfo field–may result in errors.

pyxb.RequireValidWhenGenerating(value=None)

Query or set a flag that controls validation checking in XML generation.

Normally any attempts to convert a binding instance to a DOM or XML representation requires that the binding validate against the content model, since only in this way can the content be generated in the correct order. In some cases it may be necessary or useful to generate a document from a binding that is incomplete. If validation is not required, the generated documents may not validate even if the content validates, because ordering constraints will be ignored.

Parameters:value – If absent or None, no change is made; otherwise, this

enables (True) or disables (False) the requirement that instances validate before being converted to XML. :type value: bool

Returns:True iff attempts to generate XML for a binding that does not

validate should raise an exception.

pyxb.RequireValidWhenParsing(value=None)

Query or set a flag that controls validation checking in XML parsing.

Normally any attempts to convert XML to a binding instance to a binding instance requires that the document validate against the content model. In some cases it may be necessary or useful to process a document that is incomplete. If validation is not required, the generated documents may not validate even if the content validates, because ordering constraints will be ignored.

Parameters:value – If absent or None, no change is made; otherwise, this

enables (True) or disables (False) the requirement that documents validate when being converted to bindings. :type value: bool

Returns:True iff attempts to generate bindings for a document that

does not validate should raise an exception.

class pyxb.ValidationConfig

Bases: object

Class holding configuration related to validation.

pyxb.GlobalValidationConfig is available to influence validation in all contexts. Each binding class has a reference to an instance of this class, which can be inspected using pyxb.binding.basis._TypeBinding_mixin._GetValidationConfig and changed using pyxb.binding.basis._TypeBinding_mixin._SetValidationConfig. Each binding instance has a reference inherited from its class which can be inspected using pyxb.binding.basis._TypeBinding_mixin._validationConfig and changed using pyxb.binding.basis._TypeBinding_mixin._setValidationConfig.

This allows fine control on a per class and per-instance basis.

forBinding replaces RequireValidWhenParsing.

forDocument replaces RequireValidWhenGenerating.

contentInfluencesGeneration, orphanElementInContent, and invalidElementInContent control how pyxb.binding.basis.complexTypeDefinition.orderedContent affects generated documents.

ALWAYS = -1

Always do it.

GIVE_UP = 2

If an error occurs ignore it and stop using whatever provided the cause of the error. (E.g., if an element in a content list fails stop processing the content list and execute as though it was absent).

IGNORE_ONCE = 1

If an error occurs ignore it and continue with the next one. (E.g., if an element in a content list fails skip it and continue with the next element in the list.)

MIXED_ONLY = 4

Only when content type is mixed.

NEVER = 0

Never do it.

RAISE_EXCEPTION = 3

If an error occurs, raise an exception.

_ValidationConfig__contentInfluencesGeneration = 4
_ValidationConfig__forBinding = True
_ValidationConfig__forDocument = True
_ValidationConfig__getContentInfluencesGeneration()

Determine whether complex type content influences element order in document generation.

The value is one of ALWAYS, NEVER, MIXED_ONLY (default).

_ValidationConfig__getInvalidElementInContent()

How to handle invalid elements in content lists.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

_ValidationConfig__getOrphanElementInContent()

How to handle unrecognized elements in content lists.

This is used when consulting a complex type instance content list to influence the generation of documents from a binding instance.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

_ValidationConfig__invalidElementInContent = 1
_ValidationConfig__orphanElementInContent = 1
_getForBinding()

True iff validation should be performed when manipulating a binding instance.

This includes parsing a document or DOM tree, using a binding instance class constructor, or assigning to an element or attribute field of a binding instance.

_getForDocument()

True iff validation should be performed when creating a document from a binding instance.

This applies at invocation of toDOM(). toxml() invokes toDOM().

_setContentInfluencesGeneration(value)

Set the value of contentInfluencesGeneration.

_setForBinding(value)

Configure whether validation should be performed when manipulating a binding instance.

_setForDocument(value)

Configure whether validation should be performed when generating a document from a binding instance.

_setInvalidElementInContent(value)

Set the value of invalidElementInContent.

_setOrphanElementInContent(value)

Set the value of orphanElementInContent.

contentInfluencesGeneration

Determine whether complex type content influences element order in document generation.

The value is one of ALWAYS, NEVER, MIXED_ONLY (default).

copy()

Make a copy of this instance.

Use this to get a starting point when you need to customize validation on a per-instance/per-class basis.

forBinding

True iff validation should be performed when manipulating a binding instance.

This includes parsing a document or DOM tree, using a binding instance class constructor, or assigning to an element or attribute field of a binding instance.

forDocument

True iff validation should be performed when creating a document from a binding instance.

This applies at invocation of toDOM(). toxml() invokes toDOM().

invalidElementInContent

How to handle invalid elements in content lists.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

orphanElementInContent

How to handle unrecognized elements in content lists.

This is used when consulting a complex type instance content list to influence the generation of documents from a binding instance.

The value is one of IGNORE_ONCE (default), GIVE_UP, RAISE_EXCEPTION.

pyxb.XMLStyle_minidom = 0

Use xml.dom.minidom for XML processing. This is the fastest, but does not provide location information. It produces DOM instances.

pyxb.XMLStyle_saxdom = 1

Use pyxb.utils.saxdom for XML processing. This is the slowest, but both provides location information and generates a DOM instance.

pyxb.XMLStyle_saxer = 2

Use pyxb.binding.saxer when converting documents to binding instances. This style supports location information in the bindings. It produces binding instances directly, without going through a DOM stage, so is faster than XMLStyle_saxdom. However, since the pyxb.xmlschema.structures classes require a DOM model, XMLStyle_saxdom will be used for pyxb.utils.domutils.StringToDOM if this style is selected.

pyxb._SetXMLStyle(style=None)

Set the interface used to parse XML content.

This can be invoked within code. The system default of XMLStyle_saxer can also be overridden at runtime by setting the environment variable PYXB_XML_STYLE to one of minidom, saxdom, or saxer.

Parameters:style – One of XMLStyle_minidom, XMLStyle_saxdom,

XMLStyle_saxer. If not provided, the system default is used.

class pyxb.cscRoot(*args, **kw)

Bases: object

This little bundle of joy exists because in Python 2.6 it became an error to invoke object.__init__ with parameters (unless you also override __new__, in which case it’s only a warning. Whatever.). Since I’m bloody not going to check in every class whether super(Myclass,self) refers to object (even if I could figure out how to do that, ‘cuz the obvious solutions don’t work), we’ll just make this thing the root of all U{cooperative super calling<http://www.geocities.com/foetsch/python/new_style_classes.htm#super>} hierarchies. The standard syntax in PyXB for this pattern is:

def method_csc (self, *args, **kw):
  self_fn = lambda *_args, **_kw: self
  super_fn = getattr(super(ThisClass, self), 'method_csc', self_fn)
  return super_fn(*args, **kw)