prov.serializers

prov.serializers defines the pluggable serializer interface used by ProvDocument.serialize() and ProvDocument.deserialize(), and the registry that looks up the serializer class for a given format string ("json", "xml", "rdf", "provn"). For how to use each format, see the Work with PROV-JSON, Work with PROV-XML, Work with PROV-O (RDF), and Work with PROV-N how-to guides; this page documents the underlying interface and registry only.

class prov.serializers.Serializer(document: ProvDocument | None = None)

Bases: ABC

Serializer for PROV documents.

document = None

PROV document to serialise.

abstractmethod serialize(stream: IOBase, **args: Any) → None

Serialize self.document and write it to a stream.

Subclasses implement this to encode the bound document and write the result to stream.

Parameters:

• stream – Stream to write the serialized document into.

• **args – Format-specific serialization options, passed through by subclasses.

abstractmethod deserialize(stream: io.IOBase, **args: Any) → ProvDocument

Read and parse a document from a stream.

Subclasses implement this to parse stream and build a new ProvDocument from it.

Parameters:

• stream – Stream to deserialize the document from.

• **args – Format-specific deserialization options, passed through by subclasses.

Returns:

The deserialized ProvDocument.

class prov.serializers.Registry

Registry of serializers.

serializers: ClassVar[dict[str, type[Serializer]] | None] = None

Property caching all available serializers in a dict.

static load_serializers() → None

Load all serializers whose optional dependencies are installed.

json and provn have no optional dependencies and are always registered. rdf (needs rdflib) and xml (needs lxml) are registered only if their extra is installed, so that import prov and JSON/PROV-N work in a minimal install; requesting an unavailable format then raises an informative DoNotExist (see get()) rather than a bare ModuleNotFoundError.

The insertion order is kept as json, rdf, provn, xml (the historic order when all extras are present) because prov.read()’s format auto-detection iterates Registry.serializers in order and several tests (test_read_auto_detects_rdf, test_read_auto_detect_of_xml_hits_uncaught_rdf_syntax_error, test_read_on_unparseable_content_raises_bad_syntax) pin the exact candidate tried second.

prov.serializers.get(format_name: str) → type[Serializer]

Return the serializer class registered for a format.

Parameters:

format_name – Registry key, e.g. "json", "xml", "rdf", "provn".

Returns:

The Serializer subclass for the format.

Raises:

DoNotExist – If no serializer is registered under format_name.

class prov.serializers.DoNotExist

Bases: Error

Exception for the case a serializer is not available.

Reading documents

prov.read() auto-detects the format of a source by trying each registered deserializer in turn; see Work with PROV-JSON for its caveats around error reporting.

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

Read a ProvDocument from a file, path, or string.

If format is not given, the format is detected lazily by trying each registered serializer’s deserialize() in turn and returning the first one that succeeds. 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 of auto-detection is that no proper error messages will be produced; pass the format parameter explicitly to get the actual traceback from the matching deserializer.

Parameters:

• source – File-like stream, path, or raw content to deserialize.

• format – Serialization format to use (e.g. "json", "xml", "rdf", "provn"). If None, every registered format is tried in turn.

Returns:

The deserialized ProvDocument.

Raises:

TypeError – If format is None and none of the registered serializers could deserialize source.