# prov package

## Subpackages

- prov.serializers package
  - Module contents
  - prov.serializers.provjson module
  - prov.serializers.provn module
  - prov.serializers.provrdf module
  - prov.serializers.provxml module

## Submodules

## prov.constants module

## prov.dot module

Graphical visualisation support for prov.model.

This module produces graphical visualisation for provenanve graphs. Requires pydotplus module and Graphviz.

References:

- pydotplus homepage: http://pydotplus.readthedocs.io/
- Graphviz: http://www.graphviz.org/
- DOT Language: http://www.graphviz.org/doc/info/lang.html

`prov.dot.``htlm_link_if_uri`(value)

`prov.dot.``prov_to_dot`(bundle, show_nary=True, use_labels=False, direction='BT', show_element_attributes=True, show_relation_attributes=True)

  Convert a provenance bundle/document into a DOT graphical representation.

  Parameters:

  - bundle – The provenance bundle/document to be converted.
  - show_nary (bool) – shows all elements in n-ary relations.
  - use_labels (bool) – uses the prov:label property of an element as its name (instead of its identifier).
  - direction – specifies the direction of the graph. Valid values are “BT” (default), “TB”, “LR”, “RL”.
  - show_element_attributes (bool) – shows attributes of elements.
  - show_relation_attributes (bool) – shows attributes of relations.

  Returns: | `pydot.Dot` – the Dot object.

## prov.graph module

`prov.graph.``graph_to_prov`(g)

  Convert a MultiDiGraph back to a `ProvDocument`.

  Parameters: | g – The graph instance to convert.

`prov.graph.``prov_to_graph`(prov_document)

  Convert a `ProvDocument` to a MultiDiGraph instance of the NetworkX library.

  Parameters: | prov_document – The `ProvDocument` instance to convert.

## prov.identifier module

class `prov.identifier.``Identifier`(uri)

  Bases: `object`

  Base class for all identifiers and also represents xsd:anyURI

  `provn_representation`()
  `uri`

class `prov.identifier.``Namespace`(prefix, uri)

  Bases: `object`

  `contains`(identifier)
  `prefix`
  `qname`(identifier)
  `uri`

class `prov.identifier.``QualifiedName`(namespace, localpart)

  Bases: `prov.identifier.Identifier`

  `localpart`
  `namespace`
  `provn_representation`()

## prov.model module

Python implementation of the W3C Provenance Data Model (PROV-DM), including support for PROV-JSON import/export

References:

PROV-DM: http://www.w3.org/TR/prov-dm/ PROV-JSON: https://provenance.ecs.soton.ac.uk/prov-json/

class `prov.model.``Literal`(value, datatype=None, langtag=None)

  Bases: `object`

  `datatype`
  `has_no_langtag`()
  `langtag`
  `provn_representation`()
  `value`

class `prov.model.``NamespaceManager`(namespaces=None, default=None, parent=None)

  Bases: `dict`

  `add_namespace`(namespace)
  `add_namespaces`(namespaces)

    Add multiple namespaces into this manager

    Parameters: | namespaces (list of `Namespace` or) – a collection of namespace(s) to add.

    dict of {prefix: uri} :returns: None

  `get_anonymous_identifier`(local_prefix='id')
  `get_default_namespace`()
  `get_namespace`(uri)
  `get_registered_namespaces`()
  `set_default_namespace`(uri)
  `valid_qualified_name`(qname)

class `prov.model.``ProvActivity`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvElement`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:startTime>, <QualifiedName: prov:endTime>)
  `get_endTime`()
  `get_startTime`()
  `get_type`()
  `set_time`(startTime=None, endTime=None)
  `used`(entity, time=None, attributes=None)
  `wasAssociatedWith`(agent, plan=None, attributes=None)
  `wasEndedBy`(trigger, ender=None, time=None, attributes=None)
  `wasInformedBy`(informant, attributes=None)
  `wasStartedBy`(trigger, starter=None, time=None, attributes=None)

class `prov.model.``ProvAgent`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvElement`

  `actedOnBehalfOf`(responsible, activity=None, attributes=None)
  `get_type`()

class `prov.model.``ProvAlternate`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:alternate1>, <QualifiedName: prov:alternate2>)
  `get_type`()

class `prov.model.``ProvAssociation`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:activity>, <QualifiedName: prov:agent>, <QualifiedName: prov:plan>)
  `get_type`()

class `prov.model.``ProvAttribution`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:entity>, <QualifiedName: prov:agent>)
  `get_type`()

class `prov.model.``ProvBundle`(records=None, identifier=None, namespaces=None, document=None)

  Bases: `object`

  `actedOnBehalfOf`(delegate, responsible, activity=None, identifier=None, other_attributes=None)
  `activity`(identifier, startTime=None, endTime=None, other_attributes=None)
  `add_namespace`(namespace_or_prefix, uri=None)
  `add_record`(record)
  `agent`(identifier, other_attributes=None)
  `alternate`(alternate1, alternate2)
  `alternateOf`(alternate1, alternate2)
  `association`(activity, agent=None, plan=None, identifier=None, other_attributes=None)
  `attribution`(entity, agent, identifier=None, other_attributes=None)
  `bundles`
  `collection`(identifier, other_attributes=None)
  `communication`(informed, informant, identifier=None, other_attributes=None)
  `default_ns_uri`

    Returns the default namespace’s URI, if any

  `delegation`(delegate, responsible, activity=None, identifier=None, other_attributes=None)
  `derivation`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `document`

    Returns the parent document, if any

  `end`(activity, trigger=None, ender=None, time=None, identifier=None, other_attributes=None)
  `entity`(identifier, other_attributes=None)
  `generation`(entity, activity=None, time=None, identifier=None, other_attributes=None)
  `get_default_namespace`()
  `get_provn`(_indent_level=0)
  `get_record`(identifier)
  `get_records`(class_or_type_or_tuple=None)
  `get_registered_namespaces`()
  `hadMember`(collection, entity)
  `hadPrimarySource`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `has_bundles`()
  `identifier`

    Returns the bundle’s identifier

  `influence`(influencee, influencer, identifier=None, other_attributes=None)
  `invalidation`(entity, activity=None, time=None, identifier=None, other_attributes=None)
  `is_bundle`()
  `is_document`()
  `membership`(collection, entity)
  `mention`(specificEntity, generalEntity, bundle)
  `mentionOf`(specificEntity, generalEntity, bundle)
  `namespaces`

    Returns the set of registered namespaces

  `new_record`(record_type, identifier, attributes=None, other_attributes=None)
  `plot`(filename=None, show_nary=True, use_labels=False, show_element_attributes=True, show_relation_attributes=True)

    Convenience function to plot a prov document.

    Parameters:

    - filename (string, optional) – The filename to save to. If not given, it will open an interactive matplotlib plot. The filetype is determined from the filename ending.
    - show_nary (bool) – shows all elements in n-ary relations.
    - use_labels – uses the prov:label property of an element as its

    name (instead of its identifier). :type use_labels: bool :param show_element_attributes: shows attributes of elements. :type show_element_attributes: bool :param show_relation_attributes: shows attributes of relations. :type show_relation_attributes: bool

  `primary_source`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `quotation`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `records`

    Returns the list of all records in the current bundle

  `revision`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `set_default_namespace`(uri)
  `specialization`(specificEntity, generalEntity)
  `specializationOf`(specificEntity, generalEntity)
  `start`(activity, trigger=None, starter=None, time=None, identifier=None, other_attributes=None)
  `unified`()

    Unifies all records in the bundle that haves same identifiers

    Returns: | `ProvBundle` – the new unified bundle.

  `update`(other)

    Append all the records of the other ProvBundle into this bundle.

    Parameters: | other (`ProvBundle`) – the other bundle whose records to be appended.
    Returns: | None.

  `usage`(activity, entity=None, time=None, identifier=None, other_attributes=None)
  `used`(activity, entity=None, time=None, identifier=None, other_attributes=None)
  `valid_qualified_name`(identifier)
  `wasAssociatedWith`(activity, agent=None, plan=None, identifier=None, other_attributes=None)
  `wasAttributedTo`(entity, agent, identifier=None, other_attributes=None)
  `wasDerivedFrom`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `wasEndedBy`(activity, trigger=None, ender=None, time=None, identifier=None, other_attributes=None)
  `wasGeneratedBy`(entity, activity=None, time=None, identifier=None, other_attributes=None)
  `wasInfluencedBy`(influencee, influencer, identifier=None, other_attributes=None)
  `wasInformedBy`(informed, informant, identifier=None, other_attributes=None)
  `wasInvalidatedBy`(entity, activity=None, time=None, identifier=None, other_attributes=None)
  `wasQuotedFrom`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `wasRevisionOf`(generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None)
  `wasStartedBy`(activity, trigger=None, starter=None, time=None, identifier=None, other_attributes=None)

class `prov.model.``ProvCommunication`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:informed>, <QualifiedName: prov:informant>)
  `get_type`()

class `prov.model.``ProvDelegation`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:delegate>, <QualifiedName: prov:responsible>, <QualifiedName: prov:activity>)
  `get_type`()

class `prov.model.``ProvDerivation`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:generatedEntity>, <QualifiedName: prov:usedEntity>, <QualifiedName: prov:activity>, <QualifiedName: prov:generation>, <QualifiedName: prov:usage>)
  `get_type`()

class `prov.model.``ProvDocument`(records=None, namespaces=None)

  Bases: `prov.model.ProvBundle`

  `add_bundle`(bundle, identifier=None)

    Add a bundle to the current document

  `bundle`(identifier)
  `bundles`
  static `deserialize`(source=None, content=None, format='json', **args)

    Deserialize the `ProvDocument` from source (a stream or a filepath) or directly from a string content

    Format defaults to PROV-JSON.

  `flattened`()

    Flattens the document by moving all the records in its bundles up to the document level.

    Returns: | `ProvDocument` – the (new) flattened document.

  `has_bundles`()
  `is_bundle`()
  `is_document`()
  `serialize`(destination=None, format='json', **args)

    Serialize the `ProvDocument` to destination

    If destination is None serialize method returns the serialization as a string. Format defaults to PROV-JSON.

  `unified`()

    Returns a new document containing all records having same identifiers unified (including those inside bundles)

  `update`(other)

    Append all the records of the other document/bundle into this document. Bundles having same identifiers will be merged.

    Parameters: | other (`ProvDocument` or `ProvBundle`) – the other document/bundle whose records to be appended.
    Returns: | None.

class `prov.model.``ProvElement`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRecord`

  `is_element`()

exception `prov.model.``ProvElementIdentifierRequired`

  Bases: `prov.model.ProvException`

class `prov.model.``ProvEnd`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:activity>, <QualifiedName: prov:trigger>, <QualifiedName: prov:ender>, <QualifiedName: prov:time>)
  `get_type`()

class `prov.model.``ProvEntity`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvElement`

  `alternateOf`(alternate2)
  `get_type`()
  `hadMember`(entity)
  `specializationOf`(generalEntity)
  `wasAttributedTo`(agent, attributes=None)
  `wasDerivedFrom`(usedEntity, activity=None, generation=None, usage=None, attributes=None)
  `wasGeneratedBy`(activity, time=None, attributes=None)
  `wasInvalidatedBy`(activity, time=None, attributes=None)

exception `prov.model.``ProvException`

  Bases: `prov.Error`

  Base class for PROV model exceptions.

exception `prov.model.``ProvExceptionInvalidQualifiedName`(qname)

  Bases: `prov.model.ProvException`

class `prov.model.``ProvGeneration`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:entity>, <QualifiedName: prov:activity>, <QualifiedName: prov:time>)
  `get_type`()

class `prov.model.``ProvInfluence`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:influencee>, <QualifiedName: prov:influencer>)
  `get_type`()

class `prov.model.``ProvInvalidation`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:entity>, <QualifiedName: prov:activity>, <QualifiedName: prov:time>)
  `get_type`()

class `prov.model.``ProvMembership`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:collection>, <QualifiedName: prov:entity>)
  `get_type`()

class `prov.model.``ProvMention`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvSpecialization`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:specificEntity>, <QualifiedName: prov:generalEntity>, <QualifiedName: prov:bundle>)
  `get_type`()

class `prov.model.``ProvRecord`(bundle, identifier, attributes=None)

  Bases: `object`

  Base class for PROV records.

  `FORMAL_ATTRIBUTES` = ()
  `add_asserted_type`(type_identifier)
  `add_attributes`(attributes)
  `args`
  `attributes`
  `bundle`
  `copy`()

    Return an exact copy of this record.

  `extra_attributes`
  `formal_attributes`
  `get_asserted_types`()
  `get_attribute`(attr_name)
  `get_provn`()
  `get_type`()

    Returning the PROV type of the record

  `identifier`
  `is_element`()
  `is_relation`()
  `label`
  `value`

class `prov.model.``ProvRelation`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRecord`

  `is_relation`()

class `prov.model.``ProvSpecialization`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:specificEntity>, <QualifiedName: prov:generalEntity>)
  `get_type`()

class `prov.model.``ProvStart`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:activity>, <QualifiedName: prov:trigger>, <QualifiedName: prov:starter>, <QualifiedName: prov:time>)
  `get_type`()

class `prov.model.``ProvUsage`(bundle, identifier, attributes=None)

  Bases: `prov.model.ProvRelation`

  `FORMAL_ATTRIBUTES` = (<QualifiedName: prov:activity>, <QualifiedName: prov:entity>, <QualifiedName: prov:time>)
  `get_type`()

exception `prov.model.``ProvWarning`

  Bases: `Warning`

  Base class for PROV model warnings.

`prov.model.``encoding_provn_value`(value)

`prov.model.``first`(a_set)

`prov.model.``parse_boolean`(value)

`prov.model.``parse_xsd_datetime`(value)

`prov.model.``parse_xsd_types`(value, datatype)

`prov.model.``sorted_attributes`(element, attributes)

  Helper function sorting attributes into the order required by PROV-XML.

  Parameters:

  - element – The prov element used to derive the type and the attribute order for the type.
  - attributes – The attributes to sort.

## Module contents

exception `prov.``Error`

  Bases: `Exception`

  Base class for all errors in this package.

`prov.``read`(source, format=None)

  Convenience function returning a ProvDocument instance.

  It does a lazy format detection by simply using try/except for all known formats. The deserializers should fail fairly early when data of the wrong type is passed to them thus the try/except is likely cheap. One could of course also do some more advanced format auto-detection but I am not sure that is necessary.

  The downside is that no proper error messages will be produced, use the format parameter to get the actual traceback.