Ignore changes in the amount of whitespace
Differences between version dated 2005-08-14 13:47:09 and 2010-01-31 00:36:31
(spanning 27 versions)
Deletions are marked like this.
Additions are marked like this.
Overview
--------
XXX TBD
-----------------
Developer's Guide
-----------------
This section isn't written yet. Currently planned topics include::
Eggs are a distribution format for Python modules, similar in concept to Java's
"jars" or Ruby's "gems". They differ from previous Python distribution formats
in that they are importable (i.e. they can be added to ``sys.path``), and they
are *discoverable*, meaning that they carry metadata that unambiguously
identifies their contents and dependencies, and thus 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".
The ``pkg_resources`` module provides runtime facilities for finding,
introspecting, activating and using eggs and other "pluggable" distribution
formats. Because these are new concepts in Python (and not that well-
established in other languages either), it helps to have a few special terms
for talking about eggs and how they can be used:
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 unamabiguously
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, development eggs,
and egg links. Built eggs are directories or zipfiles whose name ends
with ``.egg`` and follows the egg naming conventions, and contain an
``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are
normal directories of Python code with one or more ``ProjectName.egg-info``
subdirectories. And egg links are ``*.egg-link`` files that contain the
name of a built or development egg, to support symbolic linking on
platforms that do not have native symbolic links.
(For more information about these terms and concepts, see also this
`architectural overview`_ of ``pkg_resources`` and Python Eggs in general.)
.. _architectural overview: http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html
.. -----------------
.. Developer's Guide
.. -----------------
.. This section isn't written yet. Currently planned topics include
Accessing Resources
Finding and Activating Package Distributions
get_provider()
Metadata access
Extended Discovery and Installation
Supporting Custom PEP 302 Implementations
.. For now, please check out the extensive `API Reference`_ below.
-------------
corresponding package in all distributions on ``sys.path`` that contain a
package of that name. (More precisely, if an importer's
``find_module(name)`` returns a loader, then it will also be searched for
the package's contents.) Whenever a Distribution's ``to_install()`` method
the package's contents.) Whenever a Distribution's ``activate()`` method
is invoked, it checks for the presence of namespace packages and updates
their ``__path__`` contents accordingly.
``require(*requirements)``
Ensure that distributions matching `requirements` are activated
`requirements` must be a string or a (possibly-nested) sequence
thereof, specifying the distributions and versions required. The
return value is a sequence of the distributions that needed to be
For the syntax of requirement specifiers, see the section below on
`Requirements Parsing`_.
Note: in general, it should not be necessary for you to call this method
In general, it should not be necessary for you to call this method
directly. It's intended more for use in quick-and-dirty scripting and
interactive interpreter hacking than for production use. If you're creating
an actual library or application, it's strongly recommended that you create
there. That way, tools like EasyInstall can automatically detect what
requirements your package has, and deal with them accordingly.
Note that calling ``require('SomePackage')`` will not install
``SomePackage`` if it isn't already present. If you need to do this, you
should use the ``resolve()`` method instead, which allows you to pass an
``installer`` callback that will be invoked when a needed distribution
can't be found on the local machine. You can then have this callback
display a dialog, automatically download the needed distribution, or
whatever else is appropriate for your application. See the documentation
below on the ``resolve()`` method for more information, and also on the
``obtain()`` method of ``Environment`` objects.
``run_script(requires, script_name)``
Locate distribution specified by `requires` and run its `script_name`
script. `requires` must be a string containing a requirement specifier.
should use this when you add additional items to ``sys.path`` and you want
the global ``working_set`` to reflect the change. This method is also
called by the ``WorkingSet()`` constructor during initialization.
This method uses ``find_distributions(entry,False)`` to find distributions
This method uses ``find_distributions(entry, True)`` to find distributions
corresponding to the path entry, and then ``add()`` them. `entry` is
always appended to the ``entries`` attribute, even if it is already
present, however. (This is because ``sys.path`` can contain the same value
distribution for a given project can be active in a given ``WorkingSet``.
``__iter__()``
Yield distributions for non-duplicate projects in the working set.
Yield distributions for non-duplicate projects in the working set.
The yield order is the order in which the items' path entries were
added to the working set.
``find(req)``
Find a distribution matching `req` (a ``Requirement`` instance).
Find a distribution matching `req` (a ``Requirement`` instance).
If there is an active distribution for the requested project, this
returns it, as long as it meets the version requirement specified by
`req`. But, if there is an active distribution for the project and it
``resolve(requirements, env=None, installer=None)``
List all distributions needed to (recursively) meet `requirements`
`requirements` must be a sequence of ``Requirement`` objects. `env`,
if supplied, should be an ``Environment`` instance. If
not supplied, an ``Environment`` is created from the working set's
should return a ``Distribution`` or ``None``. (See the ``obtain()`` method
of `Environment Objects`_, below, for more information on the `installer`
argument.)
``add(dist, entry=None)``
Add `dist` to working set, associated with `entry`
If `entry` is unspecified, it defaults to ``dist.location``. On exit from
this routine, `entry` is added to the end of the working set's ``.entries``
(if it wasn't already present).
`dist` is only added to the working set if it's for a project that
doesn't already have a distribution active in the set. If it's
successfully added, any callbacks registered with the ``subscribe()``
yourself to deal with the existing items; just register the callback and
be prepared for the fact that it will be called immediately by this method.
Note that callbacks *must not* allow exceptions to propagate, or they will
interfere with the operation of other callbacks and possibly result in an
inconsistent working set state. Callbacks should use a try/except block
to ignore, log, or otherwise process any errors, especially since the code
that caused the callback to be invoked is unlikely to be able to handle
the errors any better than the callback itself.
``pkg_resources.add_activation_listener()`` is an alternate spelling of
``pkg_resources.working_set.subscribe()``.
Locating Plugins
----------------
Extensible applications will sometimes have a "plugin directory" or a set of
plugin directories, from which they want to load entry points or other
metadata. The ``find_plugins()`` method allows you to do this, by scanning an
environment for the newest version of each project that can be safely loaded
without conflicts or missing requirements.
``find_plugins(plugin_env, full_env=None, fallback=True)``
Scan `plugin_env` and identify which distributions could be added to this
working set without version conflicts or missing requirements.
Example usage::
distributions, errors = working_set.find_plugins(
Environment(plugin_dirlist)
)
map(working_set.add, distributions) # add plugins+libs to sys.path
print "Couldn't load", errors # display errors
The `plugin_env` should be an ``Environment`` instance that contains only
distributions that are in the project's "plugin directory" or directories.
The `full_env`, if supplied, should be an ``Environment`` instance that
contains all currently-available distributions.
If `full_env` is not supplied, one is created automatically from the
``WorkingSet`` this method is called on, which will typically mean that
every directory on ``sys.path`` will be scanned for distributions.
This method returns a 2-tuple: (`distributions`, `error_info`), where
`distributions` is a list of the distributions found in `plugin_env` that
were loadable, along with any other distributions that are needed to resolve
their dependencies. `error_info` is a dictionary mapping unloadable plugin
distributions to an exception instance describing the error that occurred.
Usually this will be a ``DistributionNotFound`` or ``VersionConflict``
instance.
Most applications will use this method mainly on the master ``working_set``
instance in ``pkg_resources``, and then immediately add the returned
distributions to the working set so that they are available on sys.path.
This will make it possible to find any entry points, and allow any other
metadata tracking and hooks to be activated.
The resolution algorithm used by ``find_plugins()`` is as follows. First,
the project names of the distributions present in `plugin_env` are sorted.
Then, each project's eggs are tried in descending version order (i.e.,
newest version first).
An attempt is made to resolve each egg's dependencies. If the attempt is
successful, the egg and its dependencies are added to the output list and to
a temporary copy of the working set. The resolution process continues with
the next project name, and no older eggs for that project are tried.
If the resolution attempt fails, however, the error is added to the error
dictionary. If the `fallback` flag is true, the next older version of the
plugin is tried, until a working version is found. If false, the resolution
process continues with the next plugin project name.
Some applications may have stricter fallback requirements than others. For
example, an application that has a database schema or persistent objects
may not be able to safely downgrade a version of a package. Others may want
to ensure that a new plugin configuration is either 100% good or else
revert to a known-good configuration. (That is, they may wish to revert to
a known configuration if the `error_info` return value is non-empty.)
Note that this algorithm gives precedence to satisfying the dependencies of
alphabetically prior project names in case of version conflicts. If two
projects named "AaronsPlugin" and "ZekesPlugin" both need different versions
of "TomsLibrary", then "AaronsPlugin" will win and "ZekesPlugin" will be
disabled due to version conflict.
``Environment`` Objects
=======================
``Environment`` objects are used by ``pkg_resources`` to index available
distributions during dependency resolution.
``Environment(search_path=None, platform=get_platform(), python=PY_MAJOR)``
``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)``
Create an environment snapshot by scanning `search_path` for distributions
compatible with `platform` and `python`. `search_path` should be a
sequence of strings such as might be used on ``sys.path``. If a
``can_add(dist)``
Is distribution `dist` acceptable for this environment? If it's not
compatible with the platform and python version specified at creation of
the environment, False is returned.
compatible with the ``platform`` and ``python`` version values specified
when the environment was created, a false value is returned.
``__add__(dist_or_env)`` (``+`` operator)
Add a distribution or environment to an ``Environment`` instance, returning
a *new* environment object that contains all the distributions previously
contained by both. The new environment will have a ``platform`` and
``python`` of ``None``, meaning that it will not reject any distributions
from being added to it; it will simply accept whatever is added. If you
want the added items to be filtered for platform and Python version, or
you want to add them to the *same* environment instance, you should use
in-place addition (``+=``) instead.
``__iadd__(dist_or_env)`` (``+=`` operator)
Add a distribution or environment to an ``Environment`` instance
*in-place*, updating the existing instance and returning it. The
``platform`` and ``python`` filter attributes take effect, so distributions
in the source that do not have a suitable platform string or Python version
are silently ignored.
``best_match(req, working_set, installer=None)``
Find distribution best matching `req` and usable on `working_set`
parsed using the ``parse_version()`` utility function. Otherwise, it is
assumed to be an already-parsed version.
The ``Requirement`` object's version specifiers (``.specs``) are internally
sorted into ascending version order, and used to establish what ranges of
versions are acceptable. Adjacent redundant conditions are effectively
consolidated (e.g. ``">1, >2"`` produces the same results as ``">1"``, and
``"<2,<3"`` produces the same results as``"<3"``). ``"!="`` versions are
excised from the ranges they fall within. The version being tested for
acceptability is then checked for membership in the resulting ranges.
(Note that providing conflicting conditions for the same version (e.g.
``"<2,>=2"`` or ``"==2,!=2"``) is meaningless and may therefore produce
bizarre results when compared with actual version number(s).)
``__eq__(other_requirement)``
A requirement compares equal to another requirement if they have
case-insensitively equal project names, version specifiers, and "extras".
or indexing.
``extras``
A tuple of names of "extras" that this requirement calls for.
A tuple of names of "extras" that this requirement calls for. (These will
be all-lowercase and normalized using the ``safe_extra()`` parsing utility
function, so they may not exactly equal the extras the requirement was
created with.)
``specs``
A list of ``(op,version)`` tuples, sorted in ascending parsed-version
order. The `op` in each tuple is a comparison operator, represented as
a string. The `version` is the (unparsed) version number. The relative
order of tuples containing the same version numbers is undefined, since
having more than one operator for a given version is either redundant or
self-contradictory.
Entry Points
``__str__()``
The string form of an ``EntryPoint`` is a string that could be passed to
``EntryPoint.parse()`` to yield an equivalent ``EntryPoint``.
``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``.
``Distribution`` Objects
implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by
delegating them to the `metadata` object.
``Distribution.from_location(location, basename, metadata=None)`` (classmethod)
``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod)
Create a distribution for `location`, which must be a string such as a
URL, filename, or other string that might be used on ``sys.path``.
`basename` is a string naming the distribution, like ``Foo-1.2-py2.4.egg``.
If `basename` ends with ``.egg``, then the project's name, version, python
version and platform are extracted from the filename and used to set those
properties of the created distribution.
properties of the created distribution. Any additional keyword arguments
are forwarded to the ``Distribution()`` constructor.
``Distribution.from_filename(filename, metadata=None)`` (classmethod)
``Distribution.from_filename(filename, metadata=None**kw)`` (classmethod)
Create a distribution by parsing a local filename. This is a shorter way
of saying ``Distribution.from_location(normalize_path(filename),
os.path.basename(filename), metadata)``. In other words, it creates a
distribution whose location is the normalize form of the filename, parsing
name and version information from the base portion of the filename.
name and version information from the base portion of the filename. Any
additional keyword arguments are forwarded to the ``Distribution()``
constructor.
``Distribution(location,metadata,project_name,version,py_version,platform,precedence)``
Create a distribution by setting its properties. All arguments are
``dist.key`` is short for ``dist.project_name.lower()``. It's used for
case-insensitive comparison and indexing of distributions by project name.
extras
A list of strings, giving the names of extra features defined by the
project's dependency list (the ``extras_require`` argument specified in
the project's setup script).
version
A string denoting what release of the project this distribution contains.
When a ``Distribution`` is constructed, the `version` argument is passed
py_version
The major/minor Python version the distribution supports, as a string.
For example, "2.3" or "2.4". The default is the current version of Python.
platform
A string representing the platform the distribution is intended for, or
``None`` if the distribution is "pure Python" and therefore cross-platform.
See `Platform Utilities`_ below for more information on platform strings.
precedence
A distribution's ``precedence`` is used to determine the relative order of
two distributions that have the same ``project_name`` and
``parsed_version``. The default precedence is ``pkg_resources.EGG_DIST``,
which is the highest (i.e. most preferred) precedence. The full list
of predefined precedences, from most preferred to least preferred, is:
``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, and ``CHECKOUT_DIST``.
Normally, precedences other than ``EGG_DIST`` are used only by the
``setuptools.package_index`` module, when sorting distributions found in a
package index to determine their suitability for installation.
``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, ``CHECKOUT_DIST``, and
``DEVELOP_DIST``. Normally, precedences other than ``EGG_DIST`` are used
only by the ``setuptools.package_index`` module, when sorting distributions
found in a package index to determine their suitability for installation.
"System" and "Development" eggs (i.e., ones that use the ``.egg-info``
format), however, are automatically given a precedence of ``DEVELOP_DIST``.
``as_requirement()``
Return a ``Requirement`` instance that matches this distribution's project
name and version.
``requires(extras=())``
List the ``Requirement`` objects that specify this distribution's
dependencies. If `extras` is specified, it should be a sequence of names
of "extras" defined by the distribution, and the list returned will then
include any dependencies needed to support the named "extras".
``clone(**kw)``
Create a copy of the distribution. Any supplied keyword arguments override
the corresponding argument to the ``Distribution()`` constructor, allowing
you to change some of the copied distribution's attributes.
``egg_name()``
Return what this distribution's standard filename should be, not including
the ".egg" extension. For example, a distribution for project "Foo"
version 1.2 that runs on Python 2.3 for Windows would have an ``egg_name()``
of ``Foo-1.2-py2.3-win32``. Any dashes in the name or version are
converted to underscores. (``Distribution.from_location()`` will convert
them back when parsing a ".egg" file name.)
them back when parsing a ".egg" file name.)
``__cmp__(other)``, ``__hash__()``
Distribution objects are hashed and compared on the basis of their parsed
version and precedence, followed by their key (lowercase project name),
location, Python version, and platform.
The following methods are used to access ``EntryPoint`` objects advertised
by the distribution. See the section above on `Entry Points`_ for more
detailed information about these operations:
* ``has_resource(resource_name)``
* ``resource_isdir(resource_name)``
* ``resource_listdir(resource_name)``
If the distribution was created with a `metadata` argument, these resource and
metadata access methods are all delegated to that `metadata` provider.
Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution
obtain an extraction location, and only for names they intend to
extract, as it tracks the generated names for possible cleanup later.
``extraction_error()``
Raise an ``ExtractionError`` describing the active exception as interfering
with the extraction process. You should call this if you encounter any
OS errors extracting the file to the cache path; it will format the
operating system exception for you, and add other information to the
``ExtractionError`` instance that may be needed by programs that want to
wrap or handle extraction errors themselves.
``postprocess(tempname, filename)``
Perform any platform-specific postprocessing of `tempname`.
Resource providers should call this method ONLY after successfully
to the working set). If the named package can't be imported, or the
``Requirement`` can't be satisfied, an exception is raised.
Note also that if you supply a package name, and the package is not part
of a pluggable distribution (i.e., it has no metadata), then you will still
get an ``IResourceProvider`` object, but it will return ``False`` when
asked if any metadata files or directories exist.
NOTE: if you use a package name rather than a ``Requirement``, the object
you get back may not be a pluggable distribution, depending on the method
by which the package was installed. In particular, "development" packages
and "single-version externally-managed" packages do not have any way to
map from a package name to the corresponding project's metadata. Do not
write code that passes a package name to ``get_provider()`` and then tries
to retrieve project metadata from the returned object. It may appear to
work when the named package is in an ``.egg`` file or directory, but
it will fail in other installation scenarios. If you want project
metadata, you need to ask for a *project*, not a package.
``IMetadataProvider`` Methods
VersionConflict
UnknownExtra
ExtractionError
``ResolutionError``
This class is used as a base class for the other three exceptions, so that
you can catch all of them with a single "except" clause. It is also raised
One of the "extras" requested was not recognized by the distribution it
was requested from.
``ExtractionError``
A problem occurred extracting a resource to the Python Egg cache. The
following attributes are available on instances of this exception:
manager
The resource manager that raised this exception
cache_path
The base directory for resource extraction
original_error
The exception instance that caused extraction to fail
Supporting Custom Importers
===========================
`importer_type`. `importer_type` is the type or class of a PEP 302
"importer" (sys.path item handler), and `namespace_handler` is a callable
with a signature like this::
def namespace_handler(importer, path_entry, moduleName, module):
# return a path_entry to use for child packages
Namespace handlers are only called if the relevant importer object has
already agreed that it can handle the relevant path item. The handler
should only return a subpath if the module ``__path__`` does not already
IResourceProvider
-----------------
``IResourceProvider`` is an abstract class that documents what methods are
required of objects returned by a `provider_factory` registered with
``register_loader_type()``. ``IResourceProvider`` is a subclass of
ZipProvider
EggMetadata
EmptyProvider
FileMetadata
``NullProvider``
``EggProvider``
This provider class adds in some egg-specific features that are common
to zipped and unzipped eggs.
``DefaultProvider``
This provider class is used for unpacked eggs and "plain old Python"
filesystem modules.
itself is a ".egg"). It can also be a combination, such as a zipfile egg
that also contains other eggs.
``FileMetadata(path_to_pkg_info)``
Create an ``IResourceProvider`` that provides exactly one metadata
resource: ``PKG-INFO``. The supplied path should be a distutils PKG-INFO
file. This is basically the same as an ``EmptyProvider``, except that
requests for ``PKG-INFO`` will be answered using the contents of the
designated file. (This provider is used to wrap ``.egg-info`` files
installed by vendor-supplied system packages.)
Utility Functions
=================
The algorithm assumes that strings like "-" and any alpha string that
alphabetically follows "final" represents a "patch level". So, "2.4-1"
is assumed to be a branch or patch of "2.4", and therefore "2.4.1" is
considered newer than "2.4-1", whic in turn is newer than "2.4".
considered newer than "2.4-1", which in turn is newer than "2.4".
Strings like "a", "b", "c", "alpha", "beta", "candidate" and so on (that
come before "final" alphabetically) are assumed to be pre-release versions,
so that the version "2.4" is considered newer than "2.4a1".
so that the version "2.4" is considered newer than "2.4a1". Any "-"
characters preceding a pre-release indicator are removed. (In versions of
setuptools prior to 0.6a9, "-" characters were not removed, leading to the
unintuitive result that "0.2-rc1" was considered a newer version than
"0.2".)
Finally, to handle miscellaneous cases, the strings "pre", "preview", and
"rc" are treated as if they were "c", i.e. as though they were release
candidates, and therefore are not as new as a version string that does not
contain them.
contain them. And the string "dev" is treated as if it were an "@" sign;
that is, a version coming before even "a" or "alpha".
.. _yield_lines():
are generating a filename from this you should replace any "-" characters
in the output with underscores.
``safe_extra(extra)``
Return a "safe" form of an extra's name, suitable for use in a requirement
string or a setup script's ``extras_require`` keyword. This routine is
similar to ``safe_name()`` except that non-alphanumeric runs are replaced
by a single underbar (``_``), and the result is lowercased.
``to_filename(name_or_version)``
Escape a name or version string so it can be used in a dash-separated
filename (or ``#egg=name-version`` tag) without ambiguity. You
should only pass in values that were returned by ``safe_name()`` or
``safe_version()``.
Platform Utilities
------------------
``get_platform()``
``get_build_platform()``
Return this platform's identifier string. For Windows, the return value
is ``"win32"``, and for Mac OS X it is a string of the form
``"macosx-10.4-ppc"``. All other platforms return the same uname-based
string that the ``distutils.util.get_platform()`` function returns.
This string is the minimum platform version required by distributions built
on the local machine. (Backward compatibility note: setuptools versions
prior to 0.6b1 called this function ``get_platform()``, and the function is
still available under that name for backward compatibility reasons.)
``get_supported_platform()`` (New in 0.6b1)
This is the similar to ``get_build_platform()``, but is the maximum
platform version that the local machine supports. You will usually want
to use this value as the ``provided`` argument to the
``compatible_platforms()`` function.
``compatible_platforms(provided, required)``
Return true if a distribution built on the `provided` platform may be used
for obtaining an "importer" object. It first checks for an importer for
the path item in ``sys.path_importer_cache``, and if not found it calls
each of the ``sys.path_hooks`` and caches the result if a good importer is
found. If no importer is found, this routine returns an ``ImpWrapper``
instance that wraps the builtin import machinery as a PEP 302-compliant
"importer" object. This ``ImpWrapper`` is *not* cached; instead a new
instance is returned each time.
found. If no importer is found, this routine returns a wrapper object
that wraps the builtin import machinery as a PEP 302-compliant "importer"
object. This wrapper object is *not* cached; instead a new instance is
returned each time.
File/Path Utilities
(notably Cygwin and Mac OS X) the ``normcase`` function does not accurately
reflect the platform's case-sensitivity, so there is always the possibility
of two apparently-different paths being equal on such platforms.
----------------------------
Release Notes/Change History
----------------------------
0.6c10
* Prevent lots of spurious "already imported from another path" warnings (e.g.
when pkg_resources is imported late).
0.6c9
* Fix ``resource_listdir('')`` always returning an empty list for zipped eggs.
0.6c7
* Fix package precedence problem where single-version eggs installed in
``site-packages`` would take precedence over ``.egg`` files (or directories)
installed in ``site-packages``.
0.6c6
* Fix extracted C extensions not having executable permissions under Cygwin.
* Allow ``.egg-link`` files to contain relative paths.
* Fix cache dir defaults on Windows when multiple environment vars are needed
to construct a path.
0.6c4
* Fix "dev" versions being considered newer than release candidates.
0.6c3
* Python 2.5 compatibility fixes.
0.6c2
* Fix a problem with eggs specified directly on ``PYTHONPATH`` on
case-insensitive filesystems possibly not showing up in the default
working set, due to differing normalizations of ``sys.path`` entries.
0.6b3
* Fixed a duplicate path insertion problem on case-insensitive filesystems.
0.6b1
* Split ``get_platform()`` into ``get_supported_platform()`` and
``get_build_platform()`` to work around a Mac versioning problem that caused
the behavior of ``compatible_platforms()`` to be platform specific.
* Fix entry point parsing when a standalone module name has whitespace
between it and the extras.
0.6a11
* Added ``ExtractionError`` and ``ResourceManager.extraction_error()`` so that
cache permission problems get a more user-friendly explanation of the
problem, and so that programs can catch and handle extraction errors if they
need to.
0.6a10
* Added the ``extras`` attribute to ``Distribution``, the ``find_plugins()``
method to ``WorkingSet``, and the ``__add__()`` and ``__iadd__()`` methods
to ``Environment``.
* ``safe_name()`` now allows dots in project names.
* There is a new ``to_filename()`` function that escapes project names and
versions for safe use in constructing egg filenames from a Distribution
object's metadata.
* Added ``Distribution.clone()`` method, and keyword argument support to other
``Distribution`` constructors.
* Added the ``DEVELOP_DIST`` precedence, and automatically assign it to
eggs using ``.egg-info`` format.
0.6a9
* Don't raise an error when an invalid (unfinished) distribution is found
unless absolutely necessary. Warn about skipping invalid/unfinished eggs
when building an Environment.
* Added support for ``.egg-info`` files or directories with version/platform
information embedded in the filename, so that system packagers have the
option of including ``PKG-INFO`` files to indicate the presence of a
system-installed egg, without needing to use ``.egg`` directories, zipfiles,
or ``.pth`` manipulation.
* Changed ``parse_version()`` to remove dashes before pre-release tags, so
that ``0.2-rc1`` is considered an *older* version than ``0.2``, and is equal
to ``0.2rc1``. The idea that a dash *always* meant a post-release version
was highly non-intuitive to setuptools users and Python developers, who
seem to want to use ``-rc`` version numbers a lot.
0.6a8
* Fixed a problem with ``WorkingSet.resolve()`` that prevented version
conflicts from being detected at runtime.
* Improved runtime conflict warning message to identify a line in the user's
program, rather than flagging the ``warn()`` call in ``pkg_resources``.
* Avoid giving runtime conflict warnings for namespace packages, even if they
were declared by a different package than the one currently being activated.
* Fix path insertion algorithm for case-insensitive filesystems.
* Fixed a problem with nested namespace packages (e.g. ``peak.util``) not
being set as an attribute of their parent package.
0.6a6
* Activated distributions are now inserted in ``sys.path`` (and the working
set) just before the directory that contains them, instead of at the end.
This allows e.g. eggs in ``site-packages`` to override unmanaged modules in
the same location, and allows eggs found earlier on ``sys.path`` to override
ones found later.
* When a distribution is activated, it now checks whether any contained
non-namespace modules have already been imported and issues a warning if
a conflicting module has already been imported.
* Changed dependency processing so that it's breadth-first, allowing a
depender's preferences to override those of a dependee, to prevent conflicts
when a lower version is acceptable to the dependee, but not the depender.
* Fixed a problem extracting zipped files on Windows, when the egg in question
has had changed contents but still has the same version number.
0.6a4
* Fix a bug in ``WorkingSet.resolve()`` that was introduced in 0.6a3.
0.6a3
* Added ``safe_extra()`` parsing utility routine, and use it for Requirement,
EntryPoint, and Distribution objects' extras handling.
0.6a1
* Enhanced performance of ``require()`` and related operations when all
requirements are already in the working set, and enhanced performance of
directory scanning for distributions.
* Fixed some problems using ``pkg_resources`` w/PEP 302 loaders other than
``zipimport``, and the previously-broken "eager resource" support.
* Fixed ``pkg_resources.resource_exists()`` not working correctly, along with
some other resource API bugs.
* Many API changes and enhancements:
* Added ``EntryPoint``, ``get_entry_map``, ``load_entry_point``, and
``get_entry_info`` APIs for dynamic plugin discovery.
* ``list_resources`` is now ``resource_listdir`` (and it actually works)
* Resource API functions like ``resource_string()`` that accepted a package
name and resource name, will now also accept a ``Requirement`` object in
place of the package name (to allow access to non-package data files in
an egg).
* ``get_provider()`` will now accept a ``Requirement`` instance or a module
name. If it is given a ``Requirement``, it will return a corresponding
``Distribution`` (by calling ``require()`` if a suitable distribution
isn't already in the working set), rather than returning a metadata and
resource provider for a specific module. (The difference is in how
resource paths are interpreted; supplying a module name means resources
path will be module-relative, rather than relative to the distribution's
root.)
* ``Distribution`` objects now implement the ``IResourceProvider`` and
``IMetadataProvider`` interfaces, so you don't need to reference the (no
longer available) ``metadata`` attribute to get at these interfaces.
* ``Distribution`` and ``Requirement`` both have a ``project_name``
attribute for the project name they refer to. (Previously these were
``name`` and ``distname`` attributes.)
* The ``path`` attribute of ``Distribution`` objects is now ``location``,
because it isn't necessarily a filesystem path (and hasn't been for some
time now). The ``location`` of ``Distribution`` objects in the filesystem
should always be normalized using ``pkg_resources.normalize_path()``; all
of the setuptools and EasyInstall code that generates distributions from
the filesystem (including ``Distribution.from_filename()``) ensure this
invariant, but if you use a more generic API like ``Distribution()`` or
``Distribution.from_location()`` you should take care that you don't
create a distribution with an un-normalized filesystem path.
* ``Distribution`` objects now have an ``as_requirement()`` method that
returns a ``Requirement`` for the distribution's project name and version.
* Distribution objects no longer have an ``installed_on()`` method, and the
``install_on()`` method is now ``activate()`` (but may go away altogether
soon). The ``depends()`` method has also been renamed to ``requires()``,
and ``InvalidOption`` is now ``UnknownExtra``.
* ``find_distributions()`` now takes an additional argument called ``only``,
that tells it to only yield distributions whose location is the passed-in
path. (It defaults to False, so that the default behavior is unchanged.)
* ``AvailableDistributions`` is now called ``Environment``, and the
``get()``, ``__len__()``, and ``__contains__()`` methods were removed,
because they weren't particularly useful. ``__getitem__()`` no longer
raises ``KeyError``; it just returns an empty list if there are no
distributions for the named project.
* The ``resolve()`` method of ``Environment`` is now a method of
``WorkingSet`` instead, and the ``best_match()`` method now uses a working
set instead of a path list as its second argument.
* There is a new ``pkg_resources.add_activation_listener()`` API that lets
you register a callback for notifications about distributions added to
``sys.path`` (including the distributions already on it). This is
basically a hook for extensible applications and frameworks to be able to
search for plugin metadata in distributions added at runtime.
0.5a13
* Fixed a bug in resource extraction from nested packages in a zipped egg.
0.5a12
* Updated extraction/cache mechanism for zipped resources to avoid inter-
process and inter-thread races during extraction. The default cache
location can now be set via the ``PYTHON_EGGS_CACHE`` environment variable,
and the default Windows cache is now a ``Python-Eggs`` subdirectory of the
current user's "Application Data" directory, if the ``PYTHON_EGGS_CACHE``
variable isn't set.
0.5a10
* Fix a problem with ``pkg_resources`` being confused by non-existent eggs on
``sys.path`` (e.g. if a user deletes an egg without removing it from the
``easy-install.pth`` file).
* Fix a problem with "basket" support in ``pkg_resources``, where egg-finding
never actually went inside ``.egg`` files.
* Made ``pkg_resources`` import the module you request resources from, if it's
not already imported.
0.5a4
* ``pkg_resources.AvailableDistributions.resolve()`` and related methods now
accept an ``installer`` argument: a callable taking one argument, a
``Requirement`` instance. The callable must return a ``Distribution``
object, or ``None`` if no distribution is found. This feature is used by
EasyInstall to resolve dependencies by recursively invoking itself.
0.4a4
* Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource
directory extraction for zipped eggs.
0.4a3
* Fixed scripts not being able to see a ``__file__`` variable in ``__main__``
* Fixed a problem with ``resource_isdir()`` implementation that was introduced
in 0.4a2.
0.4a1
* Fixed a bug in requirements processing for exact versions (i.e. ``==`` and
``!=``) when only one condition was included.
* Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of
arbitrary distribution names and versions found on PyPI.
0.3a4
* ``pkg_resources`` now supports resource directories, not just the resources
in them. In particular, there are ``resource_listdir()`` and
``resource_isdir()`` APIs.
* ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain
multiple distributions in subdirectories whose names end with ``.egg``.
Having such a "basket" in a directory on ``sys.path`` is equivalent to
having the individual eggs in that directory, but the contained eggs can
be individually added (or not) to ``sys.path``. Currently, however, there
is no automated way to create baskets.
* Namespace package manipulation is now protected by the Python import lock.
0.3a1
* Initial release.
