5000 #ˆl–Ðz¾”TÂXÔÝÆ_¸Å£¿ „}—ÂßÂÁ?÷============================================================= Package Discovery and Resource Access using ``pkg_resources`` ============================================================= The ``pkg_resources`` module distributed with ``setuptools`` provides an API for Python libraries to access their resource files, and for extensible applications and frameworks to automatically discover plugins. It also provides runtime support for using C extensions that are inside zipfile-format eggs, support for merging packages that have separately-distributed modules or subpackages, and APIs for managing Python's current "working set" of active packages. .. contents:: **Table of Contents** -------- Overview -------- The ``pkg_resources`` module provides runtime facilities for finding, introspecting, activating and using installed Python distributions. Some of the more advanced features (notably the support for parallel installation of multiple versions) rely specifically on the "egg" format (either as a zip archive or subdirectory), while others (such as plugin discovery) will work correctly so long as "egg-info" metadata directories are available for relevant distributions. Eggs are a distribution format for Python modules, similar in concept to Java's "jars" or Ruby's "gems", or the "wheel" format defined in PEP 427. However, unlike a pure distribution format, eggs can also be installed and added directly to ``sys.path`` as an import location. When installed in this way, eggs are *discoverable*, meaning that they carry metadata that unambiguously identifies their contents and dependencies. This means that an installed egg can be *automatically* found and added to ``sys.path`` in response to simple requests of the form, "get me everything I need to use docutils' PDF support". This feature allows mutually conflicting versions of a distribution to co-exist in the same Python installation, with individual applications activating the desired version at runtime by manipulating the contents of ``sys.path`` (this differs from the virtual environment approach, which involves creating isolated environments for each application). The following terms are needed in order to explain the capabilities offered by this module: project A library, framework, script, plugin, application, or collection of data or other resources, or some combination thereof. Projects are assumed to have "relatively unique" names, e.g. names registered with PyPI. release A snapshot of a project at a particular point in time, denoted by a version identifier. distribution A file or files that represent a particular release. importable distribution A file or directory that, if placed on ``sys.path``, allows Python to import any modules contained within it. pluggable distribution An importable distribution whose filename unambiguously identifies its release (i.e. project and version), and whose contents unambiguously specify what releases of other projects will satisfy its runtime requirements. extra An "extra" is an optional feature of a release, that may impose additional runtime requirements. For example, if docutils PDF support required a PDF support library to be present, docutils could define its PDF support as an "extra", and list what other project releases need to be available in order to provide it. environment A collection of distributions potentially available for importing, but not necessarily active. More than one distribution (i.e. release version) for a given project may be present in an environment. working set A collection of distributions actually available for importing, as on ``sys.path``. At most one distribution (release version) of a given project may be present in a working set, as otherwise there would be ambiguity as to what to import. eggs Eggs are pluggable distributions in one of the three formats currently supported by ``pkg_resources``. There are built eggs, dev