prov package

Subpackages

prov.serializers package

Submodules

prov.constants module

prov.dot module

Graphical visualisation support for prov.model.

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

References:

pydot homepage: https://github.com/erocarrera/pydot
Graphviz: http://www.graphviz.org/
DOT Language: http://www.graphviz.org/doc/info/lang.html

prov.dot.htlm_link_if_uri(value: Any) → str[source]

prov.dot.prov_to_dot(bundle: ProvBundle, show_nary: bool = True, use_labels: bool = False, direction: str = 'BT', show_element_attributes: bool = True, show_relation_attributes: bool = True) → Dot[source]

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

Parameters:

bundle (ProvBundle) – 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: MultiDiGraph) → ProvDocument[source]

Convert a MultiDiGraph that was previously produced by prov_to_graph() back to a ProvDocument.

Parameters:: g – The graph instance to convert.

prov.graph.prov_to_graph(prov_document: ProvDocument) → MultiDiGraph[source]

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: str)[source]

Bases: object

Base class for all identifiers and also represents xsd:anyURI.

provn_representation() → str[source]

Returns the PROV-N representation of the URI.

Returns:: str: The PROV-N representation of the URI.

property uri: str

Returns the URI associated with the current identifier.

Returns:: str: The URI representing the resource identifier.

class prov.identifier.Namespace(prefix: str, uri: str)[source]

Bases: object

PROV Namespace.

contains(identifier: Identifier) → bool[source]

Indicates whether the identifier provided is contained in this namespace.

Parameters:: identifier – Identifier to check.
Returns:: bool

property prefix: str: Namespace prefix.

qname(identifier: str | Identifier) → QualifiedName | None[source]

Returns the qualified name of the identifier given using the namespace prefix.

Parameters:: identifier – Identifier to resolve to a qualified name.
Returns:: QualifiedName

property uri: str: Namespace URI.

class prov.identifier.QualifiedName(namespace: Namespace, localpart: str)[source]

Bases: Identifier

Represents a qualified name, which combines a namespace and a local part for use in identifying entities in a namespace-aware context.

This class facilitates handling and manipulation of qualified names, which combine a namespace and a local identifier. It supports string representation, hashing, and retrieval of individual components (namespace or local part).

property localpart: str: Local part of qualified name.

property namespace: Namespace: Namespace of qualified name.

provn_representation() → str[source]: PROV-N representation of qualified name in a string.

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://openprovenance.org/prov-json/

class prov.model.Literal(value: Any, datatype: QualifiedName | None = None, langtag: str | None = None)[source]

Bases: object

property datatype: QualifiedName | None

has_no_langtag() → bool[source]

property langtag: str | None

provn_representation() → str[source]

property value: str

class prov.model.NamespaceManager(namespaces: dict[str, str] | Iterable[Namespace] | None = None, default: str | None = None, parent: NamespaceManager | None = None)[source]

Bases: dict

Manages namespaces for PROV documents and bundles.

add_namespace(namespace: Namespace) → Namespace[source]

Adds a namespace (if not available, yet).

Parameters:: namespace – Namespace to add.

add_namespaces(namespaces: dict[str, str] | Iterable[Namespace]) → None[source]

Add multiple namespaces into this manager.

Parameters:: namespaces (List of Namespace or dict of {prefix: uri}.) – A collection of namespace(s) to add.
Returns:: None

get_anonymous_identifier(local_prefix: str = 'id') → Identifier[source]

Returns an anonymous identifier (without a namespace prefix).

Parameters:: local_prefix – Optional local namespace prefix as a string (default: ‘id’).
Returns:: Identifier

get_default_namespace() → Namespace | None[source]

Returns the default namespace.

Returns:: Namespace

get_namespace(uri: str) → Namespace | None[source]

Returns the namespace prefix for the given URI.

Parameters:: uri – Namespace URI.
Returns:: Namespace.

get_registered_namespaces() → Iterable[Namespace][source]

Returns all registered namespaces.

Returns:: Iterable of Namespace.

parent: NamespaceManager | None = None: Parent NamespaceManager this manager one is a child of.

set_default_namespace(uri: str) → None[source]

Sets the default namespace to the one of a given URI.

Parameters:: uri – Namespace URI.

valid_qualified_name(qname: QualifiedName | str | Identifier) → QualifiedName | None[source]

Resolves an identifier to a valid qualified name.

Parameters:: qname – Qualified name as QualifiedName or a tuple (namespace, identifier).
Returns:: QualifiedName or None in case of failure.

Bases: ProvElement

Provenance Activity element.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:startTime>, <QualifiedName: prov:endTime>): Formal attributes names of this record type, in the expected order.

get_endTime() → datetime | None[source]

Returns the time the activity ended.

Returns:: datetime.datetime

get_startTime() → datetime | None[source]

Returns the time the activity started.

Returns:: datetime.datetime

set_time(startTime: datetime | None = None, endTime: datetime | None = None) → None[source]

Sets the time this activity took place.

Parameters:

startTime – Start time for the activity. Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
endTime – Start time for the activity. Either a datetime.datetime object or a string that can be parsed by dateutil.parser().

Creates a new usage record for this activity.

Parameters:

entity – Entity or string identifier of the entity involved in the usage relationship (default: None).
time – Optional time for the usage (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new association record for this activity.

Parameters:

agent – Agent or string identifier of the agent involved in the association (default: None).
plan – Optionally extra entity to state qualified association through an internal plan (default: None).
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new end record for this activity.

Parameters:

trigger – Entity triggering the end of this activity.
ender – Optionally extra activity to state a qualified end through which the trigger entity for the end is generated (default: None).
time – Optional time for the end (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new communication record for this activity.

Parameters:

informant – The informing activity (relationship source).
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new start record for this activity. The activity did not exist before the start by the trigger.

Parameters:

trigger – Entity triggering the start of this activity.
starter – Optional extra activity to state a qualified start through which the trigger entity for the start is generated (default: None).
time – Optional time for the start (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Bases: ProvElement

Provenance Agent element.

Creates a new delegation record on behalf of this agent.

Parameters:

responsible – Agent the responsibility is delegated to.
activity – Optionally extra activity to state qualified delegation internally (default: None).
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Bases: ProvRelation

Provenance Alternate relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:alternate1>, <QualifiedName: prov:alternate2>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Association relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:activity>, <QualifiedName: prov:agent>, <QualifiedName: prov:plan>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Attribution relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:entity>, <QualifiedName: prov:agent>): Formal attributes names of this record type, in the expected order.

Bases: object

PROV Bundle

Creates a new delegation record on behalf of an agent.

Parameters:

delegate – Agent delegating the responsibility (relationship source).
responsible – Agent the responsibility is delegated to (relationship destination).
activity – Optionally extra activity to state qualified delegation internally (default: None).
identifier – Identifier for new association record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new activity.

Parameters:

identifier – Identifier for new activity.
startTime – Optional start time for the activity (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
endTime – Optional start time for the activity (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

add_namespace(namespace_or_prefix: Namespace | str, uri: str | None = None) → Namespace[source]

Adds a namespace (if not available, yet).

Parameters:

namespace_or_prefix – Namespace or its prefix as a string to add.
uri – Namespace URI (default: None). Must be present if only a prefix is given in the previous parameter.

add_record(record: ProvRecord) → ProvRecord[source]

Adds a new record that to the bundle.

Parameters:: record – ProvRecord to be added.

Creates a new agent.

Parameters:

identifier – Identifier for new agent.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new alternate record between two entities.

Parameters:

alternate1 – Entity or a string identifier for the first entity (relationship source).
alternate2 – Entity or a string identifier for the second entity (relationship destination).

Creates a new alternate record between two entities.

Parameters:

alternate1 – Entity or a string identifier for the first entity (relationship source).
alternate2 – Entity or a string identifier for the second entity (relationship destination).

Creates a new association record for an activity.

Parameters:

activity – Activity or a string identifier for the activity.
agent – Agent or string identifier of the agent involved in the association (default: None).
plan – Optionally extra entity to state qualified association through an internal plan (default: None).
identifier – Identifier for new association record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new attribution record between an entity and an agent.

Parameters:

entity – Entity or a string identifier for the entity (relationship source).
agent – Agent or string identifier of the agent involved in the attribution (relationship destination).
identifier – Identifier for new attribution record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

property bundles: Iterable[ProvBundle]

Returns bundles contained in the document

Returns:: Iterable of ProvBundle.

Creates a new collection record for a particular record.

Parameters:

identifier – Identifier for new collection record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new communication record for an entity.

Parameters:

informed – The informed activity (relationship destination).
informant – The informing activity (relationship source).
identifier – Identifier for new communication record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

property default_ns_uri: str | None

Returns the default namespace’s URI, if any.

Returns:: URI as string.

Creates a new delegation record on behalf of an agent.

Parameters:

delegate – Agent delegating the responsibility (relationship source).
responsible – Agent the responsibility is delegated to (relationship destination).
activity – Optionally extra activity to state qualified delegation internally (default: None).
identifier – Identifier for new association record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new derivation record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the derivation (default: None).
generation – Optionally extra activity to state qualified generation through a generation (default: None).
usage – XXX (default: None).
identifier – Identifier for new derivation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

property document: ProvDocument | None

Returns the parent document, if any.

Returns:: ProvDocument.

Creates a new end record for an activity.

Parameters:

activity – Activity or a string identifier for the entity.
trigger – trigger: Entity triggering the end of this activity.
ender – Optionally extra activity to state a qualified end through which the trigger entity for the end is generated (default: None).
time – Optional time for the end (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new end record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new entity.

Parameters:

identifier – Identifier for new entity.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new generation record for an entity.

Parameters:

entity – Entity or a string identifier for the entity.
activity – Activity or string identifier of the activity involved in the generation (default: None).
time – Optional time for the generation (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new generation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

get_default_namespace() → Namespace | None[source]

Returns the default namespace.

Returns:: Namespace

get_provn(_indent_level: int = 0) → str[source]

Returns the PROV-N representation of the bundle.

Returns:: String

get_record(identifier: QualifiedName | str | Identifier) → list[ProvRecord][source]

Returns one or more records matching a given identifier.

Parameters:: identifier – Record identifier.
Returns:: List of ProvRecord

get_records(class_or_type_or_tuple: type | tuple[type] | None = None) → Iterable[ProvRecord][source]

Returns all records. Returned records may be filtered by the optional argument.

Parameters:: class_or_type_or_tuple – A filter on the type for which records are to be returned (default: None). The filter checks by the type of the record using the isinstance check on the record.
Returns:: List of ProvRecord objects.

get_registered_namespaces() → Iterable[Namespace][source]

Returns all registered namespaces.

Returns:: Iterable of Namespace.

Creates a new membership record for an entity to a collection.

Parameters:

collection – Collection the entity is to be added to.
entity – Entity to be added to the collection.

Creates a new primary source record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the primary source (default: None).
generation – Optionally to state qualified primary source through a generation activity (default: None).
usage – XXX (default: None).
identifier – Identifier for new primary source record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

has_bundles() → bool[source]

True if the object has at least one bundle, False otherwise.

Returns:: bool

property identifier: QualifiedName | None: Returns the bundle’s identifier

Creates a new influence record between two entities, activities or agents.

Parameters:

influencee – Influenced entity, activity or agent (relationship source).
influencer – Influencing entity, activity or agent (relationship destination).
identifier – Identifier for new influence record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new invalidation record for an entity.

Parameters:

entity – Entity or a string identifier for the entity.
activity – Activity or string identifier of the activity involved in the invalidation (default: None).
time – Optional time for the invalidation (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for the new invalidation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

is_bundle() → bool[source]

True if the object is a bundle, False otherwise.

Returns:: bool

is_document() → bool[source]

True if the object is a document, False otherwise.

Returns:: bool

mandatory_valid_qname(identifier: QualifiedName | str | Identifier) → QualifiedName[source]: Determines if the given identifier is a valid qualified name and returns it. If the provided identifier is not valid, an exception is raised.

Creates a new membership record for an entity to a collection.

Parameters:

collection – Collection the entity is to be added to.
entity – Entity to be added to the collection.

Creates a new mention record for a specific from a general entity.

Parameters:

specificEntity – Entity or a string identifier for the specific entity (relationship source).
generalEntity – Entity or a string identifier for the general entity (relationship destination).
bundle – XXX

Creates a new mention record for a specific from a general entity.

Parameters:

specificEntity – Entity or a string identifier for the specific entity (relationship source).
generalEntity – Entity or a string identifier for the general entity (relationship destination).
bundle – XXX

property namespaces: set[Namespace]

Returns the set of registered namespaces.

Returns:: Set of Namespace.

Creates a new record.

Parameters:

record_type – Type of record (one of PROV_REC_CLS).
identifier – Identifier for new record.
attributes – Attributes as a dictionary or list of tuples to be added to the record optionally (default: None).
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

plot(filename: str | bytes | PathLike | None = None, show_nary: bool = True, use_labels: bool = False, show_element_attributes: bool = True, show_relation_attributes: bool = True) → None[source]

Convenience function to plot a PROV document.

Parameters:

filename (String) – 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 (bool) – Uses the prov:label property of an element as its name (instead of its identifier).
show_element_attributes (bool) – Shows attributes of elements.
show_relation_attributes (bool) – Shows attributes of relations.

Creates a new primary source record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the primary source (default: None).
generation – Optionally to state qualified primary source through a generation activity (default: None).
usage – XXX (default: None).
identifier – Identifier for new primary source record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new quotation record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the quotation (default: None).
generation – Optionally to state qualified quotation through a generation activity (default: None).
usage – XXX (default: None).
identifier – Identifier for new quotation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

property records: list[ProvRecord]: Returns the list of all records in the current bundle

Creates a new revision record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the revision (default: None).
generation – Optionally to state qualified revision through a generation activity (default: None).
usage – XXX (default: None).
identifier – Identifier for new revision record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

set_default_namespace(uri: str) → None[source]

Sets the default namespace through a given URI.

Parameters:: uri – Namespace URI.

Creates a new specialisation record for a specific from a general entity.

Parameters:

specificEntity – Entity or a string identifier for the specific entity (relationship source).
generalEntity – Entity or a string identifier for the general entity (relationship destination).

Creates a new specialisation record for a specific from a general entity.

Parameters:

specificEntity – Entity or a string identifier for the specific entity (relationship source).
generalEntity – Entity or a string identifier for the general entity (relationship destination).

Creates a new start record for an activity.

Parameters:

activity – Activity or a string identifier for the entity.
trigger – Entity triggering the start of this activity.
starter – Optionally extra activity to state a qualified start through which the trigger entity for the start is generated (default: None).
time – Optional time for the start (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new start record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

unified() → ProvBundle[source]

Unifies all records in the bundle that haves same identifiers

Returns:: ProvBundle – the new unified bundle.

update(other: ProvBundle) → None[source]

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

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

Creates a new usage record for an activity.

Parameters:

activity – Activity or a string identifier for the entity.
entity – Entity or string identifier of the entity involved in the usage relationship (default: None).
time – Optional time for the usage (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new usage record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new usage record for an activity.

Parameters:

activity – Activity or a string identifier for the entity.
entity – Entity or string identifier of the entity involved in the usage relationship (default: None).
time – Optional time for the usage (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new usage record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

valid_qualified_name(identifier: QualifiedName | str | Identifier) → QualifiedName | None[source]

Creates a new association record for an activity.

Parameters:

activity – Activity or a string identifier for the activity.
agent – Agent or string identifier of the agent involved in the association (default: None).
plan – Optionally extra entity to state qualified association through an internal plan (default: None).
identifier – Identifier for new association record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new attribution record between an entity and an agent.

Parameters:

entity – Entity or a string identifier for the entity (relationship source).
agent – Agent or string identifier of the agent involved in the attribution (relationship destination).
identifier – Identifier for new attribution record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new derivation record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the derivation (default: None).
generation – Optionally extra activity to state qualified generation through a generation (default: None).
usage – XXX (default: None).
identifier – Identifier for new derivation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new end record for an activity.

Parameters:

activity – Activity or a string identifier for the entity.
trigger – trigger: Entity triggering the end of this activity.
ender – Optionally extra activity to state a qualified end through which the trigger entity for the end is generated (default: None).
time – Optional time for the end (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new end record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new generation record for an entity.

Parameters:

entity – Entity or a string identifier for the entity.
activity – Activity or string identifier of the activity involved in the generation (default: None).
time – Optional time for the generation (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new generation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new influence record between two entities, activities or agents.

Parameters:

influencee – Influenced entity, activity or agent (relationship source).
influencer – Influencing entity, activity or agent (relationship destination).
identifier – Identifier for new influence record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new communication record for an entity.

Parameters:

informed – The informed activity (relationship destination).
informant – The informing activity (relationship source).
identifier – Identifier for new communication record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new invalidation record for an entity.

Parameters:

entity – Entity or a string identifier for the entity.
activity – Activity or string identifier of the activity involved in the invalidation (default: None).
time – Optional time for the invalidation (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for the new invalidation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new quotation record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the quotation (default: None).
generation – Optionally to state qualified quotation through a generation activity (default: None).
usage – XXX (default: None).
identifier – Identifier for new quotation record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new revision record for a generated entity from a used entity.

Parameters:

generatedEntity – Entity or a string identifier for the generated entity (relationship source).
usedEntity – Entity or a string identifier for the used entity (relationship destination).
activity – Activity or string identifier of the activity involved in the revision (default: None).
generation – Optionally to state qualified revision through a generation activity (default: None).
usage – XXX (default: None).
identifier – Identifier for new revision record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new start record for an activity.

Parameters:

activity – Activity or a string identifier for the entity.
trigger – Entity triggering the start of this activity.
starter – Optionally extra activity to state a qualified start through which the trigger entity for the start is generated (default: None).
time – Optional time for the start (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
identifier – Identifier for new start record.
other_attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Bases: ProvRelation

Provenance Communication relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:informed>, <QualifiedName: prov:informant>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Delegation relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:delegate>, <QualifiedName: prov:responsible>, <QualifiedName: prov:activity>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Derivation relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:generatedEntity>, <QualifiedName: prov:usedEntity>, <QualifiedName: prov:activity>, <QualifiedName: prov:generation>, <QualifiedName: prov:usage>): Formal attributes names of this record type, in the expected order.

class prov.model.ProvDocument(records: Iterable[ProvRecord] | None = None, namespaces: dict[str, str] | Iterable[Namespace] | None = None)[source]

Bases: ProvBundle

Provenance Document.

add_bundle(bundle: ProvBundle, identifier: QualifiedName | None = None) → None[source]

Add a bundle to the current document.

Parameters:

bundle (ProvBundle) – The bundle to add to the document.
identifier – The (optional) identifier to use for the bundle (default: None). If none given, use the identifier from the bundle itself.

bundle(identifier: QualifiedName | str | Identifier) → ProvBundle[source]

Returns a new bundle from the current document.

Parameters:: identifier – The identifier to use for the bundle.
Returns:: ProvBundle

property bundles: Iterable[ProvBundle]

Returns bundles contained in the document

Returns:: Iterable of ProvBundle.

Deserialize the ProvDocument from source (a stream or a file path) or directly from a string content.

Available serializers can be queried by the value of :py:attr:~prov.serializers.Registry.serializers after loading them via :py:func:~prov.serializers.Registry.load_serializers().

Note: Not all serializers support deserialization.

Parameters:

source – Stream object to deserialize the PROV document from (default: None).
content – String to deserialize the PROV document from (default: None).
format – Serialization format (default: ‘json’), defaulting to PROV-JSON.

Returns:

ProvDocument

flattened() → ProvDocument[source]

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

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

has_bundles() → bool[source]

True if the object has at least one bundle, False otherwise.

Returns:: bool

is_bundle() → bool[source]

True if the object is a bundle, False otherwise.

Returns:: bool

is_document() → bool[source]

True if the object is a document, False otherwise.

Returns:: bool

Serialize the ProvDocument to the destination.

Available serializers can be queried by the value of :py:attr:~prov.serializers.Registry.serializers after loading them via :py:func:~prov.serializers.Registry.load_serializers().

Parameters:

destination – Stream object to serialize the output to. Default is None, which serializes as a string.
format – Serialization format (default: ‘json’), defaulting to PROV-JSON.

Returns:

Serialization in a string if no destination was given, None otherwise.

unified() → ProvDocument[source]

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

Returns:: ProvDocument

update(other: ProvBundle) → None[source]

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

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

Bases: ProvRecord

Provenance Element (nodes in the provenance graph).

is_element() → bool[source]

True, if the record is an element, False otherwise.

Returns:: bool

exception prov.model.ProvElementIdentifierRequired[source]

Bases: ProvException

Exception for a missing element identifier.

Bases: ProvRelation

Provenance End relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:activity>, <QualifiedName: prov:trigger>, <QualifiedName: prov:ender>, <QualifiedName: prov:time>): Formal attributes names of this record type, in the expected order.

Bases: ProvElement

Provenance Entity element

alternateOf(alternate2: ProvEntity | QualifiedName | str | Identifier) → ProvEntity[source]

Creates a new alternate record between this and another entity.

Parameters:: alternate2 – Entity or a string identifier for the second entity.

hadMember(entity: ProvEntity | QualifiedName | str | Identifier) → ProvEntity[source]

Creates a new membership record to an entity for a collection.

Parameters:: entity – Entity to be added to the collection.

specializationOf(generalEntity: ProvEntity | QualifiedName | str | Identifier) → ProvEntity[source]

Creates a new specialisation record for this from a general entity.

Parameters:: generalEntity – Entity or a string identifier for the general entity.

Creates a new attribution record between this entity and an agent.

Parameters:

agent – Agent or string identifier of the agent involved in the attribution.
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new derivation record for this entity from a used entity.

Parameters:

usedEntity – Entity or a string identifier for the used entity.
activity – Activity or string identifier of the activity involved in the derivation (default: None).
generation – Optional generation record to state qualified derivation through an internal generation (default: None).
usage – Optional usage record to state qualified derivation through an internal usage (default: None).
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new generation record to this entity.

Parameters:

activity – Activity or string identifier of the activity involved in the generation (default: None).
time – Optional time for the generation (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

Creates a new invalidation record for this entity.

Parameters:

activity – Activity or string identifier of the activity involved in the invalidation (default: None).
time – Optional time for the invalidation (default: None). Either a datetime.datetime object or a string that can be parsed by dateutil.parser().
attributes – Optional other attributes as a dictionary or list of tuples to be added to the record optionally (default: None).

exception prov.model.ProvException[source]

Bases: Error

Base class for PROV model exceptions.

exception prov.model.ProvExceptionInvalidQualifiedName(qname: Any)[source]

Bases: ProvException

Exception for an invalid qualified identifier name.

qname = None: Intended qualified name.

Bases: ProvRelation

Provenance Generation relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:entity>, <QualifiedName: prov:activity>, <QualifiedName: prov:time>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Influence relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:influencee>, <QualifiedName: prov:influencer>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Invalidation relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:entity>, <QualifiedName: prov:activity>, <QualifiedName: prov:time>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Membership relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:collection>, <QualifiedName: prov:entity>): Formal attributes names of this record type, in the expected order.

Bases: ProvSpecialization

Provenance Mention relationship (specific Specialization).

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:specificEntity>, <QualifiedName: prov:generalEntity>, <QualifiedName: prov:bundle>): Formal attributes names of this record type, in the expected order.

Bases: object

Base class for PROV records.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (): Formal attributes names of this record type, in the expected order.

add_asserted_type(type_identifier: QualifiedName) → None[source]

Adds a PROV type assertion to the record.

Parameters:: type_identifier – PROV namespace identifier to add.

Add attributes to the record.

Parameters:: attributes – Dictionary of attributes, with keys being qualified identifiers. Alternatively, an iterable of tuples (key, value) with the keys satisfying the same condition.

property args: tuple

All values of the record’s formal attributes.

Returns:: Tuple

property attributes: list[tuple[QualifiedName, Any]]

All record attributes.

Returns:: List of tuples (name, value)

property bundle: ProvBundle

Bundle of the record.

Returns:: ProvBundle

copy() → ProvRecord[source]: Return an exact copy of this record.

property extra_attributes: tuple[tuple[QualifiedName, Any], ...]

All names and values of the record’s attributes that are not formal attributes.

Returns:: Tuple of tuples (name, value)

property formal_attributes: tuple[tuple[QualifiedName, Any], ...]

All names and values of the record’s formal attributes.

Returns:: Tuple of tuples (name, value)

get_asserted_types() → set[QualifiedName][source]: Returns the set of all asserted PROV types of this record.

get_attribute(attr_name: QualifiedName | str | Identifier) → set[source]

Returns the attribute values (if any) for the specified attribute name).

Parameters:: attr_name – Name of the attribute.
Returns:: Set of value(s) of the specified attribute.
Return type:: set

get_provn() → str[source]

Returns the PROV-N representation of the record.

Returns:: String

get_type() → QualifiedName[source]: Returns the PROV type of the record.

property identifier: QualifiedName | None: Record’s identifier.

is_element() → bool[source]

True, if the record is an element, False otherwise.

Returns:: bool

is_relation() → bool[source]

True, if the record is a relation, False otherwise.

Returns:: bool

property label: str: Identifying label of the record.

property value: Any: Value of the record.

Bases: ProvRecord

Provenance Relationship (edge between nodes).

is_relation() → bool[source]

True, if the record is a relation, False otherwise.

Returns:: bool

Bases: ProvRelation

Provenance Specialization relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:specificEntity>, <QualifiedName: prov:generalEntity>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Start relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:activity>, <QualifiedName: prov:trigger>, <QualifiedName: prov:starter>, <QualifiedName: prov:time>): Formal attributes names of this record type, in the expected order.

Bases: ProvRelation

Provenance Usage relationship.

FORMAL_ATTRIBUTES: tuple[QualifiedName, ...] = (<QualifiedName: prov:activity>, <QualifiedName: prov:entity>, <QualifiedName: prov:time>): Formal attributes names of this record type, in the expected order.

exception prov.model.ProvWarning[source]

Bases: Warning

Base class for PROV model warnings.

prov.model.encoding_provn_value(value: str | datetime | float | bool | QualifiedName) → str[source]

prov.model.first(a_set: set[Any]) → Any | None[source]

prov.model.parse_boolean(value: str) → bool | None[source]

prov.model.parse_xsd_datetime(value: str) → datetime | None[source]

prov.model.parse_xsd_types(value: str, datatype: QualifiedName) → str | datetime | float | int | bool | Identifier | None[source]

prov.model.sorted_attributes(element: QualifiedName, attributes: Iterable[tuple[QualifiedName, Any]]) → list[tuple[QualifiedName, Any]][source]

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[source]

Bases: Exception

Base class for all errors in this package.

prov.read(source: str | bytes | os.PathLike, format: str | None = None) → ProvDocument | None[source]

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.