pex 2.54.2__py2.py3-none-any.whl → 2.69.0__py2.py3-none-any.whl

pex/cli/commands/pip/core.py

@@ -133,11 +133,9 @@ def download_distributions(configuration):
                     requirements=requirement_configuration.requirements,
                     requirement_files=requirement_configuration.requirement_files,
                     constraint_files=requirement_configuration.constraint_files,
-                    indexes=resolver_configuration.repos_configuration.indexes,
-                    find_links=resolver_configuration.repos_configuration.find_links,
+                    repos_configuration=resolver_configuration.repos_configuration,
                     resolver_version=pip_configuration.resolver_version,
                     network_configuration=resolver_configuration.network_configuration,
-                    password_entries=pip_configuration.repos_configuration.password_entries,
                     build_configuration=pip_configuration.build_configuration,
                     transitive=pip_configuration.transitive,
                     max_parallel_jobs=pip_configuration.max_jobs,
@@ -162,11 +160,9 @@ def download_distributions(configuration):
                     extras=resolver_configuration.extras,
                     dependency_groups=resolver_configuration.dependency_groups,
                     constraint_files=requirement_configuration.constraint_files,
-                    indexes=resolver_configuration.repos_configuration.indexes,
-                    find_links=resolver_configuration.repos_configuration.find_links,
+                    repos_configuration=resolver_configuration.repos_configuration,
                     resolver_version=pip_configuration.resolver_version,
                     network_configuration=resolver_configuration.network_configuration,
-                    password_entries=pip_configuration.repos_configuration.password_entries,
                     build_configuration=pip_configuration.build_configuration,
                     transitive=pip_configuration.transitive,
                     max_parallel_jobs=pip_configuration.max_jobs,
@@ -188,11 +184,9 @@ def download_distributions(configuration):
                     constraint_files=requirement_configuration.constraint_files,
                     allow_prereleases=pip_configuration.allow_prereleases,
                     transitive=pip_configuration.transitive,
-                    indexes=resolver_configuration.repos_configuration.indexes,
-                    find_links=resolver_configuration.repos_configuration.find_links,
+                    repos_configuration=resolver_configuration.repos_configuration,
                     resolver_version=pip_configuration.resolver_version,
                     network_configuration=resolver_configuration.network_configuration,
-                    password_entries=pip_configuration.repos_configuration.password_entries,
                     build_configuration=pip_configuration.build_configuration,
                     max_parallel_jobs=pip_configuration.max_jobs,
                     pip_log=pip_configuration.log,
@@ -229,10 +223,8 @@ def build_wheels(
         package_index_configuration=PackageIndexConfiguration.create(
             pip_version=configuration.pip_configuration.version,
             resolver_version=configuration.pip_configuration.resolver_version,
-            indexes=configuration.pip_configuration.repos_configuration.indexes,
-            find_links=configuration.pip_configuration.repos_configuration.find_links,
+            repos_configuration=configuration.pip_configuration.repos_configuration,
             network_configuration=configuration.pip_configuration.network_configuration,
-            password_entries=configuration.pip_configuration.repos_configuration.password_entries,
             use_pip_config=configuration.pip_configuration.use_pip_config,
             extra_pip_requirements=configuration.pip_configuration.extra_requirements,
             keyring_provider=configuration.pip_configuration.keyring_provider,

pex/cli/commands/pip/wheel.py

@@ -55,7 +55,7 @@ class Wheel(BuildTimeCommand):
                     core.build_wheels(
                         configuration,
                         tuple(
-                            BuildRequest.create(
+                            BuildRequest.for_file(
                                 target=target,
                                 source_path=sdist.path,
                                 subdirectory=sdist.subdirectory,

pex/cli/commands/run.py

@@ -10,12 +10,11 @@ import os.path
 import posixpath
 import shutil
 import sys
-import tarfile
 from argparse import _ActionsContainer
-from contextlib import closing
 
 from pex import dependency_configuration, interpreter
 from pex import resolver as pip_resolver
+from pex import sdist
 from pex.artifact_url import ArtifactURL, Fingerprint
 from pex.atomic_directory import atomic_directory
 from pex.build_system import pep_517
@@ -616,11 +615,9 @@ class Run(CacheAwareMixin, BuildTimeCommand):
             constraint_files=run_spec.all_requirements.constraint_files,
             allow_prereleases=pip_configuration.allow_prereleases,
             transitive=False,
-            indexes=pip_configuration.repos_configuration.indexes,
-            find_links=pip_configuration.repos_configuration.find_links,
+            repos_configuration=pip_configuration.repos_configuration,
             resolver_version=pip_configuration.resolver_version,
             network_configuration=pip_configuration.network_configuration,
-            password_entries=pip_configuration.repos_configuration.password_entries,
             build_configuration=pip_configuration.build_configuration,
             max_parallel_jobs=pip_configuration.max_jobs,
             pip_log=pip_configuration.log,
@@ -678,19 +675,19 @@ class Run(CacheAwareMixin, BuildTimeCommand):
                         return package, os.path.join(lock_dest_dir, lock_path)
         elif is_sdist(distribution.path):
             if is_tar_sdist(distribution.path):
-                with closing(tarfile.open(distribution.path)) as tf:
-                    tf.extractall(lock_dest_dir)
+                sdist_root = sdist.extract_tarball(distribution.path, dest_dir=lock_dest_dir)
             else:
                 with open_zip(distribution.path) as zf:
                     zf.extractall(lock_dest_dir)
-            entries = glob.glob(os.path.join(lock_dest_dir, "*"))
-            if len(entries) != 1:
-                return Error(
-                    "Expected {sdist} to have 1 entry, found {count}: {entries}".format(
-                        sdist=distribution.path, count=len(entries), entries=entries
+                entries = glob.glob(os.path.join(lock_dest_dir, "*"))
+                if len(entries) != 1:
+                    return Error(
+                        "Expected {sdist} to have 1 entry, found {count}: {entries}".format(
+                            sdist=distribution.path, count=len(entries), entries=entries
+                        )
                     )
-                )
-            sdist_root = entries[0]
+                sdist_root = entries[0]
+
             for lock_name in run_spec.locks:
                 lock_path = os.path.join(sdist_root, lock_name)
                 if os.path.exists(lock_path):
@@ -724,11 +721,9 @@ class Run(CacheAwareMixin, BuildTimeCommand):
                 requirements=run_spec.all_requirements.requirements,
                 requirement_files=run_spec.all_requirements.requirement_files,
                 constraint_files=run_spec.all_requirements.constraint_files,
-                indexes=pip_configuration.repos_configuration.indexes,
-                find_links=pip_configuration.repos_configuration.find_links,
+                repos_configuration=pip_configuration.repos_configuration,
                 resolver_version=pip_configuration.resolver_version,
                 network_configuration=pip_configuration.network_configuration,
-                password_entries=pip_configuration.repos_configuration.password_entries,
                 build_configuration=pip_configuration.build_configuration,
                 transitive=pip_configuration.transitive,
                 max_parallel_jobs=pip_configuration.max_jobs,
@@ -746,11 +741,9 @@ class Run(CacheAwareMixin, BuildTimeCommand):
                 constraint_files=run_spec.all_requirements.constraint_files,
                 allow_prereleases=pip_configuration.allow_prereleases,
                 transitive=pip_configuration.transitive,
-                indexes=pip_configuration.repos_configuration.indexes,
-                find_links=pip_configuration.repos_configuration.find_links,
+                repos_configuration=pip_configuration.repos_configuration,
                 resolver_version=pip_configuration.resolver_version,
                 network_configuration=pip_configuration.network_configuration,
-                password_entries=pip_configuration.repos_configuration.password_entries,
                 build_configuration=pip_configuration.build_configuration,
                 max_parallel_jobs=pip_configuration.max_jobs,
                 pip_log=pip_configuration.log,

pex/cli/commands/venv.py

@@ -8,14 +8,17 @@ import logging
 import os.path
 from argparse import ArgumentParser, _ActionsContainer
 
-from pex import pex_warnings
+from pex import dependency_configuration, pex_warnings
 from pex.cli.command import BuildTimeCommand
 from pex.commands.command import JsonMixin, OutputMixin
 from pex.common import CopyMode, open_zip, pluralize
-from pex.dist_metadata import Distribution
+from pex.dependency_configuration import DependencyConfiguration
+from pex.dist_metadata import Distribution, Requirement
 from pex.enum import Enum
 from pex.executables import is_python_script, is_script
 from pex.executor import Executor
+from pex.fingerprinted_distribution import FingerprintedDistribution
+from pex.orderedset import OrderedSet
 from pex.pex import PEX
 from pex.pex_info import PexInfo
 from pex.resolve import configured_resolve, requirement_options, resolver_options, target_options
@@ -23,6 +26,7 @@ from pex.resolve.resolver_configuration import (
     LockRepositoryConfiguration,
     PexRepositoryConfiguration,
     PipConfiguration,
+    PylockRepositoryConfiguration,
 )
 from pex.result import Error, Ok, Result, try_
 from pex.targets import LocalInterpreter, Target, Targets
@@ -35,7 +39,7 @@ from pex.venv.installer_configuration import InstallerConfiguration
 from pex.venv.virtualenv import Virtualenv
 
 if TYPE_CHECKING:
-    from typing import Any, Dict, Iterable, Optional
+    from typing import Any, Dict, Iterable, Optional, Sequence
 
 
 logger = logging.getLogger(__name__)
@@ -123,8 +127,10 @@ class Venv(OutputMixin, JsonMixin, BuildTimeCommand):
             include_pex_lock=True,
             include_pylock=True,
             include_pre_resolved=True,
+            include_venv_repository=True,
         )
         requirement_options.register(parser)
+        dependency_configuration.register(parser)
 
     @classmethod
     def add_extra_arguments(
@@ -285,11 +291,13 @@ class Venv(OutputMixin, JsonMixin, BuildTimeCommand):
                 )
 
         requirement_configuration = requirement_options.configure(self.options)
+        dependency_config = dependency_configuration.configure(self.options)
         with TRACER.timed("Resolving distributions"):
             resolved = configured_resolve.resolve(
                 targets=targets,
                 requirement_configuration=requirement_configuration,
                 resolver_configuration=resolver_configuration,
+                dependency_configuration=dependency_config,
             )
 
         pex = None  # type: Optional[PEX]
@@ -298,6 +306,8 @@ class Venv(OutputMixin, JsonMixin, BuildTimeCommand):
             pex = PEX(resolver_configuration.pex_repository, interpreter=target.get_interpreter())
         elif isinstance(resolver_configuration, LockRepositoryConfiguration):
             lock = resolver_configuration.lock_file_path
+        elif isinstance(resolver_configuration, PylockRepositoryConfiguration):
+            lock = resolver_configuration.lock_file_path
 
         with TRACER.timed(
             "Installing {count} {wheels} in {subject} at {dest_dir}".format(
@@ -308,10 +318,6 @@ class Venv(OutputMixin, JsonMixin, BuildTimeCommand):
             )
         ):
             hermetic_scripts = not update and installer_configuration.hermetic_scripts
-            distributions = tuple(
-                resolved_distribution.distribution
-                for resolved_distribution in resolved.distributions
-            )
             provenance = (
                 Provenance.create(venv=venv)
                 if venv
@@ -322,27 +328,41 @@ class Venv(OutputMixin, JsonMixin, BuildTimeCommand):
                     pex=pex,
                     installer_configuration=installer_configuration,
                     provenance=provenance,
-                    distributions=distributions,
+                    distributions=tuple(
+                        resolved_distribution.distribution
+                        for resolved_distribution in resolved.distributions
+                    ),
                     dest_dir=dest_dir,
                     hermetic_scripts=hermetic_scripts,
                     venv=venv,
                 )
             elif venv:
-                installer.populate_venv_distributions(
+                _install_from_resolve(
                     venv=venv,
-                    distributions=distributions,
                     provenance=provenance,
-                    copy_mode=(
-                        CopyMode.COPY
-                        if installer_configuration.site_packages_copies
-                        else CopyMode.LINK
+                    installer_configuration=installer_configuration,
+                    dependency_config=dependency_config,
+                    requirements=tuple(
+                        OrderedSet(
+                            itertools.chain.from_iterable(
+                                resolved_distribution.direct_requirements
+                                for resolved_distribution in resolved.distributions
+                            )
+                        )
+                    ),
+                    distributions=tuple(
+                        resolved_distribution.fingerprinted_distribution
+                        for resolved_distribution in resolved.distributions
                     ),
                     hermetic_scripts=hermetic_scripts,
                 )
             else:
                 installer.populate_flat_distributions(
                     dest_dir=dest_dir,
-                    distributions=distributions,
+                    distributions=tuple(
+                        resolved_distribution.distribution
+                        for resolved_distribution in resolved.distributions
+                    ),
                     provenance=provenance,
                     copy_mode=(
                         CopyMode.COPY
@@ -366,7 +386,10 @@ class Venv(OutputMixin, JsonMixin, BuildTimeCommand):
                 try_(
                     installer.ensure_pip_installed(
                         venv,
-                        distributions=distributions,
+                        distributions=tuple(
+                            resolved_distribution.distribution
+                            for resolved_distribution in resolved.distributions
+                        ),
                         scope=installer_configuration.scope,
                         collisions_ok=installer_configuration.collisions_ok,
                         source=source,
@@ -439,3 +462,49 @@ def _install_from_pex(
             )
         else:
             installer.populate_flat_sources(dst=dest_dir, pex=pex, provenance=provenance)
+
+
+def _install_from_resolve(
+    venv,  # type: Virtualenv
+    provenance,  # type: Provenance
+    installer_configuration,  # type: InstallerConfiguration
+    dependency_config,  # type: DependencyConfiguration
+    requirements,  # type: Sequence[Requirement]
+    distributions,  # type: Sequence[FingerprintedDistribution]
+    hermetic_scripts,  # type: bool
+):
+    # type: (...) -> None
+
+    activated_dists = tuple(dist.distribution for dist in distributions)
+    installer.populate_venv_distributions(
+        venv=venv,
+        distributions=activated_dists,
+        provenance=provenance,
+        copy_mode=(
+            CopyMode.COPY if installer_configuration.site_packages_copies else CopyMode.LINK
+        ),
+        hermetic_scripts=hermetic_scripts,
+    )
+
+    pex_info = PexInfo.default()
+    pex_info.includes_tools = False
+    pex_info.venv = True
+    pex_info.venv_copies = installer_configuration.copies
+    pex_info.venv_site_packages_copies = installer_configuration.site_packages_copies
+    pex_info.venv_system_site_packages = installer_configuration.system_site_packages
+    pex_info.venv_hermetic_scripts = installer_configuration.hermetic_scripts
+    dependency_config.configure(pex_info)
+    for requirement in requirements:
+        pex_info.add_requirement(requirement)
+    for distribution in distributions:
+        pex_info.add_distribution(os.path.basename(distribution.location), distribution.fingerprint)
+
+    installer.install_pex_main(
+        target_dir=provenance.target_dir,
+        venv=venv,
+        pex_info=pex_info,
+        activated_dists=activated_dists,
+        shebang=provenance.calculate_shebang(hermetic_scripts=hermetic_scripts),
+        venv_python=provenance.target_python,
+        bin_path=installer_configuration.bin_path,
+    )

pex/cli/pex.py

@@ -3,6 +3,7 @@
 
 from __future__ import absolute_import
 
+import sys
 from argparse import ArgumentError, ArgumentTypeError
 
 from pex.cli import commands
@@ -12,7 +13,7 @@ from pex.result import catch
 from pex.typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from typing import Union
+    from typing import Optional, Union
 
 
 class Pex3(Main[BuildTimeCommand]):
@@ -23,14 +24,20 @@ class Pex3(Main[BuildTimeCommand]):
     """
 
 
-def main():
-    # type: () -> Union[int, str]
+def main(subcommand=None):
+    # type: (Optional[str]) -> Union[int, str]
 
     pex3 = Pex3(command_types=commands.all_commands())
     try:
-        with pex3.parsed_command() as command:
+        args = [subcommand] + sys.argv[1:] if subcommand else None
+        with pex3.parsed_command(args=args) as command:
             result = catch(command.run)
             result.maybe_display()
             return result.exit_code
     except (ArgumentError, ArgumentTypeError, GlobalConfigurationError) as e:
         return str(e)
+
+
+def run():
+    # type: () -> Union[int, str]
+    return main("run")

pex/common.py

@@ -204,6 +204,56 @@ _MKDTEMP_SINGLETON = MktempTeardownRegistry()
 setattr(zipfile, "ZIP64_LIMIT", (1 << 32) - 1)
 
 
+class _ZipFileTypeValue(Enum.Value):
+    def __init__(
+        self,
+        value,  # type: str
+        deterministic_mode,  # type: int
+    ):
+        # type: (...) -> None
+        super(_ZipFileTypeValue, self).__init__(value)
+        self.deterministic_mode = deterministic_mode
+
+    @property
+    def deterministic_external_attr(self):
+        # type: () -> int
+        return self.deterministic_mode << 16
+
+
+class ZipFileType(Enum["ZipFileType.Value"]):
+    @classmethod
+    def from_zip_info(cls, zip_info):
+        # type: (ZipInfo) -> ZipFileType.Value
+
+        if zip_info.filename.endswith("/"):
+            return ZipFileType.DIRECTORY
+
+        mode = zip_info.external_attr >> 16
+        if stat.S_IXUSR & mode:
+            return ZipFileType.EXECUTABLE
+
+        return ZipFileType.FILE
+
+    @classmethod
+    def from_path(cls, path):
+        # type: (Text) -> ZipFileType.Value
+        if os.path.isdir(path):
+            return ZipFileType.DIRECTORY
+        elif is_exe(path):
+            return ZipFileType.EXECUTABLE
+        return ZipFileType.FILE
+
+    class Value(_ZipFileTypeValue):
+        pass
+
+    DIRECTORY = Value("directory", 0o755)
+    EXECUTABLE = Value("executable", 0o755)
+    FILE = Value("file", 0o644)
+
+
+ZipFileType.seal()
+
+
 class ZipFileEx(ZipFile):
     """A ZipFile that works around several issues in the stdlib.
 
@@ -218,8 +268,8 @@ class ZipFileEx(ZipFile):
     @classmethod
     def zip_info_from_file(
         cls,
-        filename,  # type: str
-        arcname=None,  # type: Optional[str]
+        filename,  # type: Text
+        arcname=None,  # type: Optional[Text]
         date_time=None,  # type: Optional[time.struct_time]
         file_mode=None,  # type: Optional[int]
         compress=True,  # type: bool
@@ -259,8 +309,8 @@ class ZipFileEx(ZipFile):
 
     def write_deterministic(
         self,
-        filename,  # type: str
-        arcname=None,  # type: Optional[str]
+        filename,  # type: Text
+        arcname=None,  # type: Optional[Text]
         digest=None,  # type: Optional[Digest]
         deterministic=True,  # type: bool
         compress=True,  # type: bool
@@ -270,7 +320,7 @@ class ZipFileEx(ZipFile):
                 filename,
                 arcname=arcname,
                 date_time=DETERMINISTIC_DATETIME.timetuple(),
-                file_mode=0o755 if (is_exe(filename) or os.path.isdir(filename)) else 0o644,
+                file_mode=ZipFileType.from_path(filename).deterministic_mode,
                 digest=digest,
                 compress=compress,
             )
@@ -278,8 +328,8 @@ class ZipFileEx(ZipFile):
 
     def write_ex(
         self,
-        filename,  # type: str
-        arcname=None,  # type: Optional[str]
+        filename,  # type: Text
+        arcname=None,  # type: Optional[Text]
         date_time=None,  # type: Optional[time.struct_time]
         file_mode=None,  # type: Optional[int]
         digest=None,  # type: Optional[Digest]

pex/compatibility.py

@@ -62,7 +62,7 @@ if PY2:
         # type: (AnyStr, Text) -> bytes
         if isinstance(st, unicode):
             return st.encode(encoding)
-        elif isinstance(st, bytes):
+        elif isinstance(st, (str, bytes)):
             return st
         else:
             raise ValueError("Cannot convert %s to bytes" % type(st))

pex/dependency_configuration.py

@@ -4,10 +4,11 @@
 from __future__ import absolute_import
 
 import itertools
+import re
 from argparse import Namespace, _ActionsContainer
 from collections import defaultdict
 
-from pex.dist_metadata import Distribution, Requirement
+from pex.dist_metadata import Distribution, Requirement, RequirementParseError
 from pex.orderedset import OrderedSet
 from pex.pep_503 import ProjectName
 from pex.pex_info import PexInfo
@@ -22,13 +23,69 @@ else:
     from pex.third_party import attr
 
 
+@attr.s(frozen=True)
+class Override(object):
+    class InvalidError(ValueError):
+        pass
+
+    @classmethod
+    def parse(cls, override):
+        # type: (str) -> Override
+
+        project_name = None  # type: Optional[ProjectName]
+        raw_requirement = override
+
+        # See: https://peps.python.org/pep-0508/#names
+        project_name_re = r"[A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9]"
+        match = re.match(
+            r"^(?P<project>{project_name_re})\s*=\s*(?P<requirement>{project_name_re}.*)$".format(
+                project_name_re=project_name_re
+            ),
+            override,
+            re.IGNORECASE,
+        )
+        if match:
+            raw_project_name = match.group("project")
+            raw_requirement = match.group("requirement")
+            try:
+                project_name = ProjectName(raw_project_name)
+            except ProjectName.InvalidError as e:
+                raise cls.InvalidError(
+                    "Invalid project name {raw_project_name!r} in override {override!r}: "
+                    "{err}".format(raw_project_name=raw_project_name, override=override, err=e)
+                )
+        try:
+            requirement = Requirement.parse(raw_requirement)
+        except RequirementParseError as e:
+            raise cls.InvalidError(
+                "Invalid override requirement {raw_requirement!r}: {err}".format(
+                    raw_requirement=raw_requirement, err=e
+                )
+            )
+
+        return cls(project_name=project_name or requirement.project_name, requirement=requirement)
+
+    project_name = attr.ib()  # type: ProjectName
+    requirement = attr.ib()  # type: Requirement
+
+    def __str__(self):
+        # type: () -> str
+
+        if self.requirement.project_name == self.project_name:
+            return str(self.requirement)
+
+        return "{project_name}={requirement}".format(
+            project_name=self.project_name, requirement=self.requirement
+        )
+
+
 @attr.s(frozen=True)
 class DependencyConfiguration(object):
     @classmethod
     def create(
         cls,
         excluded=(),  # type: Iterable[Union[str, Requirement]]
-        overridden=(),  # type: Iterable[Union[str, Requirement]]
+        overridden=(),  # type: Iterable[Union[str, Override]]
     ):
         # type: (...) -> DependencyConfiguration
 
@@ -36,8 +93,8 @@ class DependencyConfiguration(object):
             OrderedSet
         )  # type: DefaultDict[ProjectName, OrderedSet[Requirement]]
         for o in overridden:
-            override = o if isinstance(o, Requirement) else Requirement.parse(o)
-            overridden_projects[override.project_name].add(override)
+            override = o if isinstance(o, Override) else Override.parse(o)
+            overridden_projects[override.project_name].add(override.requirement)
 
         return cls(
             excluded=tuple(
@@ -64,25 +121,32 @@ class DependencyConfiguration(object):
         # type: (PexInfo) -> None
         for excluded in self.excluded:
             pex_info.add_exclude(excluded)
-        for override in sorted(
-            itertools.chain.from_iterable(self.overridden.values()), key=lambda req: req.key
-        ):
-            pex_info.add_override(override)
+        for project_name, overrides in self.overridden.items():
+            for override in sorted(overrides, key=lambda req: req.key):
+                pex_info.add_override(Override(project_name=project_name, requirement=override))
 
     def excluded_by(self, item):
         # type: (Union[Distribution, Requirement]) -> Tuple[Requirement, ...]
         return tuple(req for req in self.excluded if item in req)
 
     def all_overrides(self):
-        # type: () -> Tuple[Requirement, ...]
-        return tuple(itertools.chain.from_iterable(self.overridden.values()))
+        # type: () -> Tuple[Override, ...]
+        return tuple(
+            Override(project_name=project_name, requirement=requirement)
+            for project_name, requirements in self.overridden.items()
+            for requirement in requirements
+        )
 
     def overrides_for(self, requirement):
         # type: (Requirement) -> Tuple[Requirement, ...]
         return self.overridden.get(requirement.project_name, ())
 
-    def overridden_by(self, requirement, target):
-        # type: (Requirement, Target) -> Optional[Requirement]
+    def overridden_by(
+        self,
+        requirement,  # type: Requirement
+        target,  # type: Target
+    ):
+        # type: (...) -> Optional[Requirement]
         overrides = self.overrides_for(requirement)
         applicable_overrides = [
             override for override in overrides if target.requirement_applies(override)
@@ -152,9 +216,17 @@ def register(parser):
         type=str,
         action="append",
         help=(
-            "Specifies a transitive requirement to override when resolving. Any distribution "
-            "requirement in the PEX's resolve that matches the override project name is replaced "
-            "with the given override requirement. This option can be used multiple times."
+            "Specifies a transitive requirement to override when resolving. Overrides can either "
+            "modify an existing dependency on a project name by changing extras, version "
+            "constraints or markers or else they can completely swap out the dependency for a "
+            "dependency on another project altogether. For the former, simply supply the "
+            "requirement you wish. For example, specifying `--override cowsay==5.0` will override "
+            "any transitive dependency on cowsay that has any combination of extras, version "
+            "constraints or markers with the requirement `cowsay==5.0`. To completely replace "
+            "cowsay with another library altogether, you can specify an override like "
+            "`--override cowsay=my-cowsay>2`. This will replace any transitive dependency on "
+            "cowsay that has any combination of extras, version constraints or markers with the "
+            "requirement `my-cowsay>2`. This option can be used multiple times."
         ),
     )