Skip to content
Back to top
View this page

# 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 `test_read_auto_detect_with_broken_tell_degrades_to_no_rewind` pins JSON as the first candidate tried — a non-seekable stream can only attempt the first format, so JSON must remain first for JSON content to be auto-detected on broken streams.

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`.