:mod:`packaging.database` --- Database of installed distributions ================================================================= .. module:: packaging.database :synopsis: Functions to query and manipulate installed distributions. This module provides an implementation of :PEP:`376`. It was originally intended to land in :mod:`pkgutil`, but with the inclusion of Packaging in the standard library, it was thought best to include it in a submodule of :mod:`packaging`, leaving :mod:`pkgutil` to deal with imports. Installed Python distributions are represented by instances of :class:`Distribution`, or :class:`EggInfoDistribution` for legacy egg formats. Most functions also provide an extra argument ``use_egg_info`` to take legacy distributions into account. For the purpose of this module, "installed" means that the distribution's :file:`.dist-info`, :file:`.egg-info` or :file:`egg` directory or file is found on :data:`sys.path`. For example, if the parent directory of a :file:`dist-info` directory is added to :envvar:`PYTHONPATH`, then it will be available in the database. Classes representing installed distributions -------------------------------------------- .. class:: Distribution(path) Class representing an installed distribution. It is different from :class:`packaging.dist.Distribution` which holds the list of files, the metadata and options during the run of a Packaging command. Instantiate with the *path* to a ``.dist-info`` directory. Instances can be compared and sorted. Other available methods are: .. XXX describe how comparison works .. method:: get_distinfo_file(path, binary=False) Return a read-only file object for a file located at :file:`{project}-{version}.dist-info/{path}`. *path* should be a ``'/'``-separated path relative to the ``.dist-info`` directory or an absolute path; if it is an absolute path and doesn't start with the path to the :file:`.dist-info` directory, a :class:`PackagingError` is raised. If *binary* is ``True``, the file is opened in binary mode. .. method:: get_resource_path(relative_path) .. TODO .. method:: list_distinfo_files(local=False) Return an iterator over all files located in the :file:`.dist-info` directory. If *local* is ``True``, each returned path is transformed into a local absolute path, otherwise the raw value found in the :file:`RECORD` file is returned. .. method:: list_installed_files(local=False) Iterate over the files installed with the distribution and registered in the :file:`RECORD` file and yield a tuple ``(path, md5, size)`` for each line. If *local* is ``True``, the returned path is transformed into a local absolute path, otherwise the raw value is returned. A local absolute path is an absolute path in which occurrences of ``'/'`` have been replaced by :data:`os.sep`. .. method:: uses(path) Check whether *path* was installed by this distribution (i.e. if the path is present in the :file:`RECORD` file). *path* can be a local absolute path or a relative ``'/'``-separated path. Returns a boolean. Available attributes: .. attribute:: metadata Instance of :class:`packaging.metadata.Metadata` filled with the contents of the :file:`{project}-{version}.dist-info/METADATA` file. .. attribute:: name Shortcut for ``metadata['Name']``. .. attribute:: version Shortcut for ``metadata['Version']``. .. attribute:: requested Boolean indicating whether this distribution was requested by the user of automatically installed as a dependency. .. class:: EggInfoDistribution(path) Class representing a legacy distribution. It is compatible with distutils' and setuptools' :file:`.egg-info` and :file:`.egg` files and directories. .. FIXME should be named EggDistribution Instantiate with the *path* to an egg file or directory. Instances can be compared and sorted. Other available methods are: .. method:: list_installed_files(local=False) .. method:: uses(path) Available attributes: .. attribute:: metadata Instance of :class:`packaging.metadata.Metadata` filled with the contents of the :file:`{project-version}.egg-info/PKG-INFO` or :file:`{project-version}.egg` file. .. attribute:: name Shortcut for ``metadata['Name']``. .. attribute:: version Shortcut for ``metadata['Version']``. Functions to work with the database ----------------------------------- .. function:: get_distribution(name, use_egg_info=False, paths=None) Return an instance of :class:`Distribution` or :class:`EggInfoDistribution` for the first installed distribution matching *name*. Egg distributions are considered only if *use_egg_info* is true; if both a dist-info and an egg file are found, the dist-info prevails. The directories to be searched are given in *paths*, which defaults to :data:`sys.path`. Returns ``None`` if no matching distribution is found. .. FIXME param should be named use_egg .. function:: get_distributions(use_egg_info=False, paths=None) Return an iterator of :class:`Distribution` instances for all installed distributions found in *paths* (defaults to :data:`sys.path`). If *use_egg_info* is true, also return instances of :class:`EggInfoDistribution` for legacy distributions found. .. function:: get_file_users(path) Return an iterator over all distributions using *path*, a local absolute path or a relative ``'/'``-separated path. .. XXX does this work with prefixes or full file path only? .. function:: obsoletes_distribution(name, version=None, use_egg_info=False) Return an iterator over all distributions that declare they obsolete *name*. *version* is an optional argument to match only specific releases (see :mod:`packaging.version`). If *use_egg_info* is true, legacy egg distributions will be considered as well. .. function:: provides_distribution(name, version=None, use_egg_info=False) Return an iterator over all distributions that declare they provide *name*. *version* is an optional argument to match only specific releases (see :mod:`packaging.version`). If *use_egg_info* is true, legacy egg distributions will be considered as well. Utility functions ----------------- .. function:: distinfo_dirname(name, version) Escape *name* and *version* into a filename-safe form and return the directory name built from them, for example :file:`{safename}-{safeversion}.dist-info.` In *name*, runs of non-alphanumeric characters are replaced with one ``'_'``; in *version*, spaces become dots, and runs of other non-alphanumeric characters (except dots) a replaced by one ``'-'``. .. XXX wth spaces in version numbers? For performance purposes, the list of distributions is being internally cached. Caching is enabled by default, but you can control it with these functions: .. function:: clear_cache() Clear the cache. .. function:: disable_cache() Disable the cache, without clearing it. .. function:: enable_cache() Enable the internal cache, without clearing it. Examples -------- Printing all information about a distribution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given the name of an installed distribution, we shall print out all information that can be obtained using functions provided in this module:: import sys import packaging.database try: name = sys.argv[1] except ValueError: sys.exit('Not enough arguments') # first create the Distribution instance dist = packaging.database.Distribution(path) if dist is None: sys.exit('No such distribution') print('Information about %r' % dist.name) print() print('Files') print('=====') for path, md5, size in dist.list_installed_files(): print('* Path: %s' % path) print(' Hash %s, Size: %s bytes' % (md5, size)) print() print('Metadata') print('========') for key, value in dist.metadata.items(): print('%20s: %s' % (key, value)) print() print('Extra') print('=====') if dist.requested: print('* It was installed by user request') else: print('* It was installed as a dependency') If we save the script above as ``print_info.py``, we can use it to extract information from a :file:`.dist-info` directory. By typing in the console: .. code-block:: sh python print_info.py choxie we get the following output: .. code-block:: none Information about 'choxie' Files ===== * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9/truffles.py Hash 5e052db6a478d06bad9ae033e6bc08af, Size: 111 bytes * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9/choxie/chocolate.py Hash ac56bf496d8d1d26f866235b95f31030, Size: 214 bytes * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9/choxie/__init__.py Hash 416aab08dfa846f473129e89a7625bbc, Size: 25 bytes * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/INSTALLER Hash d41d8cd98f00b204e9800998ecf8427e, Size: 0 bytes * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/METADATA Hash 696a209967fef3c8b8f5a7bb10386385, Size: 225 bytes * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/REQUESTED Hash d41d8cd98f00b204e9800998ecf8427e, Size: 0 bytes * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/RECORD Hash None, Size: None bytes Metadata ======== Metadata-Version: 1.2 Name: choxie Version: 2.0.0.9 Platform: [] Supported-Platform: UNKNOWN Summary: Chocolate with a kick! Description: UNKNOWN Keywords: [] Home-page: UNKNOWN Author: UNKNOWN Author-email: UNKNOWN Maintainer: UNKNOWN Maintainer-email: UNKNOWN License: UNKNOWN Classifier: [] Download-URL: UNKNOWN Obsoletes-Dist: ['truffles (<=0.8,>=0.5)', 'truffles (<=0.9,>=0.6)'] Project-URL: [] Provides-Dist: ['truffles (1.0)'] Requires-Dist: ['towel-stuff (0.1)'] Requires-Python: UNKNOWN Requires-External: [] Extra ===== * It was installed as a dependency Getting metadata about a distribution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sometimes you're not interested about the packaging information contained in a full :class:`Distribution` object but just want to do something with its :attr:`~Distribution.metadata`:: >>> from packaging.database import get_distribution >>> info = get_distribution('chocolate').metadata >>> info['Keywords'] ['cooking', 'happiness'] Finding out obsoleted distributions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Now, we tackle a different problem, we are interested in finding out which distributions have been obsoleted. This can be easily done as follows:: import packaging.database # iterate over all distributions in the system for dist in packaging.database.get_distributions(): name, version = dist.name, dist.version # find out which distributions obsolete this name/version combination replacements = packaging.database.obsoletes_distribution(name, version) if replacements: print('%r %s is obsoleted by' % (name, version), ', '.join(repr(r.name) for r in replacements)) This is how the output might look like: .. code-block:: none 'strawberry' 0.6 is obsoleted by 'choxie' 'grammar' 1.0a4 is obsoleted by 'towel-stuff'