d1_common.types package¶

DataONE API types

DataONE services use XML messaging over HTTP as the primary means of communication between service nodes and clients. The XML messages are defined by XML Schema specifications and must be valid.

This package provides serialization, deserialization and validation of DataONE API XML types, allowing developers to handle the DataONE types as native objects, reducing development time.

Implicit validation is performed whenever objects are serialized and deserialized, so that developers can assume that information that was received from a DataONE node is complete and syntactically correct before attempting to process it. Also, attempts to submit incomplete or syntactically incorrect information to a DataONE node cause local errors that are easy to debug, rather than less specific errors returned from the target node to which the incorrect types were sent.

Notes

PyXB generated classes are specific to the version of the schema and the version of PyXB installed. Hence, even though PyXB generated classes are provided with the distribution of d1_common_python, it may be necessary to regenerate the classes depending on the particular version of PyXB installed.

To regenerate the binding classes, call the genbind script:

cd to the src folder of this distribution
$ export D1COMMON_ROOT="$(pwd)"
$ bash ${D1COMMON_ROOT}/d1_common/types/scripts/genbind

Submodules¶

d1_common.types.dataoneErrors module¶

Import the PyXB binding required for handling the DataONE Exception types.

d1_common.types.dataoneTypes module¶

Combine the PyXB bindings required for handling all DataONE types.

d1_common.types.dataoneTypes_v1 module¶

Import PyXB bindings required for handling v1.0 DataONE types.

d1_common.types.dataoneTypes_v1_1 module¶

Combine all PyXB bindings required for handling DataONE types up to and including v1.1.

d1_common.types.dataoneTypes_v1_2 module¶

Combine all PyXB bindings required for handling DataONE types up to and including v1.1.

d1_common.types.dataoneTypes_v2_0 module¶

Combine the PyXB bindings required for handling all DataONE types.

d1_common.types.exceptions module¶

Native objects for holding DataONE Exceptions.

Wrap the PyXB client with Exception based classes
PyXB based XML serialization and deserialization
Add deserialize to string and HTTP headers

Notes

traceInformation:

traceInformation is an xs:anyType, meaning that is essentially the root of a new XML document of arbitrary complexity. Since the contents of the elements are unknown at the time when the PyXB binding are created, PyXB cannot automatically serialize and deserialize the traceInformation field together with the rest of the DataONEException XML type.

To make it easier to use the traceInformation element, we support a special case where it can be read and written as a single string of bytes, where the contents are application specific. Any other content must be generated and parsed as XML by the user.

Example of serialized DataONE Exception:

<error detailCode="1020" errorCode="404" name="NotFound" identifier="testpid">
<description>Attempted to perform operation on non-existing object</description>
<traceInformation>view_handler.py(128)
views.py(102)
auth.py(392)
auth.py(315)
</traceInformation>
</error>

d1_common.types.exceptions.xml_is_dataone_exception(xml_str)¶: Return True if XML doc is a valid DataONE Exception.

d1_common.types.exceptions.pyxb_is_dataone_exception(obj_pyxb)¶: Return True if PyXB object is a valid DataONE Exception.

d1_common.types.exceptions.deserialize(dataone_exception_xml)¶: Deserialize a DataONE Exception XML doc.

d1_common.types.exceptions.deserialize_from_headers(headers)¶: Deserialize a DataONE Exception that is stored in a map of HTTP headers (used in responses to HTTP HEAD requests).

d1_common.types.exceptions.create_exception_by_name(name, detailCode='0', description='', traceInformation=None, identifier=None, nodeId=None)¶

Create a DataONEException based object by name.

Parameters

name – str The type name of a DataONE Exception. E.g. NotFound.

If an unknown type name is used, it is automatically set to ServiceFailure. As the XML Schema for DataONE Exceptions does not restrict the type names, this may occur when deserializing an exception not defined by DataONE.
detailCode – int Optional index into a table of predefined error conditions.