InstallCommand Class Reference

Inheritance diagram for InstallCommand:

Collaboration diagram for InstallCommand:

Public Member Functions
None	add_options (self)
int	run (self, Values options, List[str] args)
Public Member Functions inherited from RequirementCommand
None	__init__ (self, *Any args, **Any kw)
RequirementPreparer	make_requirement_preparer (cls, TempDirectory temp_build_dir, Values options, BuildTracker build_tracker, PipSession session, PackageFinder finder, bool use_user_site, Optional[str] download_dir=None, int verbosity=0)
BaseResolver	make_resolver (cls, RequirementPreparer preparer, PackageFinder finder, Values options, Optional[WheelCache] wheel_cache=None, bool use_user_site=False, bool ignore_installed=True, bool ignore_requires_python=False, bool force_reinstall=False, str upgrade_strategy="to-satisfy-only", Optional[bool] use_pep517=None, Optional[Tuple[int,...]] py_version_info=None)
List[InstallRequirement]	get_requirements (self, List[str] args, Values options, PackageFinder finder, PipSession session)
Public Member Functions inherited from IndexGroupCommand
None	handle_pip_version_check (self, Values options)
Public Member Functions inherited from Command
Tuple[Values, List[str]]	parse_args (self, List[str] args)
int	main (self, List[str] args)
Public Member Functions inherited from CommandContextMixIn
Generator[None, None, None]	main_context (self)
_T	enter_context (self, ContextManager[_T] context_provider)
Public Member Functions inherited from SessionCommandMixin
PipSession	get_default_session (self, Values options)

Data Fields
	cmd_opts
	parser
Data Fields inherited from Command
	name
	summary
	parser
	cmd_opts
	tempdir_registry
	verbosity

Static Public Attributes
str	usage
Static Public Attributes inherited from Command
str	usage = ""
bool	ignore_require_venv = False

Protected Member Functions
None	_handle_target_dir (self, str target_dir, TempDirectory target_temp_dir, bool upgrade)
Optional[ConflictDetails]	_determine_conflicts (self, List[InstallRequirement] to_install)
None	_warn_about_conflicts (self, ConflictDetails conflict_details, str resolver_variant)
Protected Member Functions inherited from RequirementCommand
PackageFinder	_build_package_finder (self, Values options, PipSession session, Optional[TargetPython] target_python=None, Optional[bool] ignore_requires_python=None)
Protected Member Functions inherited from Command
int	_main (self, List[str] args)
Protected Member Functions inherited from SessionCommandMixin
Optional[List[str]]	_get_index_urls (cls, Values options)
PipSession	_build_session (self, Values options, Optional[int] retries=None, Optional[int] timeout=None, bool fallback_to_certifi=False)

Additional Inherited Members
Static Public Member Functions inherited from RequirementCommand
str	determine_resolver_variant (Values options)
None	trace_basic_info (PackageFinder finder)
Protected Attributes inherited from CommandContextMixIn
	_in_main_context
	_main_context
Protected Attributes inherited from SessionCommandMixin
	_session

Detailed Description

Install packages from:

- PyPI (and other indexes) using requirement specifiers.
- VCS project urls.
- Local project directories.
- Local or remote source archives.

pip also supports installing from "requirements files", which provide
an easy way to specify a whole environment to be installed.

Definition at line 52 of file install.py.

Member Function Documentation

_determine_conflicts()

Optional[ConflictDetails] _determine_conflicts (   self, List[InstallRequirement]   to_install  )

protected

Definition at line 571 of file install.py.

    ) -> Optional[ConflictDetails]:
        try:
            return check_install_conflicts(to_install)
        except Exception:
            logger.exception(
                "Error while checking for conflicts. Please file an issue on "
                "pip's issue tracker: https://github.com/pypa/pip/issues/new"
            )
            return None
 

References i.

Referenced by InstallCommand.run().

Here is the caller graph for this function:

_handle_target_dir()

None _handle_target_dir (   self, str  target_dir, TempDirectory  target_temp_dir, bool   upgrade  )

protected

Definition at line 517 of file install.py.

    ) -> None:
        ensure_dir(target_dir)
 
        # Checking both purelib and platlib directories for installed
        # packages to be moved to target directory
        lib_dir_list = []
 
        # Checking both purelib and platlib directories for installed
        # packages to be moved to target directory
        scheme = get_scheme("", home=target_temp_dir.path)
        purelib_dir = scheme.purelib
        platlib_dir = scheme.platlib
        data_dir = scheme.data
 
        if os.path.exists(purelib_dir):
            lib_dir_list.append(purelib_dir)
        if os.path.exists(platlib_dir) and platlib_dir != purelib_dir:
            lib_dir_list.append(platlib_dir)
        if os.path.exists(data_dir):
            lib_dir_list.append(data_dir)
 
        for lib_dir in lib_dir_list:
            for item in os.listdir(lib_dir):
                if lib_dir == data_dir:
                    ddir = os.path.join(data_dir, item)
                    if any(s.startswith(ddir) for s in lib_dir_list[:-1]):
                        continue
                target_item_dir = os.path.join(target_dir, item)
                if os.path.exists(target_item_dir):
                    if not upgrade:
                        logger.warning(
                            "Target directory %s already exists. Specify "
                            "--upgrade to force replacement.",
                            target_item_dir,
                        )
                        continue
                    if os.path.islink(target_item_dir):
                        logger.warning(
                            "Target directory %s already exists and is "
                            "a link. pip will not automatically replace "
                            "links, please remove if replacement is "
                            "desired.",
                            target_item_dir,
                        )
                        continue
                    if os.path.isdir(target_item_dir):
                        shutil.rmtree(target_item_dir)
                    else:
                        os.remove(target_item_dir)
 
                shutil.move(os.path.join(lib_dir, item), target_item_dir)
 

References i.

Referenced by InstallCommand.run().

Here is the caller graph for this function:

_warn_about_conflicts()

None _warn_about_conflicts (   self, ConflictDetails  conflict_details, str   resolver_variant  )

protected

Definition at line 583 of file install.py.

    ) -> None:
        package_set, (missing, conflicting) = conflict_details
        if not missing and not conflicting:
            return
 
        parts: List[str] = []
        if resolver_variant == "legacy":
            parts.append(
                "pip's legacy dependency resolver does not consider dependency "
                "conflicts when selecting packages. This behaviour is the "
                "source of the following dependency conflicts."
            )
        else:
            assert resolver_variant == "2020-resolver"
            parts.append(
                "pip's dependency resolver does not currently take into account "
                "all the packages that are installed. This behaviour is the "
                "source of the following dependency conflicts."
            )
 
        # NOTE: There is some duplication here, with commands/check.py
        for project_name in missing:
            version = package_set[project_name][0]
            for dependency in missing[project_name]:
                message = (
                    "{name} {version} requires {requirement}, "
                    "which is not installed."
                ).format(
                    name=project_name,
                    version=version,
                    requirement=dependency[1],
                )
                parts.append(message)
 
        for project_name in conflicting:
            version = package_set[project_name][0]
            for dep_name, dep_version, req in conflicting[project_name]:
                message = (
                    "{name} {version} requires {requirement}, but {you} have "
                    "{dep_name} {dep_version} which is incompatible."
                ).format(
                    name=project_name,
                    version=version,
                    requirement=req,
                    dep_name=dep_name,
                    dep_version=dep_version,
                    you=("you" if resolver_variant == "2020-resolver" else "you'll"),
                )
                parts.append(message)
 
        logger.critical("\n".join(parts))
 
 

References i.

Referenced by InstallCommand.run().

Here is the caller graph for this function:

add_options()

None add_options

(

self

)

Reimplemented from Command.

Definition at line 72 of file install.py.

    def add_options(self) -> None:
        self.cmd_opts.add_option(cmdoptions.requirements())
        self.cmd_opts.add_option(cmdoptions.constraints())
        self.cmd_opts.add_option(cmdoptions.no_deps())
        self.cmd_opts.add_option(cmdoptions.pre())
 
        self.cmd_opts.add_option(cmdoptions.editable())
        self.cmd_opts.add_option(
            "--dry-run",
            action="store_true",
            dest="dry_run",
            default=False,
            help=(
                "Don't actually install anything, just print what would be. "
                "Can be used in combination with --ignore-installed "
                "to 'resolve' the requirements."
            ),
        )
        self.cmd_opts.add_option(
            "-t",
            "--target",
            dest="target_dir",
            metavar="dir",
            default=None,
            help=(
                "Install packages into <dir>. "
                "By default this will not replace existing files/folders in "
                "<dir>. Use --upgrade to replace existing packages in <dir> "
                "with new versions."
            ),
        )
        cmdoptions.add_target_python_options(self.cmd_opts)
 
        self.cmd_opts.add_option(
            "--user",
            dest="use_user_site",
            action="store_true",
            help=(
                "Install to the Python user install directory for your "
                "platform. Typically ~/.local/, or %APPDATA%\\Python on "
                "Windows. (See the Python documentation for site.USER_BASE "
                "for full details.)"
            ),
        )
        self.cmd_opts.add_option(
            "--no-user",
            dest="use_user_site",
            action="store_false",
            help=SUPPRESS_HELP,
        )
        self.cmd_opts.add_option(
            "--root",
            dest="root_path",
            metavar="dir",
            default=None,
            help="Install everything relative to this alternate root directory.",
        )
        self.cmd_opts.add_option(
            "--prefix",
            dest="prefix_path",
            metavar="dir",
            default=None,
            help=(
                "Installation prefix where lib, bin and other top-level "
                "folders are placed. Note that the resulting installation may "
                "contain scripts and other resources which reference the "
                "Python interpreter of pip, and not that of ``--prefix``. "
                "See also the ``--python`` option if the intention is to "
                "install packages into another (possibly pip-free) "
                "environment."
            ),
        )
 
        self.cmd_opts.add_option(cmdoptions.src())
 
        self.cmd_opts.add_option(
            "-U",
            "--upgrade",
            dest="upgrade",
            action="store_true",
            help=(
                "Upgrade all specified packages to the newest available "
                "version. The handling of dependencies depends on the "
                "upgrade-strategy used."
            ),
        )
 
        self.cmd_opts.add_option(
            "--upgrade-strategy",
            dest="upgrade_strategy",
            default="only-if-needed",
            choices=["only-if-needed", "eager"],
            help=(
                "Determines how dependency upgrading should be handled "
                "[default: %default]. "
                '"eager" - dependencies are upgraded regardless of '
                "whether the currently installed version satisfies the "
                "requirements of the upgraded package(s). "
                '"only-if-needed" -  are upgraded only when they do not '
                "satisfy the requirements of the upgraded package(s)."
            ),
        )
 
        self.cmd_opts.add_option(
            "--force-reinstall",
            dest="force_reinstall",
            action="store_true",
            help="Reinstall all packages even if they are already up-to-date.",
        )
 
        self.cmd_opts.add_option(
            "-I",
            "--ignore-installed",
            dest="ignore_installed",
            action="store_true",
            help=(
                "Ignore the installed packages, overwriting them. "
                "This can break your system if the existing package "
                "is of a different version or was installed "
                "with a different package manager!"
            ),
        )
 
        self.cmd_opts.add_option(cmdoptions.ignore_requires_python())
        self.cmd_opts.add_option(cmdoptions.no_build_isolation())
        self.cmd_opts.add_option(cmdoptions.use_pep517())
        self.cmd_opts.add_option(cmdoptions.no_use_pep517())
        self.cmd_opts.add_option(cmdoptions.check_build_deps())
        self.cmd_opts.add_option(cmdoptions.override_externally_managed())
 
        self.cmd_opts.add_option(cmdoptions.config_settings())
        self.cmd_opts.add_option(cmdoptions.global_options())
 
        self.cmd_opts.add_option(
            "--compile",
            action="store_true",
            dest="compile",
            default=True,
            help="Compile Python source files to bytecode",
        )
 
        self.cmd_opts.add_option(
            "--no-compile",
            action="store_false",
            dest="compile",
            help="Do not compile Python source files to bytecode",
        )
 
        self.cmd_opts.add_option(
            "--no-warn-script-location",
            action="store_false",
            dest="warn_script_location",
            default=True,
            help="Do not warn when installing scripts outside PATH",
        )
        self.cmd_opts.add_option(
            "--no-warn-conflicts",
            action="store_false",
            dest="warn_about_conflicts",
            default=True,
            help="Do not warn about broken dependencies",
        )
        self.cmd_opts.add_option(cmdoptions.no_binary())
        self.cmd_opts.add_option(cmdoptions.only_binary())
        self.cmd_opts.add_option(cmdoptions.prefer_binary())
        self.cmd_opts.add_option(cmdoptions.require_hashes())
        self.cmd_opts.add_option(cmdoptions.progress_bar())
        self.cmd_opts.add_option(cmdoptions.root_user_action())
 
        index_opts = cmdoptions.make_option_group(
            cmdoptions.index_group,
            self.parser,
        )
 
        self.parser.insert_option_group(0, index_opts)
        self.parser.insert_option_group(0, self.cmd_opts)
 
        self.cmd_opts.add_option(
            "--report",
            dest="json_report_file",
            metavar="file",
            default=None,
            help=(
                "Generate a JSON file describing what pip did to install "
                "the provided requirements. "
                "Can be used in combination with --dry-run and --ignore-installed "
                "to 'resolve' the requirements. "
                "When - is used as file name it writes to stdout. "
                "When writing to stdout, please combine with the --quiet option "
                "to avoid mixing pip logging output with JSON output."
            ),
        )
 

References Command.cmd_opts, CacheCommand.cmd_opts, CompletionCommand.cmd_opts, ConfigurationCommand.cmd_opts, DebugCommand.cmd_opts, DownloadCommand.cmd_opts, FreezeCommand.cmd_opts, HashCommand.cmd_opts, IndexCommand.cmd_opts, InspectCommand.cmd_opts, InstallCommand.cmd_opts, ListCommand.cmd_opts, SearchCommand.cmd_opts, ShowCommand.cmd_opts, UninstallCommand.cmd_opts, WheelCommand.cmd_opts, and i.

run()

int run	(		self,
		Values	options,
		List[str]	args
	)

Reimplemented from Command.

Definition at line 266 of file install.py.

    def run(self, options: Values, args: List[str]) -> int:
        if options.use_user_site and options.target_dir is not None:
            raise CommandError("Can not combine '--user' and '--target'")
 
        # Check whether the environment we're installing into is externally
        # managed, as specified in PEP 668. Specifying --root, --target, or
        # --prefix disables the check, since there's no reliable way to locate
        # the EXTERNALLY-MANAGED file for those cases. An exception is also
        # made specifically for "--dry-run --report" for convenience.
        installing_into_current_environment = (
            not (options.dry_run and options.json_report_file)
            and options.root_path is None
            and options.target_dir is None
            and options.prefix_path is None
        )
        if (
            installing_into_current_environment
            and not options.override_externally_managed
        ):
            check_externally_managed()
 
        upgrade_strategy = "to-satisfy-only"
        if options.upgrade:
            upgrade_strategy = options.upgrade_strategy
 
        cmdoptions.check_dist_restriction(options, check_target=True)
 
        logger.verbose("Using %s", get_pip_version())
        options.use_user_site = decide_user_install(
            options.use_user_site,
            prefix_path=options.prefix_path,
            target_dir=options.target_dir,
            root_path=options.root_path,
            isolated_mode=options.isolated_mode,
        )
 
        target_temp_dir: Optional[TempDirectory] = None
        target_temp_dir_path: Optional[str] = None
        if options.target_dir:
            options.ignore_installed = True
            options.target_dir = os.path.abspath(options.target_dir)
            if (
                # fmt: off
                os.path.exists(options.target_dir) and
                not os.path.isdir(options.target_dir)
                # fmt: on
            ):
                raise CommandError(
                    "Target path exists but is not a directory, will not continue."
                )
 
            # Create a target directory for using with the target option
            target_temp_dir = TempDirectory(kind="target")
            target_temp_dir_path = target_temp_dir.path
            self.enter_context(target_temp_dir)
 
        global_options = options.global_options or []
 
        session = self.get_default_session(options)
 
        target_python = make_target_python(options)
        finder = self._build_package_finder(
            options=options,
            session=session,
            target_python=target_python,
            ignore_requires_python=options.ignore_requires_python,
        )
        build_tracker = self.enter_context(get_build_tracker())
 
        directory = TempDirectory(
            delete=not options.no_clean,
            kind="install",
            globally_managed=True,
        )
 
        try:
            reqs = self.get_requirements(args, options, finder, session)
            check_legacy_setup_py_options(options, reqs)
 
            wheel_cache = WheelCache(options.cache_dir)
 
            # Only when installing is it permitted to use PEP 660.
            # In other circumstances (pip wheel, pip download) we generate
            # regular (i.e. non editable) metadata and wheels.
            for req in reqs:
                req.permit_editable_wheels = True
 
            preparer = self.make_requirement_preparer(
                temp_build_dir=directory,
                options=options,
                build_tracker=build_tracker,
                session=session,
                finder=finder,
                use_user_site=options.use_user_site,
                verbosity=self.verbosity,
            )
            resolver = self.make_resolver(
                preparer=preparer,
                finder=finder,
                options=options,
                wheel_cache=wheel_cache,
                use_user_site=options.use_user_site,
                ignore_installed=options.ignore_installed,
                ignore_requires_python=options.ignore_requires_python,
                force_reinstall=options.force_reinstall,
                upgrade_strategy=upgrade_strategy,
                use_pep517=options.use_pep517,
            )
 
            self.trace_basic_info(finder)
 
            requirement_set = resolver.resolve(
                reqs, check_supported_wheels=not options.target_dir
            )
 
            if options.json_report_file:
                report = InstallationReport(requirement_set.requirements_to_install)
                if options.json_report_file == "-":
                    print_json(data=report.to_dict())
                else:
                    with open(options.json_report_file, "w", encoding="utf-8") as f:
                        json.dump(report.to_dict(), f, indent=2, ensure_ascii=False)
 
            if options.dry_run:
                # In non dry-run mode, the legacy versions and specifiers check
                # will be done as part of conflict detection.
                requirement_set.warn_legacy_versions_and_specifiers()
                would_install_items = sorted(
                    (r.metadata["name"], r.metadata["version"])
                    for r in requirement_set.requirements_to_install
                )
                if would_install_items:
                    write_output(
                        "Would install %s",
                        " ".join("-".join(item) for item in would_install_items),
                    )
                return SUCCESS
 
            try:
                pip_req = requirement_set.get_requirement("pip")
            except KeyError:
                modifying_pip = False
            else:
                # If we're not replacing an already installed pip,
                # we're not modifying it.
                modifying_pip = pip_req.satisfied_by is None
            protect_pip_from_modification_on_windows(modifying_pip=modifying_pip)
 
            reqs_to_build = [
                r
                for r in requirement_set.requirements.values()
                if should_build_for_install_command(r)
            ]
 
            _, build_failures = build(
                reqs_to_build,
                wheel_cache=wheel_cache,
                verify=True,
                build_options=[],
                global_options=global_options,
            )
 
            if build_failures:
                raise InstallationError(
                    "Could not build wheels for {}, which is required to "
                    "install pyproject.toml-based projects".format(
                        ", ".join(r.name for r in build_failures)  # type: ignore
                    )
                )
 
            to_install = resolver.get_installation_order(requirement_set)
 
            # Check for conflicts in the package set we're installing.
            conflicts: Optional[ConflictDetails] = None
            should_warn_about_conflicts = (
                not options.ignore_dependencies and options.warn_about_conflicts
            )
            if should_warn_about_conflicts:
                conflicts = self._determine_conflicts(to_install)
 
            # Don't warn about script install locations if
            # --target or --prefix has been specified
            warn_script_location = options.warn_script_location
            if options.target_dir or options.prefix_path:
                warn_script_location = False
 
            installed = install_given_reqs(
                to_install,
                global_options,
                root=options.root_path,
                home=target_temp_dir_path,
                prefix=options.prefix_path,
                warn_script_location=warn_script_location,
                use_user_site=options.use_user_site,
                pycompile=options.compile,
            )
 
            lib_locations = get_lib_location_guesses(
                user=options.use_user_site,
                home=target_temp_dir_path,
                root=options.root_path,
                prefix=options.prefix_path,
                isolated=options.isolated_mode,
            )
            env = get_environment(lib_locations)
 
            installed.sort(key=operator.attrgetter("name"))
            items = []
            for result in installed:
                item = result.name
                try:
                    installed_dist = env.get_distribution(item)
                    if installed_dist is not None:
                        item = f"{item}-{installed_dist.version}"
                except Exception:
                    pass
                items.append(item)
 
            if conflicts is not None:
                self._warn_about_conflicts(
                    conflicts,
                    resolver_variant=self.determine_resolver_variant(options),
                )
 
            installed_desc = " ".join(items)
            if installed_desc:
                write_output(
                    "Successfully installed %s",
                    installed_desc,
                )
        except OSError as error:
            show_traceback = self.verbosity >= 1
 
            message = create_os_error_message(
                error,
                show_traceback,
                options.use_user_site,
            )
            logger.error(message, exc_info=show_traceback)  # noqa
 
            return ERROR
 
        if options.target_dir:
            assert target_temp_dir
            self._handle_target_dir(
                options.target_dir, target_temp_dir, options.upgrade
            )
        if options.root_user_action == "warn":
            warn_if_run_as_root()
        return SUCCESS
 

References ListCommand._build_package_finder(), RequirementCommand._build_package_finder(), IndexCommand._build_package_finder(), InstallCommand._determine_conflicts(), InstallCommand._handle_target_dir(), InstallCommand._warn_about_conflicts(), pip._internal.commands.install.create_os_error_message(), pip._internal.commands.install.decide_user_install(), RequirementCommand.determine_resolver_variant(), CommandContextMixIn.enter_context(), SessionCommandMixin.get_default_session(), pip._internal.commands.install.get_lib_location_guesses(), RequirementCommand.get_requirements(), Metadata.get_requirements(), i, RequirementCommand.make_requirement_preparer(), RequirementCommand.make_resolver(), RequirementCommand.trace_basic_info(), Command.verbosity, and RequirementPreparer.verbosity.

Here is the call graph for this function:

Field Documentation

cmd_opts

cmd_opts

Definition at line 103 of file install.py.

Referenced by RequirementCommand.__init__(), CacheCommand.add_options(), CompletionCommand.add_options(), ConfigurationCommand.add_options(), DownloadCommand.add_options(), FreezeCommand.add_options(), HashCommand.add_options(), InspectCommand.add_options(), InstallCommand.add_options(), ListCommand.add_options(), SearchCommand.add_options(), ShowCommand.add_options(), UninstallCommand.add_options(), and WheelCommand.add_options().

parser

parser

Definition at line 243 of file install.py.

Referenced by ListCommand.add_options(), UpdatingDefaultsHelpFormatter.expand_default(), Command.parse_args(), DebugCommand.run(), and HashCommand.run().

usage

str usage

static

Initial value:

=  """
      %prog [options] <requirement specifier> [package-index-options] ...
      %prog [options] -r <requirements file> [package-index-options] ...
      %prog [options] [-e] <vcs project url> ...
      %prog [options] [-e] <local project path> ...
      %prog [options] <archive url/path> ..."""

Definition at line 65 of file install.py.

---

The documentation for this class was generated from the following file:

• /home/liwuen/projects_dev/pqc-engineering-ssec-23/venv/lib/python3.12/site-packages/pip/_internal/commands/install.py