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
See also
The DataONE API XML Schemas.
Although this directory is not a package, this __init__.py file is required for pytest to be able to reach test directories below this directory.
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.
See also
For remaining args, see:
DataONEException()
-
d1_common.types.exceptions.
create_exception_by_error_code
(errorCode, detailCode='0', description='', traceInformation=None, identifier=None, nodeId=None)¶ Create a DataONE Exception object by errorCode.
See Also: For args, see:
DataONEException()
-
exception
d1_common.types.exceptions.
DataONEException
(errorCode, detailCode='0', description='', traceInformation=None, identifier=None, nodeId=None)¶ Bases:
Exception
Base class for exceptions raised by DataONE.
-
__init__
(errorCode, detailCode='0', description='', traceInformation=None, identifier=None, nodeId=None)¶ Args: errorCode: int HTTP Status code for the error. E.g., NotFound is 404.
- detailCode: int
Optional index into a table of predefined error conditions.
- description: str
Optional additional information about the error, intended for users. E.g., if the error is NotFound, this may the resource that was not found.
- traceInformation: str
Optional additional information about the error, intended for developers. E.g., stack traces or source code references.
- identifier: str
Optional Persistent ID (PID) or Series ID (SID).
- nodeId: str
Optional Node Identifier URN. E.g., urn:node:MyNode
-
friendly_format
()¶ Serialize to a format more suitable for displaying to end users.
-
serialize_to_transport
(encoding='utf-8', xslt_url=None)¶ Serialize to XML
bytes
with prolog.- Parameters
encoding – str Encoding to use for XML doc bytes
xslt_url – str If specified, add a processing instruction to the XML doc that specifies the download location for an XSLT stylesheet.
- Returns
XML holding a DataONEError based type.
- Return type
bytes
-
serialize_to_display
(xslt_url=None)¶ Serialize to a pretty printed Unicode str, suitable for display.
Args: xslt_url: url Optional link to an XSLT stylesheet. If provided, a processing instruction for the stylesheet is included in the XML prolog.
-
encode
(encoding='utf-8')¶ Serialize to UTF-8 encoded XML bytes with prolog.
-
serialize_to_headers
()¶ Serialize to a dict of HTTP headers.
Used in responses to HTTP HEAD requests. As with regular HTTP GET requests, HEAD requests may return DataONE Exceptions. Since a response to a HEAD request cannot include a body, the error is returned as a set of HTTP headers instead of an XML document.
-
get_pyxb
()¶ Generate a DataONE Exception PyXB object.
The PyXB object supports directly reading and writing the individual values that may be included in a DataONE Exception.
-
property
name
¶ Returns:
str: Type name of object based on DataONEException. E.g.:
AuthenticationTimeout
.
-
-
exception
d1_common.types.exceptions.
AuthenticationTimeout
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type AuthenticationTimeout.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
IdentifierNotUnique
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type IdentifierNotUnique.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
InsufficientResources
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type InsufficientResources.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
InvalidCredentials
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type InvalidCredentials.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
InvalidRequest
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type InvalidRequest.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
InvalidSystemMetadata
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type InvalidSystemMetadata.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
InvalidToken
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type InvalidToken.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
NotAuthorized
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type NotAuthorized.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
NotFound
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type NotFound.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
NotImplemented
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type NotImplemented.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
ServiceFailure
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type ServiceFailure.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
UnsupportedMetadataType
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type UnsupportedMetadataType.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
UnsupportedType
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type UnsupportedType.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
SynchronizationFailed
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type SynchronizationFailed.
See Also:
DataONEException()
-
exception
d1_common.types.exceptions.
VersionMismatch
(detailCode, description=None, traceInformation=None, identifier=None, nodeId=None)¶ Bases:
d1_common.types.exceptions.DataONEException
DataONE Exception of type VersionMismatch.
See Also:
DataONEException()