prov 3.2.0__tar.gz → 3.2.2__tar.gz

{prov-3.2.0/src/prov.egg-info → prov-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prov
-Version: 3.2.0
+Version: 3.2.2
 Summary: A library for W3C Provenance Data Model supporting PROV-N, PROV-JSON, PROV-XML, PROV-O (RDF) and PROV-JSONLD
 Author-email: Trung Dong Huynh <trungdong@donggiang.com>
 License-Expression: MIT
@@ -9,6 +9,7 @@ Project-URL: Documentation, https://prov.readthedocs.io
 Project-URL: Repository, https://github.com/trungdong/prov
 Project-URL: Issues, https://github.com/trungdong/prov/issues
 Project-URL: Changelog, https://prov.readthedocs.io/en/latest/history.html
+Project-URL: Discussions, https://github.com/trungdong/prov/discussions
 Keywords: provenance,graph,model,PROV,PROV-DM,PROV-JSON,W3C,PROV-XML,PROV-N,PROV-O,RDF,PROV-JSONLD,JSON-LD
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -83,9 +84,11 @@ Over 7,000 public repositories on GitHub
 3.0.0 completed the modernisation programme (tooling, type hints, tests, documentation and
 standards conformance) and 3.1.0 added PROV-JSONLD.
 [What's new in 3](https://prov.readthedocs.io/en/latest/whats-new-3.html) summarises the 3.x
-line for projects still on 2.x.
+line for projects still on 2.x, and the announcement post
+[PROV Python 3.x: a major release](https://trungdong.github.io/provpy-3.html) covers what
+changed and who uses the package.
 [ROADMAP.md](https://github.com/trungdong/prov/blob/main/ROADMAP.md) lists the planned
-releases and the API-stability promise. Feedback is welcome on the
+releases and the support policy. Feedback is welcome on the
 [issue tracker](https://github.com/trungdong/prov/issues).
 
 ## Supported versions

{prov-3.2.0 → prov-3.2.2}/README.md

@@ -36,9 +36,11 @@ Over 7,000 public repositories on GitHub
 3.0.0 completed the modernisation programme (tooling, type hints, tests, documentation and
 standards conformance) and 3.1.0 added PROV-JSONLD.
 [What's new in 3](https://prov.readthedocs.io/en/latest/whats-new-3.html) summarises the 3.x
-line for projects still on 2.x.
+line for projects still on 2.x, and the announcement post
+[PROV Python 3.x: a major release](https://trungdong.github.io/provpy-3.html) covers what
+changed and who uses the package.
 [ROADMAP.md](https://github.com/trungdong/prov/blob/main/ROADMAP.md) lists the planned
-releases and the API-stability promise. Feedback is welcome on the
+releases and the support policy. Feedback is welcome on the
 [issue tracker](https://github.com/trungdong/prov/issues).
 
 ## Supported versions

{prov-3.2.0 → prov-3.2.2}/pyproject.toml

@@ -66,6 +66,7 @@ Documentation = "https://prov.readthedocs.io"
 Repository = "https://github.com/trungdong/prov"
 Issues = "https://github.com/trungdong/prov/issues"
 Changelog = "https://prov.readthedocs.io/en/latest/history.html"
+Discussions = "https://github.com/trungdong/prov/discussions"
 
 [build-system]
 requires = ["setuptools>=40.8.0", "wheel"]  # PEP 508 specifications.
@@ -196,4 +197,51 @@ exclude_lines = [
 [tool.mypy]
 python_version = "3.10"
 strict = true
-exclude = ["^src/prov/tests/"]
+
+# Test modules that do not yet pass strict mypy. The list only shrinks. A PR
+# that makes a module pass deletes its name, and a new test module never joins.
+[[tool.mypy.overrides]]
+module = [
+    "prov.tests.conftest",
+    "prov.tests.examples",
+    "prov.tests.strategies",
+    "prov.tests.test_attribute_merging",
+    "prov.tests.test_attributes",
+    "prov.tests.test_chaining",
+    "prov.tests.test_cli_smoke",
+    "prov.tests.test_conformance_dm",
+    "prov.tests.test_datetime_parsing",
+    "prov.tests.test_dot",
+    "prov.tests.test_examples",
+    "prov.tests.test_extras",
+    "prov.tests.test_graphs",
+    "prov.tests.test_identifier",
+    "prov.tests.test_identifier_slots",
+    "prov.tests.test_json",
+    "prov.tests.test_json_schema",
+    "prov.tests.test_jsonld",
+    "prov.tests.test_jsonld_schema",
+    "prov.tests.test_jsonld_semantics",
+    "prov.tests.test_literal_semantics",
+    "prov.tests.test_malformed",
+    "prov.tests.test_model",
+    "prov.tests.test_namespace_cache",
+    "prov.tests.test_numeric_typing",
+    "prov.tests.test_property_roundtrip",
+    "prov.tests.test_provn",
+    "prov.tests.test_provn_corpus",
+    "prov.tests.test_provn_escaping",
+    "prov.tests.test_provn_lexer",
+    "prov.tests.test_provn_profiles",
+    "prov.tests.test_public_api",
+    "prov.tests.test_qnames",
+    "prov.tests.test_rdf",
+    "prov.tests.test_read",
+    "prov.tests.test_scripts",
+    "prov.tests.test_statements",
+    "prov.tests.test_unification_constraints",
+    "prov.tests.test_unification_rules",
+    "prov.tests.test_xml",
+    "prov.tests.test_xml_schema",
+]
+ignore_errors = true

{prov-3.2.0 → prov-3.2.2}/src/prov/__init__.py

@@ -3,15 +3,15 @@ from __future__ import annotations  # defer eval: TYPE_CHECKING names in signatu
 import logging
 import os
 import warnings
-from collections.abc import Iterable
 from typing import IO, TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
     from prov.model import ProvDocument, StreamOrPath
+    from prov.serializers import Serializer
 
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
-__version__ = "3.2.0"
+__version__ = "3.2.2"
 
 __all__ = ["Error", "model", "read"]
 
@@ -66,7 +66,7 @@ def _prepare_stream(
 def _detect_and_parse(
     src: StreamOrPath | None,
     content: str | bytes | None,
-    serializers: Iterable[str],
+    serializers: dict[str, type[Serializer]],
     **kwargs: Any,
 ) -> ProvDocument:
     """Try each registered format in turn, returning the first non-empty parse.
@@ -107,10 +107,14 @@ def _detect_and_parse(
                     start_pos = None
             try:
                 # kwargs are format-specific (e.g. profile= for provn); a
-                # candidate that doesn't understand them would otherwise
+                # candidate that doesn't understand an option would otherwise
                 # raise TypeError, indistinguishable here from "not this
-                # format", so only the candidate they're meant for gets them.
-                candidate_kwargs = kwargs if format == "provn" else {}
+                # format", so each candidate only gets the options it declares.
+                candidate_kwargs = {
+                    key: value
+                    for key, value in kwargs.items()
+                    if key in serializers[format].deserialize_options
+                }
                 document = ProvDocument.deserialize(
                     source=src, content=content, format=format, **candidate_kwargs
                 )
@@ -176,19 +180,20 @@ def read(
             ``"rdf"``, ``"provn"``). If ``None``, every registered format is
             tried in turn.
         **kwargs: Passed to the deserializer, for example ``profile`` for
-            PROV-N. With ``format`` given explicitly, the named deserializer
-            receives them as given. With auto-detection, only the ``provn``
-            candidate receives them, since ``json``/``rdf``/``xml``/``jsonld``
-            do not accept format-specific keyword arguments and would
-            otherwise raise a ``TypeError`` indistinguishable from "not this
-            format".
+            PROV-N or ``rdf_format`` for PROV-O. Each serializer declares
+            the options it accepts (``deserialize_options``); with
+            ``format`` given, an undeclared option raises ``TypeError``;
+            with auto-detection, every candidate receives only the options
+            it declares.
 
     Returns:
         The deserialized :class:`~prov.model.ProvDocument`.
 
     Raises:
-        TypeError: If ``format`` is ``None`` and no registered serializer
-            produced a non-empty document from ``source``.
+        TypeError: If ``format`` is given and names an option the
+            corresponding deserializer does not declare, or if ``format``
+            is ``None`` and no registered serializer produced a non-empty
+            document from ``source``.
     """
     # Lazy imports to not globber the namespace.
     from prov.model import ProvDocument
@@ -198,11 +203,20 @@ def read(
         Registry.load_serializers()
     if Registry.serializers is None:  # pragma: no cover -- populated above
         raise AssertionError("Registry.serializers is not populated")
-    serializers = Registry.serializers.keys()
+    serializers = Registry.serializers
 
     src, content = _resolve_source(source)
 
     if format:
+        cls = serializers.get(format.lower())
+        if cls is not None:
+            unknown = sorted(set(kwargs) - cls.deserialize_options)
+            if unknown:
+                accepted = ", ".join(sorted(cls.deserialize_options)) or "none"
+                raise TypeError(
+                    f"the {format.lower()!r} deserializer accepts no option "
+                    f"{unknown[0]!r}; it accepts: {accepted}"
+                )
         try:
             return ProvDocument.deserialize(
                 source=src, content=content, format=format.lower(), **kwargs

{prov-3.2.0 → prov-3.2.2}/src/prov/_warnings.py

@@ -1,4 +1,8 @@
-"""Shared ``warnings.warn()`` stacklevel helper.
+"""``ProvWarning`` and the shared ``warnings.warn()`` stacklevel helper.
+
+Both live here, not in :mod:`prov.model.records`, so that :mod:`prov.identifier`
+can emit ``ProvWarning`` without importing :mod:`prov.model` and creating a
+cycle; :mod:`prov.model` re-exports both under their historic names.
 
 Attributing a warning to its caller with a fixed ``stacklevel`` only works
 when every call path between the ``warn()`` site and the external caller
@@ -12,6 +16,10 @@ import sys
 from types import FrameType
 
 
+class ProvWarning(Warning):
+    """Base class for PROV model warnings."""
+
+
 def external_stacklevel(skip: int = 1) -> int:
     """Return the ``stacklevel`` of the nearest frame outside ``prov``.
 

{prov-3.2.0 → prov-3.2.2}/src/prov/dot.py

@@ -63,6 +63,7 @@ from prov.model import (
     ProvWarning,
     sorted_attributes,
 )
+from prov.model.records import _xsd_datetime_text
 
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
@@ -294,7 +295,7 @@ def _attach_attribute_annotation(
             escape(
                 str(value)
                 if not isinstance(value, datetime)
-                else str(value.isoformat())
+                else _xsd_datetime_text(value)
             ),
         )
         for attr, value in attributes

{prov-3.2.0 → prov-3.2.2}/src/prov/identifier.py

@@ -1,8 +1,11 @@
 from __future__ import annotations  # defer eval: Namespace used before it's defined
 
 import re
+import warnings
 from typing import Any, Final
 
+from prov._warnings import ProvWarning, external_stacklevel
+
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
 
@@ -52,6 +55,19 @@ _PROVN_LOCAL_LEADING_ESCAPE = "-."
 # PN_LOCAL's own character class ([53]), the shared NCName table minus '.'
 # (see the comment on _NCNAME_CHARS above).
 _PN_CHARS = _NCNAME_CHARS.replace(".", "")
+# The characters in _PN_CHARS that are legal anywhere in PN_LOCAL but, being
+# combining marks rather than letters, cannot start it ([53]'s PN_CHARS_BASE
+# vs. PN_CHARS): the NameChar-only part of _NCNAME_CHARS, minus '-'/'.'
+# (handled positionally above) and the digits (PN_LOCAL allows a leading
+# digit). Spelled the same way as _NCNAME_CHARS so a look-alike codepoint
+# stays visible on inspection.
+_PN_LOCAL_BAD_START = re.compile(
+    "["
+    "\xb7"  # NameChar: #xB7 (middle dot)
+    "\u0300-\u036f"  # NameChar: [#x0300-#x036F]
+    "\u203f-\u2040"  # NameChar: [#x203F-#x2040]
+    "]"
+)
 # The remaining characters PN_LOCAL allows unescaped ([54]'s PLX minus '%').
 _PN_CHARS_OTHER = "/@~&+*?#$!"
 _PROVN_HEX_PAIR = re.compile(r"[0-9A-Fa-f]{2}")
@@ -77,29 +93,91 @@ _PROVN_LOCAL_NEEDS_ESCAPE = re.compile(
 )
 
 
-def _provn_escape_local(localpart: str) -> str:
-    """Return ``localpart`` escaped for use in a PROV-N ``PN_LOCAL`` position."""
-    if not _PROVN_LOCAL_NEEDS_ESCAPE.search(localpart):
-        return localpart
+def _slot_state(state: Any) -> dict[str, Any]:
+    """Normalise a pickled state to a dict.
+
+    Pickles from 3.1.1 carry the instance ``__dict__``; pickles from 3.2.0,
+    whose classes had ``__slots__`` but no ``__getstate__``, carry the
+    ``(dict_state, slot_state)`` tuple Python builds for slotted objects.
+    """
+    if isinstance(state, tuple):
+        dict_state, slot_state = state
+        return {**(dict_state or {}), **(slot_state or {})}
+    return dict(state)
+
+
+def _escape_local_char(
+    localpart: str, i: int, last_index: int, char: str
+) -> tuple[str, bool]:
+    """Return one character's PROV-N spelling and whether it was percent-encoded."""
+    if i == 0 and _PN_LOCAL_BAD_START.match(char):
+        # PN_LOCAL_BAD_START chars are legal PN_CHARS but cannot start a
+        # PN_LOCAL, and there is no backslash escape for "start here";
+        # percent-encoding is the only way to write one first.
+        return "".join(f"%{byte:02X}" for byte in char.encode("utf-8")), True
+    if char == "%":
+        # An existing valid escape (e.g. "%20") is kept verbatim; a bare
+        # '%' not followed by two hex digits is not, so it is escaped
+        # itself to keep the sequence unambiguous.
+        return (char if _PROVN_HEX_PAIR.match(localpart, i + 1) else "%25"), False
+    if (
+        (i == 0 and char in _PROVN_LOCAL_LEADING_ESCAPE)
+        or (i == last_index and char == ".")
+        or char in _PROVN_LOCAL_METACHARS
+    ):
+        return f"\\{char}", False
+    if _PROVN_LOCAL_NEEDS_PERCENT_ENCODING.match(char):
+        # "surrogatepass" lets a lone surrogate (unpaired, e.g. from WTF-8 or
+        # a Windows filename) be percent-encoded from its raw UTF-16 code
+        # unit rather than raising UnicodeEncodeError.
+        encoded = char.encode("utf-8", "surrogatepass")
+        return "".join(f"%{byte:02X}" for byte in encoded), True
+    return char, False
+
+
+def _provn_escape_local(localpart: str) -> tuple[str, bool]:
+    """Return ``localpart`` escaped for use in a PROV-N ``PN_LOCAL`` position.
+
+    Returns the escaped text and whether it was percent-encoded anywhere: a
+    backslash escape (a metacharacter, or a leading/trailing ``-``/``.``) is
+    reversible and a PROV-N reader recovers the original text, but a
+    percent-encoded character is not, so the caller warns when it happens.
+    """
+    if not _PROVN_LOCAL_NEEDS_ESCAPE.search(localpart) and not (
+        localpart and _PN_LOCAL_BAD_START.match(localpart[0])
+    ):
+        return localpart, False
     last_index = len(localpart) - 1
     parts = []
+    encoded = False
     for i, char in enumerate(localpart):
-        if char == "%":
-            # An existing valid escape (e.g. "%20") is kept verbatim; a bare
-            # '%' not followed by two hex digits is not, so it is escaped
-            # itself to keep the sequence unambiguous.
-            parts.append(char if _PROVN_HEX_PAIR.match(localpart, i + 1) else "%25")
-        elif (
-            (i == 0 and char in _PROVN_LOCAL_LEADING_ESCAPE)
-            or (i == last_index and char == ".")
-            or char in _PROVN_LOCAL_METACHARS
-        ):
-            parts.append(f"\\{char}")
-        elif _PROVN_LOCAL_NEEDS_PERCENT_ENCODING.match(char):
-            parts.extend(f"%{byte:02X}" for byte in char.encode("utf-8"))
-        else:
-            parts.append(char)
-    return "".join(parts)
+        text, char_was_encoded = _escape_local_char(localpart, i, last_index, char)
+        parts.append(text)
+        encoded = encoded or char_was_encoded
+    return "".join(parts), encoded
+
+
+def _provn_escape_local_and_warn(localpart: str, uri: str) -> str:
+    """Escape ``localpart`` for a PROV-N ``PN_LOCAL`` position, warning if that
+    changes the IRI a PROV-N reader recovers.
+
+    ``uri`` is the identifier's full URI, named in the warning so the caller
+    can find which identifier is affected. Shared by
+    :meth:`QualifiedName.provn_bare_representation` and the bundle-header
+    prefix path in :mod:`prov.model.bundle`, so both raise the same
+    :class:`~prov.model.ProvWarning` for the same reason rather than one of
+    them silently changing the IRI.
+    """
+    escaped, encoded = _provn_escape_local(localpart)
+    if encoded:
+        warnings.warn(
+            f"the local part {localpart!r} of <{uri}> contains a character PROV-N "
+            "cannot write; it is percent-encoded, which changes the IRI a PROV-N "
+            "reader recovers",
+            ProvWarning,
+            stacklevel=external_stacklevel(),
+        )
+    return escaped
 
 
 class Identifier:
@@ -108,7 +186,7 @@ class Identifier:
     # TODO: make Identifier an "abstract" base class and move xsd:anyURI
     # into a subclass
 
-    __slots__ = ("_hash", "_uri")
+    __slots__ = ("__weakref__", "_hash", "_uri")
 
     # This field is assign-once. The hash is computed from it at construction,
     # and a later reassignment would leave the cached hash stale. #444 tracks
@@ -126,9 +204,21 @@ class Identifier:
         self._hash = self._compute_hash()
 
     def _compute_hash(self) -> int:
-        """Hash for this identifier, class-distinguished so identifiers with
-        the same URI but a different concrete type do not collide."""
-        return hash((self._uri, self.__class__))
+        """Hash by URI alone, so equal identifiers hash equal whatever their
+        concrete class: ``__eq__`` compares URIs across Identifier subclasses."""
+        return hash(self._uri)
+
+    def __getstate__(self) -> dict[str, Any]:
+        """Pickle state: every slot except the process-specific ``_hash``,
+        which :meth:`__setstate__` recomputes in the loading process."""
+        return {"_uri": self._uri}
+
+    def __setstate__(self, state: Any) -> None:
+        # Also accepts the __dict__ state of 3.1.1 pickles and the
+        # (dict_state, slot_state) tuple of 3.2.0 pickles.
+        state = _slot_state(state)
+        object.__setattr__(self, "_uri", state["_uri"])
+        object.__setattr__(self, "_hash", self._compute_hash())
 
     @property
     def uri(self) -> str:
@@ -191,11 +281,25 @@ class QualifiedName(Identifier):
         )
 
     def _compute_hash(self) -> int:
-        """Hash by URI alone. Unlike the base class, a QualifiedName never
-        needs class-distinguishing, so no different concrete type shares a
-        URI with it in practice."""
+        """Hash by URI alone, as the base class does; kept explicit because
+        the string form is cached separately."""
         return hash(self._uri)
 
+    def __getstate__(self) -> dict[str, Any]:
+        return {
+            "_uri": self._uri,
+            "_namespace": self._namespace,
+            "_localpart": self._localpart,
+            "_str": self._str,
+        }
+
+    def __setstate__(self, state: Any) -> None:
+        state = _slot_state(state)
+        object.__setattr__(self, "_namespace", state["_namespace"])
+        object.__setattr__(self, "_localpart", state["_localpart"])
+        object.__setattr__(self, "_str", state["_str"])
+        Identifier.__setstate__(self, state)
+
     @property
     def namespace(self) -> Namespace:
         """Namespace of qualified name."""
@@ -212,20 +316,32 @@ class QualifiedName(Identifier):
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: {self._str}>"
 
-    def __hash__(self) -> int:
-        return self._hash
-
     def provn_bare_representation(self) -> str:
         """Return the ``prefix:local`` PROV-N form used at IDENTIFIER positions.
 
         The local part's PROV-N metacharacters (``= ' ( ) , : ; [ ]``) are
         backslash-escaped per grammar production [55] ``PN_CHARS_ESC`` (#223),
         as are a leading ``-``/``.`` and a trailing ``.`` (forbidden bare by
-        [53]/[54]); characters PN_LOCAL cannot express at all are
-        percent-encoded. The prefix is never escaped, as it cannot contain
-        these characters.
+        [53]/[54]); a character PN_LOCAL cannot express at all, or cannot
+        start it, is percent-encoded instead, which changes the IRI a PROV-N
+        reader recovers, so that emits a :class:`~prov.model.ProvWarning`.
+        The prefix is never escaped, as it cannot contain these characters.
+
+        Raises:
+            ProvException: If the local part is empty and the namespace has no
+                prefix, which has no PROV-N spelling.
         """
-        escaped_localpart = _provn_escape_local(self._localpart)
+        if not self._localpart and not self._namespace.prefix:
+            # Imported here, not at module level, to avoid a cycle:
+            # prov.model.records imports prov.identifier.
+            from prov.model.records import ProvException
+
+            raise ProvException(
+                f"the qualified name for <{self._uri}> has an empty local part in a "
+                "namespace with no prefix, which PROV-N cannot write; give the "
+                "namespace a prefix"
+            )
+        escaped_localpart = _provn_escape_local_and_warn(self._localpart, self._uri)
         return (
             ":".join([self._namespace.prefix, escaped_localpart])
             if self._namespace.prefix
@@ -240,7 +356,7 @@ class QualifiedName(Identifier):
 class Namespace:
     """PROV Namespace."""
 
-    __slots__ = ("_cache", "_prefix", "_uri")
+    __slots__ = ("__weakref__", "_cache", "_prefix", "_uri")
 
     # These fields are assign-once. They take part in equality and hashing,
     # so reassigning one after the object has been used as a set member or
@@ -331,6 +447,19 @@ class Namespace:
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: {self._prefix} {{{self._uri}}}>"
 
+    def __getstate__(self) -> dict[str, Any]:
+        """Pickle state without the interning cache, which is rebuilt lazily."""
+        return {"_prefix": self._prefix, "_uri": self._uri}
+
+    def __setstate__(self, state: Any) -> None:
+        # Also accepts the __dict__ state of 3.1.1 pickles and the
+        # (dict_state, slot_state) tuple of 3.2.0 pickles; either way any
+        # cache carried in the state is discarded and rebuilt lazily.
+        state = _slot_state(state)
+        object.__setattr__(self, "_prefix", state["_prefix"])
+        object.__setattr__(self, "_uri", state["_uri"])
+        object.__setattr__(self, "_cache", {})
+
     def __getitem__(self, localpart: str) -> QualifiedName:
         if localpart in self._cache:
             return self._cache[localpart]

{prov-3.2.0 → prov-3.2.2}/src/prov/model/__init__.py

@@ -22,6 +22,7 @@ from typing import Any as Any, Union as Union
 from urllib.parse import urlparse as urlparse
 
 from prov import Error as Error, serializers as serializers
+from prov._warnings import ProvWarning as ProvWarning
 from prov.constants import *
 from prov.identifier import (
     Identifier as Identifier,
@@ -44,6 +45,7 @@ from prov.model.records import (
     ActivityRef as ActivityRef,
     AgentRef as AgentRef,
     AttributePair as AttributePair,
+    AttributeValue as AttributeValue,
     DatetimeOrStr as DatetimeOrStr,
     EntityRef as EntityRef,
     GenerationRef as GenerationRef,
@@ -78,7 +80,6 @@ from prov.model.records import (
     ProvStart as ProvStart,
     ProvUnificationError as ProvUnificationError,
     ProvUsage as ProvUsage,
-    ProvWarning as ProvWarning,
     QualifiedNameCandidate as QualifiedNameCandidate,
     RecordAttributesArg as RecordAttributesArg,
     StreamOrPath as StreamOrPath,