merge for release 1.2.6

MANIFEST.in

@@ -35,7 +35,7 @@ exclude doc/*.eap
 prune doc/W3C
 
 # Examples that didn't go into bundles
-recursive-include examples *.txt *.py *.sh *.xsd *.xml *-patch *.out *.xhtml
+recursive-include examples *.txt *.py *.sh *.xsd *.xml *-patch *.out *.expected *.xhtml
 include examples/unicode_jp/pyxbgen_jp
 
 # Detritus

README.txt

@@ -1,5 +1,5 @@
 PyXB -- Python W3C XML Schema Bindings
-Version 1.2.5
+Version 1.2.6
 
 The source releases includes pre-built bundles for common XML namespaces,
 assorted web service namespaces, and SAML.  A bundle with over 75 namespaces
@@ -8,7 +8,7 @@ those, read pyxb/bundles/opengis/README.txt before installing PyXB.
 
 Installation:  python setup.py install
 
-Documentation: doc/html
+Documentation: doc/html or https://pabigot.github.io/pyxb/
 
 Help Forum: http://sourceforge.net/forum/forum.php?forum_id=956708
 

README.txt.in

@@ -8,7 +8,7 @@ those, read pyxb/bundles/opengis/README.txt before installing PyXB.
 
 Installation:  python setup.py install
 
-Documentation: doc/html
+Documentation: doc/html or https://pabigot.github.io/pyxb/
 
 Help Forum: http://sourceforge.net/forum/forum.php?forum_id=956708
 

doc/Makefile

@@ -6,16 +6,12 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 
-EPYDOC        = epydoc
-EPYDOCOPTS    = --config documentation.cfg
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-.PHONY: apihtml
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -30,19 +26,15 @@ help:
 	@echo "  linkcheck to check all external links for integrity"
 	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
 
-apihtml:
-	mkdir -p html/api
-	PYTHONPATH=.. $(EPYDOC) $(EPYDOCOPTS)
-
 pyxbgen_cli.txt: ../pyxb/binding/generate.py ../maintainer/gendoc
 	PYTHONPATH=.. ../maintainer/gendoc \
-        | sed -e 's@  *$$@@' \
+        | sed -e 's@  *$$@@' -e '$${/^$$/d;}' \
         > $@
 
 GENERATED_TXT += pyxbgen_cli.txt
 
 html: $(GENERATED_TXT)
-	PYTHONPATH=. $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) html
+	PYTHONPATH=.:.. $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) html
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 

doc/arch_binding.txt

@@ -19,27 +19,27 @@ Supporting Capabilities
 Common Binding Instance Features
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:api:`pyxb.binding.basis._TypeBinding_mixin` is a marker class to indicate
+:py:obj:`pyxb.binding.basis._TypeBinding_mixin` is a marker class to indicate
 that the incorporating class represents a binding associated with a type
 definition (whether simple or complex).  The key features of this mixin are:
 
- - The :api:`_ExpandedName
+ - The :py:obj:`_ExpandedName
    <pyxb.binding.basis._TypeBinding_mixin._ExpandedName>` class variable is
    overridden in each class to identify the type definition corresponding to
    the class.
 
- - The :api:`_XSDLocation
+ - The :py:obj:`_XSDLocation
    <pyxb.binding.basis._TypeBinding_mixin._XSDLocation>` class variable is
    overridden in each class to provide the line, column, and schema at which
    the data type definition was found.  This is used in diagnostics.
 
- - The :api:`namespace context
+ - The :py:obj:`namespace context
    <pyxb.binding.basis._TypeBinding_mixin._namespaceContext>` of the type
    definition is recorded to allow users to perform QName resolution of values
    within instance documents (see, for example, the customized bindings in
    ``pyxb.bundles.wssplat.wsdl11``).
 
- - Each instance records the :api:`pyxb.binding.basis.element` instance that
+ - Each instance records the :py:obj:`pyxb.binding.basis.element` instance that
    determines where the type came from.  The element is required in order to
    provide the correct name when converting the binding instance to a DOM
    instance on its way to expression as a text XML document.
@@ -48,7 +48,7 @@ definition (whether simple or complex).  The key features of this mixin are:
    <http://www.w3.org/TR/xmlschema-1/#xsi_nil>`_ information for the instance
    is stored.
 
- - A :api:`Factory <pyxb.binding.basis._TypeBinding_mixin>` infrastructure is
+ - A :py:obj:`Factory <pyxb.binding.basis._TypeBinding_mixin>` infrastructure is
    provided to allow creation of new instances of the binding while permitting
    developers to customize the generated binding classes; see
    :ref:`binding_customization`.
@@ -70,38 +70,38 @@ their XML name, the chances of conflict are high.
 PyXB resolves this by ensuring every identifiable object has a unique
 identifier within its context.  The steps involved are:
 
-#. Make object name into an :api:`identifier
+#. Make object name into an :py:obj:`identifier
    <pyxb.utils.utility.MakeIdentifier>` by stripping out non-printable
    characters, replacing characters that cannot appear in identifiers with
    underscores, stripping leading underscores, and prefixing an initial
    digit with the character ``n``.
 
-#. :api:`Deconflict <pyxb.utils.utility.DeconflictKeyword>` the resulting
-   identifier from Python :api:`reserved identifiers
+#. :py:obj:`Deconflict <pyxb.utils.utility.DeconflictKeyword>` the resulting
+   identifier from Python :py:obj:`reserved identifiers
    <pyxb.utils.utility._Keywords>` and other context-specific keywords.
 
 #. Prepend the standard prefix that denotes the identifier's :ref:`visibility
    <identifier_naming>` (public, protected, private)
 
-#. Make the resulting identifier :api:`unique <pyxb.utils.utility.MakeUnique>`
+#. Make the resulting identifier :py:obj:`unique <pyxb.utils.utility.MakeUnique>`
    within its context (containing class or module).
 
 These steps are encapsulated into a single function
-:api:`pyxb.utils.utility.PrepareIdentifier` which takes parameters that
+:py:obj:`pyxb.utils.utility.PrepareIdentifier` which takes parameters that
 customize the context for the identifier.
 
 In addition to name conflicts with namespace-global identifiers appearing
 directly in the module, conflicts may also appear within a binding class as a
 result of collision with names from Python keywords, public class names, and
 public field or method names in the class.  The
-:api:`pyxb.utils.utility._DeconflictSymbols_mixin` is used to refine the set
+:py:obj:`pyxb.utils.utility._DeconflictSymbols_mixin` is used to refine the set
 of type-specific public names.  If you customize a generated binding class by
 extending from it, you must specify your own class variable
 ``_ReservedSymbols`` with a value that is the union of your symbols and those
-of the superclass(es) (see :api:`pyxb.utils.utility._DeconflictSymbols_mixin`
+of the superclass(es) (see :py:obj:`pyxb.utils.utility._DeconflictSymbols_mixin`
 for details).
 
-Deconfliction of module-level names occurs prior to :api:`code generation
+Deconfliction of module-level names occurs prior to :py:obj:`code generation
 <pyxb.binding.generate.GeneratePython>`.  Identifiers are deconflicted in
 favor of higher items on this list:
 
@@ -122,9 +122,9 @@ the generated bindings by adding both functionality and derived content.
 Maintenance issues require that these extensions exist separately from the
 automatically-generated binding modules; usability requires that they inherit
 from the automatically-generated modules.  This is supported by the
-:api:`pyxb.binding.basis._DynamicCreate_mixin` class.
+:py:obj:`pyxb.binding.basis._DynamicCreate_mixin` class.
 
-This class provides a :api:`method
+This class provides a :py:obj:`method
 <pyxb.binding.basis._DynamicCreate_mixin._DynamicCreate>` which is used by
 the generated bindings to create new instances of themselves.  The raw
 bindings are generated into a sub-module with the prefix ``raw``, and the
@@ -159,10 +159,10 @@ Simple Type Definitions
 
 `Simple type definitions
 <http://www.w3.org/TR/xmlschema-1/#Simple_Type_Definitions>`_ derive from
-:api:`pyxb.binding.basis.simpleTypeDefinition` and a standard Python type.
+:py:obj:`pyxb.binding.basis.simpleTypeDefinition` and a standard Python type.
 
 For simple types that are not derived by list or union, you can construct
-instances using the :api:`Factory <pyxb.binding.basis._TypeBinding_mixin>`
+instances using the :py:obj:`Factory <pyxb.binding.basis._TypeBinding_mixin>`
 method or directly, providing the value as an argument.  New instance creation
 is validated against the `facets
 <http://www.w3.org/TR/xmlschema-2/#rf-facets>`_ recorded in the binding class.
@@ -175,7 +175,7 @@ Each class corresponding to a simple type definition has class variables for
 the `constraining facets <http://www.w3.org/TR/xmlschema-2/#rf-facets>`_
 that are valid for that class.  These variables are named by prefixing the
 facet name with ``_CF_``, and have a value that is an instance of the
-corresponding :api:`facet class <pyxb.binding.facets>`.  Where possible, the
+corresponding :py:obj:`facet class <pyxb.binding.facets>`.  Where possible, the
 variables are inherited from the parent class; when a simple type is derived
 by restriction, the restricted class overrides its parent with a new value
 for the corresponding facet.
@@ -199,21 +199,21 @@ Enumeration and pattern constraints maintain a list of the respective
 acceptable enumeration and pattern values.
 
 Facets implement the
-:api:`pyxb.binding.facets.ConstrainingFacet.validateConstraint` method, which
+:py:obj:`pyxb.binding.facets.ConstrainingFacet.validateConstraint` method, which
 in turn is invoked by the
-:api:`pyxb.binding.basis.simpleTypeDefinition.XsdConstraintsOK` class method
+:py:obj:`pyxb.binding.basis.simpleTypeDefinition.XsdConstraintsOK` class method
 when given a value that may or may not satisfy the constraints.  The
-:api:`Factory <pyxb.binding.basis._TypeBinding_mixin.Factory>` will normally
+:py:obj:`Factory <pyxb.binding.basis._TypeBinding_mixin.Factory>` will normally
 validate the constraints before allowing a new instance to be returned.
 
 List Types
 ^^^^^^^^^^
 
 Simple types that derive by `list
 <http://www.w3.org/TR/xmlschema-2/#atomic-vs-list>`_ extend from
-:api:`pyxb.binding.basis.STD_list` which in turn descends from the Python
+:py:obj:`pyxb.binding.basis.STD_list` which in turn descends from the Python
 ``list`` type.  These derived classes must override the base class
-:api:`pyxb.binding.basis.STD_list._ItemType` value with the appropriate
+:py:obj:`pyxb.binding.basis.STD_list._ItemType` value with the appropriate
 class to use when creating or validating list members.
 
 When constructing an instance of a simple list type, you can provide a list as
@@ -224,9 +224,9 @@ Union Types
 ^^^^^^^^^^^
 
 Union types are classes that are never instantiated.  Instead, the binding
-classes define a :api:`pyxb.binding.basis.STD_union._MemberTypes` variable
+classes define a :py:obj:`pyxb.binding.basis.STD_union._MemberTypes` variable
 which contains a list of binding classes that are permitted as members of the
-union.  The :api:`pyxb.binding.basis.STD_union.Factory` method attempts, in
+union.  The :py:obj:`pyxb.binding.basis.STD_union.Factory` method attempts, in
 turn, to create an instance of each potential member type using the arguments
 passed into it.  The returned value is the first instance that was
 successfully created.
@@ -236,7 +236,7 @@ member of a union is not recorded in the attribute value.  See
 :ref:`attributeUse`.
 
 It is not possible to construct an instance of a union type directly.  You
-must use the :api:`Factory <pyxb.binding.basis.STD_union.Factory>` method,
+must use the :py:obj:`Factory <pyxb.binding.basis.STD_union.Factory>` method,
 with an argument that is acceptable as an initializer for one of the member
 types.
 
@@ -246,24 +246,24 @@ Complex Type Definitions
 
 `Complex type definitions
 <http://www.w3.org/TR/xmlschema-1/#Complex_Type_Definitions>`_ derive from
-:api:`pyxb.binding.basis.complexTypeDefinition`.  Classes representing complex
-type definitions record maps that specify :api:`attribute
-<pyxb.binding.content.AttributeUse>` and :api:`element
+:py:obj:`pyxb.binding.basis.complexTypeDefinition`.  Classes representing complex
+type definitions record maps that specify :py:obj:`attribute
+<pyxb.binding.content.AttributeUse>` and :py:obj:`element
 <pyxb.binding.content.ElementDeclaration>` use structures to record the attributes and
 elements that comprise the type.  Each such structure is stored as a private
 class field and is used by Python properties to provide access to element and
 attribute values in a binding instance.
 
-The base :api:`pyxb.binding.basis.complexTypeDefinition` class provides the
+The base :py:obj:`pyxb.binding.basis.complexTypeDefinition` class provides the
 infrastructure to identify the appropriate attribute or element given an XML
 tag name.  For classes corresponding to types that enable `wildcards
 <http://www.w3.org/TR/xmlschema-1/#Wildcards>`_, it also provides a mechanism
-to access unrecognized elements and attributes.  :api:`Wildcard elements
+to access unrecognized elements and attributes.  :py:obj:`Wildcard elements
 <pyxb.binding.basis.complexTypeDefinition.wildcardElements>` are converted to
 binding instances if their namespace and name are recognized, and otherwise
-are left as DOM nodes.  :api:`Wildcard attributes
+are left as DOM nodes.  :py:obj:`Wildcard attributes
 <pyxb.binding.basis.complexTypeDefinition.wildcardAttributeMap>` are stored in
-a map from their :api:`expanded name <pyxb.namespace.ExpandedName>` to the
+a map from their :py:obj:`expanded name <pyxb.namespace.ExpandedName>` to the
 unicode value of the attribute.
 
 When creating a complex type definition, you can provide the values for its
@@ -301,8 +301,8 @@ Simple Content
 Complex types with simple content (i.e., those in which the body of the
 element is an octet sequence in the lexical space of a specified simple type)
 are distinguished by providing a value for the class-level
-:api:`pyxb.binding.basis.complexTypeDefinition._TypeDefinition` variable.
-For these types, the :api:`pyxb.binding.basis.complexTypeDefinition.content`
+:py:obj:`pyxb.binding.basis.complexTypeDefinition._TypeDefinition` variable.
+For these types, the :py:obj:`pyxb.binding.basis.complexTypeDefinition.content`
 method returns the instance of that type that corresponds to the content of
 the object.
 
@@ -335,17 +335,16 @@ was not necessary for ``v.simple`` or ``v.attribute``.
 Mixed and Element-Only Content
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-`Mixed and element-only content
-<http://www.w3.org/TR/xmlschema-1/#content_type>`_ nodes use the :api:`
-<pyxb.binding.basis.complexTypeDefinition._ElementBindingDeclForName>` method
+`Mixed and element-only content <http://www.w3.org/TR/xmlschema-1/#content_type>`_ nodes
+use the :py:obj:`pyxb.binding.basis.complexTypeDefinition._ElementBindingDeclForName` method
 to manage the mapping from XML schema element names to class members.  The
 element and attribute names are distinct.  Instances of complex types also
-reference a :api:`content automaton
+reference a :py:obj:`content automaton
 <pyxb.binding.content.AutomatonConfiguration>` to ensure the constraints of
 the schema are satisfied.  These structures are described in
 :ref:`contentModel`.
 
-For these types, the :api:`pyxb.binding.basis.complexTypeDefinition.content`
+For these types, the :py:obj:`pyxb.binding.basis.complexTypeDefinition.content`
 method returns a list, in parsed order, of the Python objects and (if mixed)
 non-element content that belong to the instance.  Be aware that this order
 currently does not influence the order of elements when converting bindings
@@ -356,7 +355,7 @@ Elements
 
 Unlike the bindings for schema type definitions, which are represented as
 Python classes, bindings corresponding to XML Schema element declarations are
-represented as instances of the :api:`pyxb.binding.basis.element` class.  The
+represented as instances of the :py:obj:`pyxb.binding.basis.element` class.  The
 instances can be used to create new binding instances that are associated with
 the element.  Elements are used in the content model to identify transitions
 through a finite automaton.

doc/arch_component.txt

@@ -8,7 +8,7 @@ complex relation of data objects.  Each object class corresponds to one of
 the thirteen `XML Schema Components
 <www.w3.org/TR/xmlschema-1/index.html#components>`_, and names of components
 and their properties follow those definitions.  All classes specific to the
-component model are found in the :api:`pyxb.xmlschema.structures` module.
+component model are found in the :py:obj:`pyxb.xmlschema.structures` module.
 
 The relationships amongst components is depicted in the following diagram.
 Composite aggregation generally denotes ownership and shared aggregation
@@ -22,44 +22,44 @@ Component Model Mix-ins
 A variety of :ref:`mixins` are used to allow common code to be abstracted or
 to mark objects as having certain capabilities.  These mixins are:
 
-- :api:`pyxb.xmlschema.structures._SchemaComponent_mixin` marks the object
+- :py:obj:`pyxb.xmlschema.structures._SchemaComponent_mixin` marks the object
   as being a schema component and holds its
-  :api:`pyxb.namespace.NamespaceContext`.  It also records relations between
+  :py:obj:`pyxb.namespace.NamespaceContext`.  It also records relations between
   components in a global definition and their clones where those definitions
   are expanded.
 
-- :api:`pyxb.xmlschema.structures._Singleton_mixin` is used to ensure there is only one instance each
+- :py:obj:`pyxb.xmlschema.structures._Singleton_mixin` is used to ensure there is only one instance each
   of the `simple ur-type
   <http://www.w3.org/TR/xmlschema-1/#simple-ur-type-itself>`_ and `ur-type
   <http://www.w3.org/TR/xmlschema-1/#ur-type-itself>`_.  It overloads
   ``__new__`` to ensure that only one instance of the class is ever
   constructed.
 
-- :api:`pyxb.xmlschema.structures._Annotated_mixin` provides the support for all components that
+- :py:obj:`pyxb.xmlschema.structures._Annotated_mixin` provides the support for all components that
   contain an `annotation <http://www.w3.org/TR/xmlschema-1/#cAnnotations>`_
   as a child element.
 
-- :api:`pyxb.xmlschema.structures._NamedComponent_mixin` supports components
+- :py:obj:`pyxb.xmlschema.structures._NamedComponent_mixin` supports components
   that can be identified by name.  This includes the target namespace (which
   may be anonymous) if the component is global, and the `complex type
   definition <http://www.w3.org/TR/xmlschema-1/#Complex_Type_Definitions>`_
   that serves as the component's `scope
   <http://www.w3.org/TR/xmlschema-1/#e-scope>`_ when it is local.
 
-- :api:`pyxb.xmlschema.structures._ValueConstraint_mixin` provides support
+- :py:obj:`pyxb.xmlschema.structures._ValueConstraint_mixin` provides support
   for components that have `value constraints
   <http://www.w3.org/TR/xmlschema-1/#e-value_constraint>`_ : that is,
   provide a default value and optionally require a fixed value.
 
-- :api:`pyxb.xmlschema.structures._ScopedDeclaration_mixin` is used by
+- :py:obj:`pyxb.xmlschema.structures._ScopedDeclaration_mixin` is used by
   `element declarations
   <http://www.w3.org/TR/xmlschema-1/#cElement_Declarations>`_ and `complex
   type definitions
   <http://www.w3.org/TR/xmlschema-1/#Complex_Type_Definitions>`_ which may be
   named but only referenceable within a specific `scope
   <http://www.w3.org/TR/xmlschema-1/#e-scope>`_.
 
-- :api:`pyxb.xmlschema.structures._AttributeWildcard_mixin` provides support
+- :py:obj:`pyxb.xmlschema.structures._AttributeWildcard_mixin` provides support
   for `attribute group definitions
   <http://www.w3.org/TR/xmlschema-1/#cAttribute_Group_Definitions>`_ and
   `complex type definitions
@@ -72,7 +72,7 @@ Other Information
 
 Most of the important information about the component model is best obtained
 from the `specification <http://www.w3.org/TR/xmlschema-1/#components>`_ or
-from the :api:`PyXB component model API <pyxb.xmlschema.structures>`.
+from the :py:obj:`PyXB component model API <pyxb.xmlschema.structures>`.
 Tidbits of other relevant information:
 
 - An understanding of :ref:`resolution` is important.