Document markers.default_environment()

docs/conf.py

@@ -21,6 +21,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx_toolbox.more_autodoc.autotypeddict",
 ]
 
 # General information about the project.

docs/markers.rst

@@ -62,8 +62,8 @@ Reference
 
     Evaluate the marker given the context of the current Python process.
 
-    :param dict environment: A dictionary containing keys and values to
-                             override the detected environment.
+    :param Environment environment: A dictionary containing keys and values to
+                                    override the detected environment.
     :raises: UndefinedComparison: If the marker uses a comparison on strings
                                   which are not valid versions per the
                                   :ref:`specification of version specifiers
@@ -72,6 +72,18 @@ Reference
                                        isn't present inside of the environment
                                        dictionary.
 
+.. autotypeddict:: packaging.markers.Environment
+
+    A dictionary that represents a Python environment.
+
+.. function:: default_environment()
+
+    Returns a dictionary representing the current Python process. This is the
+    base environment that is used when evaluating markers in
+    :meth:`Marker.evaluate`.
+
+    :rtype: Environment
+
 .. exception:: InvalidMarker
 
     Raised when attempting to create a :class:`Marker` with a string that

docs/requirements.txt

@@ -1 +1,2 @@
 furo
+sphinx-toolbox

pyproject.toml

@@ -51,6 +51,7 @@ exclude_lines = ["pragma: no cover", "@abc.abstractmethod", "@abc.abstractproper
 strict = true
 show_error_codes = true
 enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+warn_unused_ignores = true
 
 [[tool.mypy.overrides]]
 module = ["_manylinux"]

src/packaging/_compat.py

@@ -0,0 +1,25 @@
+import sys
+import typing
+
+if sys.version_info[:2] >= (3, 8):  # pragma: no cover
+    from typing import Literal, TypedDict
+elif typing.TYPE_CHECKING:  # pragma: no cover
+    from typing_extensions import Literal, TypedDict
+else:  # pragma: no cover
+    try:
+        from typing_extensions import Literal, TypedDict
+    except ImportError:
+
+        class Literal:
+            def __init_subclass__(*_args, **_kwargs):
+                pass
+
+        class TypedDict:
+            def __init_subclass__(*_args, **_kwargs):
+                pass
+
+
+__all__ = [
+    "Literal",
+    "TypedDict",
+]

src/packaging/markers.py

@@ -8,6 +8,7 @@
 import sys
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
+from ._compat import TypedDict
 from ._parser import (
     MarkerAtom,
     MarkerList,
@@ -50,6 +51,22 @@ class UndefinedEnvironmentName(ValueError):
     """
 
 
+class Environment(TypedDict, total=False):
+    implementation_name: str
+    implementation_version: str
+    os_name: str
+    platform_machine: str
+    platform_release: str
+    platform_system: str
+    platform_version: str
+    python_full_version: str
+    platform_python_implementation: str
+    python_version: str
+    sys_platform: str
+
+    extra: Optional[str]
+
+
 def _normalize_extra_values(results: Any) -> Any:
     """
     Normalize extra values.
@@ -134,10 +151,11 @@ def _normalize(*values: str, key: str) -> Tuple[str, ...]:
     return values
 
 
-def _evaluate_markers(markers: MarkerList, environment: Dict[str, str]) -> bool:
+def _evaluate_markers(markers: MarkerList, environment: Environment) -> bool:
     groups: List[List[bool]] = [[]]
 
     for marker in markers:
+
         assert isinstance(marker, (list, tuple, str))
 
         if isinstance(marker, list):
@@ -147,12 +165,12 @@ def _evaluate_markers(markers: MarkerList, environment: Dict[str, str]) -> bool:
 
             if isinstance(lhs, Variable):
                 environment_key = lhs.value
-                lhs_value = environment[environment_key]
+                lhs_value = environment[environment_key]  # type: ignore[literal-required] # noqa: E501
                 rhs_value = rhs.value
             else:
                 lhs_value = lhs.value
                 environment_key = rhs.value
-                rhs_value = environment[environment_key]
+                rhs_value = environment[environment_key]  # type: ignore[literal-required] # noqa: E501
 
             lhs_value, rhs_value = _normalize(lhs_value, rhs_value, key=environment_key)
             groups[-1].append(_eval_op(lhs_value, op, rhs_value))
@@ -172,7 +190,7 @@ def format_full_version(info: "sys._version_info") -> str:
     return version
 
 
-def default_environment() -> Dict[str, str]:
+def default_environment() -> Environment:
     iver = format_full_version(sys.implementation.version)
     implementation_name = sys.implementation.name
     return {
@@ -231,7 +249,7 @@ def __eq__(self, other: Any) -> bool:
 
         return str(self) == str(other)
 
-    def evaluate(self, environment: Optional[Dict[str, str]] = None) -> bool:
+    def evaluate(self, environment: Optional[Environment] = None) -> bool:
         """Evaluate a marker.
 
         Return the boolean from evaluating the given marker against the

src/packaging/metadata.py

@@ -3,7 +3,6 @@
 import email.message
 import email.parser
 import email.policy
-import sys
 import typing
 from typing import (
     Any,
@@ -19,25 +18,9 @@
 )
 
 from . import requirements, specifiers, utils, version as version_module
+from ._compat import Literal, TypedDict
 
 T = typing.TypeVar("T")
-if sys.version_info[:2] >= (3, 8):  # pragma: no cover
-    from typing import Literal, TypedDict
-else:  # pragma: no cover
-    if typing.TYPE_CHECKING:
-        from typing_extensions import Literal, TypedDict
-    else:
-        try:
-            from typing_extensions import Literal, TypedDict
-        except ImportError:
-
-            class Literal:
-                def __init_subclass__(*_args, **_kwargs):
-                    pass
-
-            class TypedDict:
-                def __init_subclass__(*_args, **_kwargs):
-                    pass
 
 
 try: