Environment Class Reference

Public Member Functions
	__init__ (self, search_path=None, platform=get_supported_platform(), python=PY_MAJOR)
	can_add (self, dist)
	remove (self, dist)
	scan (self, search_path=None)
	__getitem__ (self, project_name)
	add (self, dist)
	best_match (self, req, working_set, installer=None, replace_conflicting=False)
	obtain (self, requirement, installer=None)
	__iter__ (self)
	__iadd__ (self, other)
	__add__ (self, other)

Data Fields
	platform
	python

Protected Attributes
	_distmap

Detailed Description

Searchable snapshot of distributions on a search path

Definition at line 1031 of file __init__.py.

Constructor & Destructor Documentation

__init__()

__init__	(		self,
			search_path = None,
			platform = get_supported_platform(),
			python = PY_MAJOR
	)

Snapshot distributions available on a search path

Any distributions found on `search_path` are added to the environment.
`search_path` should be a sequence of ``sys.path`` items.  If not
supplied, ``sys.path`` is used.

`platform` is an optional string specifying the name of the platform
that platform-specific distributions must be compatible with.  If
unspecified, it defaults to the current platform.  `python` is an
optional string naming the desired version of Python (e.g. ``'3.6'``);
it defaults to the current version.

You may explicitly set `platform` (and/or `python`) to ``None`` if you
wish to map *all* distributions, not just those compatible with the
running platform or Python version.

Definition at line 1034 of file __init__.py.

    ):
        """Snapshot distributions available on a search path
 
        Any distributions found on `search_path` are added to the environment.
        `search_path` should be a sequence of ``sys.path`` items.  If not
        supplied, ``sys.path`` is used.
 
        `platform` is an optional string specifying the name of the platform
        that platform-specific distributions must be compatible with.  If
        unspecified, it defaults to the current platform.  `python` is an
        optional string naming the desired version of Python (e.g. ``'3.6'``);
        it defaults to the current version.
 
        You may explicitly set `platform` (and/or `python`) to ``None`` if you
        wish to map *all* distributions, not just those compatible with the
        running platform or Python version.
        """
        self._distmap = {}
        self.platform = platform
        self.python = python
        self.scan(search_path)
 

Referenced by Protocol.__init_subclass__().

Here is the caller graph for this function:

Member Function Documentation

__add__()

__add__	(		self,
			other
	)

Add an environment or distribution to an environment

Definition at line 1167 of file __init__.py.

    def __add__(self, other):
        """Add an environment or distribution to an environment"""
        new = self.__class__([], platform=None, python=None)
        for env in self, other:
            new += env
        return new
 
 
# XXX backward compatibility

Referenced by wait_base.__radd__().

Here is the caller graph for this function:

__getitem__()

__getitem__	(		self,
			project_name
	)

Return a newest-to-oldest list of distributions for `project_name`

Uses case-insensitive `project_name` comparison, assuming all the
project's distributions use their project's name converted to all
lowercase as their key.

Definition at line 1091 of file __init__.py.

    def __getitem__(self, project_name):
        """Return a newest-to-oldest list of distributions for `project_name`
 
        Uses case-insensitive `project_name` comparison, assuming all the
        project's distributions use their project's name converted to all
        lowercase as their key.
 
        """
        distribution_key = project_name.lower()
        return self._distmap.get(distribution_key, [])
 

__iadd__()

__iadd__	(		self,
			other
	)

In-place addition of a distribution or environment

Definition at line 1155 of file __init__.py.

    def __iadd__(self, other):
        """In-place addition of a distribution or environment"""
        if isinstance(other, Distribution):
            self.add(other)
        elif isinstance(other, Environment):
            for project in other:
                for dist in other[project]:
                    self.add(dist)
        else:
            raise TypeError("Can't add %r to environment" % (other,))
        return self
 

Referenced by ParseResults.extend().

Here is the caller graph for this function:

__iter__()

__iter__

(

self

)

Yield the unique project names of the available distributions

Definition at line 1149 of file __init__.py.

    def __iter__(self):
        """Yield the unique project names of the available distributions"""
        for key in self._distmap.keys():
            if self[key]:
                yield key
 

add()

add	(		self,
			dist
	)

Add `dist` if we ``can_add()`` it and it has not already been added

Definition at line 1102 of file __init__.py.

    def add(self, dist):
        """Add `dist` if we ``can_add()`` it and it has not already been added"""
        if self.can_add(dist) and dist.has_version():
            dists = self._distmap.setdefault(dist.key, [])
            if dist not in dists:
                dists.append(dist)
                dists.sort(key=operator.attrgetter('hashcmp'), reverse=True)
 

Referenced by UninstallPathSet.add(), Manifest.add_many(), HTTPHeaderDict.extend(), and BuildTracker.track().

Here is the caller graph for this function:

best_match()

best_match	(		self,
			req,
			working_set,
			installer = None,
			replace_conflicting = False
	)

Find distribution best matching `req` and usable on `working_set`

This calls the ``find(req)`` method of the `working_set` to see if a
suitable distribution is already active.  (This may raise
``VersionConflict`` if an unsuitable version of the project is already
active in the specified `working_set`.)  If a suitable distribution
isn't active, this method returns the newest distribution in the
environment that meets the ``Requirement`` in `req`.  If no suitable
distribution is found, and `installer` is supplied, then the result of
calling the environment's ``obtain(req, installer)`` method will be
returned.

Definition at line 1110 of file __init__.py.

    def best_match(self, req, working_set, installer=None, replace_conflicting=False):
        """Find distribution best matching `req` and usable on `working_set`
 
        This calls the ``find(req)`` method of the `working_set` to see if a
        suitable distribution is already active.  (This may raise
        ``VersionConflict`` if an unsuitable version of the project is already
        active in the specified `working_set`.)  If a suitable distribution
        isn't active, this method returns the newest distribution in the
        environment that meets the ``Requirement`` in `req`.  If no suitable
        distribution is found, and `installer` is supplied, then the result of
        calling the environment's ``obtain(req, installer)`` method will be
        returned.
        """
        try:
            dist = working_set.find(req)
        except VersionConflict:
            if not replace_conflicting:
                raise
            dist = None
        if dist is not None:
            return dist
        for dist in self[req.key]:
            if dist in req:
                return dist
        # try to download/install
        return self.obtain(req, installer)
 

Referenced by Terminal256Formatter._color_index().

Here is the caller graph for this function:

can_add()

can_add	(		self,
			dist
	)

Is distribution `dist` acceptable for this environment?

The distribution must match the platform and python version
requirements specified when this environment was created, or False
is returned.

Definition at line 1058 of file __init__.py.

    def can_add(self, dist):
        """Is distribution `dist` acceptable for this environment?
 
        The distribution must match the platform and python version
        requirements specified when this environment was created, or False
        is returned.
        """
        py_compat = (
            self.python is None
            or dist.py_version is None
            or dist.py_version == self.python
        )
        return py_compat and compatible_platforms(dist.platform, self.platform)
 

obtain()

obtain	(		self,
			requirement,
			installer = None
	)

Obtain a distribution matching `requirement` (e.g. via download)

Obtain a distro that matches requirement (e.g. via download).  In the
base ``Environment`` class, this routine just returns
``installer(requirement)``, unless `installer` is None, in which case
None is returned instead.  This method is a hook that allows subclasses
to attempt other ways of obtaining a distribution before falling back
to the `installer` argument.

Definition at line 1137 of file __init__.py.

    def obtain(self, requirement, installer=None):
        """Obtain a distribution matching `requirement` (e.g. via download)
 
        Obtain a distro that matches requirement (e.g. via download).  In the
        base ``Environment`` class, this routine just returns
        ``installer(requirement)``, unless `installer` is None, in which case
        None is returned instead.  This method is a hook that allows subclasses
        to attempt other ways of obtaining a distribution before falling back
        to the `installer` argument."""
        if installer is not None:
            return installer(requirement)
 

Referenced by VersionControl.unpack().

Here is the caller graph for this function:

remove()

remove	(		self,
			dist
	)

Remove `dist` from the environment

Definition at line 1072 of file __init__.py.

    def remove(self, dist):
        """Remove `dist` from the environment"""
        self._distmap[dist.key].remove(dist)
 

Referenced by Sequencer.remove_node(), and BuildTracker.track().

Here is the caller graph for this function:

scan()

scan	(		self,
			search_path = None
	)

Scan `search_path` for distributions usable in this environment

Any distributions found are added to the environment.
`search_path` should be a sequence of ``sys.path`` items.  If not
supplied, ``sys.path`` is used.  Only distributions conforming to
the platform/python version defined at initialization are added.

Definition at line 1076 of file __init__.py.

    def scan(self, search_path=None):
        """Scan `search_path` for distributions usable in this environment
 
        Any distributions found are added to the environment.
        `search_path` should be a sequence of ``sys.path`` items.  If not
        supplied, ``sys.path`` is used.  Only distributions conforming to
        the platform/python version defined at initialization are added.
        """
        if search_path is None:
            search_path = sys.path
 
        for item in search_path:
            for dist in find_distributions(item):
                self.add(dist)
 

Referenced by Scanner.get_char().

Here is the caller graph for this function:

Field Documentation

_distmap

_distmap

protected

Definition at line 1053 of file __init__.py.

platform

platform

Definition at line 1054 of file __init__.py.

python

python

Definition at line 1055 of file __init__.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/_vendor/pkg_resources/__init__.py