prov 3.2.2__tar.gz → 3.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prov
-Version: 3.2.2
+Version: 3.2.3
 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
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

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

@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
@@ -215,14 +216,12 @@ module = [
     "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",
@@ -240,7 +239,6 @@ module = [
     "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",
 ]

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

@@ -11,7 +11,7 @@ if TYPE_CHECKING:
 
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
-__version__ = "3.2.2"
+__version__ = "3.2.3"
 
 __all__ = ["Error", "model", "read"]
 
@@ -76,6 +76,7 @@ def _detect_and_parse(
             document from ``src``/``content``.
     """
     # Lazy import: prov and prov.model are circularly dependent.
+    from prov._warnings import collect_warnings, warn
     from prov.model import ProvDocument
 
     stream, start_pos = _prepare_stream(src)
@@ -105,24 +106,33 @@ def _detect_and_parse(
                     # A seek that fails mid-loop degrades to no-rewind for
                     # the remaining attempts rather than aborting detection.
                     start_pos = None
-            try:
-                # kwargs are format-specific (e.g. profile= for provn); a
-                # candidate that doesn't understand an option would otherwise
-                # raise TypeError, indistinguishable here from "not this
-                # 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
-                )
-            except Exception:
-                # Any failure from a candidate deserializer means "not this
-                # format" -- move on to the next candidate.
-                continue
+            # prov's warnings from each candidate are collected, not shown: a
+            # candidate that fails or parses to an empty document is "not this
+            # format", so its warnings are noise, and under an ``error`` filter
+            # a warning raised inside the candidate would be swallowed below as
+            # a parse failure.
+            with collect_warnings() as collected:
+                try:
+                    # kwargs are format-specific (e.g. profile= for provn); a
+                    # candidate that doesn't understand an option would
+                    # otherwise raise TypeError, indistinguishable here from
+                    # "not this 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
+                    )
+                except Exception:  # nosec B112 - nosemgrep
+                    # Any failure from a candidate deserializer means "not
+                    # this format" -- move on to the next candidate.
+                    continue
             if document.get_records() or document.has_bundles():
+                for message, category in collected:
+                    warn(message, category)
                 return document
             # A parse producing a completely empty document (e.g. rdflib
             # accepts empty input, or the xml deserializer walking a
@@ -168,6 +178,11 @@ def read(
     ``format`` explicitly to get the actual traceback from the matching
     deserializer.
 
+    ``prov``'s own warnings from a candidate that fails or produces an empty
+    document are dropped. Those of the chosen candidate are emitted at the
+    caller's line, so an ``error`` filter raises them from here. Warnings from
+    other libraries are emitted where they occur.
+
     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.

prov-3.2.3/src/prov/_warnings.py

@@ -0,0 +1,120 @@
+"""``ProvWarning``, its 3.3.0 subclass and the helpers that emit them.
+
+All live here, not in :mod:`prov.model.records`, so that :mod:`prov.identifier`
+can emit them without importing :mod:`prov.model` and creating a cycle;
+:mod:`prov.model` re-exports both warning classes under their public names.
+The module also holds the :func:`warn` helper every serializer uses.
+
+Attributing a warning to its caller with a fixed ``stacklevel`` only works
+when every call path between the ``warn()`` site and the external caller
+has the same number of frames. Several call paths do not (a serializer
+reached directly vs. via :func:`prov.read`, or a relation drawn at the
+top of a document vs. inside a nested bundle), so the stacklevel has to be
+found by walking the real call stack instead.
+"""
+
+import sys
+import warnings
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from types import FrameType
+
+
+class ProvWarning(Warning):
+    """Base class for PROV model warnings."""
+
+
+class ProvFutureRejectionWarning(ProvWarning):
+    r"""Input that ``prov`` 3.2.x reads but 3.3.0 rejects or reads differently.
+
+    ``prov`` still reads the input as before. Turn this class into an error,
+    for example with ``warnings.simplefilter("error", ProvFutureRejectionWarning)``,
+    to find every such input without failing on any other :class:`ProvWarning`.
+    Each message ends with the issue that tracks its 3.3.0 rule, such as
+    ``(#529)``, so a ``message=`` filter can silence one issue. Write it as
+    ``r"(?s).*\(#529\)$"``, since ``(?s)`` lets the pattern match a message
+    that spans lines.
+    """
+
+
+def future_rejection_message(
+    detail: str, outcome: str = "reject this", *, issue: int
+) -> str:
+    """Return ``detail`` followed by the clause every 3.3.0 warning ends with.
+
+    Args:
+        detail: What was found, starting with its position where the
+            format has one.
+        outcome: What 3.3.0 does instead, completing ``"prov 3.3.0 will"``.
+        issue: Number of the GitHub issue that tracks the 3.3.0 rule.
+
+    Returns:
+        For example ``"<detail>. prov 3.3.0 will reject this (#529)"``.
+    """
+    return f"{detail}. prov 3.3.0 will {outcome} (#{issue})"
+
+
+def external_stacklevel(skip: int = 1) -> int:
+    """Return the ``stacklevel`` of the nearest frame outside ``prov``.
+
+    Walks the call stack outward starting at the frame ``skip`` levels
+    above the caller of this function, stopping at the first frame whose
+    module is not ``prov`` or a ``prov.`` submodule. A frame in
+    ``prov.tests.`` counts as external, since the test suite calls into
+    ``prov`` directly and still wants the warning attributed to its own
+    filename.
+
+    Args:
+        skip: Number of frames between this function and the ``warn()``
+            call site whose stacklevel is being computed (default ``1``,
+            i.e. this function's direct caller is that site).
+
+    Returns:
+        The ``stacklevel`` value to pass to ``warnings.warn()``, or
+        ``skip + 1`` if the walk exhausts without finding an external frame.
+    """
+    frame: FrameType | None = sys._getframe(skip)
+    level = skip
+    while frame is not None:
+        module_name = frame.f_globals.get("__name__", "")
+        is_internal = module_name == "prov" or module_name.startswith("prov.")
+        is_tests = module_name.startswith("prov.tests.")
+        if not is_internal or is_tests:
+            return level
+        frame = frame.f_back
+        level += 1
+    return skip + 1
+
+
+_collected: ContextVar[list[tuple[str, type[Warning]]] | None] = ContextVar(
+    "prov_collected_warnings", default=None
+)
+
+
+def warn(message: str, category: type[Warning] = ProvWarning) -> None:
+    """Warn on behalf of ``prov``, at the nearest caller outside ``prov``.
+
+    Inside :func:`collect_warnings` the warning is appended to the active
+    collection instead, for the code that opened it to emit or drop.
+    """
+    collected = _collected.get()
+    if collected is not None:
+        collected.append((message, category))
+        return
+    warnings.warn(message, category, stacklevel=external_stacklevel())
+
+
+@contextmanager
+def collect_warnings() -> Iterator[list[tuple[str, type[Warning]]]]:
+    """Collect what :func:`warn` would emit in this context, instead of emitting it.
+
+    The collection lives in a :class:`~contextvars.ContextVar`, so it touches
+    no global warning state and concurrent threads or tasks keep their own.
+    """
+    collected: list[tuple[str, type[Warning]]] = []
+    token = _collected.set(collected)
+    try:
+        yield collected
+    finally:
+        _collected.reset(token)

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

@@ -562,6 +562,11 @@ def prov_to_dot(
 
     Returns:
         The :class:`pydot.Dot` graph object.
+
+    Warns:
+        ProvFutureRejectionWarning: Propagated from
+            :meth:`~prov.model.ProvBundle.unified`. In prov 3.3.0 that call
+            raises instead, and the bundle is drawn as asserted.
     """
     if direction not in {"BT", "TB", "LR", "RL"}:
         # Invalid direction is provided

{prov-3.2.2 → prov-3.2.3}/src/prov/graph.py

@@ -106,6 +106,9 @@ def prov_to_graph(prov_document: ProvDocument) -> nx.MultiDiGraph[Any]:
             formal attributes is unset, or because an undeclared endpoint's
             element type cannot be inferred (its attribute has no
             :data:`INFERRED_ELEMENT_CLASS` entry).
+        ProvFutureRejectionWarning: Propagated from
+            :meth:`~prov.model.ProvBundle.unified`, which prov 3.3.0 makes
+            raise instead.
     """
     g: nx.MultiDiGraph[Any] = nx.MultiDiGraph()
     unified = prov_document.unified()

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

@@ -1,10 +1,10 @@
 from __future__ import annotations  # defer eval: Namespace used before it's defined
 
 import re
-import warnings
+from contextvars import ContextVar
 from typing import Any, Final
 
-from prov._warnings import ProvWarning, external_stacklevel
+from prov._warnings import ProvFutureRejectionWarning, future_rejection_message, warn
 
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
@@ -92,6 +92,22 @@ _PROVN_LOCAL_NEEDS_ESCAPE = re.compile(
     + f"|{_PROVN_LOCAL_NEEDS_PERCENT_ENCODING.pattern}"
 )
 
+# One search settles the common case in provn_bare_representation(): a local
+# part this does not match is written as it stands, with no warning.
+_PROVN_LOCAL_NOT_PLAIN = re.compile(
+    f"^{_PN_LOCAL_BAD_START.pattern}|{_PROVN_LOCAL_NEEDS_ESCAPE.pattern}"
+)
+# A local part PROV-N writes without percent-encoding. A '%' falls outside it,
+# so a local part holding one goes to _provn_escape_local() to be settled.
+_PROVN_LOCAL_WRITABLE = re.compile(
+    f"(?!{_PN_LOCAL_BAD_START.pattern})[{_PROVN_LOCAL_ALLOWED_UNESCAPED}]*"
+)
+
+# False while Namespace._adopt() copies a name that was checked when first built.
+_check_local_parts: ContextVar[bool] = ContextVar(
+    "prov_check_local_parts", default=True
+)
+
 
 def _slot_state(state: Any) -> dict[str, Any]:
     """Normalise a pickled state to a dict.
@@ -116,10 +132,12 @@ def _escape_local_char(
         # 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
+        # An existing valid escape (e.g. "%20") is kept verbatim. A bare
+        # '%' not followed by two hex digits is written as "%25", which a
+        # PROV-N reader keeps as that text, so it counts as encoded.
+        if _PROVN_HEX_PAIR.match(localpart, i + 1):
+            return char, False
+        return "%25", True
     if (
         (i == 0 and char in _PROVN_LOCAL_LEADING_ESCAPE)
         or (i == last_index and char == ".")
@@ -141,7 +159,8 @@ def _provn_escape_local(localpart: str) -> tuple[str, bool]:
     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.
+    percent-encoded character, or a bare ``%`` written as ``%25``, 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])
@@ -170,16 +189,28 @@ def _provn_escape_local_and_warn(localpart: str, uri: str) -> str:
     """
     escaped, encoded = _provn_escape_local(localpart)
     if encoded:
-        warnings.warn(
+        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(),
+            "reader recovers"
         )
     return escaped
 
 
+def _provn_string_literal(value: str) -> str:
+    """Quote ``value`` as a PROV-N string, triple-quoted if it has a line feed."""
+    # Escape backslashes first, so quote-escaping below doesn't re-escape
+    # the backslashes it just introduced.
+    s = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    if "\n" in s:
+        return f'"""{s}"""'
+    else:
+        # STRING_LITERAL2 ([60]) forbids a bare CR in a short string; the
+        # lexer decodes the "\r" escape, so use it rather than emit one raw.
+        s = s.replace("\r", "\\r")
+        return f'"{s}"'
+
+
 class Identifier:
     """Base class for all identifiers and also represents xsd:anyURI."""
 
@@ -229,7 +260,7 @@ class Identifier:
         return self._uri
 
     def __eq__(self, other: Any) -> bool:
-        return self.uri == other.uri if isinstance(other, Identifier) else False
+        return self._uri == other._uri if isinstance(other, Identifier) else False
 
     def __hash__(self) -> int:
         return self._hash
@@ -239,7 +270,7 @@ class Identifier:
 
     def provn_representation(self) -> str:
         """Return the PROV-N representation of this identifier as an xsd:anyURI literal."""
-        return f'"{self._uri}" %% xsd:anyURI'
+        return f"{_provn_string_literal(self._uri)} %% xsd:anyURI"
 
 
 class QualifiedName(Identifier):
@@ -271,7 +302,9 @@ class QualifiedName(Identifier):
         Args:
             namespace (Namespace): The namespace object containing a URI and optional
                 prefix associated with this qualified name.
-            localpart (str): The local part of the qualified name.
+            localpart (str): The local part of the qualified name. One that
+                PROV-N cannot write without changing the IRI, such as
+                ``"a b"``, emits a :class:`~prov.model.ProvFutureRejectionWarning`.
         """
         Identifier.__init__(self, "".join([namespace.uri, localpart]))
         self._namespace = namespace
@@ -279,6 +312,21 @@ class QualifiedName(Identifier):
         self._str = (
             ":".join([namespace.prefix, localpart]) if namespace.prefix else localpart
         )
+        # An ASCII identifier, the usual local part, needs no regex.
+        if (
+            not (localpart.isascii() and localpart.isidentifier())
+            and not _PROVN_LOCAL_WRITABLE.fullmatch(localpart)
+            and _check_local_parts.get()
+            and _provn_escape_local(localpart)[1]
+        ):
+            warn(
+                future_rejection_message(
+                    f"the local part {localpart!r} of <{self._uri}> contains a "
+                    "character PROV-N cannot write",
+                    issue=524,
+                ),
+                ProvFutureRejectionWarning,
+            )
 
     def _compute_hash(self) -> int:
         """Hash by URI alone, as the base class does; kept explicit because
@@ -341,12 +389,11 @@ class QualifiedName(Identifier):
                 "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
-            else escaped_localpart
-        )
+        localpart = self._localpart
+        if _PROVN_LOCAL_NOT_PLAIN.search(localpart):
+            localpart = _provn_escape_local_and_warn(localpart, self._uri)
+        prefix = self._namespace.prefix
+        return f"{prefix}:{localpart}" if prefix else localpart
 
     def provn_representation(self) -> str:
         """Return the PROV-N representation of this qualified name as a quoted string."""
@@ -390,7 +437,7 @@ class Namespace:
         """Namespace prefix."""
         return self._prefix
 
-    def contains(self, identifier: Identifier) -> bool:
+    def contains(self, identifier: str | Identifier) -> bool:
         """Check whether the given identifier's URI is contained in this namespace.
 
         Args:
@@ -429,18 +476,11 @@ class Namespace:
 
     def __eq__(self, other: Any) -> bool:
         return (
-            (self._uri == other.uri and self._prefix == other.prefix)
+            (self._uri == other._uri and self._prefix == other._prefix)
             if isinstance(other, Namespace)
             else False
         )
 
-    def __ne__(self, other: Any) -> bool:
-        return (
-            not isinstance(other, Namespace)
-            or self._uri != other.uri
-            or self._prefix != other.prefix
-        )
-
     def __hash__(self) -> int:
         return hash((self._uri, self._prefix))
 
@@ -460,6 +500,21 @@ class Namespace:
         object.__setattr__(self, "_uri", state["_uri"])
         object.__setattr__(self, "_cache", {})
 
+    def _adopt(self, qname: QualifiedName) -> QualifiedName:
+        """Return ``qname``'s local part in this namespace, without a second check.
+
+        ``qname`` was checked when it was built, so the copy a bundle makes in
+        its own namespace does not repeat the warning.
+        """
+        localpart = qname.localpart
+        if localpart in self._cache:
+            return self._cache[localpart]
+        token = _check_local_parts.set(False)
+        try:
+            return self[localpart]
+        finally:
+            _check_local_parts.reset(token)
+
     def __getitem__(self, localpart: str) -> QualifiedName:
         if localpart in self._cache:
             return self._cache[localpart]

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

@@ -22,7 +22,10 @@ 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._warnings import (
+    ProvFutureRejectionWarning as ProvFutureRejectionWarning,
+    ProvWarning as ProvWarning,
+)
 from prov.constants import *
 from prov.identifier import (
     Identifier as Identifier,