Upgrading to 3.0¶
Summary¶
3.0 is the only release in the prov roadmap allowed to break compatibility. Two changes
matter for most users:
prov.dotandprov.graphneed extras. Installprov[dot]orprov[graph]if your code imports either module, or callsprov_to_dot(),prov_to_graph()orgraph_to_prov().unified()raises instead of silently merging.ProvBundle.unified()andProvDocument.unified()raiseprov.model.ProvUnificationErrorwhen records sharing an identifier disagree on a formal attribute or have incompatible types.prov_to_graph()callsunified()internally, so it can raise too.prov_to_dot()catches the error and renders the document without unifying it. 3.3.0 deprecatedProvBundle.unified().
Both were signposted from 2.4.0 with a runtime warning, which every later 2.x release also
carries. If your test suite ran clean under 2.4.0 or later with
-W error::DeprecationWarning -W error::FutureWarning, neither change affects your code.
Everything else is a set of narrow bug fixes, mostly to serializer output for edge cases, and one renamed type alias. Those could not be signposted by a warning, because they change the result of calls that already succeeded. Skim the table below for the ones that touch your code, or skip to what’s removed.
Install the extras you need¶
If your code uses |
Install |
|---|---|
|
|
|
|
The interactive display in |
|
A plain pip install prov still gives you the core data model and the PROV-JSON, PROV-N
and PROV-JSONLD serializers. Extras combine, for example
pip install "prov[rdf,xml,dot,graph]". See Installation.
Dependency changes¶
python-dateutilis dropped in favour of the standard library’sdatetime.fromisoformat(). Typical ISO 8601 timestamps are unaffected. Non-standard strings that dateutil parsed permissively, such as"Nov 7, 2011"or a barexsd:datelike"2011-11-16", are no longer accepted. An unparseabletime=,startTime=orendTime=factory argument now raisesprov.model.ProvExceptioninstead of a rawdateutilerror.rdflibfloor raised to 7.0.0. Upgrade if you pin rdflib 6.x alongsideprov[rdf]. Output differences are limited to those rdflib 7 already introduced under 2.x.
Bug fixes that change output or equality¶
Each of these fixes a real bug, but each also changes output or equality for inputs that worked without error before, which is why they waited for 3.0. Five need action:
Issue |
What changed |
Action |
|---|---|---|
Attribute sets used to silently drop Python-equal but differently typed values ( |
Recheck code that reads attributes through |
|
|
Recheck code relying on differently formatted decimals comparing unequal. |
|
Language tags now compare and hash case-insensitively. Serialized output keeps the original casing. |
Recheck code relying on differently cased tags comparing unequal. |
|
Malformed PROV-JSON now raises |
Update exception handlers. Catch |
|
PROV-XML parsing now uses a hardened parser. External DTD entities no longer resolve, and affected values come back empty instead of expanded. |
If you need to detect rather than neutralise entity use, reject documents containing |
The other fixes change what a serializer writes for inputs that already worked, and a few
change what a value decodes to in Python: a prov:QUALIFIED_NAME literal becomes a
QualifiedName, xsd:base64Binary decodes to its base64 text rather than a bytes repr, a
qualified Start or End node’s time becomes the relation’s formal time, PROV-JSON’s typed
$ value is always a string, and two inputs that raised ValueError now succeed. The
3.0.0 section of the changelog lists each with its issue. Recheck byte comparisons of serialized output, and code that
reads those decoded values.
Documented limitation, not a fix. Two same-identifier relations that differ in
prov:time still cannot round-trip through PROV-O, because PROV-O names a relation by its
identifier; decoding raises a clear, chained error (caveat C1 on
Conformance, #217). Give
such relations distinct identifiers if they must survive an RDF round trip.
unified() now enforces PROV-CONSTRAINTS¶
Before 3.0, unified() merged same-identifier records by unioning their attributes with no
conflict detection. 3.0 merges by PROV-CONSTRAINTS
term unification; Unification and flattening has the full model. In short:
Two different concrete values for the same formal attribute raise
prov.model.ProvUnificationErrorinstead of merging silently. A missing attribute still unifies with any concrete value, as before.Records sharing an identifier but of incompatible types, such as an entity and an activity, raise the same error, naming both types, instead of merging into whichever record was asserted first. Overlaps the specification permits, such as an agent that is also an entity, still merge as separate, per-type records.
Each bundle unifies independently. Nothing merges across a bundle boundary.
Non-formal (“extra”) attributes keep their set-union behaviour.
Uniqueness constraints not keyed on the record identifier are out of scope. They belong to the separate, opt-in validation engine tracked as #62.
ProvUnificationError subclasses ProvException, so an existing except ProvException
handler around unified() keeps working. prov_to_dot() catches the error and falls back
to rendering the non-unified bundle. prov_to_graph() lets it propagate. Building and
serializing a document with these conflicts is still legal in 3.0, because prov performs
no structural validation at assertion or serialization time by design
(#257). Only calling unified() on such a
document, or decoding its RDF form, raises.
Action: if you call unified(), directly or through prov_to_graph(), on documents
where same-identifier records might disagree on a formal attribute or type, catch
ProvUnificationError or fix the document to avoid the conflict.
Removed¶
3.0 removes everything 2.4.0 marked deprecated. Nothing else is scheduled for removal.
The unconditional
pydotandnetworkxdependencies, superseded by thedotandgraphextras above.import prov.dotandimport prov.graphnow raiseModuleNotFoundErrornaming the extra to install.python-dateutilas a runtime dependency, and the incidentalprov.model.dateutilre-export that came from importing it.prov.model.GenrationRef, the misspelled type alias used for thegenerationparameter ofwasDerivedFrom(),wasRevisionOf(),wasQuotedFrom()andhadPrimarySource(). It is renamedGenerationRef, with no alias kept for the old spelling.