.. _reference: API Reference ============= This is the place where the functions and classes in ``distlib's`` public API are described. The ``distlib.database`` package -------------------------------- Classes ^^^^^^^ .. class:: DistributionPath 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: .. method:: __init__(path=None, include_egg=False) Initialise the instance using a particular path. :param path: The path to use when looking for distributions. If ``None`` is specified, ``sys.path`` is used. :type path: list of str :param include_egg: If ``True``, legacy distributions (eggs) are included in the search; otherwise, they aren't. .. method:: enable_cache() 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 :meth:`disable_cache` and cleared using :meth:`clear_cache` (disabling won't automatically clear it). .. method:: disable_cache() Disables the cache, but doesn't clear it. .. method:: clear_cache() Clears the cache, but doesn't change its enabled/disabled status. If enabled, the cache will be re-populated when querying for distributions. .. method:: get_distributions() The main querying method if you want to look at all the distributions. It returns an iterator which returns :class:`Distribution` and, if ``include_egg`` was specified as ``True`` for the instance, also instances of any :class:`EggInfoDistribution` for any legacy distributions found. .. method:: get_distribution(name) 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 :class:`Distribution` (or, if ``include_egg`` was specified as ``True`` for the instance, an instance of :class:`EggInfoDistribution` if a legacy distribution was found with that name). :param name: The name of the distribution to search for. :type name: str .. method:: get_exported_entries(category, name=None) Returns an iterator for entries exported by distributions on the path. :param category: The export category to look in. :type category: str :param name: A specific name to search for. If not specified, all entries in the category are returned. :type name: str :returns: An iterator which iterates over exported entries (instances of :class:`ExportEntry`). .. class:: Distribution 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: .. attribute:: name The name of the distribution. .. attribute:: version The version of the distribution. .. attribute:: metadata The metadata for the distribution. This is a :class:`distlib.metadata.Metadata` instance. .. attribute:: download_url The download URL for the distribution. If there are multiple URLs, this will be one of the values in :attr:`download_urls`. .. attribute:: download_urls A set of known download URLs for the distribution. .. versionadded:: 0.2.0 The ``download_urls`` attribute was added. .. attribute:: digest 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...')``. .. attribute:: digests A dictionary mapping download URLs to digests, if and when digests are available. .. versionadded:: 0.2.0 The ``digests`` attribute was added. .. attribute:: locator The locator for an instance which has been retrieved through a locator. This is ``None`` for an installed distribution. .. class:: InstalledDistribution(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 :class:`DistributionPath`. Properties: .. attribute:: requested Whether the distribution was installed by user request (if not, it may have been installed as a dependency of some other distribution). .. attribute:: exports The distribution's exports, as described in :ref:`dist-exports`. This is a cached property. Methods: .. method:: list_installed_files(local=False) 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. :param 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. .. method:: list_distinfo_files(local=False) Similar to :meth:`list_installed_files`, but only returns metadata files. :param local: As for :meth:`list_installed_files`. .. method:: check_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: * The path in ``RECORD`` which failed to match. * One of the strings 'exists', 'size' or 'hash' according to what didn't match (existence is checked first, then size, then hash). * The expected value of what didn't match (as obtained from ``RECORD``). * The actual value of what didn't match (as obtained from the file system). .. method:: read_exports(filename=None) Read exports information from a file. Normal access to a distribution's exports should be through its :attr:`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). :param filename: The filename to read from, or ``None`` to read from the default location. :type filename: str :returns: The exports read from the file. :rtype: dict .. method:: write_exports(exports, filename=None) Write exports information to a file. If no filename is specified, the ``EXPORTS`` file in the ``.dist-info`` directory is written. :param exports: A dictionary whose keys are categories and whose values are dictionaries which contain :class:`ExportEntry` instances keyed on their name. :type exports: dict :param filename: The filename to read from, or ``None`` to read from the default location. :type filename: str .. class:: EggInfoDistribution Analogous to :class:`Distribution`, but covering legacy distributions. This class is not instantiated directly. Instances of it are returned from querying a :class:`DistributionPath`. Properties: .. attribute:: name The name of the distribution. .. attribute:: version The version of the distribution. .. attribute:: metadata The metadata for the distribution. This is a :class:`distlib.metadata.Metadata` instance. Methods: .. method:: list_installed_files(local=False) Returns a list all of the individual files installed as part of the distribution. :param local: If ``True``, the paths returned are local absolute paths (i.e. with platform-specific directory separators as indicated by ``os.sep``). .. class:: DependencyGraph 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``. .. method:: add_distribution(distribution) Add *distribution* to the graph. .. method:: add_edge(x, y, label=None) Add an edge from distribution *x* to distribution *y* with the given *label* (string). .. method:: add_missing(distribution, requirement) Add a missing *requirement* (string) for the given *distribution*. .. method:: repr_node(dist, level=1) 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: .. attribute:: adjacency_list 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). .. attribute:: reverse_list Dictionary mapping distributions to a list of predecessors. This allows efficient traversal. .. attribute:: missing Dictionary mapping distributions to a list of requirements that were not provided by any distribution. The ``distlib.resources`` package --------------------------------- .. currentmodule:: distlib.resources Attributes ^^^^^^^^^^ .. attribute:: cache An instance of :class:`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 :class:`Resource` instance, the cache will be needed, and if not set by you, an instance with a default location will be created. See :func:`distlib.util.get_cache_base` for more information. Functions ^^^^^^^^^ .. function:: finder(package) 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 :class:`ImportError` will be raised. :param package: The name of the package for which a finder is desired. :type package: str :returns: A finder for the package. .. function:: register_finder(loader, finder_maker) Register a callable which makes finders for a particular type of :pep:`302` loader. :param loader: The loader for which a finder is to be returned. :param finder_maker: A callable to be registered, which is called when a loader of the specified type is used to load a package. The callable is called with a single argument -- the Python module object corresponding to the package -- and must return a finder for that package. Classes ^^^^^^^ .. class:: Resource A class representing resources. It is never instantiated directly, but always through calling a finder's ``find`` method. Properties: .. attribute:: is_container Whether this instance is a container of other resources. .. attribute:: bytes All of the resource data as a byte string. Raises an exception if accessed on a container resource. .. attribute:: size The size of the resource data in bytes. Raises an exception if accessed on a container resource. .. attribute:: resources The relative names of all the contents of this resource. Raises an exception if accessed on a resource which is *not* a container. .. attribute:: path 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 :meth:`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. .. attribute:: file_path 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 :class:`~distlib.resources.Cache` documentation for more information about the cache. Methods: .. method:: as_stream() A binary stream of the resource's data. This must be closed by the caller when it's finished with. Raises an exception if called on a container resource. .. class:: ResourceFinder A base class for resource finders, which finds resources for packages stored in the file system. .. method:: __init__(module) Initialise the finder for the package specified by ``module``. :param module: The Python module object representing a package. .. method:: find(resource_name) Find a resource with the name specified by ``resource_name`` and return a ``Resource`` instance which represents it. :param resource_name: A fully qualified resource name, with hierarchical components separated by '/'. :returns: A :class:`Resource` instance, or ``None`` if a resource with that name wasn't found. .. method:: iterator(resource_name) Return a generator which walks through the resources available through ``resource_name``. :param 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``. .. method:: is_container(resource) Return whether a resource is a container of other resources. :param resource: The resource whose status as container is wanted. :type resource: a :class:`Resource` instance :returns: ``True`` or ``False``. .. method:: get_stream(resource) Return a binary stream for the specified resource. :param resource: The resource for which a stream is wanted. :type resource: a :class:`Resource` instance :returns: A binary stream for the resource. .. method:: get_bytes(resource) Return the contents of the specified resource as a byte string. :param resource: The resource for which the bytes are wanted. :type resource: a :class:`Resource` instance :returns: The data in the resource as a byte string. .. method:: get_size(resource) Return the size of the specified resource in bytes. :param resource: The resource for which the size is wanted. :type resource: a :class:`Resource` instance :returns: The size of the resource in bytes. .. class:: ZipResourceFinder This has the same interface as :class:`ResourceFinder`. .. class:: ResourceCache This class implements a cache for resources which must be accessible as files in the file system. It is based on :class:`~distlib.util.Cache`, and adds resource-specific methods. .. method:: __init__(base=None) 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 :func:`~distlib.util.get_cache_base` is used. .. method:: get(resource) Ensures that the resource is available as a file in the file system, and returns the name of that file. This method calls the resource's finder's :meth:`get_cache_info` method. .. method:: is_stale(resource, path) Returns whether the data in the resource which is cached in the file system is stale compared to the resource's current data. The default implementation returns ``True``, causing the resource's data to be re-written to the file every time. The ``distlib.scripts`` package ------------------------------- .. currentmodule:: distlib.scripts Classes ^^^^^^^ .. class:: ScriptMaker A class used to install scripts based on specifications. .. attribute:: source_dir The directory where script sources are to be found. .. attribute:: target_dir The directory where scripts are to be created. .. attribute:: add_launchers Whether to create native executable launchers on Windows. .. attribute:: force Whether to overwrite scripts even when timestamps show they're up to date. .. attribute:: set_mode Whether, on Posix, the scripts should have their execute mode set. .. attribute:: script_template 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. .. method:: __init__(source_directory, target_directory, add_launchers=True, dry_run=False) Initialise the instance with options that control its behaviour. :param source_directory: Where to find scripts to install. :type source_directory: str :param target_directory: Where to install scripts to. :type target_directory: str :param add_launchers: If true, create executable launchers on Windows. The executables are currently generated from the following project: https://bitbucket.org/vinay.sajip/simple_launcher/ :type add_launchers: bool :param dry_run: If true, don't actually install scripts - just pretend to. .. method:: make(specification, options=None) Make a script in the target directory. :param specification: A specification, which can take one of the following forms: * A filename, relative to ``source_directory``, such as ``foo.py`` or ``subdir/bar.py``. * A reference to a callable, given in the form:: name = some_package.some_module:some_callable [flags] where the *flags* part is optional. When this form is passed, a Python stub script is created with the appropriate shebang line and with code to load and call the specified callable with no arguments, returning its value as the return code from the script. For more information about flags, see :ref:`flag-formats`. :type specification: str :param options: If specified, a dictionary of options used to control script creation. Currently, the following keys are checked: ``gui``: This should be a ``bool`` which, if ``True``, indicates that the script is a windowed application. This distinction is only drawn on Windows if ``add_launchers`` is ``True``, and results in a windowed native launcher application if ``options['gui']`` is ``True`` (otherwise, the native executable launcher is a console application). ``interpreter_args``: If specified, this should be a list of strings which are appended to the interpreter executable in the shebang line. If there are values with spaces, you will need to surround them with double quotes. .. note:: Linux does not handle passing arguments to interpreters particularly well -- multiple arguments are bundled up into one when passing to the interpreter -- see https://en.wikipedia.org/wiki/Shebang_line#Portability for more information. This may also affect other POSIX platforms -- consult the OS documentation for your system if necessary. On Windows, the ``distlib`` native executable launchers *do* parse multiple arguments and pass them to the interpreter. :type options: dict :returns: A list of absolute pathnames of files installed (or which would have been installed, but for ``dry_run`` being true). .. method:: make_multiple(specifications, options) Make multiple scripts from an iterable. This method just calls :meth:`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). :param specifications: an iterable giving the specifications to follow. :param options: As for the :meth:`make` method. :returns: A list of absolute pathnames of files installed (or which would have been installed, but for ``dry_run`` being true). The ``distlib.locators`` package -------------------------------- .. currentmodule:: distlib.locators Classes ^^^^^^^^ .. class:: Locator The base class for locators. Implements logic common to multiple locators. .. method:: __init__(scheme='default') Initialise an instance of the locator. :param scheme: The version scheme to use. :type scheme: str .. method:: get_project(name) 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 :class:`distlib.util.Distribution`. .. method:: convert_url_to_download_info(url, project_name) Extract information from a URL about the name and version of a distribution. :param url: The URL potentially of an archive (though it needn't be). :type url: str :param project_name: This must match the project name determined from the archive (case-insensitive matching is used). :type project_name: str :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: * url -- the URL passed in, minus any fragment portion. * filename -- a suitable filename to use for the archive locally. Optional keys returned are: * md5_digest -- the MD5 hash of the archive, for verification after downloading. This is extracted from the fragment portion, if any, of the passed-in URL. * sha256_digest -- the SHA256 hash of the archive, for verification after downloading. This is extracted from the fragment portion, if any, of the passed-in URL. :rtype: dict .. method:: get_distribution_names Get the names of all distributions known to this locator. The base class raises :class:`NotImplementedError`; this method should be implemented in a subclass. :returns: All distributions known to this locator. :rtype: set .. method:: locate(requirement, prereleases=False) 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 :class:`~distlib.database.Distribution` is returned. The returned instance will have, at a minimum, ``name``, ``version`` and ``source_url`` populated. :param requirement: The name and optional version constraints of the distribution to locate, e.g. ``'Flask'`` or ``'Flask (>= 0.7, < 0.9)'``. :type requirement: str :param prereleases: If ``True``, prereleases are treated like normal releases. The default behaviour is to not return any prereleases unless they are the only ones which match the requirement. :type prereleases: bool :returns: A matching instance of :class:`~distlib.database.Distribution`, or ``None``. .. method:: get_errors() This returns a (possibly empty) list of error messages relating to a recent :meth:`~distlib.locators.Locator.get_project` or :meth:`~distlib.locators.Locator.locate` call. Fetching the errors clears the error list. .. versionadded:: 0.2.4 .. class:: DirectoryLocator(Locator) 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``. .. method:: __init__(base_dir, **kwargs) :param base_dir: The base directory to scan for distribution archives. :type base_dir: str :param kwargs: Passed to base class constructor, apart from the following keyword arguments: * ``recursive`` (defaults to ``True``) -- if ``False``, no recursion into subdirectories occurs. .. class:: PyPIRPCLocator(Locator) This locator uses the PyPI XML-RPC interface to locate distribution archives and other data about downloads. .. method:: __init__(url, **kwargs) :param url: The base URL to use for the XML-RPC service. :type url: str :param kwargs: Passed to base class constructor. .. method:: get_project(name) See :meth:`Locator.get_project`. .. class:: PyPIJSONLocator(Locator) 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. .. method:: __init__(url, **kwargs) :param url: The base URL to use for the JSON service. :type url: str :param kwargs: Passed to base class constructor. .. method:: get_project(name) See :meth:`Locator.get_project`. .. class:: SimpleScrapingLocator This locator uses the PyPI 'simple' interface -- a Web scraping interface -- to locate distribution archives. .. method:: __init__(url, timeout=None, num_workers=10, **kwargs) :param url: The base URL to use for the simple service HTML pages. :type url: str :param timeout: How long (in seconds) to wait before giving up on a remote resource. :type timeout: float :param num_workers: The number of worker threads created to perform scraping activities. :type num_workers: int :param kwargs: Passed to base class constructor. .. class:: DistPathLocator This locator uses a :class:`DistributionPath` instance to locate installed distributions. .. method:: __init__(url, distpath, **kwargs) :param distpath: The distribution path to use. :type distpath: :class:`DistributionPath` :param kwargs: Passed to base class constructor. .. class:: AggregatingLocator(Locator) 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. .. method:: __init__(*locators, **kwargs) :param locators: A list of aggregators to delegate finding projects to. :type locators: sequence of locators :param merge: If this *kwarg* is ``True``, each aggregator in the list is asked to provide results, which are aggregated into a results dictionary. If ``False``, the first non-empty return value from the list of aggregators is returned. The locators are consulted in the order in which they're passed in. :type merge: bool .. class:: DependencyFinder This class allows you to recursively find all the distributions which a particular distribution depends on. .. method:: __init__(locator) Initialise an instance with the locator to be used for locating distributions. .. method:: find(requirement, metas_extras=None, prereleases=False) Find all the distributions needed to fulfill ``requirement``. :param requirement: A string of the from ``name (version)`` where version can include an inequality constraint, or an instance of :class:`Distribution` (e.g. representing a distribution on the local hard disk). :param meta_extras: A list of meta extras such as :test:, :build: and so on, to be included in the dependencies. :param prereleases: If ``True``, allow pre-release versions to be returned - otherwise, don't return prereleases unless they're all that's available. :returns: A 2-tuple. The first element is a set of :class:`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 :class:`Distribution` instances returned, some attributes will be set: * The instance representing the passed-in ``requirement`` will have the :attr:`requested` attribute set to ``True``. * All requirements which are not installation requirements (in other words, are needed only for build and test) will have the :attr:`build_time_dependency` attribute set to ``True``. Functions ^^^^^^^^^ .. function:: get_all_distribution_names(url=None) Retrieve the names of all distributions registered on an index. :param url: The XML-RPC service URL of the node to query. If not specified, The main PyPI index is queried. :type url: str :returns: A list of the names of distributions registered on the index. Note that some of the names may be Unicode. :rtype: list .. function:: locate(requirement, prereleases=False) 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 :class:`~distlib.database.Distribution` is returned. The returned instance will have, at a minimum, ``name``, ``version``, ``download_url`` and ``download_urls``. :param requirement: The name and optional version constraints of the distribution to locate, e.g. ``'Flask'`` or ``'Flask (>= 0.7, < 0.9)'``. :type requirement: str :param prereleases: If ``True``, prereleases are treated like normal releases. The default behaviour is to not return any prereleases unless they are the only ones which match the requirement. :type prereleases: bool :returns: A matching instance of :class:`~distlib.database.Distribution`, or ``None``. Variables ^^^^^^^^^ .. attribute:: default_locator This attribute holds a locator which is used by :func:`locate` to locate distributions. The ``distlib.index`` package -------------------------------- .. currentmodule:: distlib.index Classes ^^^^^^^^ .. class:: PackageIndex 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: .. method:: __init__(url=None, mirror_host=None) Initialise an instance, setting instance attributes named from the keyword arguments. :param url: The root URL for the index. If not specified, the URL for PyPI is used ('http://pypi.python.org/pypi'). :param mirror_host: The DNS name for a host which can be used to determine available mirror hosts for the index. If not specified, the value 'last.pypi.python.org' is used. .. method:: register(metadata) Register a project with the index. :param metadata: A :class:`~distlib.metadata.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 :class:`HTTPError` exception will be raised. .. method:: upload_file(metadata, filename, signer=None, sign_password=None, filetype='sdist', pyversion='source', keystore=None) Upload a distribution to the index. :param metadata: A :class:`~distlib.metadata.Metadata` instance. This should have at least the ``Name`` and ``Version`` fields set, and ideally as much metadata as possible about this distribution. :param file_name: The path to the file which is to be uploaded. :param signer: If specified, this needs to be a string identifying the GnuPG private key which is to be used for signing the distribution. :param sign_password: The passphrase which allows access to the private key used for the signature. :param filetype: The type of the file being uploaded. This would have values such as ``sdist`` (for a source distribution), ``bdist_wininst`` for a Windows installer, and so on. Consult the ``distutils`` documentation for the full set of possible values. :param pyversion: The Python version this distribution is compatible with. If it's a pure-Python distribution, the value to use would be ``source`` - for distributions which are for specific Python versions, you would use the Python version in the form ``X.Y``. :param keystore: The path to a directory which contains the keys used in signing. If not specified, the instance's ``gpg_home`` attribute is used instead. This parameter is not used unless a signer is specified. :returns: An ``urllib`` HTTP response returned by the index. If an error occurs, an :class:`HTTPError` exception will be raised. .. versionchanged:: 0.1.9 The ``keystore`` argument was added. .. method:: upload_documentation(metadata, doc_dir) 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. :param metadata: A :class:`~distlib.metadata.Metadata` instance. This should have at least the ``Name`` and ``Version`` fields set. :param doc_dir: The path to the root directory for the HTML documentation. This directory should be the one that contains ``index.html``. :returns: An ``urllib`` HTTP response returned by the index. If an error occurs, an :class:`HTTPError` exception will be raised. .. method:: verify_signature(self, signature_filename, data_filename, keystore=None) Verify a digital signature against a downloaded distribution. :param signature_filename: The path to the file which contains the digital signature. :param data_filename: The path to the file which was supposedly signed to obtain the signature in ``signature_filename``. :param keystore: The path to a directory which contains the keys used in verification. If not specified, the instance's ``gpg_home`` attribute is used instead. :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. .. versionchanged:: 0.1.9 The ``keystore`` argument was added. .. method:: search(query, operation=None) Search the index for distributions matching a search query. :param query: The query, either as a string or a dictionary. If a string ``'foo'`` is passed, it will be treated equivalently to passing the dictionary ``{'name': 'foo'}``. The dictionary can have the following keys: * name * version * stable_version * author * author_email * maintainer * maintainer_email * home_page * license * summary * description * keywords * platform * download_url * classifiers (list of classifier strings) * project_url * docs_url (URL of the pythonhosted.org docs if they've been supplied) :param operation: If specified, it should be either ``'and'`` or ``'or'``. If not specified, ``'and'`` is assumed. This is only used if a passed dictionary has multiple keys. It determines whether the intersection or the union of matches is returned. :returns: A (possibly empty) list of the distributions matching the query. Each entry in the list will be a dictionary with the following keys: * _pypi_ordering -- the internal ordering value (an integer) * name --The name of the distribution * version -- the version of the distribution * summary -- the summary for that version .. versionadded:: 0.1.8 Additional attributes: .. attribute:: username The username to use when authenticating with the index. .. attribute:: password The password to use when authenticating with the index. .. attribute:: gpg The path to the signing and verification program. .. attribute:: gpg_home The location of the key database for the signing and verification program. .. attribute:: mirrors The list of hosts which are mirrors for this index. .. attribute:: boundary The boundary value to use when MIME-encoding requests to be sent to the index. This should be a byte-string. The ``distlib.util`` package ------------------------------- .. currentmodule:: distlib.util Classes ^^^^^^^^ .. class:: Cache This base class implements common operations for ``distlib`` caches. .. method:: __init__(base) 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. .. method:: prefix_to_dir(prefix) 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 :func:`~distlib.util.path_to_cache_dir`. .. class:: ExportEntry Attributes: A class holding information about a exports entry. .. attribute:: name The name of the entry. .. attribute:: prefix 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. .. attribute:: suffix 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. .. attribute:: flags A list of flags. See :ref:`flag-formats` for more information. .. attribute:: value 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 :func:`resolve` with the ``prefix`` and ``suffix`` properties. .. attribute:: dist The distribution which exports this entry. This is normally an instance of :class:`InstalledDistribution`. Functions ^^^^^^^^^ .. function:: get_cache_base() 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 :func:`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: * As a place to cache package resources which need to be in the file system, because they are used by APIs which either expect filesystem paths, or to be able to use OS-level file handles. An example of the former is the :meth:`SSLContext.load_verify_locations` method in Python's ``ssl`` module. The subdirectory ``resource-cache`` is used for this purpose. * As a place to cache shared libraries which are extracted as a result of calling the :meth:`~wheel.Wheel.mount` method of the :class:`~wheel.Wheel` class. The subdirectory ``dylib-cache`` is used for this purpose. 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. .. function:: path_to_cache_dir(path) 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: #. On Windows, any ``':'`` in the drive is replaced with ``'---'``. #. Any occurrence of ``os.sep`` is replaced with ``'--'``. #. ``'.cache'`` is appended. .. function:: get_export_entry(specification) Return a export entry from a specification, if it matches the expected format, or else ``None``. :param specification: A specification, as documented for the :meth:`distlib.scripts.ScriptMaker.make` method. :type specification: str :returns: ``None`` if the specification didn't match the expected form for an entry, or else an instance of :class:`ExportEntry` holding information about the entry. .. function:: resolve(module_name, dotted_path) 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. :param module_name: The name of a Python module or package, e.g. ``os`` or ``os.path``. :type module_name: str :param dotted_path: The path of an object expected to be in the module's namespace, e.g. ``'environ'``, ``'sep'`` or ``'path.supports_unicode_filenames'``. :type dotted_path: str The ``distlib.wheel`` package ----------------------------- This package has functionality which allows you to work with wheels (see :pep:`427`). Attributes ^^^^^^^^^^ .. attribute:: cache An instance of :class:`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 :class:`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 :func:`distlib.util.get_cache_base` for more information. Classes ^^^^^^^ .. class:: Wheel This class represents wheels -- either existing wheels, or wheels to be built. .. method:: __init__(spec) Initialise an instance from a specification. :param spec: 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). :type spec: str .. method:: build(paths, tags=None, wheel_version=None) Build a wheel. The ``name``, ``version`` and ``buildver`` should already have been set correctly. :param paths: This should be a dictionary with keys ``'prefix'``, ``'scripts'``, ``'headers'``, ``'data'`` and one of ``'purelib'`` or ``'platlib'``. These must point to valid paths if they are to be included in the wheel. :param tags: If specified, this should be a dictionary with optional keys ``'pyver'``, ``'abi'`` and ``'arch'`` indicating lists of tags which indicate environments with which the wheel is compatible. :param wheel_version: If specified, this is written to the wheel's "Wheel-Version" metadata. If not specified, the implementation's latest supported wheel version is used. .. method:: install(self, paths, maker, **kwargs) Install from a wheel. :param paths: This should be a dictionary with keys ``'prefix'``, ``'scripts'``, ``'headers'``, ``'data'``, ``'purelib'`` and ``'platlib'``. These must point to valid paths to which files may be written if they are in the wheel. Only one of the ``'purelib'`` and ``'platlib'`` paths will be used (in the case where they are different), depending on whether the wheel is for a pure-Python distribution. :param maker: This should be set to a suitably configured instance of :class:`ScriptMaker`. The ``source_dir`` and ``target_dir`` arguments can be set to ``None`` when creating the instance - these will be set to appropriate values inside this method. :param warner: If specified, should be a callable that will be called with (software_wheel_ver, file_wheel_ver) if they differ. They will both be in the form of tuples (major_ver, minor_ver). :param lib_only: It's conceivable that one might want to install only the library portion of a package -- not installing scripts, headers, data and so on. If ``lib_only`` is specified as ``True``, only the ``site-packages`` contents will be installed. .. method:: is_compatible() Determine whether this wheel instance is compatible with the running Python. :return: ``True`` if compatible, else ``False``. .. method:: is_mountable() Determine whether this wheel instance is indicated suitable for mounting in its metadata. :return: ``True`` if mountable, else ``False``. .. method:: mount(append=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 :class:`DistlibException` is raised. (The :meth:`is_compatible` method is used to determine compatibility.) If the wheel is indicated as not suitable for mounting, a :class:`DistlibException` is raised. (The :meth:`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 :class:`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 :func:`~distlib.util.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. .. method:: unmount() 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 :func:`~distlib.util.get_cache_base` documentation for suggested cleanup scenarios. .. method:: verify() Verify sizes and hashes of the wheel's contents against the sizes and hashes declared in the wheel's RECORD. Raise a :class:`DistlibException` if a size or digest mismatch is detected. .. versionadded:: 0.1.8 .. method:: update(modifier, dest_dir=None, **kwargs) 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). .. versionadded:: 0.1.8 .. attribute:: name The name of the distribution. .. attribute:: version The version of the distribution .. attribute:: buildver The build tag for the distribution. .. attribute:: pyver A list of Python versions with which the wheel is compatible. See :pep:`427` and :pep:`425` for details. .. attribute:: abi A list of application binary interfaces (ABIs) with which the wheel is compatible. See :pep:`427` and :pep:`425` for details. .. attribute:: arch A list of architectures with which the wheel is compatible. See :pep:`427` and :pep:`425` for details. .. attribute:: dirname The directory in which a wheel file is found/to be created. .. attribute:: filename The filename of the wheel (computed from the other attributes) .. attribute:: metadata The metadata for the distribution in the wheel, as a :class:`Metadata` instance. .. attribute:: info The wheel metadata (contents of the ``WHEEL`` metadata file) as a dictionary. .. attribute:: exists Whether the wheel file exists. .. versionadded:: 0.1.8 Functions ^^^^^^^^^ .. function:: is_compatible(wheel, tags=None) 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. :param wheel: A :class:`Wheel` instance or the filename of a wheel. :param tags: A set of tags to check for compatibility. If not specified, it defaults to the set of tags which are compatible with this Python implementation. :return: ``True`` if compatible, else ``False``. Attributes ^^^^^^^^^^ .. attribute:: COMPATIBLE_TAGS A set of (``pyver``, ``abi``, ``arch``) tags which are compatible with this Python implementation. Next steps ---------- You might find it helpful to look at the `mailing list `_.