pip 25.2__py3-none-any.whl → 26.0__py3-none-any.whl

pip/_internal/cli/cmdoptions.py

@@ -11,7 +11,6 @@ pass on state. To be consistent, all options will follow this design.
 # mypy: strict-optional=False
 from __future__ import annotations
 
-import importlib.util
 import logging
 import os
 import pathlib
@@ -28,7 +27,9 @@ from pip._internal.exceptions import CommandError
 from pip._internal.locations import USER_CACHE_DIR, get_src_prefix
 from pip._internal.models.format_control import FormatControl
 from pip._internal.models.index import PyPI
+from pip._internal.models.release_control import ReleaseControl
 from pip._internal.models.target_python import TargetPython
+from pip._internal.utils.datetime import parse_iso_datetime
 from pip._internal.utils.hashes import STRONG_HASHES
 from pip._internal.utils.misc import strtobool
 
@@ -101,6 +102,29 @@ def check_dist_restriction(options: Values, check_target: bool = False) -> None:
             )
 
 
+def check_build_constraints(options: Values) -> None:
+    """Function for validating build constraints options.
+
+    :param options: The OptionParser options.
+    """
+    if hasattr(options, "build_constraints") and options.build_constraints:
+        if not options.build_isolation:
+            raise CommandError(
+                "--build-constraint cannot be used with --no-build-isolation."
+            )
+
+        # Import here to avoid circular imports
+        from pip._internal.network.session import PipSession
+        from pip._internal.req.req_file import get_file_content
+
+        # Eagerly check build constraints file contents
+        # is valid so that we don't fail in when trying
+        # to check constraints in isolated build process
+        with PipSession() as session:
+            for constraint_file in options.build_constraints:
+                get_file_content(constraint_file, session)
+
+
 def _path_option_check(option: Option, opt: str, value: str) -> str:
     return os.path.expanduser(value)
 
@@ -161,8 +185,7 @@ require_virtualenv: Callable[..., Option] = partial(
     action="store_true",
     default=False,
     help=(
-        "Allow pip to only run in a virtual environment; "
-        "exit with an error otherwise."
+        "Allow pip to only run in a virtual environment; exit with an error otherwise."
     ),
 )
 
@@ -405,6 +428,54 @@ def find_links() -> Option:
     )
 
 
+def _handle_uploaded_prior_to(
+    option: Option, opt: str, value: str, parser: OptionParser
+) -> None:
+    """
+    This is an optparse.Option callback for the --uploaded-prior-to option.
+
+    Parses an ISO 8601 datetime string. If no timezone is specified in the string,
+    local timezone is used.
+
+    Note: This option only works with indexes that provide upload-time metadata
+    as specified in the simple repository API:
+    https://packaging.python.org/en/latest/specifications/simple-repository-api/
+    """
+    if value is None:
+        return None
+
+    try:
+        uploaded_prior_to = parse_iso_datetime(value)
+        # Use local timezone if no offset is given in the ISO string.
+        if uploaded_prior_to.tzinfo is None:
+            uploaded_prior_to = uploaded_prior_to.astimezone()
+        parser.values.uploaded_prior_to = uploaded_prior_to
+    except ValueError as exc:
+        msg = (
+            f"invalid value: {value!r}: {exc}. "
+            f"Expected an ISO 8601 datetime string, "
+            f"e.g '2023-01-01' or '2023-01-01T00:00:00Z'"
+        )
+        raise_option_error(parser, option=option, msg=msg)
+
+
+def uploaded_prior_to() -> Option:
+    return Option(
+        "--uploaded-prior-to",
+        dest="uploaded_prior_to",
+        metavar="datetime",
+        action="callback",
+        callback=_handle_uploaded_prior_to,
+        type="str",
+        help=(
+            "Only consider packages uploaded prior to the given date time. "
+            "Accepts ISO 8601 strings (e.g., '2023-01-01T00:00:00Z'). "
+            "Uses local timezone if none specified. Only effective when "
+            "installing from indexes that provide upload-time metadata."
+        ),
+    )
+
+
 def trusted_host() -> Option:
     return Option(
         "--trusted-host",
@@ -430,6 +501,21 @@ def constraints() -> Option:
     )
 
 
+def build_constraints() -> Option:
+    return Option(
+        "--build-constraint",
+        dest="build_constraints",
+        action="append",
+        type="str",
+        default=[],
+        metavar="file",
+        help=(
+            "Constrain build dependencies using the given constraints file. "
+            "This option can be used multiple times."
+        ),
+    )
+
+
 def requirements() -> Option:
     return Option(
         "-r",
@@ -443,6 +529,18 @@ def requirements() -> Option:
     )
 
 
+def requirements_from_scripts() -> Option:
+    return Option(
+        "--requirements-from-script",
+        action="append",
+        default=[],
+        dest="requirements_from_scripts",
+        metavar="file",
+        help="Install dependencies of the given script file"
+        "as defined by PEP 723 inline metadata. ",
+    )
+
+
 def editable() -> Option:
     return Option(
         "-e",
@@ -544,6 +642,86 @@ def only_binary() -> Option:
     )
 
 
+def _get_release_control(values: Values, option: Option) -> Any:
+    """Get a release_control object."""
+    return getattr(values, option.dest)
+
+
+def _handle_all_releases(
+    option: Option, opt_str: str, value: str, parser: OptionParser
+) -> None:
+    existing = _get_release_control(parser.values, option)
+    existing.handle_mutual_excludes(
+        value,
+        existing.all_releases,
+        existing.only_final,
+        "all_releases",
+    )
+
+
+def _handle_only_final(
+    option: Option, opt_str: str, value: str, parser: OptionParser
+) -> None:
+    existing = _get_release_control(parser.values, option)
+    existing.handle_mutual_excludes(
+        value,
+        existing.only_final,
+        existing.all_releases,
+        "only_final",
+    )
+
+
+def all_releases() -> Option:
+    release_control = ReleaseControl(set(), set())
+    return Option(
+        "--all-releases",
+        dest="release_control",
+        action="callback",
+        callback=_handle_all_releases,
+        type="str",
+        default=release_control,
+        help="Allow all release types (including pre-releases) for a package. "
+        "Can be supplied multiple times, and each time adds to the existing "
+        'value. Accepts either ":all:" to allow pre-releases for all '
+        'packages, ":none:" to empty the set (notice the colons), or one or '
+        "more package names with commas between them (no colons). Cannot be "
+        "used with --pre.",
+    )
+
+
+def only_final() -> Option:
+    release_control = ReleaseControl(set(), set())
+    return Option(
+        "--only-final",
+        dest="release_control",
+        action="callback",
+        callback=_handle_only_final,
+        type="str",
+        default=release_control,
+        help="Only allow final releases (no pre-releases) for a package. Can be "
+        "supplied multiple times, and each time adds to the existing value. "
+        'Accepts either ":all:" to disable pre-releases for all packages, '
+        '":none:" to empty the set, or one or more package names with commas '
+        "between them. Cannot be used with --pre.",
+    )
+
+
+def check_release_control_exclusive(options: Values) -> None:
+    """
+    Raise an error if --pre is used with --all-releases or --only-final,
+    and transform --pre into --all-releases :all: if used alone.
+    """
+    if not hasattr(options, "pre") or not options.pre:
+        return
+
+    release_control = options.release_control
+    if release_control.all_releases or release_control.only_final:
+        raise CommandError("--pre cannot be used with --all-releases or --only-final.")
+
+    # Transform --pre into --all-releases :all:
+    release_control.all_releases.add(":all:")
+
+
 platforms: Callable[..., Option] = partial(
     Option,
     "--platform",
@@ -796,6 +974,7 @@ ignore_requires_python: Callable[..., Option] = partial(
     help="Ignore the Requires-Python information.",
 )
 
+
 no_build_isolation: Callable[..., Option] = partial(
     Option,
     "--no-build-isolation",
@@ -813,62 +992,16 @@ check_build_deps: Callable[..., Option] = partial(
     dest="check_build_deps",
     action="store_true",
     default=False,
-    help="Check the build dependencies when PEP517 is used.",
+    help="Check the build dependencies.",
 )
 
 
-def _handle_no_use_pep517(
-    option: Option, opt: str, value: str, parser: OptionParser
-) -> None:
-    """
-    Process a value provided for the --no-use-pep517 option.
-
-    This is an optparse.Option callback for the no_use_pep517 option.
-    """
-    # Since --no-use-pep517 doesn't accept arguments, the value argument
-    # will be None if --no-use-pep517 is passed via the command-line.
-    # However, the value can be non-None if the option is triggered e.g.
-    # by an environment variable, for example "PIP_NO_USE_PEP517=true".
-    if value is not None:
-        msg = """A value was passed for --no-use-pep517,
-        probably using either the PIP_NO_USE_PEP517 environment variable
-        or the "no-use-pep517" config file option. Use an appropriate value
-        of the PIP_USE_PEP517 environment variable or the "use-pep517"
-        config file option instead.
-        """
-        raise_option_error(parser, option=option, msg=msg)
-
-    # If user doesn't wish to use pep517, we check if setuptools is installed
-    # and raise error if it is not.
-    packages = ("setuptools",)
-    if not all(importlib.util.find_spec(package) for package in packages):
-        msg = (
-            f"It is not possible to use --no-use-pep517 "
-            f"without {' and '.join(packages)} installed."
-        )
-        raise_option_error(parser, option=option, msg=msg)
-
-    # Otherwise, --no-use-pep517 was passed via the command-line.
-    parser.values.use_pep517 = False
-
-
 use_pep517: Any = partial(
     Option,
     "--use-pep517",
     dest="use_pep517",
     action="store_true",
-    default=None,
-    help="Use PEP 517 for building source distributions "
-    "(use --no-use-pep517 to force legacy behaviour).",
-)
-
-no_use_pep517: Any = partial(
-    Option,
-    "--no-use-pep517",
-    dest="use_pep517",
-    action="callback",
-    callback=_handle_no_use_pep517,
-    default=None,
+    default=True,
     help=SUPPRESS_HELP,
 )
 
@@ -901,30 +1034,11 @@ config_settings: Callable[..., Option] = partial(
     action="callback",
     callback=_handle_config_settings,
     metavar="settings",
-    help="Configuration settings to be passed to the PEP 517 build backend. "
+    help="Configuration settings to be passed to the build backend. "
     "Settings take the form KEY=VALUE. Use multiple --config-settings options "
     "to pass multiple keys to the backend.",
 )
 
-build_options: Callable[..., Option] = partial(
-    Option,
-    "--build-option",
-    dest="build_options",
-    metavar="options",
-    action="append",
-    help="Extra arguments to be supplied to 'setup.py bdist_wheel'.",
-)
-
-global_options: Callable[..., Option] = partial(
-    Option,
-    "--global-option",
-    dest="global_options",
-    action="append",
-    metavar="options",
-    help="Extra global options to be supplied to the setup.py "
-    "call before the install or bdist_wheel command.",
-)
-
 no_clean: Callable[..., Option] = partial(
     Option,
     "--no-clean",
@@ -1072,6 +1186,8 @@ use_new_feature: Callable[..., Option] = partial(
     default=[],
     choices=[
         "fast-deps",
+        "build-constraint",
+        "inprocess-build-deps",
     ]
     + ALWAYS_ENABLED_FEATURES,
     help="Enable new functionality, that may be backward incompatible.",
@@ -1134,5 +1250,18 @@ index_group: dict[str, Any] = {
         extra_index_url,
         no_index,
         find_links,
+        uploaded_prior_to,
+    ],
+}
+
+package_selection_group: dict[str, Any] = {
+    "name": "Package Selection Options",
+    "options": [
+        pre,
+        all_releases,
+        only_final,
+        no_binary,
+        only_binary,
+        prefer_binary,
     ],
 }

pip/_internal/cli/index_command.py

@@ -23,6 +23,8 @@ from pip._internal.cli.command_context import CommandContextMixIn
 if TYPE_CHECKING:
     from ssl import SSLContext
 
+    from pip._vendor.packaging.utils import NormalizedName
+
     from pip._internal.network.session import PipSession
 
 logger = logging.getLogger(__name__)
@@ -103,6 +105,7 @@ class SessionCommandMixin(CommandContextMixIn):
         session = PipSession(
             cache=os.path.join(cache_dir, "http-v2") if cache_dir else None,
             retries=retries if retries is not None else options.retries,
+            resume_retries=options.resume_retries,
             trusted_hosts=options.trusted_hosts,
             index_urls=self._get_index_urls(options),
             ssl_context=ssl_context,
@@ -149,6 +152,23 @@ class IndexGroupCommand(Command, SessionCommandMixin):
     This also corresponds to the commands that permit the pip version check.
     """
 
+    def should_exclude_prerelease(
+        self, options: Values, package_name: NormalizedName
+    ) -> bool:
+        """
+        Determine if pre-releases should be excluded for a package.
+        """
+        # Check per-package release control settings
+        if options.release_control:
+            allow_prereleases = options.release_control.allows_prereleases(package_name)
+            if allow_prereleases is True:
+                return False  # Include pre-releases
+            elif allow_prereleases is False:
+                return True  # Exclude pre-releases
+
+        # No specific setting: exclude prereleases by default
+        return True
+
     def handle_pip_version_check(self, options: Values) -> None:
         """
         Do the pip version check if not disabled.

pip/_internal/cli/main.py

@@ -8,12 +8,6 @@ import os
 import sys
 import warnings
 
-from pip._internal.cli.autocompletion import autocomplete
-from pip._internal.cli.main_parser import parse_command
-from pip._internal.commands import create_command
-from pip._internal.exceptions import PipError
-from pip._internal.utils import deprecation
-
 logger = logging.getLogger(__name__)
 
 
@@ -45,6 +39,17 @@ logger = logging.getLogger(__name__)
 
 
 def main(args: list[str] | None = None) -> int:
+    # NOTE: Lazy imports to speed up import of this module,
+    # which is imported from the pip console script. This doesn't
+    # speed up normal pip execution, but might be important in the future
+    # if we use ``multiprocessing`` module,
+    # which imports __main__ for each spawned subprocess.
+    from pip._internal.cli.autocompletion import autocomplete
+    from pip._internal.cli.main_parser import parse_command
+    from pip._internal.commands import create_command
+    from pip._internal.exceptions import PipError
+    from pip._internal.utils import deprecation
+
     if args is None:
         args = sys.argv[1:]
 

pip/_internal/cli/main_parser.py

@@ -6,6 +6,8 @@ import os
 import subprocess
 import sys
 
+from pip._vendor.rich.markup import escape
+
 from pip._internal.build_env import get_runnable_pip
 from pip._internal.cli import cmdoptions
 from pip._internal.cli.parser import ConfigOptionParser, UpdatingDefaultsHelpFormatter
@@ -39,7 +41,7 @@ def create_main_parser() -> ConfigOptionParser:
 
     # create command listing for description
     description = [""] + [
-        f"{name:27} {command_info.summary}"
+        f"[optparse.longargs]{name:27}[/] {escape(command_info.summary)}"
         for name, command_info in commands_dict.items()
     ]
     parser.description = "\n".join(description)

pip/_internal/cli/parser.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import logging
 import optparse
+import os
+import re
 import shutil
 import sys
 import textwrap
@@ -11,8 +13,12 @@ from collections.abc import Generator
 from contextlib import suppress
 from typing import Any, NoReturn
 
+from pip._vendor.rich.markup import escape
+from pip._vendor.rich.theme import Theme
+
 from pip._internal.cli.status_codes import UNKNOWN_ERROR
 from pip._internal.configuration import Configuration, ConfigurationError
+from pip._internal.utils.logging import PipConsole
 from pip._internal.utils.misc import redact_auth_from_url, strtobool
 
 logger = logging.getLogger(__name__)
@@ -21,6 +27,17 @@ logger = logging.getLogger(__name__)
 class PrettyHelpFormatter(optparse.IndentedHelpFormatter):
     """A prettier/less verbose help formatter for optparse."""
 
+    styles = {
+        "optparse.shortargs": "green",
+        "optparse.longargs": "cyan",
+        "optparse.groups": "bold blue",
+        "optparse.metavar": "yellow",
+    }
+    highlights = {
+        r"\s(-{1}[\w]+[\w-]*)": "shortargs",  # highlight -letter as short args
+        r"\s(-{2}[\w]+[\w-]*)": "longargs",  # highlight --words as long args
+    }
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         # help position must be aligned with __init__.parseopts.description
         kwargs["max_help_position"] = 30
@@ -29,61 +46,82 @@ class PrettyHelpFormatter(optparse.IndentedHelpFormatter):
         super().__init__(*args, **kwargs)
 
     def format_option_strings(self, option: optparse.Option) -> str:
-        return self._format_option_strings(option)
-
-    def _format_option_strings(
-        self, option: optparse.Option, mvarfmt: str = " <{}>", optsep: str = ", "
-    ) -> str:
-        """
-        Return a comma-separated list of option strings and metavars.
-
-        :param option:  tuple of (short opt, long opt), e.g: ('-f', '--format')
-        :param mvarfmt: metavar format string
-        :param optsep:  separator
-        """
+        """Return a comma-separated list of option strings and metavars."""
         opts = []
 
         if option._short_opts:
-            opts.append(option._short_opts[0])
+            opts.append(f"[optparse.shortargs]{option._short_opts[0]}[/]")
         if option._long_opts:
-            opts.append(option._long_opts[0])
+            opts.append(f"[optparse.longargs]{option._long_opts[0]}[/]")
         if len(opts) > 1:
-            opts.insert(1, optsep)
+            opts.insert(1, ", ")
 
         if option.takes_value():
             assert option.dest is not None
             metavar = option.metavar or option.dest.lower()
-            opts.append(mvarfmt.format(metavar.lower()))
+            opts.append(f" [optparse.metavar]<{escape(metavar.lower())}>[/]")
 
         return "".join(opts)
 
+    def format_option(self, option: optparse.Option) -> str:
+        """Overridden method with Rich support."""
+        # fmt: off
+        result = []
+        opts = self.option_strings[option]
+        opt_width = self.help_position - self.current_indent - 2
+        # Remove the rich style tags before calculating width during
+        # text wrap calculations. Also store the length removed to adjust
+        # the padding in the else branch.
+        stripped = re.sub(r"(\[[a-z.]+\])|(\[\/\])", "", opts)
+        style_tag_length = len(opts) - len(stripped)
+        if len(stripped) > opt_width:
+            opts = "%*s%s\n" % (self.current_indent, "", opts)  # noqa: UP031
+            indent_first = self.help_position
+        else:                       # start help on same line as opts
+            opts = "%*s%-*s  " % (self.current_indent, "",      # noqa: UP031
+                                  opt_width + style_tag_length, opts)
+            indent_first = 0
+        result.append(opts)
+        if option.help:
+            help_text = self.expand_default(option)
+            help_lines = textwrap.wrap(help_text, self.help_width)
+            result.append("%*s%s\n" % (indent_first, "", help_lines[0]))  # noqa: UP031
+            result.extend(["%*s%s\n" % (self.help_position, "", line)     # noqa: UP031
+                           for line in help_lines[1:]])
+        elif opts[-1] != "\n":
+            result.append("\n")
+        return "".join(result)
+        # fmt: on
+
     def format_heading(self, heading: str) -> str:
         if heading == "Options":
             return ""
-        return heading + ":\n"
+        return "[optparse.groups]" + escape(heading) + ":[/]\n"
 
     def format_usage(self, usage: str) -> str:
         """
         Ensure there is only one newline between usage and the first heading
         if there is no description.
         """
-        msg = "\nUsage: {}\n".format(self.indent_lines(textwrap.dedent(usage), "  "))
+        contents = self.indent_lines(textwrap.dedent(usage), "  ")
+        msg = f"\n[optparse.groups]Usage:[/] {escape(contents)}\n"
         return msg
 
     def format_description(self, description: str | None) -> str:
         # leave full control over description to us
         if description:
             if hasattr(self.parser, "main"):
-                label = "Commands"
+                label = "[optparse.groups]Commands:[/]"
             else:
-                label = "Description"
+                label = "[optparse.groups]Description:[/]"
+
             # some doc strings have initial newlines, some don't
             description = description.lstrip("\n")
             # some doc strings have final newlines and spaces, some don't
             description = description.rstrip()
             # dedent, then reindent
             description = self.indent_lines(textwrap.dedent(description), "  ")
-            description = f"{label}:\n{description}\n"
+            description = f"{label}\n{description}\n"
             return description
         else:
             return ""
@@ -91,10 +129,17 @@ class PrettyHelpFormatter(optparse.IndentedHelpFormatter):
     def format_epilog(self, epilog: str | None) -> str:
         # leave full control over epilog to us
         if epilog:
-            return epilog
+            return escape(epilog)
         else:
             return ""
 
+    def expand_default(self, option: optparse.Option) -> str:
+        """Overridden HelpFormatter.expand_default() which colorizes flags."""
+        help = escape(super().expand_default(option))
+        for regex, style in self.highlights.items():
+            help = re.sub(regex, rf"[optparse.{style}] \1[/]", help)
+        return help
+
     def indent_lines(self, text: str, indent: str) -> str:
         new_lines = [indent + line for line in text.split("\n")]
         return "\n".join(new_lines)
@@ -185,27 +230,29 @@ class ConfigOptionParser(CustomOptionParser):
         override_order = ["global", self.name, ":env:"]
 
         # Pool the options into different groups
-        section_items: dict[str, list[tuple[str, Any]]] = {
-            name: [] for name in override_order
+        # Use a dict because we need to implement the fallthrough logic after PR 12201
+        # was merged which removed the fallthrough logic for options
+        section_items_dict: dict[str, dict[str, Any]] = {
+            name: {} for name in override_order
         }
 
-        for _, value in self.config.items():  # noqa: PERF102
+        for _, value in self.config.items():
             for section_key, val in value.items():
-                # ignore empty values
-                if not val:
-                    logger.debug(
-                        "Ignoring configuration key '%s' as its value is empty.",
-                        section_key,
-                    )
-                    continue
 
                 section, key = section_key.split(".", 1)
                 if section in override_order:
-                    section_items[section].append((key, val))
+                    section_items_dict[section][key] = val
 
-            # Yield each group in their override order
-            for section in override_order:
-                yield from section_items[section]
+        # Now that we a dict of items per section, convert to list of tuples
+        # Make sure we completely remove empty values again
+        section_items = {
+            name: [(k, v) for k, v in section_items_dict[name].items() if v]
+            for name in override_order
+        }
+
+        # Yield each group in their override order
+        for section in override_order:
+            yield from section_items[section]
 
     def _update_defaults(self, defaults: dict[str, Any]) -> dict[str, Any]:
         """Updates the given defaults with values from the config files and
@@ -296,3 +343,16 @@ class ConfigOptionParser(CustomOptionParser):
     def error(self, msg: str) -> NoReturn:
         self.print_usage(sys.stderr)
         self.exit(UNKNOWN_ERROR, f"{msg}\n")
+
+    def print_help(self, file: Any = None) -> None:
+        # This is unfortunate but necessary since arguments may have not been
+        # parsed yet at this point, so detect --no-color manually.
+        no_color = (
+            "--no-color" in sys.argv
+            or bool(strtobool(os.environ.get("PIP_NO_COLOR", "no") or "no"))
+            or "NO_COLOR" in os.environ
+        )
+        console = PipConsole(
+            theme=Theme(PrettyHelpFormatter.styles), no_color=no_color, file=file
+        )
+        console.print(self.format_help().rstrip(), highlight=False)