This is the place where the functions and classes in distlib's public API are described.
This class represents a set of distributions which are installed on a Python path (like PYTHONPATH / sys.path). Both new-style (distlib) and legacy (egg) distributions are catered for.
Methods:
Initialise the instance using a particular path.
| Parameters: |
|
|---|
Enables a cache, so that metadata information doesn’t have to be fetched from disk. The cache is per instance of the DistributionPath instance and is enabled by default. It can be disabled using disable_cache() and cleared using clear_cache() (disabling won’t automatically clear it).
Disables the cache, but doesn’t clear it.
Clears the cache, but doesn’t change its enabled/disabled status. If enabled, the cache will be re-populated when querying for distributions.
The main querying method if you want to look at all the distributions. It returns an iterator which returns Distribution and, if include_egg was specified as True for the instance, also instances of any EggInfoDistribution for any legacy distributions found.
Looks for a distribution by name. It returns the first one found with that name (there should only be one distribution with a given name on a given search path). Returns None if no distribution was found, or else an instance of Distribution (or, if include_egg was specified as True for the instance, an instance of EggInfoDistribution if a legacy distribution was found with that name).
| Parameters: | name (str) – The name of the distribution to search for. |
|---|
Returns an iterator for entries exported by distributions on the path.
| Parameters: | |
|---|---|
| Returns: | An iterator which iterates over exported entries (instances of ExportEntry). |
A class representing a distribution, typically one which hasn’t been installed (most likely, one which has been obtained from an index like PyPI).
Properties:
The name of the distribution.
The version of the distribution.
The metadata for the distribution. This is a distlib.metadata.Metadata instance.
The download URL for the distribution. If there are multiple URLs, this will be one of the values in download_urls.
A set of known download URLs for the distribution.
New in version 0.2.0: The download_urls attribute was added.
The digest for the source distribution. This is either None or a 2-tuple consisting of the hashing algorithm and the digest using that algorithm, e.g. ('sha256', '01234...').
A dictionary mapping download URLs to digests, if and when digests are available.
New in version 0.2.0: The digests attribute was added.
The locator for an instance which has been retrieved through a locator. This is None for an installed distribution.
A class representing an installed distribution. This class is not instantiated directly, except by packaging tools. Instances of it are returned from querying a DistributionPath.
Properties:
Whether the distribution was installed by user request (if not, it may have been installed as a dependency of some other distribution).
The distribution’s exports, as described in Exporting things from Distributions. This is a cached property.
Methods:
Returns an iterator over all of the individual files installed as part of the distribution, including metadata files. The iterator returns tuples of the form (path, hash, size). The list of files is written by the installer to the RECORD metadata file.
| Parameters: | local – If True, the paths returned are local absolute paths (i.e. with platform-specific directory separators as indicated by os.sep); otherwise, they are the values stored in the RECORD metadata file. |
|---|
Similar to list_installed_files(), but only returns metadata files.
| Parameters: | local – As for list_installed_files(). |
|---|
Runs over all the installed files to check that the size and checksum are unchanged from the values in the RECORD file, written when the distribution was installed. It returns a list of mismatches. If the files in the distribution haven’t been corrupted , an empty list will be returned; otherwise, a list of mismatches will be returned.
| Returns: | A list which, if non-empty, will contain tuples with the
following elements:
|
|---|
Read exports information from a file.
Normal access to a distribution’s exports should be through its exports attribute. This method is called from there as needed. If no filename is specified, the EXPORTS file in the .dist-info directory is read (it is expected to be present).
| Parameters: | filename (str) – The filename to read from, or None to read from the default location. |
|---|---|
| Returns: | The exports read from the file. |
| Return type: | dict |
Write exports information to a file.
If no filename is specified, the EXPORTS file in the .dist-info directory is written.
| Parameters: |
|---|
Analogous to Distribution, but covering legacy distributions. This class is not instantiated directly. Instances of it are returned from querying a DistributionPath.
Properties:
The name of the distribution.
The version of the distribution.
The metadata for the distribution. This is a distlib.metadata.Metadata instance.
Methods:
Returns a list all of the individual files installed as part of the distribution.
| Parameters: | local – If True, the paths returned are local absolute paths (i.e. with platform-specific directory separators as indicated by os.sep). |
|---|
This class represents a dependency graph between releases. The nodes are distribution instances; the edges model dependencies. An edge from a to b means that a depends on b.
Add distribution to the graph.
Add an edge from distribution x to distribution y with the given label (string).
Add a missing requirement (string) for the given distribution.
Print a subgraph starting from dist. level gives the depth of the subgraph.
Direct access to the graph nodes and edges is provided through these attributes:
Dictionary mapping distributions to a list of (other, label) tuples where other is a distribution and the edge is labelled with label (i.e. the version specifier, if such was provided).
Dictionary mapping distributions to a list of predecessors. This allows efficient traversal.
Dictionary mapping distributions to a list of requirements that were not provided by any distribution.
An instance of ResourceCache. This can be set after module import, but before calling any functionality which uses it, to ensure that the cache location is entirely under your control.
If you access the file_path property of Resource instance, the cache will be needed, and if not set by you, an instance with a default location will be created. See distlib.util.get_cache_base() for more information.
Get a finder for the specified package.
If the package hasn’t been imported yet, an attempt will be made to import it. If importing fails, an ImportError will be raised.
| Parameters: | package (str) – The name of the package for which a finder is desired. |
|---|---|
| Returns: | A finder for the package. |
Register a callable which makes finders for a particular type of PEP 302 loader.
| Parameters: |
|
|---|
A class representing resources. It is never instantiated directly, but always through calling a finder’s find method.
Properties:
Whether this instance is a container of other resources.
All of the resource data as a byte string. Raises an exception if accessed on a container resource.
The size of the resource data in bytes. Raises an exception if accessed on a container resource.
The relative names of all the contents of this resource. Raises an exception if accessed on a resource which is not a container.
This attribute is set by the resource’s finder. It is a textual representation of the path, such that if a PEP 302 loader’s get_data() method is called with the path, the resource’s bytes are returned by the loader. This attribute is analogous to the resource_filename API in setuptools. Note that for resources in zip files, the path will be a pointer to the resource in the zip file, and not directly usable as a filename. While setuptools deals with this by extracting zip entries to cache and returning filenames from the cache, this does not seem an appropriate thing to do in this package, as a resource is already made available to callers either as a stream or a string of bytes.
This attribute is the same as the path for file-based resource. For resources in a .zip file, the relevant resource is extracted to a file in a cache in the file system, and the name of the cached file is returned. This is for use with APIs that need file names, or need to be able to access data through OS-level file handles. See the Cache documentation for more information about the cache.
Methods:
A base class for resource finders, which finds resources for packages stored in the file system.
Initialise the finder for the package specified by module.
| Parameters: | module – The Python module object representing a package. |
|---|
Find a resource with the name specified by resource_name and return a Resource instance which represents it.
| Parameters: | resource_name – A fully qualified resource name, with hierarchical components separated by ‘/’. |
|---|---|
| Returns: | A Resource instance, or None if a resource with that name wasn’t found. |
Return a generator which walks through the resources available through resource_name.
| Parameters: | resource_name – A fully qualified resource name, with hierarchical components separated by ‘/’. You can use ‘’ to mean the ‘root’ resource. If the resource name refers to a non-container resource, only that resource is returned. Otherwise, the named resource is returned, followed by its children, recursively. If there is no resource named resource_name, None is returned. |
|---|---|
| Returns: | A generator to iterate over resources, or None. |
Return whether a resource is a container of other resources.
| Parameters: | resource (a Resource instance) – The resource whose status as container is wanted. |
|---|---|
| Returns: | True or False. |
Return a binary stream for the specified resource.
| Parameters: | resource (a Resource instance) – The resource for which a stream is wanted. |
|---|---|
| Returns: | A binary stream for the resource. |
This has the same interface as ResourceFinder.
This class implements a cache for resources which must be accessible as files in the file system. It is based on Cache, and adds resource-specific methods.
Initialise a cache instance with a specific directory which holds the cache. If base is not specified, the value resource-cache in the directory returned by get_cache_base() is used.
A class used to install scripts based on specifications.
The directory where script sources are to be found.
The directory where scripts are to be created.
Whether to create native executable launchers on Windows.
Whether to overwrite scripts even when timestamps show they’re up to date.
Whether, on Posix, the scripts should have their execute mode set.
The text of a template which should contain %(shebang)s, %(module)s and %(func)s in the appropriate places.
The attribute is defined at class level. You can override it at the instance level to customise your scripts.
Initialise the instance with options that control its behaviour.
| Parameters: |
|
|---|
Make a script in the target directory.
| Parameters: |
|
|---|---|
| Returns: | A list of absolute pathnames of files installed (or which would have been installed, but for dry_run being true). |
Make multiple scripts from an iterable.
This method just calls make() once for each value returned by the iterable, but it might be convenient to override this method in some scenarios to do post-processing of the installed files (for example, running 2to3 on them).
| Parameters: |
|
|---|---|
| Returns: | A list of absolute pathnames of files installed (or which would have been installed, but for dry_run being true). |
The base class for locators. Implements logic common to multiple locators.
Initialise an instance of the locator.
| Parameters: | scheme (str) – The version scheme to use. |
|---|
This method should be implemented in subclasses. It returns a (potentially empty) dictionary whose keys are the versions located for the project named by name, and whose values are instances of distlib.util.Distribution.
Extract information from a URL about the name and version of a distribution.
| Parameters: | |
|---|---|
| Returns: | None if the URL does not appear to be that of a distribution archive for the named project. Otherwise, a dictionary is returned with the following keys at a minimum:
Optional keys returned are:
|
| Return type: | dict |
Get the names of all distributions known to this locator.
The base class raises NotImplementedError; this method should be implemented in a subclass.
| Returns: | All distributions known to this locator. |
|---|---|
| Return type: | set |
This tries to locate the latest version of a potentially downloadable distribution which matches a requirement (name and version constraints). If a potentially downloadable distribution (i.e. one with a download URL) is not found, None is returned – otherwise, an instance of Distribution is returned. The returned instance will have, at a minimum, name, version and source_url populated.
| Parameters: |
|
|---|---|
| Returns: | A matching instance of Distribution, or None. |
This returns a (possibly empty) list of error messages relating to a recent get_project() or locate() call. Fetching the errors clears the error list.
New in version 0.2.4.
This locator scans the file system under a base directory, looking for distribution archives. The locator scans all subdirectories recursively, unless the recursive flag is set to False.
This locator uses the PyPI XML-RPC interface to locate distribution archives and other data about downloads.
This locator uses the PyPI JSON interface to locate distribution archives and other data about downloads. It gets the metadata and URL information in a single call, so it should perform better than the XML-RPC locator.
This locator uses the PyPI ‘simple’ interface – a Web scraping interface – to locate distribution archives.
This locator uses a DistributionPath instance to locate installed distributions.
| Parameters: |
|
|---|
This locator uses a list of other aggregators and delegates finding projects to them. It can either return the first result found (i.e. from the first aggregator in the list provided which returns a non-empty result), or a merged result from all the aggregators in the list.
| Parameters: |
|
|---|
This class allows you to recursively find all the distributions which a particular distribution depends on.
Initialise an instance with the locator to be used for locating distributions.
Find all the distributions needed to fulfill requirement.
| Parameters: |
|
|---|---|
| Returns: | A 2-tuple. The first element is a set of Distribution instances. The second element is a set of problems encountered during dependency resolution. Currently, if this set is non- empty, it will contain 2-tuples whose first element is the string ‘unsatisfied’ and whose second element is a requirement which couldn’t be satisfied. In the set of Distribution instances returned, some attributes will be set:
|
Retrieve the names of all distributions registered on an index.
| Parameters: | url (str) – The XML-RPC service URL of the node to query. If not specified, The main PyPI index is queried. |
|---|---|
| Returns: | A list of the names of distributions registered on the index. Note that some of the names may be Unicode. |
| Return type: | list |
This convenience function returns the latest version of a potentially downloadable distribution which matches a requirement (name and version constraints). If a potentially downloadable distribution (i.e. one with a download URL) is not found, None is returned – otherwise, an instance of Distribution is returned. The returned instance will have, at a minimum, name, version, download_url and download_urls.
| Parameters: |
|
|---|---|
| Returns: | A matching instance of Distribution, or None. |
This class represents a package index which is compatible with PyPI, the Python Package Index. It allows you to register projects, upload source and binary distributions (with support for digital signatures), upload documentation, verify signatures and get a list of hosts which are mirrors for the index.
Methods:
Initialise an instance, setting instance attributes named from the keyword arguments.
| Parameters: |
|
|---|
Register a project with the index.
| Parameters: | metadata – A Metadata instance. This should have at least the Name and Version fields set, and ideally as much metadata as possible about this distribution. Though it might seem odd to have to specify a version when you are initially registering a project, this is required by PyPI. You can see this in PyPI’s Web UI when you click the “Package submission” link in the left-hand side menu. |
|---|---|
| Returns: | An urllib HTTP response returned by the index. If an error occurs, an HTTPError exception will be raised. |
Upload a distribution to the index.
| Parameters: |
|
|---|---|
| Returns: | An urllib HTTP response returned by the index. If an error occurs, an HTTPError exception will be raised. |
Changed in version 0.1.9: The keystore argument was added.
Upload HTML documentation to the index. The contents of the specified directory tree will be packed into a .zip file which is then uploaded to the index.
| Parameters: |
|
|---|---|
| Returns: | An urllib HTTP response returned by the index. If an error occurs, an HTTPError exception will be raised. |
Verify a digital signature against a downloaded distribution.
| Parameters: |
|
|---|---|
| Returns: | True if the signature can be verified, else False. If an error occurs (e.g. unable to locate the public key used to verify the signature), a ValueError is raised. |
Changed in version 0.1.9: The keystore argument was added.
Search the index for distributions matching a search query.
| Parameters: |
|
|---|---|
| Returns: | A (possibly empty) list of the distributions matching the query. Each entry in the list will be a dictionary with the following keys:
|
New in version 0.1.8.
Additional attributes:
The username to use when authenticating with the index.
The password to use when authenticating with the index.
The path to the signing and verification program.
The location of the key database for the signing and verification program.
The list of hosts which are mirrors for this index.
The boundary value to use when MIME-encoding requests to be sent to the index. This should be a byte-string.
This base class implements common operations for distlib caches.
Initialise a cache instance with a specific directory which holds the cache.
Warning
If base is specified and exists, it should exist and its permissions (relevant on POSIX only) should be set to 0700 - i.e. only the user of the running process has any rights over the directory. If this is not done, the application using this functionality may be vulnerable to security breaches as a result of other processes being able to interfere with the cache.
Converts a prefix (e.g. the name of a resource’s containing .zip, or a wheel pathname) into a directory name in the cache. This implementation delegates the work to path_to_cache_dir().
Attributes:
A class holding information about a exports entry.
The name of the entry.
The prefix part of the entry. For a callable or data item in a module, this is the name of the package or module containing the item.
The suffix part of the entry. For a callable or data item in a module, this is a dotted path which points to the item in the module.
A list of flags. See Flag formats for more information.
The actual value of the entry (a callable or data item in a module, or perhaps just a module). This is a cached property of the instance, and is determined by calling resolve() with the prefix and suffix properties.
The distribution which exports this entry. This is normally an instance of InstalledDistribution.
Return the base directory which will hold distlib caches. If the directory does not exist, it is created.
On Windows, if LOCALAPPDATA is defined in the environment, then it is assumed to be a directory, and will be the parent directory of the result. On POSIX, and on Windows if LOCALAPPDATA is not defined, the user’s home directory – as determined using os.expanduser('~') – will be the parent directory of the result.
The result is just the directory '.distlib' in the parent directory as determined above.
If a home directory is unavailable (no such directory, or if it’s write- protected), a parent directory for the cache is determined using tempfile.mkdtemp(). This returns a directory to which only the running process has access (permission mask 0700 on POSIX), meaning that the cache should be isolated from possible malicious interference by other processes.
Note
This cache is used for the following purposes:
The application using this cache functionality, whether through the above mechanisms or through using the value returned from here directly, is responsible for any cache cleanup that is desired. Note that on Windows, you may not be able to do cache cleanup if any of the cached files are open (this will generally be the case with shared libraries, i.e. DLLs). The best way to do cache cleanup in this scenario may be on application startup, before any resources have been cached or wheels mounted.
Converts a path (e.g. the name of an archive) into a directory name suitable for use in a cache. The following algorithm is used:
Return a export entry from a specification, if it matches the expected format, or else None.
| Parameters: | specification (str) – A specification, as documented for the distlib.scripts.ScriptMaker.make() method. |
|---|---|
| Returns: | None if the specification didn’t match the expected form for an entry, or else an instance of ExportEntry holding information about the entry. |
Given a module name and a dotted_path representing an object in that module, resolve the passed parameters to an object and return that object.
If the module has not already been imported, this function attempts to import it, then access the object represented by dotted_path in the module’s namespace. If dotted_path is None, the module is returned. If import or attribute access fails, an ImportError or AttributeError will be raised.
| Parameters: |
|---|
This package has functionality which allows you to work with wheels (see PEP 427).
An instance of distlib.util.Cache. This can be set after module import, but before calling any functionality which uses it, to ensure that the cache location is entirely under your control.
If you call the mount method of a Wheel instance, and the wheel is successfully mounted and contains C extensions, the cache will be needed, and if not set by you, an instance with a default location will be created. See distlib.util.get_cache_base() for more information.
This class represents wheels – either existing wheels, or wheels to be built.
Initialise an instance from a specification.
| Parameters: | spec (str) – This can either be a valid filename for a wheel (for when you want to work with an existing wheel), or just the name-version-buildver portion of a wheel’s filename (for when you’re going to build a wheel for a known version and build of a named project). |
|---|
Build a wheel. The name, version and buildver should already have been set correctly.
| Parameters: |
|
|---|
Install from a wheel.
| Parameters: |
|
|---|
Determine whether this wheel instance is compatible with the running Python.
| Returns: | True if compatible, else False. |
|---|
Determine whether this wheel instance is indicated suitable for mounting in its metadata.
| Returns: | True if mountable, else False. |
|---|
Mount the wheel so that its contents can be imported directly, without the need to install the wheel. If the wheel contains C extensions and has metadata about these extensions, the extensions are also available for import.
If the wheel tags indicate it is not compatible with the running Python, a DistlibException is raised. (The is_compatible() method is used to determine compatibility.)
If the wheel is indicated as not suitable for mounting, a DistlibException is raised. (The is_mountable() method is used to determine mountability.)
param append: If True, the wheel’s pathname is added to the end of sys.path. By default, it is added to the beginning. Note
Wheels may state in their metadata that they are not intended to be mountable, in which case this method will raise a DistlibException with a suitable message. If C extensions are extracted, the location for extraction will be under the directory dylib-cache in the directory returned by get_cache_base().
Wheels may be marked by their publisher as unmountable to indicate that running directly from a zip is not supported by the packaged software.
Unmount the wheel so that its contents can no longer be imported directly. If the wheel contains C extensions and has metadata about these extensions, the extensions are also made unavailable for import.
Note
Unmounting does not automatically clean up any extracted C extensions, as that may not be desired (and not possible, on Windows, because the files will be open). See the get_cache_base() documentation for suggested cleanup scenarios.
Verify sizes and hashes of the wheel’s contents against the sizes and hashes declared in the wheel’s RECORD. Raise a DistlibException if a size or digest mismatch is detected.
New in version 0.1.8.
Allows a user-defined callable access to the contents of a wheel. The callable can modify the contents of the wheel, add new entries or remove entries. The method first extracts the wheel’s contents to a temporary location, and then calls the modifier like this:
modified = modifier(path_map, **kwargs)
where path_map is a dictionary mapping archive paths to the location of the corresponding extracted archive entry, and kwargs is whatever was passed to the update method. If the modifier returns True, a new wheel is built from the (possibly updated) contents of path_map and, as a final step, copied to the location of the original wheel (hence effectively modifying it in-place). The passed path_map will contain all of the wheel’s entries other than the RECORD entry (which will be recreated if a new wheel is built).
New in version 0.1.8.
The name of the distribution.
The version of the distribution
The build tag for the distribution.
A list of Python versions with which the wheel is compatible. See PEP 427 and PEP 425 for details.
A list of application binary interfaces (ABIs) with which the wheel is compatible. See PEP 427 and PEP 425 for details.
A list of architectures with which the wheel is compatible. See PEP 427 and PEP 425 for details.
The directory in which a wheel file is found/to be created.
The filename of the wheel (computed from the other attributes)
The metadata for the distribution in the wheel, as a Metadata instance.
The wheel metadata (contents of the WHEEL metadata file) as a dictionary.
Whether the wheel file exists.
New in version 0.1.8.
Indicate if a wheel is compatible with a set of tags. If any combination of the tags of wheel is found in tags, then the wheel is considered to be compatible.
| Parameters: |
|
|---|---|
| Returns: | True if compatible, else False. |
You might find it helpful to look at the mailing list.