Voice et bot modif

venv/lib/python3.12/site-packages/packaging/markers.py

@@ -26,8 +26,22 @@ __all__ = [
     "default_environment",
 ]
 
+
+def __dir__() -> list[str]:
+    return __all__
+
+
 Operator = Callable[[str, Union[str, AbstractSet[str]]], bool]
 EvaluateContext = Literal["metadata", "lock_file", "requirement"]
+"""A ``typing.Literal`` enumerating valid marker evaluation contexts.
+
+Valid values for the ``context`` passed to :meth:`Marker.evaluate` are:
+
+* ``"metadata"`` (for core metadata; default)
+* ``"lock_file"`` (for lock files)
+* ``"requirement"`` (i.e. all other situations)
+"""
+
 MARKERS_ALLOWING_SET = {"extras", "dependency_groups"}
 MARKERS_REQUIRING_VERSION = {
     "implementation_version",
@@ -38,25 +52,32 @@ MARKERS_REQUIRING_VERSION = {
 
 
 class InvalidMarker(ValueError):
-    """
-    An invalid marker was found, users should refer to PEP 508.
+    """Raised when attempting to create a :class:`Marker` from invalid input.
+
+    This error indicates that the given marker string does not conform to the
+    :ref:`specification of dependency specifiers <pypug:dependency-specifiers>`.
     """
 
 
 class UndefinedComparison(ValueError):
-    """
-    An invalid operation was attempted on a value that doesn't support it.
+    """Raised when evaluating an unsupported marker comparison.
+
+    This can happen when marker values are compared as versions but do not
+    conform to the :ref:`specification of version specifiers
+    <pypug:version-specifiers>`.
     """
 
 
 class UndefinedEnvironmentName(ValueError):
-    """
-    A name was attempted to be used that does not exist inside of the
-    environment.
-    """
+    """Raised when evaluating a marker that references a missing environment key."""
 
 
 class Environment(TypedDict):
+    """
+    A dictionary that represents a Python environment as captured by
+    :func:`default_environment`. All fields are required.
+    """
+
     implementation_name: str
     """The implementation's identifier, e.g. ``'cpython'``."""
 
@@ -263,7 +284,7 @@ def _evaluate_markers(
     return any(all(item) for item in groups)
 
 
-def format_full_version(info: sys._version_info) -> str:
+def _format_full_version(info: sys._version_info) -> str:
     version = f"{info.major}.{info.minor}.{info.micro}"
     kind = info.releaselevel
     if kind != "final":
@@ -272,7 +293,11 @@ def format_full_version(info: sys._version_info) -> str:
 
 
 def default_environment() -> Environment:
-    iver = format_full_version(sys.implementation.version)
+    """Return the default marker environment for the current Python process.
+
+    This is the base environment used by :meth:`Marker.evaluate`.
+    """
+    iver = _format_full_version(sys.implementation.version)
     implementation_name = sys.implementation.name
     return {
         "implementation_name": implementation_name,
@@ -290,6 +315,27 @@ def default_environment() -> Environment:
 
 
 class Marker:
+    """Represents a parsed dependency marker expression.
+
+    Marker expressions are parsed according to the
+    :ref:`specification of dependency specifiers <pypug:dependency-specifiers>`.
+
+    :param marker: The string representation of a marker expression.
+    :raises InvalidMarker: If ``marker`` cannot be parsed.
+
+    Instances are safe to serialize with :mod:`pickle`. They use a stable
+    format so the same pickle can be loaded in future packaging releases.
+
+    .. versionchanged:: 26.2
+
+        Added a stable pickle format. Pickles created with packaging 26.2+ can
+        be unpickled with future releases.  Backward compatibility with pickles
+        from packaging < 26.2 is supported but may be removed in a future
+        release.
+    """
+
+    __slots__ = ("_markers",)
+
     def __init__(self, marker: str) -> None:
         # Note: We create a Marker object without calling this constructor in
         #       packaging.requirements.Requirement. If any additional logic is
@@ -320,11 +366,21 @@ class Marker:
         except ParserSyntaxError as e:
             raise InvalidMarker(str(e)) from e
 
+    @classmethod
+    def _from_markers(cls, markers: MarkerList) -> Marker:
+        """Create a Marker instance from a pre-parsed marker tree.
+
+        This avoids re-parsing serialised marker strings when combining markers.
+        """
+        new = cls.__new__(cls)
+        new._markers = markers
+        return new
+
     def __str__(self) -> str:
         return _format_marker(self._markers)
 
     def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}('{self}')>"
+        return f"<{self.__class__.__name__}({str(self)!r})>"
 
     def __hash__(self) -> int:
         return hash(str(self))
@@ -335,6 +391,45 @@ class Marker:
 
         return str(self) == str(other)
 
+    def __getstate__(self) -> str:
+        # Return the marker expression string for compactness and stability.
+        # Internal Node objects are excluded; the string is re-parsed on load.
+        return str(self)
+
+    def __setstate__(self, state: object) -> None:
+        if isinstance(state, str):
+            # New format (26.2+): just the marker expression string.
+            try:
+                self._markers = _normalize_extra_values(_parse_marker(state))
+            except ParserSyntaxError as exc:
+                raise TypeError(f"Cannot restore Marker from {state!r}") from exc
+            return
+        if isinstance(state, dict) and "_markers" in state:
+            # Old format (packaging <= 26.1, no __slots__): plain __dict__.
+            markers = state["_markers"]
+            if isinstance(markers, list):
+                self._markers = markers
+                return
+        if isinstance(state, tuple) and len(state) == 2:
+            # Old format (packaging <= 26.1, __slots__): (None, {slot: value}).
+            _, slot_dict = state
+            if isinstance(slot_dict, dict) and "_markers" in slot_dict:
+                markers = slot_dict["_markers"]
+                if isinstance(markers, list):
+                    self._markers = markers
+                    return
+        raise TypeError(f"Cannot restore Marker from {state!r}")
+
+    def __and__(self, other: Marker) -> Marker:
+        if not isinstance(other, Marker):
+            return NotImplemented
+        return self._from_markers([self._markers, "and", other._markers])
+
+    def __or__(self, other: Marker) -> Marker:
+        if not isinstance(other, Marker):
+            return NotImplemented
+        return self._from_markers([self._markers, "or", other._markers])
+
     def evaluate(
         self,
         environment: Mapping[str, str | AbstractSet[str]] | None = None,
@@ -342,14 +437,23 @@ class Marker:
     ) -> bool:
         """Evaluate a marker.
 
-        Return the boolean from evaluating the given marker against the
-        environment. environment is an optional argument to override all or
-        part of the determined environment. The *context* parameter specifies what
-        context the markers are being evaluated for, which influences what markers
-        are considered valid. Acceptable values are "metadata" (for core metadata;
-        default), "lock_file", and "requirement" (i.e. all other situations).
+        Return the boolean from evaluating this marker against the environment.
+        The environment is determined from the current Python process unless
+        passed in explicitly.
+
+        :param environment: Mapping containing keys and values to override the
+           detected environment.
+        :param EvaluateContext context: The context in which the marker is
+            evaluated, which influences what marker names are considered valid.
+            Accepted values are ``"metadata"`` (for core metadata; default),
+            ``"lock_file"``, and ``"requirement"`` (i.e. all other situations).
+        :raises UndefinedComparison: If the marker uses a comparison on values
+            that are not valid versions per the :ref:`specification of version
+            specifiers <pypug:version-specifiers>`.
+        :raises UndefinedEnvironmentName: If the marker references a value that
+            is missing from the evaluation environment.
+        :returns: ``True`` if the marker matches, otherwise ``False``.
 
-        The environment is determined from the current Python process.
         """
         current_environment = cast(
             "dict[str, str | AbstractSet[str]]", default_environment()