# 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)

## subpackages

- pyxb.binding package
  - Submodules
  - pyxb.binding.basis module
  - pyxb.binding.content module
  - pyxb.binding.datatypes module
  - pyxb.binding.facets module
  - pyxb.binding.generate module
  - pyxb.binding.saxer module
  - pyxb.binding.xml_ module
  - Module contents
- pyxb.namespace package
  - Submodules
  - pyxb.namespace.archive module
  - pyxb.namespace.builtin module
  - pyxb.namespace.resolution module
  - pyxb.namespace.utility module
  - Module contents
- pyxb.utils package
  - Submodules
  - pyxb.utils.activestate module
  - pyxb.utils.domutils module
  - pyxb.utils.fac module
  - pyxb.utils.saxdom module
  - pyxb.utils.saxutils module
  - pyxb.utils.six module
  - pyxb.utils.templates module
  - pyxb.utils.unicode module
  - pyxb.utils.unicode_data module
  - pyxb.utils.utility module
  - pyxb.utils.xmlre module
  - Module contents
- pyxb.xmlschema package
  - Submodules
  - pyxb.xmlschema.structures module
  - Module contents

## 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)