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: io.IOBase | IO[Any] | str | bytes | os.PathLike[str], format: str | None = None) → ProvDocument | None

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

A str/bytes source naming an existing file is read from that file; any other str/bytes is parsed as raw document content.

If format is not given, the format is detected by trying each registered deserializer in turn and returning the first that both succeeds and produces a non-empty document (a parse yielding no records or bundles – e.g. rdflib parsing empty/foreign input to an empty graph – is treated as “not this format”; registered namespaces are not used as a signal here since the rdf deserializer always registers rdflib’s own default-bound namespace prefixes on every successful parse, empty or not). Auto-detection swallows all deserializer errors; pass format explicitly to get the actual traceback from the matching deserializer.

A seekable stream source (e.g. an open file object, io.StringIO, io.BytesIO) is rewound to its starting position before each auto-detection attempt, so every candidate format sees the full content. A non-seekable stream is consumed by the first candidate; pass format explicitly for those.

Parameters:

• source – File-like stream, path to an existing file, or raw content.

• 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 no registered serializer produced a non-empty document from source.