.. _bundles:

Examples of Supported Schema
============================

PyXB comes with pre-defined *bundles* which aggregate related namespaces
into pre-generated bindings that allow you to use them without having to
generate and manage them yourself.  These bundles also demonstrate the
complexity of schema that PyXB is prepared to handle.  Not all namespaces
have been fully tested, but they are expected to function correctly.

Although the generating scripts and infrastructure are part of PyXB proper,
not all these bundles may have been pre-built in your PyXB distribution.
See `Generating Bundled Bindings`_ for details on building these bundles.

.. _bundle_common:

common
------

The following namespaces are available in support of general XML use:

.. PYXB_ARCHIVE_PATH=${PYXB_ROOT}/pyxb/bundles/common// ${PYXB_ROOT}/scripts/pyxbdump \
   | awk '$2~/pyxb.bundles.common/ { print $2, $1; }' \
   | sed \
      -e 's@^@``@' \
      -e 's@ @``\t``@' \
      -e 's@$@``@' \
   | expand -40 \
   | sort \
   > /tmp/x

=====================================   ==========================================================
Binding Module                          Namespace
=====================================   ==========================================================
``pyxb.bundles.common.xhtml1``          ``http://www.w3.org/1999/xhtml``
``pyxb.bundles.common.xlink``           ``http://www.w3.org/1999/xlink``
``pyxb.bundles.common.xsd_hfp``         ``http://www.w3.org/2001/XMLSchema-hasFacetAndProperty``
=====================================   ==========================================================

.. _bundle_wssplat:

WS-*
----

The following namespaces are available in support of web service
development:

.. PYXB_ARCHIVE_PATH=${PYXB_ROOT}/pyxb/bundles/wssplat// ${PYXB_ROOT}/scripts/pyxbdump \
   | awk '$2~/pyxb.bundles.wssplat/ { print $2, $1; }' \
   | sed \
      -e 's@^@``@' \
      -e 's@ @``\t``@' \
      -e 's@$@``@' \
   | expand -40 \
   | sort \
   > /tmp/x

=====================================   ==========================================================
Binding Module                          Namespace
=====================================   ==========================================================
``pyxb.bundles.wssplat.bpws``           ``http://schemas.xmlsoap.org/ws/2003/03/business-process/``
``pyxb.bundles.wssplat.ds``             ``http://www.w3.org/2000/09/xmldsig#``
``pyxb.bundles.wssplat.httpbind``       ``http://schemas.xmlsoap.org/wsdl/http/``
``pyxb.bundles.wssplat.mimebind``       ``http://schemas.xmlsoap.org/wsdl/mime/``
``pyxb.bundles.wssplat.soap11``         ``http://schemas.xmlsoap.org/soap/envelope/``
``pyxb.bundles.wssplat.soap12``         ``http://www.w3.org/2003/05/soap-envelope``
``pyxb.bundles.wssplat.soapbind11``     ``http://schemas.xmlsoap.org/wsdl/soap/``
``pyxb.bundles.wssplat.soapbind12``     ``http://schemas.xmlsoap.org/wsdl/soap12/``
``pyxb.bundles.wssplat.soapenc``        ``http://schemas.xmlsoap.org/soap/encoding/``
``pyxb.bundles.wssplat.whttp``          ``http://www.w3.org/ns/wsdl/http``
``pyxb.bundles.wssplat.wsa``            ``http://www.w3.org/2005/08/addressing``
``pyxb.bundles.wssplat.wsam``           ``http://www.w3.org/2007/02/addressing/metadata``
``pyxb.bundles.wssplat.wscoor``         ``http://docs.oasis-open.org/ws-tx/wscoor/2006/06``
``pyxb.bundles.wssplat.wsdl11``         ``http://schemas.xmlsoap.org/wsdl/``
``pyxb.bundles.wssplat.wsdl20``         ``http://www.w3.org/ns/wsdl``
``pyxb.bundles.wssplat.wsdli``          ``http://www.w3.org/ns/wsdl-instance``
``pyxb.bundles.wssplat.wsdlx``          ``http://www.w3.org/ns/wsdl-extensions``
``pyxb.bundles.wssplat.wsnt``           ``http://docs.oasis-open.org/wsn/b-2``
``pyxb.bundles.wssplat.wsoap``          ``http://www.w3.org/ns/wsdl/soap``
``pyxb.bundles.wssplat.wsp200607``      ``http://www.w3.org/2006/07/ws-policy``
``pyxb.bundles.wssplat.wsp``            ``http://www.w3.org/ns/ws-policy``
``pyxb.bundles.wssplat.wsrf_bf``        ``http://docs.oasis-open.org/wsrf/bf-2``
``pyxb.bundles.wssplat.wsrf_br``        ``http://docs.oasis-open.org/wsn/br-2``
``pyxb.bundles.wssplat.wsrm``           ``http://docs.oasis-open.org/ws-rx/wsrm/200702``
``pyxb.bundles.wssplat.wsse``           ``http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd``
``pyxb.bundles.wssplat.wstop``          ``http://docs.oasis-open.org/wsn/t-1``
``pyxb.bundles.wssplat.wsu``            ``http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd``
``pyxb.bundles.wssplat.xenc``           ``http://www.w3.org/2001/04/xmlenc#``
=====================================   ==========================================================

.. _bundle_saml20:

SAML
----

The following namespaces are available in support of the `Security Assertion
Markup Language <http://saml.xml.org/about-saml>`_:

.. PYXB_ARCHIVE_PATH=${PYXB_ROOT}/pyxb/bundles/saml20// ${PYXB_ROOT}/scripts/pyxbdump \
   | awk '$2~/pyxb.bundles.saml20/ { print $2, $1; }' \
   | sed \
      -e 's@^@``@' \
      -e 's@ @``\t``@' \
      -e 's@$@``@' \
   | expand -40 \
   | sort \
   > /tmp/x

=====================================   ==========================================================
Binding Module                          Namespace
=====================================   ==========================================================
``pyxb.bundles.saml20.assertion``       ``urn:oasis:names:tc:SAML:2.0:assertion``
``pyxb.bundles.saml20.dce``             ``urn:oasis:names:tc:SAML:2.0:profiles:attribute:DCE``
``pyxb.bundles.saml20.ecp``             ``urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp``
``pyxb.bundles.saml20.metadata``        ``urn:oasis:names:tc:SAML:2.0:metadata``
``pyxb.bundles.saml20.protocol``        ``urn:oasis:names:tc:SAML:2.0:protocol``
``pyxb.bundles.saml20.x500``            ``urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500``
``pyxb.bundles.saml20.xacml``           ``urn:oasis:names:tc:SAML:2.0:profiles:attribute:XACML``
=====================================   ==========================================================

.. _bundle_opengis:

OpenGIS
-------

The following namespaces are available in support of `Open Geospatial
Consortium <http://www.opengeospatial.org/standards>`_ Geographic
Information System processing.  Note that several of these namespaces are
"private" bindings generated because the OGC definitions include their own
schema for use local to another schema.  The modules corresponding to these
namespace uses begin with an underscore, and should generally not be used in
other contexts.

This bundle is not populated in the distributed versions of PyXB because it
requires some 168MB of space to hold the schemas, generated bindings, and
archive files.  To build it, set ``PYXB_ROOT`` environment variable to the
absolute path of the unpacked PyXB distribution (the directory containing
:file:`setup.py`) and run these commands::

  cd ${PYXB_ROOT}
  pyxb/bundles/opengis/scripts/genbind
  python setup.py install

This will download the schemas from OGC, generate bindings for the
namespaces below, and (re-)install PyXB including the new bindings.  Other
namespaces are available and can be added by modifying the ``genbind``
script and re-running the commands above.

.. PYXB_ARCHIVE_PATH=${PYXB_ROOT}/pyxb/bundles/opengis// ${PYXB_ROOT}/scripts/pyxbdump \
   | awk '$2~/pyxb.bundles.opengis/ { print $2, $1; }' \
   | sed \
      -e 's@^@``@' \
      -e 's@ @``\t``@' \
      -e 's@$@``@' \
   | expand -50 \
   | sort \
   > /tmp/x

================================================  ==========================================================
Binding Module                                    Namespace
================================================  ==========================================================
``pyxb.bundles.opengis._ogc``                     ``http://www.opengis.net/ogc``
``pyxb.bundles.opengis.atom``                     ``http://www.w3.org/2005/Atom``
``pyxb.bundles.opengis.citygml.appearance``       ``http://www.opengis.net/citygml/appearance/1.0``
``pyxb.bundles.opengis.citygml.base``             ``http://www.opengis.net/citygml/1.0``
``pyxb.bundles.opengis.citygml.building``         ``http://www.opengis.net/citygml/building/1.0``
``pyxb.bundles.opengis.citygml.cityFurniture``    ``http://www.opengis.net/citygml/cityfurniture/1.0``
``pyxb.bundles.opengis.citygml.cityObjectGroup``  ``http://www.opengis.net/citygml/cityobjectgroup/1.0``
``pyxb.bundles.opengis.citygml.generics``         ``http://www.opengis.net/citygml/generics/1.0``
``pyxb.bundles.opengis.citygml.landUse``          ``http://www.opengis.net/citygml/landuse/1.0``
``pyxb.bundles.opengis.citygml.relief``           ``http://www.opengis.net/citygml/relief/1.0``
``pyxb.bundles.opengis.citygml.texturedSurface``  ``http://www.opengis.net/citygml/texturedsurface/1.0``
``pyxb.bundles.opengis.citygml.transportation``   ``http://www.opengis.net/citygml/transportation/1.0``
``pyxb.bundles.opengis.citygml.vegetation``       ``http://www.opengis.net/citygml/vegetation/1.0``
``pyxb.bundles.opengis.citygml.waterBody``        ``http://www.opengis.net/citygml/waterbody/1.0``
``pyxb.bundles.opengis.csw_2_0_2``                ``http://www.opengis.net/cat/csw/2.0.2``
``pyxb.bundles.opengis.csw_dc``                   ``http://purl.org/dc/elements/1.1/``
``pyxb.bundles.opengis.csw_dct``                  ``http://purl.org/dc/terms/``
``pyxb.bundles.opengis.fes_2_0``                  ``http://www.opengis.net/fes/2.0``
``pyxb.bundles.opengis.filter``                   ``http://www.opengis.net/ogc``
``pyxb.bundles.opengis.gml_3_2``                  ``http://www.opengis.net/gml/3.2``
``pyxb.bundles.opengis.gml_3_3.ce``               ``http://www.opengis.net/gml/3.3/ce``
``pyxb.bundles.opengis.gml_3_3.exr``              ``http://www.opengis.net/gml/3.3/exr``
``pyxb.bundles.opengis.gml_3_3.lr``               ``http://www.opengis.net/gml/3.3/lr``
``pyxb.bundles.opengis.gml_3_3.lro``              ``http://www.opengis.net/gml/3.3/lro``
``pyxb.bundles.opengis.gml_3_3.lrov``             ``http://www.opengis.net/gml/3.3/lrov``
``pyxb.bundles.opengis.gml_3_3.lrtr``             ``http://www.opengis.net/gml/3.3/lrtr``
``pyxb.bundles.opengis.gml_3_3.rgrid``            ``http://www.opengis.net/gml/3.3/rgrid``
``pyxb.bundles.opengis.gml_3_3.tin``              ``http://www.opengis.net/gml/3.3/tin``
``pyxb.bundles.opengis.gml_3_3.xbt``              ``http://www.opengis.net/gml/3.3/xbt``
``pyxb.bundles.opengis.gml``                      ``http://www.opengis.net/gml``
``pyxb.bundles.opengis.gmlsf``                    ``http://www.opengis.net/gmlsf``
``pyxb.bundles.opengis.ic_ism_2_1``               ``urn:us:gov:ic:ism:v2``
``pyxb.bundles.opengis.iso19139.20070417.gco``    ``http://www.isotc211.org/2005/gco``
``pyxb.bundles.opengis.iso19139.20070417.gmd``    ``http://www.isotc211.org/2005/gmd``
``pyxb.bundles.opengis.iso19139.20070417.gmx``    ``http://www.isotc211.org/2005/gmx``
``pyxb.bundles.opengis.iso19139.20070417.gsr``    ``http://www.isotc211.org/2005/gsr``
``pyxb.bundles.opengis.iso19139.20070417.gss``    ``http://www.isotc211.org/2005/gss``
``pyxb.bundles.opengis.iso19139.20070417.gts``    ``http://www.isotc211.org/2005/gts``
``pyxb.bundles.opengis.misc.xAL``                 ``urn:oasis:names:tc:ciq:xsdschema:xAL:2.0``
``pyxb.bundles.opengis.misc.xlinks``              ``http://www.w3.org/1999/xlink``
``pyxb.bundles.opengis.ogckml22``                 ``http://www.opengis.net/kml/2.2``
``pyxb.bundles.opengis.om_1_0``                   ``http://www.opengis.net/om/1.0``
``pyxb.bundles.opengis.om_2_0``                   ``http://www.opengis.net/om/2.0``
``pyxb.bundles.opengis.ows_1_1``                  ``http://www.opengis.net/ows/1.1``
``pyxb.bundles.opengis.ows_2_0``                  ``http://www.opengis.net/ows/2.0``
``pyxb.bundles.opengis.ows``                      ``http://www.opengis.net/ows``
``pyxb.bundles.opengis.sampling_1_0``             ``http://www.opengis.net/sampling/1.0``
``pyxb.bundles.opengis.sensorML_1_0_1``           ``http://www.opengis.net/sensorML/1.0.1``
``pyxb.bundles.opengis.smil20``                   ``http://www.w3.org/2001/SMIL20/``
``pyxb.bundles.opengis.smil20lang``               ``http://www.w3.org/2001/SMIL20/Language``
``pyxb.bundles.opengis.sos_1_0``                  ``http://www.opengis.net/sos/1.0``
``pyxb.bundles.opengis.sos_2_0``                  ``http://www.opengis.net/sos/2.0``
``pyxb.bundles.opengis.swe_1_0_0``                ``http://www.opengis.net/swe/1.0``
``pyxb.bundles.opengis.swe_1_0_1``                ``http://www.opengis.net/swe/1.0.1``
``pyxb.bundles.opengis.swe_2_0``                  ``http://www.opengis.net/swe/2.0``
``pyxb.bundles.opengis.swes_2_0``                 ``http://www.opengis.net/swes/2.0``
``pyxb.bundles.opengis.tml``                      ``http://www.opengis.net/tml``
``pyxb.bundles.opengis.wcs_1_1``                  ``http://www.opengis.net/wcs/1.1``
``pyxb.bundles.opengis.wfs``                      ``http://www.opengis.net/wfs``
================================================  ==========================================================

.. _bundle_layout:

Layout of a Bundle Directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``pyxb/bundles`` directory contains groups of bindings for related
schema.  These groups are called "bundles", and each subdirectory represents
a particular bundle.

With a bundle directory, the following are expected:

- A ``scripts`` directory, containing an executable ``genbind`` which
  retrieves the schema and invokes ``pyxbgen`` to build the bindings

- A ``schemas`` directory, into which the ``genbind`` script stores the
  schemas that were used to build the bindings

- The Python module files for namespace modules.  Normally these are
  :ref:`customization wrappers <customized_bindings>`

- A ``raw`` subdirectory, into which the generated bindings are placed.
  This directory is normally removed and recreated as a consequence of
  running genbind; don't expect anything in it to be persistent.

- An ``examples`` directory, with programs that show how to use the
  capabilities in the bundle

- A ``tests`` directory which validates customizations

Generating Bundled Bindings
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To create the support infrastructure for a particular bundle, set the
``PYXB_ROOT`` environment variable to the root of an unpacked PyXB
distribution and run the ``scripts/genbind`` script in the bundle root.  For
example::

  cd ${PYXB_ROOT}
  pyxb/bundles/wssplat/scripts/genbind

will invoke the :manpage:`wget(1)` program to retrieve the XML schema for a
variety of namespaces related to web services and then generate bindings and
archive files for them.

Generating bundles should be a one-time action for each release of PyXB.

.. note::

   Some servers, including http://www.w3.org, enforce an artificial delay in
   retrieving schema documents in order to encourage systems to use cached
   local copies.  The :file:`genbind` infrastructure will cache the schemas
   it downloads, but running the generation scripts for the `common`_
   bundle, and possibly others, may result in errors if the caches are
   removed and the scripts run too frequently.
