from __future__ import annotations import contextlib import functools import os import sys from typing import Literal, Protocol, cast from pip._internal.utils.deprecation import deprecated from pip._internal.utils.misc import strtobool from .base import BaseDistribution, BaseEnvironment, FilesystemWheel, MemoryWheel, Wheel __all__ = [ "BaseDistribution", "BaseEnvironment", "FilesystemWheel", "MemoryWheel", "Wheel", "get_default_environment", "get_environment", "get_wheel_distribution", "select_backend", ] def _should_use_importlib_metadata() -> bool: """Whether to use the ``importlib.metadata`` or ``pkg_resources`` backend. By default, pip uses ``importlib.metadata`` on Python 3.11+, and ``pkg_resources`` otherwise. Up to Python 3.13, This can be overridden by a couple of ways: * If environment variable ``_PIP_USE_IMPORTLIB_METADATA`` is set, it dictates whether ``importlib.metadata`` is used, for Python <3.14. * On Python 3.11, 3.12 and 3.13, Python distributors can patch ``importlib.metadata`` to add a global constant ``_PIP_USE_IMPORTLIB_METADATA = False``. This makes pip use ``pkg_resources`` (unless the user set the aforementioned environment variable to *True*). On Python 3.14+, the ``pkg_resources`` backend cannot be used. """ if sys.version_info >= (3, 14): # On Python >=3.14 we only support importlib.metadata. return True with contextlib.suppress(KeyError, ValueError): # On Python <3.14, if the environment variable is set, we obey what it says. return bool(strtobool(os.environ["_PIP_USE_IMPORTLIB_METADATA"])) if sys.version_info < (3, 11): # On Python <3.11, we always use pkg_resources, unless the environment # variable was set. return False # On Python 3.11, 3.12 and 3.13, we check if the global constant is set. import importlib.metadata return bool(getattr(importlib.metadata, "_PIP_USE_IMPORTLIB_METADATA", True)) def _emit_pkg_resources_deprecation_if_needed() -> None: if sys.version_info < (3, 11): # All pip versions supporting Python<=3.11 will support pkg_resources, # and pkg_resources is the default for these, so let's not bother users. return import importlib.metadata if hasattr(importlib.metadata, "_PIP_USE_IMPORTLIB_METADATA"): # The Python distributor has set the global constant, so we don't # warn, since it is not a user decision. return # The user has decided to use pkg_resources, so we warn. deprecated( reason="Using the pkg_resources metadata backend is deprecated.", replacement=( "to use the default importlib.metadata backend, " "by unsetting the _PIP_USE_IMPORTLIB_METADATA environment variable" ), gone_in="26.3", issue=13317, ) class Backend(Protocol): NAME: Literal["importlib", "pkg_resources"] Distribution: type[BaseDistribution] Environment: type[BaseEnvironment] @functools.cache def select_backend() -> Backend: if _should_use_importlib_metadata(): from . import importlib return cast(Backend, importlib) _emit_pkg_resources_deprecation_if_needed() from . import pkg_resources return cast(Backend, pkg_resources) def get_default_environment() -> BaseEnvironment: """Get the default representation for the current environment. This returns an Environment instance from the chosen backend. The default Environment instance should be built from ``sys.path`` and may use caching to share instance state across calls. """ return select_backend().Environment.default() def get_environment(paths: list[str] | None) -> BaseEnvironment: """Get a representation of the environment specified by ``paths``. This returns an Environment instance from the chosen backend based on the given import paths. The backend must build a fresh instance representing the state of installed distributions when this function is called. """ return select_backend().Environment.from_paths(paths) def get_directory_distribution(directory: str) -> BaseDistribution: """Get the distribution metadata representation in the specified directory. This returns a Distribution instance from the chosen backend based on the given on-disk ``.dist-info`` directory. """ return select_backend().Distribution.from_directory(directory) def get_wheel_distribution(wheel: Wheel, canonical_name: str) -> BaseDistribution: """Get the representation of the specified wheel's distribution metadata. This returns a Distribution instance from the chosen backend based on the given wheel's ``.dist-info`` directory. :param canonical_name: Normalized project name of the given wheel. """ return select_backend().Distribution.from_wheel(wheel, canonical_name) def get_metadata_distribution( metadata_contents: bytes, filename: str, canonical_name: str, ) -> BaseDistribution: """Get the dist representation of the specified METADATA file contents. This returns a Distribution instance from the chosen backend sourced from the data in `metadata_contents`. :param metadata_contents: Contents of a METADATA file within a dist, or one served via PEP 658. :param filename: Filename for the dist this metadata represents. :param canonical_name: Normalized project name of the given dist. """ return select_backend().Distribution.from_metadata_file_contents( metadata_contents, filename, canonical_name, )