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 L{exceptions<pyxb.exceptions_.PyXBException>}, and L{pyxb.namespace}. For more functionality, delve into these submodules:

  • L{pyxb.xmlschema} Module holding the L{structures<pyxb.xmlschema.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.
  • L{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.
  • L{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 C{w} is an instance of a complex type whose C{option} element is declared to be an anonymous class with simple content of type integer and an attribute of C{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))

@param instance: An instance of L{pyxb.binding.basis.complexTypeDefinition}.

@return: an iterator producing text values

pyxb.PreserveInputTimeZone(value=None)

Control whether time values are converted to UTC during input.

The U{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 C{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.

@keyword value: If absent or C{None}, no change is made; otherwise, this enables (C{True}) or disables (C{False}) the requirement that instances validate before being converted to XML. @type value: C{bool}

@return: C{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.

@keyword value: If absent or C{None}, no change is made; otherwise, this enables (C{True}) or disables (C{False}) the requirement that documents validate when being converted to bindings. @type value: C{bool}

@return: C{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.

L{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 L{pyxb.binding.basis._TypeBinding_mixin._GetValidationConfig} and changed using L{pyxb.binding.basis._TypeBinding_mixin._SetValidationConfig}. Each binding instance has a reference inherited from its class which can be inspected using L{pyxb.binding.basis._TypeBinding_mixin._validationConfig} and changed using L{pyxb.binding.basis._TypeBinding_mixin._setValidationConfig}.

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

L{forBinding} replaces L{RequireValidWhenParsing}.

L{forDocument} replaces L{RequireValidWhenGenerating}.

L{contentInfluencesGeneration}, L{orphanElementInContent}, and L{invalidElementInContent} control how L{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 L{ALWAYS}, L{NEVER}, L{MIXED_ONLY} (default).

_ValidationConfig__getInvalidElementInContent()

How to handle invalid elements in content lists.

The value is one of L{IGNORE_ONCE} (default), L{GIVE_UP}, L{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 L{IGNORE_ONCE} (default), L{GIVE_UP}, L{RAISE_EXCEPTION}.

_ValidationConfig__invalidElementInContent = 1
_ValidationConfig__orphanElementInContent = 1
_getForBinding()

C{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()

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

This applies at invocation of L{toDOM()<pyxb.binding.basis._TypeBinding_mixin.toDOM>}. L{toxml()<pyxb.binding.basis._TypeBinding_mixin.toDOM>} invokes C{toDOM()}.

_setContentInfluencesGeneration(value)

Set the value of L{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 L{invalidElementInContent}.

_setOrphanElementInContent(value)

Set the value of L{orphanElementInContent}.

contentInfluencesGeneration

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

The value is one of L{ALWAYS}, L{NEVER}, L{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

C{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

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

This applies at invocation of L{toDOM()<pyxb.binding.basis._TypeBinding_mixin.toDOM>}. L{toxml()<pyxb.binding.basis._TypeBinding_mixin.toDOM>} invokes C{toDOM()}.

invalidElementInContent

How to handle invalid elements in content lists.

The value is one of L{IGNORE_ONCE} (default), L{GIVE_UP}, L{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 L{IGNORE_ONCE} (default), L{GIVE_UP}, L{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._CorruptionDetectionEnabled = True

If C{True}, blocks attempts to assign to attributes that are reserved for PyXB methods.

Applies only at compilation time; dynamic changes are ignored.

pyxb._GenerationRequiresValid = True

Legacy flag; prefer L{forDocument<ValidationConfig.forDocument>} in L{GlobalValidationConfig}.

pyxb._InputEncoding = 'utf-8'

Default unicode encoding to assume when decoding input.

Material being written to an XML parser is treated as input.

pyxb._OutputEncoding = 'utf-8'

Default unicode encoding to use when creating output.

Material being written to an XML parser is not output.

pyxb._ParsingRequiresValid = True

Legacy flag; prefer L{forBinding<ValidationConfig.forBinding>} in L{GlobalValidationConfig}.

pyxb._SetXMLStyle(style=None)

Set the interface used to parse XML content.

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

@param style: One of L{XMLStyle_minidom}, L{XMLStyle_saxdom}, L{XMLStyle_saxer}. If not provided, the system default is used.

pyxb._XMLStyle = 2

The current XML processing style.

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

Bases: object

This little bundle of joy exists because in Python 2.6 it became an error to invoke C{object.__init__} with parameters (unless you also override C{__new__}, in which case it’s only a warning. Whatever.). Since I’m bloody not going to check in every class whether C{super(Myclass,self)} refers to C{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 C{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 L{pyxb.binding.basis.element} in question

value = None

The value proposed for the L{element}. This is usually going to be a C{xml.dom.Node} used in the attempt to create the element, C{None} if the abstract element was invoked without a node, or another type if L{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 L{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 L{xml.dom.Element} from which instantiation was attempted, if available.

type = None

The abstract L{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 L{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 L{pyxb.utils.fac.Configuration} representing the current state of the L{instance} automaton.

instance = None

The binding instance being constructed.

symbol_set = None

The leftovers from L{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 L{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 L{pyxb.binding.content.AutomatonConfiguration} representing the current state of the L{instance} content.

instance = None

The binding for which the L{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 L{_setIsNil<pyxb.binding.basis._TypeBinding_mixin._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 L{pyxb.binding.content.ElementDeclaration} contained in C{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 L{pyxb.ValidationConfig.contentInfluencesGeneration} applies, L{pyxb.ValidationConfig.orphanElementInContent} is set to L{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 L{instance} L{content<pyxb.binding.basis.complexTypeDefinition.content>} list which was not found in the L{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: Exception

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

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

Bases: 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
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 L{SimpleTypeValueError} with the L{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 L{pyxb.binding.basis.simpleTypeDefinition} that constrains values.

value = None

The value that violates the constraints of L{type}. In some cases this is a tuple of arguments passed to a constructor that failed with a built-in exception likeC{ValueError} or C{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, L{type} is the type of the list, and value C{type._ItemType} is the type for which the L{value} is unacceptable.

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

Bases: pyxb.exceptions_.SimpleTypeValueError

Raised when context requires a plural value.

Unlike L{SimpleListValueError}, in this case the plurality is external to C{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 L{pyxb.binding.basis.simpleTypeDefinition} that constrains values.

value = None

The value that violates the constraints of L{type}. In some cases this is a tuple of arguments passed to a constructor that failed with a built-in exception likeC{ValueError} or C{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, L{type} is the type of the union, and the value C{type._MemberTypes} is the set of types for which the value is unacceptable.

The L{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 L{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 L{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 L{pyxb.binding.basis._TypeBinding_mixin._element}) and no C{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 L{node} as a L{pyxb.namespace.ExpandedName}

node = None

The L{xml.dom.Element} instance that could not be recognized

node_name

The QName of the L{node} as a L{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 L{location} attribute which shows where in the original XML the problem occurred. The attribute may be C{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 C{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.

@return: a string description of validation failure

location = None

Where the error occurred in the document being parsed, if available. This will be C{None}, or an instance of L{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 L{exceptions<pyxb.exceptions_.PyXBException>}, and L{pyxb.namespace}. For more functionality, delve into these submodules:

  • L{pyxb.xmlschema} Module holding the L{structures<pyxb.xmlschema.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.
  • L{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.
  • L{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 C{w} is an instance of a complex type whose C{option} element is declared to be an anonymous class with simple content of type integer and an attribute of C{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))

@param instance: An instance of L{pyxb.binding.basis.complexTypeDefinition}.

@return: an iterator producing text values

pyxb.PreserveInputTimeZone(value=None)

Control whether time values are converted to UTC during input.

The U{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 C{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.

@keyword value: If absent or C{None}, no change is made; otherwise, this enables (C{True}) or disables (C{False}) the requirement that instances validate before being converted to XML. @type value: C{bool}

@return: C{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.

@keyword value: If absent or C{None}, no change is made; otherwise, this enables (C{True}) or disables (C{False}) the requirement that documents validate when being converted to bindings. @type value: C{bool}

@return: C{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.

L{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 L{pyxb.binding.basis._TypeBinding_mixin._GetValidationConfig} and changed using L{pyxb.binding.basis._TypeBinding_mixin._SetValidationConfig}. Each binding instance has a reference inherited from its class which can be inspected using L{pyxb.binding.basis._TypeBinding_mixin._validationConfig} and changed using L{pyxb.binding.basis._TypeBinding_mixin._setValidationConfig}.

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

L{forBinding} replaces L{RequireValidWhenParsing}.

L{forDocument} replaces L{RequireValidWhenGenerating}.

L{contentInfluencesGeneration}, L{orphanElementInContent}, and L{invalidElementInContent} control how L{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 L{ALWAYS}, L{NEVER}, L{MIXED_ONLY} (default).

_ValidationConfig__getInvalidElementInContent()

How to handle invalid elements in content lists.

The value is one of L{IGNORE_ONCE} (default), L{GIVE_UP}, L{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 L{IGNORE_ONCE} (default), L{GIVE_UP}, L{RAISE_EXCEPTION}.

_ValidationConfig__invalidElementInContent = 1
_ValidationConfig__orphanElementInContent = 1
_getForBinding()

C{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()

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

This applies at invocation of L{toDOM()<pyxb.binding.basis._TypeBinding_mixin.toDOM>}. L{toxml()<pyxb.binding.basis._TypeBinding_mixin.toDOM>} invokes C{toDOM()}.

_setContentInfluencesGeneration(value)

Set the value of L{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 L{invalidElementInContent}.

_setOrphanElementInContent(value)

Set the value of L{orphanElementInContent}.

contentInfluencesGeneration

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

The value is one of L{ALWAYS}, L{NEVER}, L{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

C{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

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

This applies at invocation of L{toDOM()<pyxb.binding.basis._TypeBinding_mixin.toDOM>}. L{toxml()<pyxb.binding.basis._TypeBinding_mixin.toDOM>} invokes C{toDOM()}.

invalidElementInContent

How to handle invalid elements in content lists.

The value is one of L{IGNORE_ONCE} (default), L{GIVE_UP}, L{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 L{IGNORE_ONCE} (default), L{GIVE_UP}, L{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._CorruptionDetectionEnabled = True

If C{True}, blocks attempts to assign to attributes that are reserved for PyXB methods.

Applies only at compilation time; dynamic changes are ignored.

pyxb._GenerationRequiresValid = True

Legacy flag; prefer L{forDocument<ValidationConfig.forDocument>} in L{GlobalValidationConfig}.

pyxb._InputEncoding = 'utf-8'

Default unicode encoding to assume when decoding input.

Material being written to an XML parser is treated as input.

pyxb._OutputEncoding = 'utf-8'

Default unicode encoding to use when creating output.

Material being written to an XML parser is not output.

pyxb._ParsingRequiresValid = True

Legacy flag; prefer L{forBinding<ValidationConfig.forBinding>} in L{GlobalValidationConfig}.

pyxb._SetXMLStyle(style=None)

Set the interface used to parse XML content.

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

@param style: One of L{XMLStyle_minidom}, L{XMLStyle_saxdom}, L{XMLStyle_saxer}. If not provided, the system default is used.

pyxb._XMLStyle = 2

The current XML processing style.

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

Bases: object

This little bundle of joy exists because in Python 2.6 it became an error to invoke C{object.__init__} with parameters (unless you also override C{__new__}, in which case it’s only a warning. Whatever.). Since I’m bloody not going to check in every class whether C{super(Myclass,self)} refers to C{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)