1============================================================= 2Package Discovery and Resource Access using ``pkg_resources`` 3============================================================= 4 5The ``pkg_resources`` module distributed with ``setuptools`` provides an API 6for Python libraries to access their resource files, and for extensible 7applications and frameworks to automatically discover plugins. It also 8provides runtime support for using C extensions that are inside zipfile-format 9eggs, support for merging packages that have separately-distributed modules or 10subpackages, and APIs for managing Python's current "working set" of active 11packages. 12 13 14.. contents:: **Table of Contents** 15 16 17-------- 18Overview 19-------- 20 21The ``pkg_resources`` module provides runtime facilities for finding, 22introspecting, activating and using installed Python distributions. Some 23of the more advanced features (notably the support for parallel installation 24of multiple versions) rely specifically on the "egg" format (either as a 25zip archive or subdirectory), while others (such as plugin discovery) will 26work correctly so long as "egg-info" metadata directories are available for 27relevant distributions. 28 29Eggs are a distribution format for Python modules, similar in concept to 30Java's "jars" or Ruby's "gems", or the "wheel" format defined in PEP 427. 31However, unlike a pure distribution format, eggs can also be installed and 32added directly to ``sys.path`` as an import location. When installed in 33this way, eggs are *discoverable*, meaning that they carry metadata that 34unambiguously identifies their contents and dependencies. This means that 35an installed egg can be *automatically* found and added to ``sys.path`` in 36response to simple requests of the form, "get me everything I need to use 37docutils' PDF support". This feature allows mutually conflicting versions of 38a distribution to co-exist in the same Python installation, with individual 39applications activating the desired version at runtime by manipulating the 40contents of ``sys.path`` (this differs from the virtual environment 41approach, which involves creating isolated environments for each 42application). 43 44The following terms are needed in order to explain the capabilities offered 45by this module: 46 47project 48 A library, framework, script, plugin, application, or collection of data 49 or other resources, or some combination thereof. Projects are assumed to 50 have "relatively unique" names, e.g. names registered with PyPI. 51 52release 53 A snapshot of a project at a particular point in time, denoted by a version 54 identifier. 55 56distribution 57 A file or files that represent a particular release. 58 59importable distribution 60 A file or directory that, if placed on ``sys.path``, allows Python to 61 import any modules contained within it. 62 63pluggable distribution 64 An importable distribution whose filename unambiguously identifies its 65 release (i.e. project and version), and whose contents unambiguously 66 specify what releases of other projects will satisfy its runtime 67 requirements. 68 69extra 70 An "extra" is an optional feature of a release, that may impose additional 71 runtime requirements. For example, if docutils PDF support required a 72 PDF support library to be present, docutils could define its PDF support as 73 an "extra", and list what other project releases need to be available in 74 order to provide it. 75 76environment 77 A collection of distributions potentially available for importing, but not 78 necessarily active. More than one distribution (i.e. release version) for 79 a given project may be present in an environment. 80 81working set 82 A collection of distributions actually available for importing, as on 83 ``sys.path``. At most one distribution (release version) of a given 84 project may be present in a working set, as otherwise there would be 85 ambiguity as to what to import. 86 87eggs 88 Eggs are pluggable distributions in one of the three formats currently 89 supported by ``pkg_resources``. There are built eggs, development eggs, 90 and egg links. Built eggs are directories or zipfiles whose name ends 91 with ``.egg`` and follows the egg naming conventions, and contain an 92 ``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are 93 normal directories of Python code with one or more ``ProjectName.egg-info`` 94 subdirectories. The development egg format is also used to provide a 95 default version of a distribution that is available to software that 96 doesn't use ``pkg_resources`` to request specific versions. Egg links 97 are ``*.egg-link`` files that contain the name of a built or 98 development egg, to support symbolic linking on platforms that do not 99 have native symbolic links (or where the symbolic link support is 100 limited). 101 102(For more information about these terms and concepts, see also this 103`architectural overview`_ of ``pkg_resources`` and Python Eggs in general.) 104 105.. _architectural overview: http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html 106 107 108.. ----------------- 109.. Developer's Guide 110.. ----------------- 111 112.. This section isn't written yet. Currently planned topics include 113 Accessing Resources 114 Finding and Activating Package Distributions 115 get_provider() 116 require() 117 WorkingSet 118 iter_distributions 119 Running Scripts 120 Configuration 121 Namespace Packages 122 Extensible Applications and Frameworks 123 Locating entry points 124 Activation listeners 125 Metadata access 126 Extended Discovery and Installation 127 Supporting Custom PEP 302 Implementations 128.. For now, please check out the extensive `API Reference`_ below. 129 130 131------------- 132API Reference 133------------- 134 135Namespace Package Support 136========================= 137 138A namespace package is a package that only contains other packages and modules, 139with no direct contents of its own. Such packages can be split across 140multiple, separately-packaged distributions. They are normally used to split 141up large packages produced by a single organization, such as in the ``zope`` 142namespace package for Zope Corporation packages, and the ``peak`` namespace 143package for the Python Enterprise Application Kit. 144 145To create a namespace package, you list it in the ``namespace_packages`` 146argument to ``setup()``, in your project's ``setup.py``. (See the 147:ref:`setuptools documentation on namespace packages <Namespace Packages>` for 148more information on this.) Also, you must add a ``declare_namespace()`` call 149in the package's ``__init__.py`` file(s): 150 151``declare_namespace(name)`` 152 Declare that the dotted package name `name` is a "namespace package" whose 153 contained packages and modules may be spread across multiple distributions. 154 The named package's ``__path__`` will be extended to include the 155 corresponding package in all distributions on ``sys.path`` that contain a 156 package of that name. (More precisely, if an importer's 157 ``find_module(name)`` returns a loader, then it will also be searched for 158 the package's contents.) Whenever a Distribution's ``activate()`` method 159 is invoked, it checks for the presence of namespace packages and updates 160 their ``__path__`` contents accordingly. 161 162Applications that manipulate namespace packages or directly alter ``sys.path`` 163at runtime may also need to use this API function: 164 165``fixup_namespace_packages(path_item)`` 166 Declare that `path_item` is a newly added item on ``sys.path`` that may 167 need to be used to update existing namespace packages. Ordinarily, this is 168 called for you when an egg is automatically added to ``sys.path``, but if 169 your application modifies ``sys.path`` to include locations that may 170 contain portions of a namespace package, you will need to call this 171 function to ensure they are added to the existing namespace packages. 172 173Although by default ``pkg_resources`` only supports namespace packages for 174filesystem and zip importers, you can extend its support to other "importers" 175compatible with PEP 302 using the ``register_namespace_handler()`` function. 176See the section below on `Supporting Custom Importers`_ for details. 177 178 179``WorkingSet`` Objects 180====================== 181 182The ``WorkingSet`` class provides access to a collection of "active" 183distributions. In general, there is only one meaningful ``WorkingSet`` 184instance: the one that represents the distributions that are currently active 185on ``sys.path``. This global instance is available under the name 186``working_set`` in the ``pkg_resources`` module. However, specialized 187tools may wish to manipulate working sets that don't correspond to 188``sys.path``, and therefore may wish to create other ``WorkingSet`` instances. 189 190It's important to note that the global ``working_set`` object is initialized 191from ``sys.path`` when ``pkg_resources`` is first imported, but is only updated 192if you do all future ``sys.path`` manipulation via ``pkg_resources`` APIs. If 193you manually modify ``sys.path``, you must invoke the appropriate methods on 194the ``working_set`` instance to keep it in sync. Unfortunately, Python does 195not provide any way to detect arbitrary changes to a list object like 196``sys.path``, so ``pkg_resources`` cannot automatically update the 197``working_set`` based on changes to ``sys.path``. 198 199``WorkingSet(entries=None)`` 200 Create a ``WorkingSet`` from an iterable of path entries. If `entries` 201 is not supplied, it defaults to the value of ``sys.path`` at the time 202 the constructor is called. 203 204 Note that you will not normally construct ``WorkingSet`` instances 205 yourself, but instead you will implicitly or explicitly use the global 206 ``working_set`` instance. For the most part, the ``pkg_resources`` API 207 is designed so that the ``working_set`` is used by default, such that you 208 don't have to explicitly refer to it most of the time. 209 210All distributions available directly on ``sys.path`` will be activated 211automatically when ``pkg_resources`` is imported. This behaviour can cause 212version conflicts for applications which require non-default versions of 213those distributions. To handle this situation, ``pkg_resources`` checks for a 214``__requires__`` attribute in the ``__main__`` module when initializing the 215default working set, and uses this to ensure a suitable version of each 216affected distribution is activated. For example:: 217 218 __requires__ = ["CherryPy < 3"] # Must be set before pkg_resources import 219 import pkg_resources 220 221 222Basic ``WorkingSet`` Methods 223---------------------------- 224 225The following methods of ``WorkingSet`` objects are also available as module- 226level functions in ``pkg_resources`` that apply to the default ``working_set`` 227instance. Thus, you can use e.g. ``pkg_resources.require()`` as an 228abbreviation for ``pkg_resources.working_set.require()``: 229 230 231``require(*requirements)`` 232 Ensure that distributions matching `requirements` are activated 233 234 `requirements` must be a string or a (possibly-nested) sequence 235 thereof, specifying the distributions and versions required. The 236 return value is a sequence of the distributions that needed to be 237 activated to fulfill the requirements; all relevant distributions are 238 included, even if they were already activated in this working set. 239 240 For the syntax of requirement specifiers, see the section below on 241 `Requirements Parsing`_. 242 243 In general, it should not be necessary for you to call this method 244 directly. It's intended more for use in quick-and-dirty scripting and 245 interactive interpreter hacking than for production use. If you're creating 246 an actual library or application, it's strongly recommended that you create 247 a "setup.py" script using ``setuptools``, and declare all your requirements 248 there. That way, tools like EasyInstall can automatically detect what 249 requirements your package has, and deal with them accordingly. 250 251 Note that calling ``require('SomePackage')`` will not install 252 ``SomePackage`` if it isn't already present. If you need to do this, you 253 should use the ``resolve()`` method instead, which allows you to pass an 254 ``installer`` callback that will be invoked when a needed distribution 255 can't be found on the local machine. You can then have this callback 256 display a dialog, automatically download the needed distribution, or 257 whatever else is appropriate for your application. See the documentation 258 below on the ``resolve()`` method for more information, and also on the 259 ``obtain()`` method of ``Environment`` objects. 260 261``run_script(requires, script_name)`` 262 Locate distribution specified by `requires` and run its `script_name` 263 script. `requires` must be a string containing a requirement specifier. 264 (See `Requirements Parsing`_ below for the syntax.) 265 266 The script, if found, will be executed in *the caller's globals*. That's 267 because this method is intended to be called from wrapper scripts that 268 act as a proxy for the "real" scripts in a distribution. A wrapper script 269 usually doesn't need to do anything but invoke this function with the 270 correct arguments. 271 272 If you need more control over the script execution environment, you 273 probably want to use the ``run_script()`` method of a ``Distribution`` 274 object's `Metadata API`_ instead. 275 276``iter_entry_points(group, name=None)`` 277 Yield entry point objects from `group` matching `name` 278 279 If `name` is None, yields all entry points in `group` from all 280 distributions in the working set, otherwise only ones matching both 281 `group` and `name` are yielded. Entry points are yielded from the active 282 distributions in the order that the distributions appear in the working 283 set. (For the global ``working_set``, this should be the same as the order 284 that they are listed in ``sys.path``.) Note that within the entry points 285 advertised by an individual distribution, there is no particular ordering. 286 287 Please see the section below on `Entry Points`_ for more information. 288 289 290``WorkingSet`` Methods and Attributes 291------------------------------------- 292 293These methods are used to query or manipulate the contents of a specific 294working set, so they must be explicitly invoked on a particular ``WorkingSet`` 295instance: 296 297``add_entry(entry)`` 298 Add a path item to the ``entries``, finding any distributions on it. You 299 should use this when you add additional items to ``sys.path`` and you want 300 the global ``working_set`` to reflect the change. This method is also 301 called by the ``WorkingSet()`` constructor during initialization. 302 303 This method uses ``find_distributions(entry,True)`` to find distributions 304 corresponding to the path entry, and then ``add()`` them. `entry` is 305 always appended to the ``entries`` attribute, even if it is already 306 present, however. (This is because ``sys.path`` can contain the same value 307 more than once, and the ``entries`` attribute should be able to reflect 308 this.) 309 310``__contains__(dist)`` 311 True if `dist` is active in this ``WorkingSet``. Note that only one 312 distribution for a given project can be active in a given ``WorkingSet``. 313 314``__iter__()`` 315 Yield distributions for non-duplicate projects in the working set. 316 The yield order is the order in which the items' path entries were 317 added to the working set. 318 319``find(req)`` 320 Find a distribution matching `req` (a ``Requirement`` instance). 321 If there is an active distribution for the requested project, this 322 returns it, as long as it meets the version requirement specified by 323 `req`. But, if there is an active distribution for the project and it 324 does *not* meet the `req` requirement, ``VersionConflict`` is raised. 325 If there is no active distribution for the requested project, ``None`` 326 is returned. 327 328``resolve(requirements, env=None, installer=None)`` 329 List all distributions needed to (recursively) meet `requirements` 330 331 `requirements` must be a sequence of ``Requirement`` objects. `env`, 332 if supplied, should be an ``Environment`` instance. If 333 not supplied, an ``Environment`` is created from the working set's 334 ``entries``. `installer`, if supplied, will be invoked with each 335 requirement that cannot be met by an already-installed distribution; it 336 should return a ``Distribution`` or ``None``. (See the ``obtain()`` method 337 of `Environment Objects`_, below, for more information on the `installer` 338 argument.) 339 340``add(dist, entry=None)`` 341 Add `dist` to working set, associated with `entry` 342 343 If `entry` is unspecified, it defaults to ``dist.location``. On exit from 344 this routine, `entry` is added to the end of the working set's ``.entries`` 345 (if it wasn't already present). 346 347 `dist` is only added to the working set if it's for a project that 348 doesn't already have a distribution active in the set. If it's 349 successfully added, any callbacks registered with the ``subscribe()`` 350 method will be called. (See `Receiving Change Notifications`_, below.) 351 352 Note: ``add()`` is automatically called for you by the ``require()`` 353 method, so you don't normally need to use this method directly. 354 355``entries`` 356 This attribute represents a "shadow" ``sys.path``, primarily useful for 357 debugging. If you are experiencing import problems, you should check 358 the global ``working_set`` object's ``entries`` against ``sys.path``, to 359 ensure that they match. If they do not, then some part of your program 360 is manipulating ``sys.path`` without updating the ``working_set`` 361 accordingly. IMPORTANT NOTE: do not directly manipulate this attribute! 362 Setting it equal to ``sys.path`` will not fix your problem, any more than 363 putting black tape over an "engine warning" light will fix your car! If 364 this attribute is out of sync with ``sys.path``, it's merely an *indicator* 365 of the problem, not the cause of it. 366 367 368Receiving Change Notifications 369------------------------------ 370 371Extensible applications and frameworks may need to receive notification when 372a new distribution (such as a plug-in component) has been added to a working 373set. This is what the ``subscribe()`` method and ``add_activation_listener()`` 374function are for. 375 376``subscribe(callback)`` 377 Invoke ``callback(distribution)`` once for each active distribution that is 378 in the set now, or gets added later. Because the callback is invoked for 379 already-active distributions, you do not need to loop over the working set 380 yourself to deal with the existing items; just register the callback and 381 be prepared for the fact that it will be called immediately by this method. 382 383 Note that callbacks *must not* allow exceptions to propagate, or they will 384 interfere with the operation of other callbacks and possibly result in an 385 inconsistent working set state. Callbacks should use a try/except block 386 to ignore, log, or otherwise process any errors, especially since the code 387 that caused the callback to be invoked is unlikely to be able to handle 388 the errors any better than the callback itself. 389 390``pkg_resources.add_activation_listener()`` is an alternate spelling of 391``pkg_resources.working_set.subscribe()``. 392 393 394Locating Plugins 395---------------- 396 397Extensible applications will sometimes have a "plugin directory" or a set of 398plugin directories, from which they want to load entry points or other 399metadata. The ``find_plugins()`` method allows you to do this, by scanning an 400environment for the newest version of each project that can be safely loaded 401without conflicts or missing requirements. 402 403``find_plugins(plugin_env, full_env=None, fallback=True)`` 404 Scan `plugin_env` and identify which distributions could be added to this 405 working set without version conflicts or missing requirements. 406 407 Example usage:: 408 409 distributions, errors = working_set.find_plugins( 410 Environment(plugin_dirlist) 411 ) 412 map(working_set.add, distributions) # add plugins+libs to sys.path 413 print "Couldn't load", errors # display errors 414 415 The `plugin_env` should be an ``Environment`` instance that contains only 416 distributions that are in the project's "plugin directory" or directories. 417 The `full_env`, if supplied, should be an ``Environment`` instance that 418 contains all currently-available distributions. 419 420 If `full_env` is not supplied, one is created automatically from the 421 ``WorkingSet`` this method is called on, which will typically mean that 422 every directory on ``sys.path`` will be scanned for distributions. 423 424 This method returns a 2-tuple: (`distributions`, `error_info`), where 425 `distributions` is a list of the distributions found in `plugin_env` that 426 were loadable, along with any other distributions that are needed to resolve 427 their dependencies. `error_info` is a dictionary mapping unloadable plugin 428 distributions to an exception instance describing the error that occurred. 429 Usually this will be a ``DistributionNotFound`` or ``VersionConflict`` 430 instance. 431 432 Most applications will use this method mainly on the master ``working_set`` 433 instance in ``pkg_resources``, and then immediately add the returned 434 distributions to the working set so that they are available on sys.path. 435 This will make it possible to find any entry points, and allow any other 436 metadata tracking and hooks to be activated. 437 438 The resolution algorithm used by ``find_plugins()`` is as follows. First, 439 the project names of the distributions present in `plugin_env` are sorted. 440 Then, each project's eggs are tried in descending version order (i.e., 441 newest version first). 442 443 An attempt is made to resolve each egg's dependencies. If the attempt is 444 successful, the egg and its dependencies are added to the output list and to 445 a temporary copy of the working set. The resolution process continues with 446 the next project name, and no older eggs for that project are tried. 447 448 If the resolution attempt fails, however, the error is added to the error 449 dictionary. If the `fallback` flag is true, the next older version of the 450 plugin is tried, until a working version is found. If false, the resolution 451 process continues with the next plugin project name. 452 453 Some applications may have stricter fallback requirements than others. For 454 example, an application that has a database schema or persistent objects 455 may not be able to safely downgrade a version of a package. Others may want 456 to ensure that a new plugin configuration is either 100% good or else 457 revert to a known-good configuration. (That is, they may wish to revert to 458 a known configuration if the `error_info` return value is non-empty.) 459 460 Note that this algorithm gives precedence to satisfying the dependencies of 461 alphabetically prior project names in case of version conflicts. If two 462 projects named "AaronsPlugin" and "ZekesPlugin" both need different versions 463 of "TomsLibrary", then "AaronsPlugin" will win and "ZekesPlugin" will be 464 disabled due to version conflict. 465 466 467``Environment`` Objects 468======================= 469 470An "environment" is a collection of ``Distribution`` objects, usually ones 471that are present and potentially importable on the current platform. 472``Environment`` objects are used by ``pkg_resources`` to index available 473distributions during dependency resolution. 474 475``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)`` 476 Create an environment snapshot by scanning `search_path` for distributions 477 compatible with `platform` and `python`. `search_path` should be a 478 sequence of strings such as might be used on ``sys.path``. If a 479 `search_path` isn't supplied, ``sys.path`` is used. 480 481 `platform` is an optional string specifying the name of the platform 482 that platform-specific distributions must be compatible with. If 483 unspecified, it defaults to the current platform. `python` is an 484 optional string naming the desired version of Python (e.g. ``'2.4'``); 485 it defaults to the currently-running version. 486 487 You may explicitly set `platform` (and/or `python`) to ``None`` if you 488 wish to include *all* distributions, not just those compatible with the 489 running platform or Python version. 490 491 Note that `search_path` is scanned immediately for distributions, and the 492 resulting ``Environment`` is a snapshot of the found distributions. It 493 is not automatically updated if the system's state changes due to e.g. 494 installation or removal of distributions. 495 496``__getitem__(project_name)`` 497 Returns a list of distributions for the given project name, ordered 498 from newest to oldest version. (And highest to lowest format precedence 499 for distributions that contain the same version of the project.) If there 500 are no distributions for the project, returns an empty list. 501 502``__iter__()`` 503 Yield the unique project names of the distributions in this environment. 504 The yielded names are always in lower case. 505 506``add(dist)`` 507 Add `dist` to the environment if it matches the platform and python version 508 specified at creation time, and only if the distribution hasn't already 509 been added. (i.e., adding the same distribution more than once is a no-op.) 510 511``remove(dist)`` 512 Remove `dist` from the environment. 513 514``can_add(dist)`` 515 Is distribution `dist` acceptable for this environment? If it's not 516 compatible with the ``platform`` and ``python`` version values specified 517 when the environment was created, a false value is returned. 518 519``__add__(dist_or_env)`` (``+`` operator) 520 Add a distribution or environment to an ``Environment`` instance, returning 521 a *new* environment object that contains all the distributions previously 522 contained by both. The new environment will have a ``platform`` and 523 ``python`` of ``None``, meaning that it will not reject any distributions 524 from being added to it; it will simply accept whatever is added. If you 525 want the added items to be filtered for platform and Python version, or 526 you want to add them to the *same* environment instance, you should use 527 in-place addition (``+=``) instead. 528 529``__iadd__(dist_or_env)`` (``+=`` operator) 530 Add a distribution or environment to an ``Environment`` instance 531 *in-place*, updating the existing instance and returning it. The 532 ``platform`` and ``python`` filter attributes take effect, so distributions 533 in the source that do not have a suitable platform string or Python version 534 are silently ignored. 535 536``best_match(req, working_set, installer=None)`` 537 Find distribution best matching `req` and usable on `working_set` 538 539 This calls the ``find(req)`` method of the `working_set` to see if a 540 suitable distribution is already active. (This may raise 541 ``VersionConflict`` if an unsuitable version of the project is already 542 active in the specified `working_set`.) If a suitable distribution isn't 543 active, this method returns the newest distribution in the environment 544 that meets the ``Requirement`` in `req`. If no suitable distribution is 545 found, and `installer` is supplied, then the result of calling 546 the environment's ``obtain(req, installer)`` method will be returned. 547 548``obtain(requirement, installer=None)`` 549 Obtain a distro that matches requirement (e.g. via download). In the 550 base ``Environment`` class, this routine just returns 551 ``installer(requirement)``, unless `installer` is None, in which case 552 None is returned instead. This method is a hook that allows subclasses 553 to attempt other ways of obtaining a distribution before falling back 554 to the `installer` argument. 555 556``scan(search_path=None)`` 557 Scan `search_path` for distributions usable on `platform` 558 559 Any distributions found are added to the environment. `search_path` should 560 be a sequence of strings such as might be used on ``sys.path``. If not 561 supplied, ``sys.path`` is used. Only distributions conforming to 562 the platform/python version defined at initialization are added. This 563 method is a shortcut for using the ``find_distributions()`` function to 564 find the distributions from each item in `search_path`, and then calling 565 ``add()`` to add each one to the environment. 566 567 568``Requirement`` Objects 569======================= 570 571``Requirement`` objects express what versions of a project are suitable for 572some purpose. These objects (or their string form) are used by various 573``pkg_resources`` APIs in order to find distributions that a script or 574distribution needs. 575 576 577Requirements Parsing 578-------------------- 579 580``parse_requirements(s)`` 581 Yield ``Requirement`` objects for a string or iterable of lines. Each 582 requirement must start on a new line. See below for syntax. 583 584``Requirement.parse(s)`` 585 Create a ``Requirement`` object from a string or iterable of lines. A 586 ``ValueError`` is raised if the string or lines do not contain a valid 587 requirement specifier, or if they contain more than one specifier. (To 588 parse multiple specifiers from a string or iterable of strings, use 589 ``parse_requirements()`` instead.) 590 591 The syntax of a requirement specifier is defined in full in PEP 508. 592 593 Some examples of valid requirement specifiers:: 594 595 FooProject >= 1.2 596 Fizzy [foo, bar] 597 PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1 598 SomethingWhoseVersionIDontCareAbout 599 SomethingWithMarker[foo]>1.0;python_version<"2.7" 600 601 The project name is the only required portion of a requirement string, and 602 if it's the only thing supplied, the requirement will accept any version 603 of that project. 604 605 The "extras" in a requirement are used to request optional features of a 606 project, that may require additional project distributions in order to 607 function. For example, if the hypothetical "Report-O-Rama" project offered 608 optional PDF support, it might require an additional library in order to 609 provide that support. Thus, a project needing Report-O-Rama's PDF features 610 could use a requirement of ``Report-O-Rama[PDF]`` to request installation 611 or activation of both Report-O-Rama and any libraries it needs in order to 612 provide PDF support. For example, you could use:: 613 614 easy_install.py Report-O-Rama[PDF] 615 616 To install the necessary packages using the EasyInstall program, or call 617 ``pkg_resources.require('Report-O-Rama[PDF]')`` to add the necessary 618 distributions to sys.path at runtime. 619 620 The "markers" in a requirement are used to specify when a requirement 621 should be installed -- the requirement will be installed if the marker 622 evaluates as true in the current environment. For example, specifying 623 ``argparse;python_version<"3.0"`` will not install in an Python 3 624 environment, but will in a Python 2 environment. 625 626``Requirement`` Methods and Attributes 627-------------------------------------- 628 629``__contains__(dist_or_version)`` 630 Return true if `dist_or_version` fits the criteria for this requirement. 631 If `dist_or_version` is a ``Distribution`` object, its project name must 632 match the requirement's project name, and its version must meet the 633 requirement's version criteria. If `dist_or_version` is a string, it is 634 parsed using the ``parse_version()`` utility function. Otherwise, it is 635 assumed to be an already-parsed version. 636 637 The ``Requirement`` object's version specifiers (``.specs``) are internally 638 sorted into ascending version order, and used to establish what ranges of 639 versions are acceptable. Adjacent redundant conditions are effectively 640 consolidated (e.g. ``">1, >2"`` produces the same results as ``">2"``, and 641 ``"<2,<3"`` produces the same results as ``"<2"``). ``"!="`` versions are 642 excised from the ranges they fall within. The version being tested for 643 acceptability is then checked for membership in the resulting ranges. 644 645``__eq__(other_requirement)`` 646 A requirement compares equal to another requirement if they have 647 case-insensitively equal project names, version specifiers, and "extras". 648 (The order that extras and version specifiers are in is also ignored.) 649 Equal requirements also have equal hashes, so that requirements can be 650 used in sets or as dictionary keys. 651 652``__str__()`` 653 The string form of a ``Requirement`` is a string that, if passed to 654 ``Requirement.parse()``, would return an equal ``Requirement`` object. 655 656``project_name`` 657 The name of the required project 658 659``key`` 660 An all-lowercase version of the ``project_name``, useful for comparison 661 or indexing. 662 663``extras`` 664 A tuple of names of "extras" that this requirement calls for. (These will 665 be all-lowercase and normalized using the ``safe_extra()`` parsing utility 666 function, so they may not exactly equal the extras the requirement was 667 created with.) 668 669``specs`` 670 A list of ``(op,version)`` tuples, sorted in ascending parsed-version 671 order. The `op` in each tuple is a comparison operator, represented as 672 a string. The `version` is the (unparsed) version number. 673 674``marker`` 675 An instance of ``packaging.markers.Marker`` that allows evaluation 676 against the current environment. May be None if no marker specified. 677 678``url`` 679 The location to download the requirement from if specified. 680 681Entry Points 682============ 683 684Entry points are a simple way for distributions to "advertise" Python objects 685(such as functions or classes) for use by other distributions. Extensible 686applications and frameworks can search for entry points with a particular name 687or group, either from a specific distribution or from all active distributions 688on sys.path, and then inspect or load the advertised objects at will. 689 690Entry points belong to "groups" which are named with a dotted name similar to 691a Python package or module name. For example, the ``setuptools`` package uses 692an entry point named ``distutils.commands`` in order to find commands defined 693by distutils extensions. ``setuptools`` treats the names of entry points 694defined in that group as the acceptable commands for a setup script. 695 696In a similar way, other packages can define their own entry point groups, 697either using dynamic names within the group (like ``distutils.commands``), or 698possibly using predefined names within the group. For example, a blogging 699framework that offers various pre- or post-publishing hooks might define an 700entry point group and look for entry points named "pre_process" and 701"post_process" within that group. 702 703To advertise an entry point, a project needs to use ``setuptools`` and provide 704an ``entry_points`` argument to ``setup()`` in its setup script, so that the 705entry points will be included in the distribution's metadata. For more 706details, see the ``setuptools`` documentation. (XXX link here to setuptools) 707 708Each project distribution can advertise at most one entry point of a given 709name within the same entry point group. For example, a distutils extension 710could advertise two different ``distutils.commands`` entry points, as long as 711they had different names. However, there is nothing that prevents *different* 712projects from advertising entry points of the same name in the same group. In 713some cases, this is a desirable thing, since the application or framework that 714uses the entry points may be calling them as hooks, or in some other way 715combining them. It is up to the application or framework to decide what to do 716if multiple distributions advertise an entry point; some possibilities include 717using both entry points, displaying an error message, using the first one found 718in sys.path order, etc. 719 720 721Convenience API 722--------------- 723 724In the following functions, the `dist` argument can be a ``Distribution`` 725instance, a ``Requirement`` instance, or a string specifying a requirement 726(i.e. project name, version, etc.). If the argument is a string or 727``Requirement``, the specified distribution is located (and added to sys.path 728if not already present). An error will be raised if a matching distribution is 729not available. 730 731The `group` argument should be a string containing a dotted identifier, 732identifying an entry point group. If you are defining an entry point group, 733you should include some portion of your package's name in the group name so as 734to avoid collision with other packages' entry point groups. 735 736``load_entry_point(dist, group, name)`` 737 Load the named entry point from the specified distribution, or raise 738 ``ImportError``. 739 740``get_entry_info(dist, group, name)`` 741 Return an ``EntryPoint`` object for the given `group` and `name` from 742 the specified distribution. Returns ``None`` if the distribution has not 743 advertised a matching entry point. 744 745``get_entry_map(dist, group=None)`` 746 Return the distribution's entry point map for `group`, or the full entry 747 map for the distribution. This function always returns a dictionary, 748 even if the distribution advertises no entry points. If `group` is given, 749 the dictionary maps entry point names to the corresponding ``EntryPoint`` 750 object. If `group` is None, the dictionary maps group names to 751 dictionaries that then map entry point names to the corresponding 752 ``EntryPoint`` instance in that group. 753 754``iter_entry_points(group, name=None)`` 755 Yield entry point objects from `group` matching `name`. 756 757 If `name` is None, yields all entry points in `group` from all 758 distributions in the working set on sys.path, otherwise only ones matching 759 both `group` and `name` are yielded. Entry points are yielded from 760 the active distributions in the order that the distributions appear on 761 sys.path. (Within entry points for a particular distribution, however, 762 there is no particular ordering.) 763 764 (This API is actually a method of the global ``working_set`` object; see 765 the section above on `Basic WorkingSet Methods`_ for more information.) 766 767 768Creating and Parsing 769-------------------- 770 771``EntryPoint(name, module_name, attrs=(), extras=(), dist=None)`` 772 Create an ``EntryPoint`` instance. `name` is the entry point name. The 773 `module_name` is the (dotted) name of the module containing the advertised 774 object. `attrs` is an optional tuple of names to look up from the 775 module to obtain the advertised object. For example, an `attrs` of 776 ``("foo","bar")`` and a `module_name` of ``"baz"`` would mean that the 777 advertised object could be obtained by the following code:: 778 779 import baz 780 advertised_object = baz.foo.bar 781 782 The `extras` are an optional tuple of "extra feature" names that the 783 distribution needs in order to provide this entry point. When the 784 entry point is loaded, these extra features are looked up in the `dist` 785 argument to find out what other distributions may need to be activated 786 on sys.path; see the ``load()`` method for more details. The `extras` 787 argument is only meaningful if `dist` is specified. `dist` must be 788 a ``Distribution`` instance. 789 790``EntryPoint.parse(src, dist=None)`` (classmethod) 791 Parse a single entry point from string `src` 792 793 Entry point syntax follows the form:: 794 795 name = some.module:some.attr [extra1,extra2] 796 797 The entry name and module name are required, but the ``:attrs`` and 798 ``[extras]`` parts are optional, as is the whitespace shown between 799 some of the items. The `dist` argument is passed through to the 800 ``EntryPoint()`` constructor, along with the other values parsed from 801 `src`. 802 803``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod) 804 Parse `lines` (a string or sequence of lines) to create a dictionary 805 mapping entry point names to ``EntryPoint`` objects. ``ValueError`` is 806 raised if entry point names are duplicated, if `group` is not a valid 807 entry point group name, or if there are any syntax errors. (Note: the 808 `group` parameter is used only for validation and to create more 809 informative error messages.) If `dist` is provided, it will be used to 810 set the ``dist`` attribute of the created ``EntryPoint`` objects. 811 812``EntryPoint.parse_map(data, dist=None)`` (classmethod) 813 Parse `data` into a dictionary mapping group names to dictionaries mapping 814 entry point names to ``EntryPoint`` objects. If `data` is a dictionary, 815 then the keys are used as group names and the values are passed to 816 ``parse_group()`` as the `lines` argument. If `data` is a string or 817 sequence of lines, it is first split into .ini-style sections (using 818 the ``split_sections()`` utility function) and the section names are used 819 as group names. In either case, the `dist` argument is passed through to 820 ``parse_group()`` so that the entry points will be linked to the specified 821 distribution. 822 823 824``EntryPoint`` Objects 825---------------------- 826 827For simple introspection, ``EntryPoint`` objects have attributes that 828correspond exactly to the constructor argument names: ``name``, 829``module_name``, ``attrs``, ``extras``, and ``dist`` are all available. In 830addition, the following methods are provided: 831 832``load()`` 833 Load the entry point, returning the advertised Python object. Effectively 834 calls ``self.require()`` then returns ``self.resolve()``. 835 836``require(env=None, installer=None)`` 837 Ensure that any "extras" needed by the entry point are available on 838 sys.path. ``UnknownExtra`` is raised if the ``EntryPoint`` has ``extras``, 839 but no ``dist``, or if the named extras are not defined by the 840 distribution. If `env` is supplied, it must be an ``Environment``, and it 841 will be used to search for needed distributions if they are not already 842 present on sys.path. If `installer` is supplied, it must be a callable 843 taking a ``Requirement`` instance and returning a matching importable 844 ``Distribution`` instance or None. 845 846``resolve()`` 847 Resolve the entry point from its module and attrs, returning the advertised 848 Python object. Raises ``ImportError`` if it cannot be obtained. 849 850``__str__()`` 851 The string form of an ``EntryPoint`` is a string that could be passed to 852 ``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``. 853 854 855``Distribution`` Objects 856======================== 857 858``Distribution`` objects represent collections of Python code that may or may 859not be importable, and may or may not have metadata and resources associated 860with them. Their metadata may include information such as what other projects 861the distribution depends on, what entry points the distribution advertises, and 862so on. 863 864 865Getting or Creating Distributions 866--------------------------------- 867 868Most commonly, you'll obtain ``Distribution`` objects from a ``WorkingSet`` or 869an ``Environment``. (See the sections above on `WorkingSet Objects`_ and 870`Environment Objects`_, which are containers for active distributions and 871available distributions, respectively.) You can also obtain ``Distribution`` 872objects from one of these high-level APIs: 873 874``find_distributions(path_item, only=False)`` 875 Yield distributions accessible via `path_item`. If `only` is true, yield 876 only distributions whose ``location`` is equal to `path_item`. In other 877 words, if `only` is true, this yields any distributions that would be 878 importable if `path_item` were on ``sys.path``. If `only` is false, this 879 also yields distributions that are "in" or "under" `path_item`, but would 880 not be importable unless their locations were also added to ``sys.path``. 881 882``get_distribution(dist_spec)`` 883 Return a ``Distribution`` object for a given ``Requirement`` or string. 884 If `dist_spec` is already a ``Distribution`` instance, it is returned. 885 If it is a ``Requirement`` object or a string that can be parsed into one, 886 it is used to locate and activate a matching distribution, which is then 887 returned. 888 889However, if you're creating specialized tools for working with distributions, 890or creating a new distribution format, you may also need to create 891``Distribution`` objects directly, using one of the three constructors below. 892 893These constructors all take an optional `metadata` argument, which is used to 894access any resources or metadata associated with the distribution. `metadata` 895must be an object that implements the ``IResourceProvider`` interface, or None. 896If it is None, an ``EmptyProvider`` is used instead. ``Distribution`` objects 897implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by 898delegating them to the `metadata` object. 899 900``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod) 901 Create a distribution for `location`, which must be a string such as a 902 URL, filename, or other string that might be used on ``sys.path``. 903 `basename` is a string naming the distribution, like ``Foo-1.2-py2.4.egg``. 904 If `basename` ends with ``.egg``, then the project's name, version, python 905 version and platform are extracted from the filename and used to set those 906 properties of the created distribution. Any additional keyword arguments 907 are forwarded to the ``Distribution()`` constructor. 908 909``Distribution.from_filename(filename, metadata=None**kw)`` (classmethod) 910 Create a distribution by parsing a local filename. This is a shorter way 911 of saying ``Distribution.from_location(normalize_path(filename), 912 os.path.basename(filename), metadata)``. In other words, it creates a 913 distribution whose location is the normalize form of the filename, parsing 914 name and version information from the base portion of the filename. Any 915 additional keyword arguments are forwarded to the ``Distribution()`` 916 constructor. 917 918``Distribution(location,metadata,project_name,version,py_version,platform,precedence)`` 919 Create a distribution by setting its properties. All arguments are 920 optional and default to None, except for `py_version` (which defaults to 921 the current Python version) and `precedence` (which defaults to 922 ``EGG_DIST``; for more details see ``precedence`` under `Distribution 923 Attributes`_ below). Note that it's usually easier to use the 924 ``from_filename()`` or ``from_location()`` constructors than to specify 925 all these arguments individually. 926 927 928``Distribution`` Attributes 929--------------------------- 930 931location 932 A string indicating the distribution's location. For an importable 933 distribution, this is the string that would be added to ``sys.path`` to 934 make it actively importable. For non-importable distributions, this is 935 simply a filename, URL, or other way of locating the distribution. 936 937project_name 938 A string, naming the project that this distribution is for. Project names 939 are defined by a project's setup script, and they are used to identify 940 projects on PyPI. When a ``Distribution`` is constructed, the 941 `project_name` argument is passed through the ``safe_name()`` utility 942 function to filter out any unacceptable characters. 943 944key 945 ``dist.key`` is short for ``dist.project_name.lower()``. It's used for 946 case-insensitive comparison and indexing of distributions by project name. 947 948extras 949 A list of strings, giving the names of extra features defined by the 950 project's dependency list (the ``extras_require`` argument specified in 951 the project's setup script). 952 953version 954 A string denoting what release of the project this distribution contains. 955 When a ``Distribution`` is constructed, the `version` argument is passed 956 through the ``safe_version()`` utility function to filter out any 957 unacceptable characters. If no `version` is specified at construction 958 time, then attempting to access this attribute later will cause the 959 ``Distribution`` to try to discover its version by reading its ``PKG-INFO`` 960 metadata file. If ``PKG-INFO`` is unavailable or can't be parsed, 961 ``ValueError`` is raised. 962 963parsed_version 964 The ``parsed_version`` is an object representing a "parsed" form of the 965 distribution's ``version``. ``dist.parsed_version`` is a shortcut for 966 calling ``parse_version(dist.version)``. It is used to compare or sort 967 distributions by version. (See the `Parsing Utilities`_ section below for 968 more information on the ``parse_version()`` function.) Note that accessing 969 ``parsed_version`` may result in a ``ValueError`` if the ``Distribution`` 970 was constructed without a `version` and without `metadata` capable of 971 supplying the missing version info. 972 973py_version 974 The major/minor Python version the distribution supports, as a string. 975 For example, "2.7" or "3.4". The default is the current version of Python. 976 977platform 978 A string representing the platform the distribution is intended for, or 979 ``None`` if the distribution is "pure Python" and therefore cross-platform. 980 See `Platform Utilities`_ below for more information on platform strings. 981 982precedence 983 A distribution's ``precedence`` is used to determine the relative order of 984 two distributions that have the same ``project_name`` and 985 ``parsed_version``. The default precedence is ``pkg_resources.EGG_DIST``, 986 which is the highest (i.e. most preferred) precedence. The full list 987 of predefined precedences, from most preferred to least preferred, is: 988 ``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, ``CHECKOUT_DIST``, and 989 ``DEVELOP_DIST``. Normally, precedences other than ``EGG_DIST`` are used 990 only by the ``setuptools.package_index`` module, when sorting distributions 991 found in a package index to determine their suitability for installation. 992 "System" and "Development" eggs (i.e., ones that use the ``.egg-info`` 993 format), however, are automatically given a precedence of ``DEVELOP_DIST``. 994 995 996 997``Distribution`` Methods 998------------------------ 999 1000``activate(path=None)`` 1001 Ensure distribution is importable on `path`. If `path` is None, 1002 ``sys.path`` is used instead. This ensures that the distribution's 1003 ``location`` is in the `path` list, and it also performs any necessary 1004 namespace package fixups or declarations. (That is, if the distribution 1005 contains namespace packages, this method ensures that they are declared, 1006 and that the distribution's contents for those namespace packages are 1007 merged with the contents provided by any other active distributions. See 1008 the section above on `Namespace Package Support`_ for more information.) 1009 1010 ``pkg_resources`` adds a notification callback to the global ``working_set`` 1011 that ensures this method is called whenever a distribution is added to it. 1012 Therefore, you should not normally need to explicitly call this method. 1013 (Note that this means that namespace packages on ``sys.path`` are always 1014 imported as soon as ``pkg_resources`` is, which is another reason why 1015 namespace packages should not contain any code or import statements.) 1016 1017``as_requirement()`` 1018 Return a ``Requirement`` instance that matches this distribution's project 1019 name and version. 1020 1021``requires(extras=())`` 1022 List the ``Requirement`` objects that specify this distribution's 1023 dependencies. If `extras` is specified, it should be a sequence of names 1024 of "extras" defined by the distribution, and the list returned will then 1025 include any dependencies needed to support the named "extras". 1026 1027``clone(**kw)`` 1028 Create a copy of the distribution. Any supplied keyword arguments override 1029 the corresponding argument to the ``Distribution()`` constructor, allowing 1030 you to change some of the copied distribution's attributes. 1031 1032``egg_name()`` 1033 Return what this distribution's standard filename should be, not including 1034 the ".egg" extension. For example, a distribution for project "Foo" 1035 version 1.2 that runs on Python 2.3 for Windows would have an ``egg_name()`` 1036 of ``Foo-1.2-py2.3-win32``. Any dashes in the name or version are 1037 converted to underscores. (``Distribution.from_location()`` will convert 1038 them back when parsing a ".egg" file name.) 1039 1040``__cmp__(other)``, ``__hash__()`` 1041 Distribution objects are hashed and compared on the basis of their parsed 1042 version and precedence, followed by their key (lowercase project name), 1043 location, Python version, and platform. 1044 1045The following methods are used to access ``EntryPoint`` objects advertised 1046by the distribution. See the section above on `Entry Points`_ for more 1047detailed information about these operations: 1048 1049``get_entry_info(group, name)`` 1050 Return the ``EntryPoint`` object for `group` and `name`, or None if no 1051 such point is advertised by this distribution. 1052 1053``get_entry_map(group=None)`` 1054 Return the entry point map for `group`. If `group` is None, return 1055 a dictionary mapping group names to entry point maps for all groups. 1056 (An entry point map is a dictionary of entry point names to ``EntryPoint`` 1057 objects.) 1058 1059``load_entry_point(group, name)`` 1060 Short for ``get_entry_info(group, name).load()``. Returns the object 1061 advertised by the named entry point, or raises ``ImportError`` if 1062 the entry point isn't advertised by this distribution, or there is some 1063 other import problem. 1064 1065In addition to the above methods, ``Distribution`` objects also implement all 1066of the `IResourceProvider`_ and `IMetadataProvider Methods`_ (which are 1067documented in later sections): 1068 1069* ``has_metadata(name)`` 1070* ``metadata_isdir(name)`` 1071* ``metadata_listdir(name)`` 1072* ``get_metadata(name)`` 1073* ``get_metadata_lines(name)`` 1074* ``run_script(script_name, namespace)`` 1075* ``get_resource_filename(manager, resource_name)`` 1076* ``get_resource_stream(manager, resource_name)`` 1077* ``get_resource_string(manager, resource_name)`` 1078* ``has_resource(resource_name)`` 1079* ``resource_isdir(resource_name)`` 1080* ``resource_listdir(resource_name)`` 1081 1082If the distribution was created with a `metadata` argument, these resource and 1083metadata access methods are all delegated to that `metadata` provider. 1084Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution 1085will appear to have no resources or metadata. This delegation approach is used 1086so that supporting custom importers or new distribution formats can be done 1087simply by creating an appropriate `IResourceProvider`_ implementation; see the 1088section below on `Supporting Custom Importers`_ for more details. 1089 1090 1091``ResourceManager`` API 1092======================= 1093 1094The ``ResourceManager`` class provides uniform access to package resources, 1095whether those resources exist as files and directories or are compressed in 1096an archive of some kind. 1097 1098Normally, you do not need to create or explicitly manage ``ResourceManager`` 1099instances, as the ``pkg_resources`` module creates a global instance for you, 1100and makes most of its methods available as top-level names in the 1101``pkg_resources`` module namespace. So, for example, this code actually 1102calls the ``resource_string()`` method of the global ``ResourceManager``:: 1103 1104 import pkg_resources 1105 my_data = pkg_resources.resource_string(__name__, "foo.dat") 1106 1107Thus, you can use the APIs below without needing an explicit 1108``ResourceManager`` instance; just import and use them as needed. 1109 1110 1111Basic Resource Access 1112--------------------- 1113 1114In the following methods, the `package_or_requirement` argument may be either 1115a Python package/module name (e.g. ``foo.bar``) or a ``Requirement`` instance. 1116If it is a package or module name, the named module or package must be 1117importable (i.e., be in a distribution or directory on ``sys.path``), and the 1118`resource_name` argument is interpreted relative to the named package. (Note 1119that if a module name is used, then the resource name is relative to the 1120package immediately containing the named module. Also, you should not use use 1121a namespace package name, because a namespace package can be spread across 1122multiple distributions, and is therefore ambiguous as to which distribution 1123should be searched for the resource.) 1124 1125If it is a ``Requirement``, then the requirement is automatically resolved 1126(searching the current ``Environment`` if necessary) and a matching 1127distribution is added to the ``WorkingSet`` and ``sys.path`` if one was not 1128already present. (Unless the ``Requirement`` can't be satisfied, in which 1129case an exception is raised.) The `resource_name` argument is then interpreted 1130relative to the root of the identified distribution; i.e. its first path 1131segment will be treated as a peer of the top-level modules or packages in the 1132distribution. 1133 1134Note that resource names must be ``/``-separated paths and cannot be absolute 1135(i.e. no leading ``/``) or contain relative names like ``".."``. Do *not* use 1136``os.path`` routines to manipulate resource paths, as they are *not* filesystem 1137paths. 1138 1139``resource_exists(package_or_requirement, resource_name)`` 1140 Does the named resource exist? Return ``True`` or ``False`` accordingly. 1141 1142``resource_stream(package_or_requirement, resource_name)`` 1143 Return a readable file-like object for the specified resource; it may be 1144 an actual file, a ``StringIO``, or some similar object. The stream is 1145 in "binary mode", in the sense that whatever bytes are in the resource 1146 will be read as-is. 1147 1148``resource_string(package_or_requirement, resource_name)`` 1149 Return the specified resource as a string. The resource is read in 1150 binary fashion, such that the returned string contains exactly the bytes 1151 that are stored in the resource. 1152 1153``resource_isdir(package_or_requirement, resource_name)`` 1154 Is the named resource a directory? Return ``True`` or ``False`` 1155 accordingly. 1156 1157``resource_listdir(package_or_requirement, resource_name)`` 1158 List the contents of the named resource directory, just like ``os.listdir`` 1159 except that it works even if the resource is in a zipfile. 1160 1161Note that only ``resource_exists()`` and ``resource_isdir()`` are insensitive 1162as to the resource type. You cannot use ``resource_listdir()`` on a file 1163resource, and you can't use ``resource_string()`` or ``resource_stream()`` on 1164directory resources. Using an inappropriate method for the resource type may 1165result in an exception or undefined behavior, depending on the platform and 1166distribution format involved. 1167 1168 1169Resource Extraction 1170------------------- 1171 1172``resource_filename(package_or_requirement, resource_name)`` 1173 Sometimes, it is not sufficient to access a resource in string or stream 1174 form, and a true filesystem filename is needed. In such cases, you can 1175 use this method (or module-level function) to obtain a filename for a 1176 resource. If the resource is in an archive distribution (such as a zipped 1177 egg), it will be extracted to a cache directory, and the filename within 1178 the cache will be returned. If the named resource is a directory, then 1179 all resources within that directory (including subdirectories) are also 1180 extracted. If the named resource is a C extension or "eager resource" 1181 (see the ``setuptools`` documentation for details), then all C extensions 1182 and eager resources are extracted at the same time. 1183 1184 Archived resources are extracted to a cache location that can be managed by 1185 the following two methods: 1186 1187``set_extraction_path(path)`` 1188 Set the base path where resources will be extracted to, if needed. 1189 1190 If you do not call this routine before any extractions take place, the 1191 path defaults to the return value of ``get_default_cache()``. (Which is 1192 based on the ``PYTHON_EGG_CACHE`` environment variable, with various 1193 platform-specific fallbacks. See that routine's documentation for more 1194 details.) 1195 1196 Resources are extracted to subdirectories of this path based upon 1197 information given by the resource provider. You may set this to a 1198 temporary directory, but then you must call ``cleanup_resources()`` to 1199 delete the extracted files when done. There is no guarantee that 1200 ``cleanup_resources()`` will be able to remove all extracted files. (On 1201 Windows, for example, you can't unlink .pyd or .dll files that are still 1202 in use.) 1203 1204 Note that you may not change the extraction path for a given resource 1205 manager once resources have been extracted, unless you first call 1206 ``cleanup_resources()``. 1207 1208``cleanup_resources(force=False)`` 1209 Delete all extracted resource files and directories, returning a list 1210 of the file and directory names that could not be successfully removed. 1211 This function does not have any concurrency protection, so it should 1212 generally only be called when the extraction path is a temporary 1213 directory exclusive to a single process. This method is not 1214 automatically called; you must call it explicitly or register it as an 1215 ``atexit`` function if you wish to ensure cleanup of a temporary 1216 directory used for extractions. 1217 1218 1219"Provider" Interface 1220-------------------- 1221 1222If you are implementing an ``IResourceProvider`` and/or ``IMetadataProvider`` 1223for a new distribution archive format, you may need to use the following 1224``IResourceManager`` methods to co-ordinate extraction of resources to the 1225filesystem. If you're not implementing an archive format, however, you have 1226no need to use these methods. Unlike the other methods listed above, they are 1227*not* available as top-level functions tied to the global ``ResourceManager``; 1228you must therefore have an explicit ``ResourceManager`` instance to use them. 1229 1230``get_cache_path(archive_name, names=())`` 1231 Return absolute location in cache for `archive_name` and `names` 1232 1233 The parent directory of the resulting path will be created if it does 1234 not already exist. `archive_name` should be the base filename of the 1235 enclosing egg (which may not be the name of the enclosing zipfile!), 1236 including its ".egg" extension. `names`, if provided, should be a 1237 sequence of path name parts "under" the egg's extraction location. 1238 1239 This method should only be called by resource providers that need to 1240 obtain an extraction location, and only for names they intend to 1241 extract, as it tracks the generated names for possible cleanup later. 1242 1243``extraction_error()`` 1244 Raise an ``ExtractionError`` describing the active exception as interfering 1245 with the extraction process. You should call this if you encounter any 1246 OS errors extracting the file to the cache path; it will format the 1247 operating system exception for you, and add other information to the 1248 ``ExtractionError`` instance that may be needed by programs that want to 1249 wrap or handle extraction errors themselves. 1250 1251``postprocess(tempname, filename)`` 1252 Perform any platform-specific postprocessing of `tempname`. 1253 Resource providers should call this method ONLY after successfully 1254 extracting a compressed resource. They must NOT call it on resources 1255 that are already in the filesystem. 1256 1257 `tempname` is the current (temporary) name of the file, and `filename` 1258 is the name it will be renamed to by the caller after this routine 1259 returns. 1260 1261 1262Metadata API 1263============ 1264 1265The metadata API is used to access metadata resources bundled in a pluggable 1266distribution. Metadata resources are virtual files or directories containing 1267information about the distribution, such as might be used by an extensible 1268application or framework to connect "plugins". Like other kinds of resources, 1269metadata resource names are ``/``-separated and should not contain ``..`` or 1270begin with a ``/``. You should not use ``os.path`` routines to manipulate 1271resource paths. 1272 1273The metadata API is provided by objects implementing the ``IMetadataProvider`` 1274or ``IResourceProvider`` interfaces. ``Distribution`` objects implement this 1275interface, as do objects returned by the ``get_provider()`` function: 1276 1277``get_provider(package_or_requirement)`` 1278 If a package name is supplied, return an ``IResourceProvider`` for the 1279 package. If a ``Requirement`` is supplied, resolve it by returning a 1280 ``Distribution`` from the current working set (searching the current 1281 ``Environment`` if necessary and adding the newly found ``Distribution`` 1282 to the working set). If the named package can't be imported, or the 1283 ``Requirement`` can't be satisfied, an exception is raised. 1284 1285 NOTE: if you use a package name rather than a ``Requirement``, the object 1286 you get back may not be a pluggable distribution, depending on the method 1287 by which the package was installed. In particular, "development" packages 1288 and "single-version externally-managed" packages do not have any way to 1289 map from a package name to the corresponding project's metadata. Do not 1290 write code that passes a package name to ``get_provider()`` and then tries 1291 to retrieve project metadata from the returned object. It may appear to 1292 work when the named package is in an ``.egg`` file or directory, but 1293 it will fail in other installation scenarios. If you want project 1294 metadata, you need to ask for a *project*, not a package. 1295 1296 1297``IMetadataProvider`` Methods 1298----------------------------- 1299 1300The methods provided by objects (such as ``Distribution`` instances) that 1301implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are: 1302 1303``has_metadata(name)`` 1304 Does the named metadata resource exist? 1305 1306``metadata_isdir(name)`` 1307 Is the named metadata resource a directory? 1308 1309``metadata_listdir(name)`` 1310 List of metadata names in the directory (like ``os.listdir()``) 1311 1312``get_metadata(name)`` 1313 Return the named metadata resource as a string. The data is read in binary 1314 mode; i.e., the exact bytes of the resource file are returned. 1315 1316``get_metadata_lines(name)`` 1317 Yield named metadata resource as list of non-blank non-comment lines. This 1318 is short for calling ``yield_lines(provider.get_metadata(name))``. See the 1319 section on `yield_lines()`_ below for more information on the syntax it 1320 recognizes. 1321 1322``run_script(script_name, namespace)`` 1323 Execute the named script in the supplied namespace dictionary. Raises 1324 ``ResolutionError`` if there is no script by that name in the ``scripts`` 1325 metadata directory. `namespace` should be a Python dictionary, usually 1326 a module dictionary if the script is being run as a module. 1327 1328 1329Exceptions 1330========== 1331 1332``pkg_resources`` provides a simple exception hierarchy for problems that may 1333occur when processing requests to locate and activate packages:: 1334 1335 ResolutionError 1336 DistributionNotFound 1337 VersionConflict 1338 UnknownExtra 1339 1340 ExtractionError 1341 1342``ResolutionError`` 1343 This class is used as a base class for the other three exceptions, so that 1344 you can catch all of them with a single "except" clause. It is also raised 1345 directly for miscellaneous requirement-resolution problems like trying to 1346 run a script that doesn't exist in the distribution it was requested from. 1347 1348``DistributionNotFound`` 1349 A distribution needed to fulfill a requirement could not be found. 1350 1351``VersionConflict`` 1352 The requested version of a project conflicts with an already-activated 1353 version of the same project. 1354 1355``UnknownExtra`` 1356 One of the "extras" requested was not recognized by the distribution it 1357 was requested from. 1358 1359``ExtractionError`` 1360 A problem occurred extracting a resource to the Python Egg cache. The 1361 following attributes are available on instances of this exception: 1362 1363 manager 1364 The resource manager that raised this exception 1365 1366 cache_path 1367 The base directory for resource extraction 1368 1369 original_error 1370 The exception instance that caused extraction to fail 1371 1372 1373Supporting Custom Importers 1374=========================== 1375 1376By default, ``pkg_resources`` supports normal filesystem imports, and 1377``zipimport`` importers. If you wish to use the ``pkg_resources`` features 1378with other (PEP 302-compatible) importers or module loaders, you may need to 1379register various handlers and support functions using these APIs: 1380 1381``register_finder(importer_type, distribution_finder)`` 1382 Register `distribution_finder` to find distributions in ``sys.path`` items. 1383 `importer_type` is the type or class of a PEP 302 "Importer" (``sys.path`` 1384 item handler), and `distribution_finder` is a callable that, when passed a 1385 path item, the importer instance, and an `only` flag, yields 1386 ``Distribution`` instances found under that path item. (The `only` flag, 1387 if true, means the finder should yield only ``Distribution`` objects whose 1388 ``location`` is equal to the path item provided.) 1389 1390 See the source of the ``pkg_resources.find_on_path`` function for an 1391 example finder function. 1392 1393``register_loader_type(loader_type, provider_factory)`` 1394 Register `provider_factory` to make ``IResourceProvider`` objects for 1395 `loader_type`. `loader_type` is the type or class of a PEP 302 1396 ``module.__loader__``, and `provider_factory` is a function that, when 1397 passed a module object, returns an `IResourceProvider`_ for that module, 1398 allowing it to be used with the `ResourceManager API`_. 1399 1400``register_namespace_handler(importer_type, namespace_handler)`` 1401 Register `namespace_handler` to declare namespace packages for the given 1402 `importer_type`. `importer_type` is the type or class of a PEP 302 1403 "importer" (sys.path item handler), and `namespace_handler` is a callable 1404 with a signature like this:: 1405 1406 def namespace_handler(importer, path_entry, moduleName, module): 1407 # return a path_entry to use for child packages 1408 1409 Namespace handlers are only called if the relevant importer object has 1410 already agreed that it can handle the relevant path item. The handler 1411 should only return a subpath if the module ``__path__`` does not already 1412 contain an equivalent subpath. Otherwise, it should return None. 1413 1414 For an example namespace handler, see the source of the 1415 ``pkg_resources.file_ns_handler`` function, which is used for both zipfile 1416 importing and regular importing. 1417 1418 1419IResourceProvider 1420----------------- 1421 1422``IResourceProvider`` is an abstract class that documents what methods are 1423required of objects returned by a `provider_factory` registered with 1424``register_loader_type()``. ``IResourceProvider`` is a subclass of 1425``IMetadataProvider``, so objects that implement this interface must also 1426implement all of the `IMetadataProvider Methods`_ as well as the methods 1427shown here. The `manager` argument to the methods below must be an object 1428that supports the full `ResourceManager API`_ documented above. 1429 1430``get_resource_filename(manager, resource_name)`` 1431 Return a true filesystem path for `resource_name`, coordinating the 1432 extraction with `manager`, if the resource must be unpacked to the 1433 filesystem. 1434 1435``get_resource_stream(manager, resource_name)`` 1436 Return a readable file-like object for `resource_name`. 1437 1438``get_resource_string(manager, resource_name)`` 1439 Return a string containing the contents of `resource_name`. 1440 1441``has_resource(resource_name)`` 1442 Does the package contain the named resource? 1443 1444``resource_isdir(resource_name)`` 1445 Is the named resource a directory? Return a false value if the resource 1446 does not exist or is not a directory. 1447 1448``resource_listdir(resource_name)`` 1449 Return a list of the contents of the resource directory, ala 1450 ``os.listdir()``. Requesting the contents of a non-existent directory may 1451 raise an exception. 1452 1453Note, by the way, that your provider classes need not (and should not) subclass 1454``IResourceProvider`` or ``IMetadataProvider``! These classes exist solely 1455for documentation purposes and do not provide any useful implementation code. 1456You may instead wish to subclass one of the `built-in resource providers`_. 1457 1458 1459Built-in Resource Providers 1460--------------------------- 1461 1462``pkg_resources`` includes several provider classes that are automatically used 1463where appropriate. Their inheritance tree looks like this:: 1464 1465 NullProvider 1466 EggProvider 1467 DefaultProvider 1468 PathMetadata 1469 ZipProvider 1470 EggMetadata 1471 EmptyProvider 1472 FileMetadata 1473 1474 1475``NullProvider`` 1476 This provider class is just an abstract base that provides for common 1477 provider behaviors (such as running scripts), given a definition for just 1478 a few abstract methods. 1479 1480``EggProvider`` 1481 This provider class adds in some egg-specific features that are common 1482 to zipped and unzipped eggs. 1483 1484``DefaultProvider`` 1485 This provider class is used for unpacked eggs and "plain old Python" 1486 filesystem modules. 1487 1488``ZipProvider`` 1489 This provider class is used for all zipped modules, whether they are eggs 1490 or not. 1491 1492``EmptyProvider`` 1493 This provider class always returns answers consistent with a provider that 1494 has no metadata or resources. ``Distribution`` objects created without 1495 a ``metadata`` argument use an instance of this provider class instead. 1496 Since all ``EmptyProvider`` instances are equivalent, there is no need 1497 to have more than one instance. ``pkg_resources`` therefore creates a 1498 global instance of this class under the name ``empty_provider``, and you 1499 may use it if you have need of an ``EmptyProvider`` instance. 1500 1501``PathMetadata(path, egg_info)`` 1502 Create an ``IResourceProvider`` for a filesystem-based distribution, where 1503 `path` is the filesystem location of the importable modules, and `egg_info` 1504 is the filesystem location of the distribution's metadata directory. 1505 `egg_info` should usually be the ``EGG-INFO`` subdirectory of `path` for an 1506 "unpacked egg", and a ``ProjectName.egg-info`` subdirectory of `path` for 1507 a "development egg". However, other uses are possible for custom purposes. 1508 1509``EggMetadata(zipimporter)`` 1510 Create an ``IResourceProvider`` for a zipfile-based distribution. The 1511 `zipimporter` should be a ``zipimport.zipimporter`` instance, and may 1512 represent a "basket" (a zipfile containing multiple ".egg" subdirectories) 1513 a specific egg *within* a basket, or a zipfile egg (where the zipfile 1514 itself is a ".egg"). It can also be a combination, such as a zipfile egg 1515 that also contains other eggs. 1516 1517``FileMetadata(path_to_pkg_info)`` 1518 Create an ``IResourceProvider`` that provides exactly one metadata 1519 resource: ``PKG-INFO``. The supplied path should be a distutils PKG-INFO 1520 file. This is basically the same as an ``EmptyProvider``, except that 1521 requests for ``PKG-INFO`` will be answered using the contents of the 1522 designated file. (This provider is used to wrap ``.egg-info`` files 1523 installed by vendor-supplied system packages.) 1524 1525 1526Utility Functions 1527================= 1528 1529In addition to its high-level APIs, ``pkg_resources`` also includes several 1530generally-useful utility routines. These routines are used to implement the 1531high-level APIs, but can also be quite useful by themselves. 1532 1533 1534Parsing Utilities 1535----------------- 1536 1537``parse_version(version)`` 1538 Parsed a project's version string as defined by PEP 440. The returned 1539 value will be an object that represents the version. These objects may 1540 be compared to each other and sorted. The sorting algorithm is as defined 1541 by PEP 440 with the addition that any version which is not a valid PEP 440 1542 version will be considered less than any valid PEP 440 version and the 1543 invalid versions will continue sorting using the original algorithm. 1544 1545.. _yield_lines(): 1546 1547``yield_lines(strs)`` 1548 Yield non-empty/non-comment lines from a string/unicode or a possibly- 1549 nested sequence thereof. If `strs` is an instance of ``basestring``, it 1550 is split into lines, and each non-blank, non-comment line is yielded after 1551 stripping leading and trailing whitespace. (Lines whose first non-blank 1552 character is ``#`` are considered comment lines.) 1553 1554 If `strs` is not an instance of ``basestring``, it is iterated over, and 1555 each item is passed recursively to ``yield_lines()``, so that an arbitrarily 1556 nested sequence of strings, or sequences of sequences of strings can be 1557 flattened out to the lines contained therein. So for example, passing 1558 a file object or a list of strings to ``yield_lines`` will both work. 1559 (Note that between each string in a sequence of strings there is assumed to 1560 be an implicit line break, so lines cannot bridge two strings in a 1561 sequence.) 1562 1563 This routine is used extensively by ``pkg_resources`` to parse metadata 1564 and file formats of various kinds, and most other ``pkg_resources`` 1565 parsing functions that yield multiple values will use it to break up their 1566 input. However, this routine is idempotent, so calling ``yield_lines()`` 1567 on the output of another call to ``yield_lines()`` is completely harmless. 1568 1569``split_sections(strs)`` 1570 Split a string (or possibly-nested iterable thereof), yielding ``(section, 1571 content)`` pairs found using an ``.ini``-like syntax. Each ``section`` is 1572 a whitespace-stripped version of the section name ("``[section]``") 1573 and each ``content`` is a list of stripped lines excluding blank lines and 1574 comment-only lines. If there are any non-blank, non-comment lines before 1575 the first section header, they're yielded in a first ``section`` of 1576 ``None``. 1577 1578 This routine uses ``yield_lines()`` as its front end, so you can pass in 1579 anything that ``yield_lines()`` accepts, such as an open text file, string, 1580 or sequence of strings. ``ValueError`` is raised if a malformed section 1581 header is found (i.e. a line starting with ``[`` but not ending with 1582 ``]``). 1583 1584 Note that this simplistic parser assumes that any line whose first nonblank 1585 character is ``[`` is a section heading, so it can't support .ini format 1586 variations that allow ``[`` as the first nonblank character on other lines. 1587 1588``safe_name(name)`` 1589 Return a "safe" form of a project's name, suitable for use in a 1590 ``Requirement`` string, as a distribution name, or a PyPI project name. 1591 All non-alphanumeric runs are condensed to single "-" characters, such that 1592 a name like "The $$$ Tree" becomes "The-Tree". Note that if you are 1593 generating a filename from this value you should combine it with a call to 1594 ``to_filename()`` so all dashes ("-") are replaced by underscores ("_"). 1595 See ``to_filename()``. 1596 1597``safe_version(version)`` 1598 This will return the normalized form of any PEP 440 version, if the version 1599 string is not PEP 440 compatible than it is similar to ``safe_name()`` 1600 except that spaces in the input become dots, and dots are allowed to exist 1601 in the output. As with ``safe_name()``, if you are generating a filename 1602 from this you should replace any "-" characters in the output with 1603 underscores. 1604 1605``safe_extra(extra)`` 1606 Return a "safe" form of an extra's name, suitable for use in a requirement 1607 string or a setup script's ``extras_require`` keyword. This routine is 1608 similar to ``safe_name()`` except that non-alphanumeric runs are replaced 1609 by a single underbar (``_``), and the result is lowercased. 1610 1611``to_filename(name_or_version)`` 1612 Escape a name or version string so it can be used in a dash-separated 1613 filename (or ``#egg=name-version`` tag) without ambiguity. You 1614 should only pass in values that were returned by ``safe_name()`` or 1615 ``safe_version()``. 1616 1617 1618Platform Utilities 1619------------------ 1620 1621``get_build_platform()`` 1622 Return this platform's identifier string. For Windows, the return value 1623 is ``"win32"``, and for Mac OS X it is a string of the form 1624 ``"macosx-10.4-ppc"``. All other platforms return the same uname-based 1625 string that the ``distutils.util.get_platform()`` function returns. 1626 This string is the minimum platform version required by distributions built 1627 on the local machine. (Backward compatibility note: setuptools versions 1628 prior to 0.6b1 called this function ``get_platform()``, and the function is 1629 still available under that name for backward compatibility reasons.) 1630 1631``get_supported_platform()`` (New in 0.6b1) 1632 This is the similar to ``get_build_platform()``, but is the maximum 1633 platform version that the local machine supports. You will usually want 1634 to use this value as the ``provided`` argument to the 1635 ``compatible_platforms()`` function. 1636 1637``compatible_platforms(provided, required)`` 1638 Return true if a distribution built on the `provided` platform may be used 1639 on the `required` platform. If either platform value is ``None``, it is 1640 considered a wildcard, and the platforms are therefore compatible. 1641 Likewise, if the platform strings are equal, they're also considered 1642 compatible, and ``True`` is returned. Currently, the only non-equal 1643 platform strings that are considered compatible are Mac OS X platform 1644 strings with the same hardware type (e.g. ``ppc``) and major version 1645 (e.g. ``10``) with the `provided` platform's minor version being less than 1646 or equal to the `required` platform's minor version. 1647 1648``get_default_cache()`` 1649 Determine the default cache location for extracting resources from zipped 1650 eggs. This routine returns the ``PYTHON_EGG_CACHE`` environment variable, 1651 if set. Otherwise, on Windows, it returns a "Python-Eggs" subdirectory of 1652 the user's "Application Data" directory. On all other systems, it returns 1653 ``os.path.expanduser("~/.python-eggs")`` if ``PYTHON_EGG_CACHE`` is not 1654 set. 1655 1656 1657PEP 302 Utilities 1658----------------- 1659 1660``get_importer(path_item)`` 1661 A deprecated alias for ``pkgutil.get_importer()`` 1662 1663 1664File/Path Utilities 1665------------------- 1666 1667``ensure_directory(path)`` 1668 Ensure that the parent directory (``os.path.dirname``) of `path` actually 1669 exists, using ``os.makedirs()`` if necessary. 1670 1671``normalize_path(path)`` 1672 Return a "normalized" version of `path`, such that two paths represent 1673 the same filesystem location if they have equal ``normalized_path()`` 1674 values. Specifically, this is a shortcut for calling ``os.path.realpath`` 1675 and ``os.path.normcase`` on `path`. Unfortunately, on certain platforms 1676 (notably Cygwin and Mac OS X) the ``normcase`` function does not accurately 1677 reflect the platform's case-sensitivity, so there is always the possibility 1678 of two apparently-different paths being equal on such platforms. 1679 1680History 1681------- 1682 16830.6c9 1684 * Fix ``resource_listdir('')`` always returning an empty list for zipped eggs. 1685 16860.6c7 1687 * Fix package precedence problem where single-version eggs installed in 1688 ``site-packages`` would take precedence over ``.egg`` files (or directories) 1689 installed in ``site-packages``. 1690 16910.6c6 1692 * Fix extracted C extensions not having executable permissions under Cygwin. 1693 1694 * Allow ``.egg-link`` files to contain relative paths. 1695 1696 * Fix cache dir defaults on Windows when multiple environment vars are needed 1697 to construct a path. 1698 16990.6c4 1700 * Fix "dev" versions being considered newer than release candidates. 1701 17020.6c3 1703 * Python 2.5 compatibility fixes. 1704 17050.6c2 1706 * Fix a problem with eggs specified directly on ``PYTHONPATH`` on 1707 case-insensitive filesystems possibly not showing up in the default 1708 working set, due to differing normalizations of ``sys.path`` entries. 1709 17100.6b3 1711 * Fixed a duplicate path insertion problem on case-insensitive filesystems. 1712 17130.6b1 1714 * Split ``get_platform()`` into ``get_supported_platform()`` and 1715 ``get_build_platform()`` to work around a Mac versioning problem that caused 1716 the behavior of ``compatible_platforms()`` to be platform specific. 1717 1718 * Fix entry point parsing when a standalone module name has whitespace 1719 between it and the extras. 1720 17210.6a11 1722 * Added ``ExtractionError`` and ``ResourceManager.extraction_error()`` so that 1723 cache permission problems get a more user-friendly explanation of the 1724 problem, and so that programs can catch and handle extraction errors if they 1725 need to. 1726 17270.6a10 1728 * Added the ``extras`` attribute to ``Distribution``, the ``find_plugins()`` 1729 method to ``WorkingSet``, and the ``__add__()`` and ``__iadd__()`` methods 1730 to ``Environment``. 1731 1732 * ``safe_name()`` now allows dots in project names. 1733 1734 * There is a new ``to_filename()`` function that escapes project names and 1735 versions for safe use in constructing egg filenames from a Distribution 1736 object's metadata. 1737 1738 * Added ``Distribution.clone()`` method, and keyword argument support to other 1739 ``Distribution`` constructors. 1740 1741 * Added the ``DEVELOP_DIST`` precedence, and automatically assign it to 1742 eggs using ``.egg-info`` format. 1743 17440.6a9 1745 * Don't raise an error when an invalid (unfinished) distribution is found 1746 unless absolutely necessary. Warn about skipping invalid/unfinished eggs 1747 when building an Environment. 1748 1749 * Added support for ``.egg-info`` files or directories with version/platform 1750 information embedded in the filename, so that system packagers have the 1751 option of including ``PKG-INFO`` files to indicate the presence of a 1752 system-installed egg, without needing to use ``.egg`` directories, zipfiles, 1753 or ``.pth`` manipulation. 1754 1755 * Changed ``parse_version()`` to remove dashes before pre-release tags, so 1756 that ``0.2-rc1`` is considered an *older* version than ``0.2``, and is equal 1757 to ``0.2rc1``. The idea that a dash *always* meant a post-release version 1758 was highly non-intuitive to setuptools users and Python developers, who 1759 seem to want to use ``-rc`` version numbers a lot. 1760 17610.6a8 1762 * Fixed a problem with ``WorkingSet.resolve()`` that prevented version 1763 conflicts from being detected at runtime. 1764 1765 * Improved runtime conflict warning message to identify a line in the user's 1766 program, rather than flagging the ``warn()`` call in ``pkg_resources``. 1767 1768 * Avoid giving runtime conflict warnings for namespace packages, even if they 1769 were declared by a different package than the one currently being activated. 1770 1771 * Fix path insertion algorithm for case-insensitive filesystems. 1772 1773 * Fixed a problem with nested namespace packages (e.g. ``peak.util``) not 1774 being set as an attribute of their parent package. 1775 17760.6a6 1777 * Activated distributions are now inserted in ``sys.path`` (and the working 1778 set) just before the directory that contains them, instead of at the end. 1779 This allows e.g. eggs in ``site-packages`` to override unmanaged modules in 1780 the same location, and allows eggs found earlier on ``sys.path`` to override 1781 ones found later. 1782 1783 * When a distribution is activated, it now checks whether any contained 1784 non-namespace modules have already been imported and issues a warning if 1785 a conflicting module has already been imported. 1786 1787 * Changed dependency processing so that it's breadth-first, allowing a 1788 depender's preferences to override those of a dependee, to prevent conflicts 1789 when a lower version is acceptable to the dependee, but not the depender. 1790 1791 * Fixed a problem extracting zipped files on Windows, when the egg in question 1792 has had changed contents but still has the same version number. 1793 17940.6a4 1795 * Fix a bug in ``WorkingSet.resolve()`` that was introduced in 0.6a3. 1796 17970.6a3 1798 * Added ``safe_extra()`` parsing utility routine, and use it for Requirement, 1799 EntryPoint, and Distribution objects' extras handling. 1800 18010.6a1 1802 * Enhanced performance of ``require()`` and related operations when all 1803 requirements are already in the working set, and enhanced performance of 1804 directory scanning for distributions. 1805 1806 * Fixed some problems using ``pkg_resources`` w/PEP 302 loaders other than 1807 ``zipimport``, and the previously-broken "eager resource" support. 1808 1809 * Fixed ``pkg_resources.resource_exists()`` not working correctly, along with 1810 some other resource API bugs. 1811 1812 * Many API changes and enhancements: 1813 1814 * Added ``EntryPoint``, ``get_entry_map``, ``load_entry_point``, and 1815 ``get_entry_info`` APIs for dynamic plugin discovery. 1816 1817 * ``list_resources`` is now ``resource_listdir`` (and it actually works) 1818 1819 * Resource API functions like ``resource_string()`` that accepted a package 1820 name and resource name, will now also accept a ``Requirement`` object in 1821 place of the package name (to allow access to non-package data files in 1822 an egg). 1823 1824 * ``get_provider()`` will now accept a ``Requirement`` instance or a module 1825 name. If it is given a ``Requirement``, it will return a corresponding 1826 ``Distribution`` (by calling ``require()`` if a suitable distribution 1827 isn't already in the working set), rather than returning a metadata and 1828 resource provider for a specific module. (The difference is in how 1829 resource paths are interpreted; supplying a module name means resources 1830 path will be module-relative, rather than relative to the distribution's 1831 root.) 1832 1833 * ``Distribution`` objects now implement the ``IResourceProvider`` and 1834 ``IMetadataProvider`` interfaces, so you don't need to reference the (no 1835 longer available) ``metadata`` attribute to get at these interfaces. 1836 1837 * ``Distribution`` and ``Requirement`` both have a ``project_name`` 1838 attribute for the project name they refer to. (Previously these were 1839 ``name`` and ``distname`` attributes.) 1840 1841 * The ``path`` attribute of ``Distribution`` objects is now ``location``, 1842 because it isn't necessarily a filesystem path (and hasn't been for some 1843 time now). The ``location`` of ``Distribution`` objects in the filesystem 1844 should always be normalized using ``pkg_resources.normalize_path()``; all 1845 of the setuptools and EasyInstall code that generates distributions from 1846 the filesystem (including ``Distribution.from_filename()``) ensure this 1847 invariant, but if you use a more generic API like ``Distribution()`` or 1848 ``Distribution.from_location()`` you should take care that you don't 1849 create a distribution with an un-normalized filesystem path. 1850 1851 * ``Distribution`` objects now have an ``as_requirement()`` method that 1852 returns a ``Requirement`` for the distribution's project name and version. 1853 1854 * Distribution objects no longer have an ``installed_on()`` method, and the 1855 ``install_on()`` method is now ``activate()`` (but may go away altogether 1856 soon). The ``depends()`` method has also been renamed to ``requires()``, 1857 and ``InvalidOption`` is now ``UnknownExtra``. 1858 1859 * ``find_distributions()`` now takes an additional argument called ``only``, 1860 that tells it to only yield distributions whose location is the passed-in 1861 path. (It defaults to False, so that the default behavior is unchanged.) 1862 1863 * ``AvailableDistributions`` is now called ``Environment``, and the 1864 ``get()``, ``__len__()``, and ``__contains__()`` methods were removed, 1865 because they weren't particularly useful. ``__getitem__()`` no longer 1866 raises ``KeyError``; it just returns an empty list if there are no 1867 distributions for the named project. 1868 1869 * The ``resolve()`` method of ``Environment`` is now a method of 1870 ``WorkingSet`` instead, and the ``best_match()`` method now uses a working 1871 set instead of a path list as its second argument. 1872 1873 * There is a new ``pkg_resources.add_activation_listener()`` API that lets 1874 you register a callback for notifications about distributions added to 1875 ``sys.path`` (including the distributions already on it). This is 1876 basically a hook for extensible applications and frameworks to be able to 1877 search for plugin metadata in distributions added at runtime. 1878 18790.5a13 1880 * Fixed a bug in resource extraction from nested packages in a zipped egg. 1881 18820.5a12 1883 * Updated extraction/cache mechanism for zipped resources to avoid inter- 1884 process and inter-thread races during extraction. The default cache 1885 location can now be set via the ``PYTHON_EGGS_CACHE`` environment variable, 1886 and the default Windows cache is now a ``Python-Eggs`` subdirectory of the 1887 current user's "Application Data" directory, if the ``PYTHON_EGGS_CACHE`` 1888 variable isn't set. 1889 18900.5a10 1891 * Fix a problem with ``pkg_resources`` being confused by non-existent eggs on 1892 ``sys.path`` (e.g. if a user deletes an egg without removing it from the 1893 ``easy-install.pth`` file). 1894 1895 * Fix a problem with "basket" support in ``pkg_resources``, where egg-finding 1896 never actually went inside ``.egg`` files. 1897 1898 * Made ``pkg_resources`` import the module you request resources from, if it's 1899 not already imported. 1900 19010.5a4 1902 * ``pkg_resources.AvailableDistributions.resolve()`` and related methods now 1903 accept an ``installer`` argument: a callable taking one argument, a 1904 ``Requirement`` instance. The callable must return a ``Distribution`` 1905 object, or ``None`` if no distribution is found. This feature is used by 1906 EasyInstall to resolve dependencies by recursively invoking itself. 1907 19080.4a4 1909 * Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource 1910 directory extraction for zipped eggs. 1911 19120.4a3 1913 * Fixed scripts not being able to see a ``__file__`` variable in ``__main__`` 1914 1915 * Fixed a problem with ``resource_isdir()`` implementation that was introduced 1916 in 0.4a2. 1917 19180.4a1 1919 * Fixed a bug in requirements processing for exact versions (i.e. ``==`` and 1920 ``!=``) when only one condition was included. 1921 1922 * Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of 1923 arbitrary distribution names and versions found on PyPI. 1924 19250.3a4 1926 * ``pkg_resources`` now supports resource directories, not just the resources 1927 in them. In particular, there are ``resource_listdir()`` and 1928 ``resource_isdir()`` APIs. 1929 1930 * ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain 1931 multiple distributions in subdirectories whose names end with ``.egg``. 1932 Having such a "basket" in a directory on ``sys.path`` is equivalent to 1933 having the individual eggs in that directory, but the contained eggs can 1934 be individually added (or not) to ``sys.path``. Currently, however, there 1935 is no automated way to create baskets. 1936 1937 * Namespace package manipulation is now protected by the Python import lock. 1938 19390.3a1 1940 * Initial release. 1941 1942