provstore-api¶
provstore-api is a python API client for ProvStore.
Contribute¶
- Issue Tracker: GitHub issues.
- Source Code: GitHub.
API Documentation¶
provstore package¶
provstore.api module¶
- class provstore.api.Api(username=None, api_key=None, base_url=None)[source]¶
Bases: object
Main ProvStore API client object
Most functions are not used directly but are instead accessed by functions of the Document, BundleManager and Bundle objects.
- To create a new Api object:
>>> from provstore.api import Api >>> api = Api(username="provstore username", api_key="api key")
Note
The username and api_key parameters can also be omitted in which case the client will look for PROVSTORE_USERNAME and PROVSTORE_API_KEY environment variables.
- FORMAT_MAP = {'json': 'application/json'}¶
provstore.bundle module¶
- class provstore.bundle.Bundle(api, document, bundle)[source]¶
Bases: object
- created_at[source]¶
Returns: When the bundle was added Return type: datetime.datetime
- identifier[source]¶
Returns: Identifier of the document, used as index on provstore.bundle_manager.BundleManager Return type: str
- prov[source]¶
Returns: This bundle’s provenance Return type: prov.model.ProvDocument
provstore.bundle_manager module¶
- class provstore.bundle_manager.BundleManager(api, document)[source]¶
Bases: object
A document’s bundle manager.
This is an iterable and will iterate through all of a document’s bundles.
- Example getting and adding bundles:
>>> api = Api() >>> api.document.create(prov_document, name="name") >>> api.bundles A BundleManager object for this document >>> api.bundles['ex:bundle'] A Bundle with the identifier given (if exists) >>> api.bundles['ex:new_bundle'] = prov_bundle Saves a new bundle with the identifier specified
provstore.document module¶
- class provstore.document.Document(api)[source]¶
Bases: object
ProvStore Document model.
Note
This class should not be instantiated manually but should be accessed via provstore.api.Api.document() like so:
>>> from provstore.api import Api >>> api = Api() >>> api.document <provstore.document.Document at ...>
- add_bundle(prov_bundle, identifier)[source]¶
Verbose method of adding a bundle.
- Can also be done as:
>>> api = Api() >>> document = api.document.get(148) >>> document.bundles['identifier'] = prov_bundle
Parameters: - prov_bundle (prov.model.ProvDocument or str) – The bundle to be added
- identifier (str) – URI or QName for this bundle
- bundles[source]¶
Returns: This document’s bundle manager Return type: provstore.bundle_manager.BundleManager
- create(prov_document, prov_format=None, refresh=False, **props)[source]¶
Create a document on ProvStore.
Parameters: - prov_document (prov.model.ProvDocument or str) – The document to be stored
- prov_format (str or None) – The format of the document provided
- refresh (bool) – Whether or not to load back the document after saving
- props (dict) – Properties for this document [name (required), public = False]
Returns: This document itself but with a reference to the newly stored document
Return type: Raises ImmutableDocumentException: If this instance already refers to another document
- created_at[source]¶
Returns: When the document was created Return type: datetime.datetime
- delete()[source]¶
Remove the document and all of its bundles from ProvStore.
Warning
Cannot be undone.
- get(document_id)[source]¶
Associate this model with a document on ProvStore.
- Example::
>>> api = Api() >>> api.document.get(148) https://provenance.ecs.soton.ac.uk/store/api/v0/documents/148 >>> api.id 148 >>> api.name ex:bundles1-sep
Parameters: document_id – The document ID on ProvStore Returns: self
- prov[source]¶
Provenance stored for this document as prov.model.ProvDocument
- read(document_id=None)[source]¶
Load the document contents and metadata from the server.
- The following are equivalent::
>>> api = Api() >>> api.set(148).read() >>> api.get(148)
Parameters: document_id – (optional) Set the document ID if this is an abstract document. Returns: self
- read_meta(document_id=None)[source]¶
Load metadata associated with the document
Note
This method is called automatically if needed when a property is first accessed. You will not normally have to use this method manually.
Parameters: document_id – (optional) set the document id if this is an abstract() document Returns: self
- read_prov(document_id=None)[source]¶
Load the provenance of this document
Note
This method is called automatically if needed when the prov() property is accessed. Manual use of this method is unusual.
Parameters: document_id – (optional) set the document id if this is an abstract() document Returns: :py:class:`prov.model.ProvDocument
- save(prov_document, prov_format=None, refresh=False, **props)¶
Create a document on ProvStore.
Parameters: - prov_document (prov.model.ProvDocument or str) – The document to be stored
- prov_format (str or None) – The format of the document provided
- refresh (bool) – Whether or not to load back the document after saving
- props (dict) – Properties for this document [name (required), public = False]
Returns: This document itself but with a reference to the newly stored document
Return type: Raises ImmutableDocumentException: If this instance already refers to another document
- set(document_id)[source]¶
Associate this document with a ProvStore document without making any calls to the API. :param int document_id: ID of the document on ProvStore :return: self