1 ===================================== 2 The Internal Structure of Python Eggs 3 ===================================== 4 5 STOP! This is not the first document you should read! 6 7 8 9 .. contents:: **Table of Contents** 10 11 12 ---------------------- 13 Eggs and their Formats 14 ---------------------- 15 16 A "Python egg" is a logical structure embodying the release of a 17 specific version of a Python project, comprising its code, resources, 18 and metadata. There are multiple formats that can be used to physically 19 encode a Python egg, and others can be developed. However, a key 20 principle of Python eggs is that they should be discoverable and 21 importable. That is, it should be possible for a Python application to 22 easily and efficiently find out what eggs are present on a system, and 23 to ensure that the desired eggs' contents are importable. 24 25 There are two basic formats currently implemented for Python eggs: 26 27 1. ``.egg`` format: a directory or zipfile *containing* the project's 28 code and resources, along with an ``EGG-INFO`` subdirectory that 29 contains the project's metadata 30 31 2. ``.egg-info`` format: a file or directory placed *adjacent* to the 32 project's code and resources, that directly contains the project's 33 metadata. 34 35 Both formats can include arbitrary Python code and resources, including 36 static data files, package and non-package directories, Python 37 modules, C extension modules, and so on. But each format is optimized 38 for different purposes. 39 40 The ``.egg`` format is well-suited to distribution and the easy 41 uninstallation or upgrades of code, since the project is essentially 42 self-contained within a single directory or file, unmingled with any 43 other projects' code or resources. It also makes it possible to have 44 multiple versions of a project simultaneously installed, such that 45 individual programs can select the versions they wish to use. 46 47 The ``.egg-info`` format, on the other hand, was created to support 48 backward-compatibility, performance, and ease of installation for system 49 packaging tools that expect to install all projects' code and resources 50 to a single directory (e.g. ``site-packages``). Placing the metadata 51 in that same directory simplifies the installation process, since it 52 isn't necessary to create ``.pth`` files or otherwise modify 53 ``sys.path`` to include each installed egg. 54 55 Its disadvantage, however, is that it provides no support for clean 56 uninstallation or upgrades, and of course only a single version of a 57 project can be installed to a given directory. Thus, support from a 58 package management tool is required. (This is why setuptools' "install" 59 command refers to this type of egg installation as "single-version, 60 externally managed".) Also, they lack sufficient data to allow them to 61 be copied from their installation source. easy_install can "ship" an 62 application by copying ``.egg`` files or directories to a target 63 location, but it cannot do this for ``.egg-info`` installs, because 64 there is no way to tell what code and resources belong to a particular 65 egg -- there may be several eggs "scrambled" together in a single 66 installation location, and the ``.egg-info`` format does not currently 67 include a way to list the files that were installed. (This may change 68 in a future version.) 69 70 71 Code and Resources 72 ================== 73 74 The layout of the code and resources is dictated by Python's normal 75 import layout, relative to the egg's "base location". 76 77 For the ``.egg`` format, the base location is the ``.egg`` itself. That 78 is, adding the ``.egg`` filename or directory name to ``sys.path`` 79 makes its contents importable. 80 81 For the ``.egg-info`` format, however, the base location is the 82 directory that *contains* the ``.egg-info``, and thus it is the 83 directory that must be added to ``sys.path`` to make the egg importable. 84 (Note that this means that the "normal" installation of a package to a 85 ``sys.path`` directory is sufficient to make it an "egg" if it has an 86 ``.egg-info`` file or directory installed alongside of it.) 87 88 89 Project Metadata 90 ================= 91 92 If eggs contained only code and resources, there would of course be 93 no difference between them and any other directory or zip file on 94 ``sys.path``. Thus, metadata must also be included, using a metadata 95 file or directory. 96 97 For the ``.egg`` format, the metadata is placed in an ``EGG-INFO`` 98 subdirectory, directly within the ``.egg`` file or directory. For the 99 ``.egg-info`` format, metadata is stored directly within the 100 ``.egg-info`` directory itself. 101 102 The minimum project metadata that all eggs must have is a standard 103 Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the 104 metadata directory appropriate to the format. Because it's possible for 105 this to be the only metadata file included, ``.egg-info`` format eggs 106 are not required to be a directory; they can just be a ``.egg-info`` 107 file that directly contains the ``PKG-INFO`` metadata. This eliminates 108 the need to create a directory just to store one file. This option is 109 *not* available for ``.egg`` formats, since setuptools always includes 110 other metadata. (In fact, setuptools itself never generates 111 ``.egg-info`` files, either; the support for using files was added so 112 that the requirement could easily be satisfied by other tools, such 113 as distutils). 114 115 In addition to the ``PKG-INFO`` file, an egg's metadata directory may 116 also include files and directories representing various forms of 117 optional standard metadata (see the section on `Standard Metadata`_, 118 below) or user-defined metadata required by the project. For example, 119 some projects may define a metadata format to describe their application 120 plugins, and metadata in this format would then be included by plugin 121 creators in their projects' metadata directories. 122 123 124 Filename-Embedded Metadata 125 ========================== 126 127 To allow introspection of installed projects and runtime resolution of 128 inter-project dependencies, a certain amount of information is embedded 129 in egg filenames. At a minimum, this includes the project name, and 130 ideally will also include the project version number. Optionally, it 131 can also include the target Python version and required runtime 132 platform if platform-specific C code is included. The syntax of an 133 egg filename is as follows:: 134 135 name ["-" version ["-py" pyver ["-" required_platform]]] "." ext 136 137 The "name" and "version" should be escaped using the ``to_filename()`` 138 function provided by ``pkg_resources``, after first processing them with 139 ``safe_name()`` and ``safe_version()`` respectively. These latter two 140 functions can also be used to later "unescape" these parts of the 141 filename. (For a detailed description of these transformations, please 142 see the "Parsing Utilities" section of the ``pkg_resources`` manual.) 143 144 The "pyver" string is the Python major version, as found in the first 145 3 characters of ``sys.version``. "required_platform" is essentially 146 a distutils ``get_platform()`` string, but with enhancements to properly 147 distinguish Mac OS versions. (See the ``get_build_platform()`` 148 documentation in the "Platform Utilities" section of the 149 ``pkg_resources`` manual for more details.) 150 151 Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate 152 for the egg's format. 153 154 Normally, an egg's filename should include at least the project name and 155 version, as this allows the runtime system to find desired project 156 versions without having to read the egg's PKG-INFO to determine its 157 version number. 158 159 Setuptools, however, only includes the version number in the filename 160 when an ``.egg`` file is built using the ``bdist_egg`` command, or when 161 an ``.egg-info`` directory is being installed by the 162 ``install_egg_info`` command. When generating metadata for use with the 163 original source tree, it only includes the project name, so that the 164 directory will not have to be renamed each time the project's version 165 changes. 166 167 This is especially important when version numbers change frequently, and 168 the source metadata directory is kept under version control with the 169 rest of the project. (As would be the case when the project's source 170 includes project-defined metadata that is not generated from by 171 setuptools from data in the setup script.) 172 173 174 Egg Links 175 ========= 176 177 In addition to the ``.egg`` and ``.egg-info`` formats, there is a third 178 egg-related extension that you may encounter on occasion: ``.egg-link`` 179 files. 180 181 These files are not eggs, strictly speaking. They simply provide a way 182 to reference an egg that is not physically installed in the desired 183 location. They exist primarily as a cross-platform alternative to 184 symbolic links, to support "installing" code that is being developed in 185 a different location than the desired installation location. For 186 example, if a user is developing an application plugin in their home 187 directory, but the plugin needs to be "installed" in an application 188 plugin directory, running "setup.py develop -md /path/to/app/plugins" 189 will install an ``.egg-link`` file in ``/path/to/app/plugins``, that 190 tells the egg runtime system where to find the actual egg (the user's 191 project source directory and its ``.egg-info`` subdirectory). 192 193 ``.egg-link`` files are named following the format for ``.egg`` and 194 ``.egg-info`` names, but only the project name is included; no version, 195 Python version, or platform information is included. When the runtime 196 searches for available eggs, ``.egg-link`` files are opened and the 197 actual egg file/directory name is read from them. 198 199 Each ``.egg-link`` file should contain a single file or directory name, 200 with no newlines. This filename should be the base location of one or 201 more eggs. That is, the name must either end in ``.egg``, or else it 202 should be the parent directory of one or more ``.egg-info`` format eggs. 203 204 As of setuptools 0.6c6, the path may be specified as a platform-independent 205 (i.e. ``/``-separated) relative path from the directory containing the 206 ``.egg-link`` file, and a second line may appear in the file, specifying a 207 platform-independent relative path from the egg's base directory to its 208 setup script directory. This allows installation tools such as EasyInstall 209 to find the project's setup directory and build eggs or perform other setup 210 commands on it. 211 212 213 ----------------- 214 Standard Metadata 215 ----------------- 216 217 In addition to the minimum required ``PKG-INFO`` metadata, projects can 218 include a variety of standard metadata files or directories, as 219 described below. Except as otherwise noted, these files and directories 220 are automatically generated by setuptools, based on information supplied 221 in the setup script or through analysis of the project's code and 222 resources. 223 224 Most of these files and directories are generated via "egg-info 225 writers" during execution of the setuptools ``egg_info`` command, and 226 are listed in the ``egg_info.writers`` entry point group defined by 227 setuptools' own ``setup.py`` file. 228 229 Project authors can register their own metadata writers as entry points 230 in this group (as described in the setuptools manual under "Adding new 231 EGG-INFO Files") to cause setuptools to generate project-specific 232 metadata files or directories during execution of the ``egg_info`` 233 command. It is up to project authors to document these new metadata 234 formats, if they create any. 235 236 237 ``.txt`` File Formats 238 ===================== 239 240 Files described in this section that have ``.txt`` extensions have a 241 simple lexical format consisting of a sequence of text lines, each line 242 terminated by a linefeed character (regardless of platform). Leading 243 and trailing whitespace on each line is ignored, as are blank lines and 244 lines whose first nonblank character is a ``#`` (comment symbol). (This 245 is the parsing format defined by the ``yield_lines()`` function of 246 the ``pkg_resources`` module.) 247 248 All ``.txt`` files defined by this section follow this format, but some 249 are also "sectioned" files, meaning that their contents are divided into 250 sections, using square-bracketed section headers akin to Windows 251 ``.ini`` format. Note that this does *not* imply that the lines within 252 the sections follow an ``.ini`` format, however. Please see an 253 individual metadata file's documentation for a description of what the 254 lines and section names mean in that particular file. 255 256 Sectioned files can be parsed using the ``split_sections()`` function; 257 see the "Parsing Utilities" section of the ``pkg_resources`` manual for 258 for details. 259 260 261 Dependency Metadata 262 =================== 263 264 265 ``requires.txt`` 266 ---------------- 267 268 This is a "sectioned" text file. Each section is a sequence of 269 "requirements", as parsed by the ``parse_requirements()`` function; 270 please see the ``pkg_resources`` manual for the complete requirement 271 parsing syntax. 272 273 The first, unnamed section (i.e., before the first section header) in 274 this file is the project's core requirements, which must be installed 275 for the project to function. (Specified using the ``install_requires`` 276 keyword to ``setup()``). 277 278 The remaining (named) sections describe the project's "extra" 279 requirements, as specified using the ``extras_require`` keyword to 280 ``setup()``. The section name is the name of the optional feature, and 281 the section body lists that feature's dependencies. 282 283 Note that it is not normally necessary to inspect this file directly; 284 ``pkg_resources.Distribution`` objects have a ``requires()`` method 285 that can be used to obtain ``Requirement`` objects describing the 286 project's core and optional dependencies. 287 288 289 ``setup_requires.txt`` 290 ---------------------- 291 292 Much like ``requires.txt`` except represents the requirements 293 specified by the ``setup_requires`` parameter to the Distribution. 294 295 296 ``dependency_links.txt`` 297 ------------------------ 298 299 A list of dependency URLs, one per line, as specified using the 300 ``dependency_links`` keyword to ``setup()``. These may be direct 301 download URLs, or the URLs of web pages containing direct download 302 links, and will be used by EasyInstall to find dependencies, as though 303 the user had manually provided them via the ``--find-links`` command 304 line option. Please see the setuptools manual and EasyInstall manual 305 for more information on specifying this option, and for information on 306 how EasyInstall processes ``--find-links`` URLs. 307 308 309 ``depends.txt`` -- Obsolete, do not create! 310 ------------------------------------------- 311 312 This file follows an identical format to ``requires.txt``, but is 313 obsolete and should not be used. The earliest versions of setuptools 314 required users to manually create and maintain this file, so the runtime 315 still supports reading it, if it exists. The new filename was created 316 so that it could be automatically generated from ``setup()`` information 317 without overwriting an existing hand-created ``depends.txt``, if one 318 was already present in the project's source ``.egg-info`` directory. 319 320 321 ``namespace_packages.txt`` -- Namespace Package Metadata 322 ======================================================== 323 324 A list of namespace package names, one per line, as supplied to the 325 ``namespace_packages`` keyword to ``setup()``. Please see the manuals 326 for setuptools and ``pkg_resources`` for more information about 327 namespace packages. 328 329 330 ``entry_points.txt`` -- "Entry Point"/Plugin Metadata 331 ===================================================== 332 333 This is a "sectioned" text file, whose contents encode the 334 ``entry_points`` keyword supplied to ``setup()``. All sections are 335 named, as the section names specify the entry point groups in which the 336 corresponding section's entry points are registered. 337 338 Each section is a sequence of "entry point" lines, each parseable using 339 the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources`` 340 manual for the complete entry point parsing syntax. 341 342 Note that it is not necessary to parse this file directly; the 343 ``pkg_resources`` module provides a variety of APIs to locate and load 344 entry points automatically. Please see the setuptools and 345 ``pkg_resources`` manuals for details on the nature and uses of entry 346 points. 347 348 349 The ``scripts`` Subdirectory 350 ============================ 351 352 This directory is currently only created for ``.egg`` files built by 353 the setuptools ``bdist_egg`` command. It will contain copies of all 354 of the project's "traditional" scripts (i.e., those specified using the 355 ``scripts`` keyword to ``setup()``). This is so that they can be 356 reconstituted when an ``.egg`` file is installed. 357 358 The scripts are placed here using the distutils' standard 359 ``install_scripts`` command, so any ``#!`` lines reflect the Python 360 installation where the egg was built. But instead of copying the 361 scripts to the local script installation directory, EasyInstall writes 362 short wrapper scripts that invoke the original scripts from inside the 363 egg, after ensuring that sys.path includes the egg and any eggs it 364 depends on. For more about `script wrappers`_, see the section below on 365 `Installation and Path Management Issues`_. 366 367 368 Zip Support Metadata 369 ==================== 370 371 372 ``native_libs.txt`` 373 ------------------- 374 375 A list of C extensions and other dynamic link libraries contained in 376 the egg, one per line. Paths are ``/``-separated and relative to the 377 egg's base location. 378 379 This file is generated as part of ``bdist_egg`` processing, and as such 380 only appears in ``.egg`` files (and ``.egg`` directories created by 381 unpacking them). It is used to ensure that all libraries are extracted 382 from a zipped egg at the same time, in case there is any direct linkage 383 between them. Please see the `Zip File Issues`_ section below for more 384 information on library and resource extraction from ``.egg`` files. 385 386 387 ``eager_resources.txt`` 388 ----------------------- 389 390 A list of resource files and/or directories, one per line, as specified 391 via the ``eager_resources`` keyword to ``setup()``. Paths are 392 ``/``-separated and relative to the egg's base location. 393 394 Resource files or directories listed here will be extracted 395 simultaneously, if any of the named resources are extracted, or if any 396 native libraries listed in ``native_libs.txt`` are extracted. Please 397 see the setuptools manual for details on what this feature is used for 398 and how it works, as well as the `Zip File Issues`_ section below. 399 400 401 ``zip-safe`` and ``not-zip-safe`` 402 --------------------------------- 403 404 These are zero-length files, and either one or the other should exist. 405 If ``zip-safe`` exists, it means that the project will work properly 406 when installed as an ``.egg`` zipfile, and conversely the existence of 407 ``not-zip-safe`` means the project should not be installed as an 408 ``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()`` 409 determines which file will be written. If the option isn't provided, 410 setuptools attempts to make its own assessment of whether the package 411 can work, based on code and content analysis. 412 413 If neither file is present at installation time, EasyInstall defaults 414 to assuming that the project should be unzipped. (Command-line options 415 to EasyInstall, however, take precedence even over an existing 416 ``zip-safe`` or ``not-zip-safe`` file.) 417 418 Note that these flag files appear only in ``.egg`` files generated by 419 ``bdist_egg``, and in ``.egg`` directories created by unpacking such an 420 ``.egg`` file. 421 422 423 424 ``top_level.txt`` -- Conflict Management Metadata 425 ================================================= 426 427 This file is a list of the top-level module or package names provided 428 by the project, one Python identifier per line. 429 430 Subpackages are not included; a project containing both a ``foo.bar`` 431 and a ``foo.baz`` would include only one line, ``foo``, in its 432 ``top_level.txt``. 433 434 This data is used by ``pkg_resources`` at runtime to issue a warning if 435 an egg is added to ``sys.path`` when its contained packages may have 436 already been imported. 437 438 (It was also once used to detect conflicts with non-egg packages at 439 installation time, but in more recent versions, setuptools installs eggs 440 in such a way that they always override non-egg packages, thus 441 preventing a problem from arising.) 442 443 444 ``SOURCES.txt`` -- Source Files Manifest 445 ======================================== 446 447 This file is roughly equivalent to the distutils' ``MANIFEST`` file. 448 The differences are as follows: 449 450 * The filenames always use ``/`` as a path separator, which must be 451 converted back to a platform-specific path whenever they are read. 452 453 * The file is automatically generated by setuptools whenever the 454 ``egg_info`` or ``sdist`` commands are run, and it is *not* 455 user-editable. 456 457 Although this metadata is included with distributed eggs, it is not 458 actually used at runtime for any purpose. Its function is to ensure 459 that setuptools-built *source* distributions can correctly discover 460 what files are part of the project's source, even if the list had been 461 generated using revision control metadata on the original author's 462 system. 463 464 In other words, ``SOURCES.txt`` has little or no runtime value for being 465 included in distributed eggs, and it is possible that future versions of 466 the ``bdist_egg`` and ``install_egg_info`` commands will strip it before 467 installation or distribution. Therefore, do not rely on its being 468 available outside of an original source directory or source 469 distribution. 470 471 472 ------------------------------ 473 Other Technical Considerations 474 ------------------------------ 475 476 477 Zip File Issues 478 =============== 479 480 Although zip files resemble directories, they are not fully 481 substitutable for them. Most platforms do not support loading dynamic 482 link libraries contained in zipfiles, so it is not possible to directly 483 import C extensions from ``.egg`` zipfiles. Similarly, there are many 484 existing libraries -- whether in Python or C -- that require actual 485 operating system filenames, and do not work with arbitrary "file-like" 486 objects or in-memory strings, and thus cannot operate directly on the 487 contents of zip files. 488 489 To address these issues, the ``pkg_resources`` module provides a 490 "resource API" to support obtaining either the contents of a resource, 491 or a true operating system filename for the resource. If the egg 492 containing the resource is a directory, the resource's real filename 493 is simply returned. However, if the egg is a zipfile, then the 494 resource is first extracted to a cache directory, and the filename 495 within the cache is returned. 496 497 The cache directory is determined by the ``pkg_resources`` API; please 498 see the ``set_cache_path()`` and ``get_default_cache()`` documentation 499 for details. 500 501 502 The Extraction Process 503 ---------------------- 504 505 Resources are extracted to a cache subdirectory whose name is based 506 on the enclosing ``.egg`` filename and the path to the resource. If 507 there is already a file of the correct name, size, and timestamp, its 508 filename is returned to the requester. Otherwise, the desired file is 509 extracted first to a temporary name generated using 510 ``mkstemp(".$extract",target_dir)``, and then its timestamp is set to 511 match the one in the zip file, before renaming it to its final name. 512 (Some collision detection and resolution code is used to handle the 513 fact that Windows doesn't overwrite files when renaming.) 514 515 If a resource directory is requested, all of its contents are 516 recursively extracted in this fashion, to ensure that the directory 517 name can be used as if it were valid all along. 518 519 If the resource requested for extraction is listed in the 520 ``native_libs.txt`` or ``eager_resources.txt`` metadata files, then 521 *all* resources listed in *either* file will be extracted before the 522 requested resource's filename is returned, thus ensuring that all 523 C extensions and data used by them will be simultaneously available. 524 525 526 Extension Import Wrappers 527 ------------------------- 528 529 Since Python's built-in zip import feature does not support loading 530 C extension modules from zipfiles, the setuptools ``bdist_egg`` command 531 generates special import wrappers to make it work. 532 533 The wrappers are ``.py`` files (along with corresponding ``.pyc`` 534 and/or ``.pyo`` files) that have the same module name as the 535 corresponding C extension. These wrappers are located in the same 536 package directory (or top-level directory) within the zipfile, so that 537 say, ``foomodule.so`` will get a corresponding ``foo.py``, while 538 ``bar/baz.pyd`` will get a corresponding ``bar/baz.py``. 539 540 These wrapper files contain a short stanza of Python code that asks 541 ``pkg_resources`` for the filename of the corresponding C extension, 542 then reloads the module using the obtained filename. This will cause 543 ``pkg_resources`` to first ensure that all of the egg's C extensions 544 (and any accompanying "eager resources") are extracted to the cache 545 before attempting to link to the C library. 546 547 Note, by the way, that ``.egg`` directories will also contain these 548 wrapper files. However, Python's default import priority is such that 549 C extensions take precedence over same-named Python modules, so the 550 import wrappers are ignored unless the egg is a zipfile. 551 552 553 Installation and Path Management Issues 554 ======================================= 555 556 Python's initial setup of ``sys.path`` is very dependent on the Python 557 version and installation platform, as well as how Python was started 558 (i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter). 559 In fact, Python also provides only two relatively robust ways to affect 560 ``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH`` 561 environment variable, and ``.pth`` files. 562 563 However, with no cross-platform way to safely and persistently change 564 environment variables, this leaves ``.pth`` files as EasyInstall's only 565 real option for persistent configuration of ``sys.path``. 566 567 But ``.pth`` files are rather strictly limited in what they are allowed 568 to do normally. They add directories only to the *end* of ``sys.path``, 569 after any locally-installed ``site-packages`` directory, and they are 570 only processed *in* the ``site-packages`` directory to start with. 571 572 This is a double whammy for users who lack write access to that 573 directory, because they can't create a ``.pth`` file that Python will 574 read, and even if a sympathetic system administrator adds one for them 575 that calls ``site.addsitedir()`` to allow some other directory to 576 contain ``.pth`` files, they won't be able to install newer versions of 577 anything that's installed in the systemwide ``site-packages``, because 578 their paths will still be added *after* ``site-packages``. 579 580 So EasyInstall applies two workarounds to solve these problems. 581 582 The first is that EasyInstall leverages ``.pth`` files' "import" feature 583 to manipulate ``sys.path`` and ensure that anything EasyInstall adds 584 to a ``.pth`` file will always appear before both the standard library 585 and the local ``site-packages`` directories. Thus, it is always 586 possible for a user who can write a Python-read ``.pth`` file to ensure 587 that their packages come first in their own environment. 588 589 Second, when installing to a ``PYTHONPATH`` directory (as opposed to 590 a "site" directory like ``site-packages``) EasyInstall will also install 591 a special version of the ``site`` module. Because it's in a 592 ``PYTHONPATH`` directory, this module will get control before the 593 standard library version of ``site`` does. It will record the state of 594 ``sys.path`` before invoking the "real" ``site`` module, and then 595 afterwards it processes any ``.pth`` files found in ``PYTHONPATH`` 596 directories, including all the fixups needed to ensure that eggs always 597 appear before the standard library in sys.path, but are in a relative 598 order to one another that is defined by their ``PYTHONPATH`` and 599 ``.pth``-prescribed sequence. 600 601 The net result of these changes is that ``sys.path`` order will be 602 as follows at runtime: 603 604 1. The ``sys.argv[0]`` directory, or an empty string if no script 605 is being executed. 606 607 2. All eggs installed by EasyInstall in any ``.pth`` file in each 608 ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order, 609 then normal ``.pth`` processing order (which is to say alphabetical 610 by ``.pth`` filename, then by the order of listing within each 611 ``.pth`` file). 612 613 3. All eggs installed by EasyInstall in any ``.pth`` file in each "site" 614 directory (such as ``site-packages``), following the same ordering 615 rules as for the ones on ``PYTHONPATH``. 616 617 4. The ``PYTHONPATH`` directories themselves, in their original order 618 619 5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not* 620 eggs installed by EasyInstall, again following the same relative 621 ordering rules. 622 623 6. The standard library and "site" directories, along with the contents 624 of any ``.pth`` files found in the "site" directories. 625 626 Notice that sections 1, 4, and 6 comprise the "normal" Python setup for 627 ``sys.path``. Sections 2 and 3 are inserted to support eggs, and 628 section 5 emulates what the "normal" semantics of ``.pth`` files on 629 ``PYTHONPATH`` would be if Python natively supported them. 630 631 For further discussion of the tradeoffs that went into this design, as 632 well as notes on the actual magic inserted into ``.pth`` files to make 633 them do these things, please see also the following messages to the 634 distutils-SIG mailing list: 635 636 * http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html 637 * http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html 638 639 640 Script Wrappers 641 --------------- 642 643 EasyInstall never directly installs a project's original scripts to 644 a script installation directory. Instead, it writes short wrapper 645 scripts that first ensure that the project's dependencies are active 646 on sys.path, before invoking the original script. These wrappers 647 have a #! line that points to the version of Python that was used to 648 install them, and their second line is always a comment that indicates 649 the type of script wrapper, the project version required for the script 650 to run, and information identifying the script to be invoked. 651 652 The format of this marker line is:: 653 654 "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n" 655 656 The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or 657 ``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated 658 sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT`` 659 wrappers, there are two strings: the project version requirement, and 660 the script name (as a filename within the ``scripts`` metadata 661 directory). For ``ENTRY-SCRIPT`` wrappers, there are three: 662 the project version requirement, the entry point group name, and the 663 entry point name. (See the "Automatic Script Creation" section in the 664 setuptools manual for more information about entry point scripts.) 665 666 In each case, the project version requirement string will be a string 667 parseable with the ``pkg_resources`` modules' ``Requirement.parse()`` 668 classmethod. The only difference between a ``SCRIPT`` wrapper and a 669 ``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original 670 source script in the project's source tree, and is created when the 671 "setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other 672 hand, uses the "installed" script written to the ``EGG-INFO/scripts`` 673 subdirectory of the corresponding ``.egg`` zipfile or directory. 674 (``.egg-info`` eggs do not have script wrappers associated with them, 675 except in the "setup.py develop" case.) 676 677 The purpose of including the marker line in generated script wrappers is 678 to facilitate introspection of installed scripts, and their relationship 679 to installed eggs. For example, an uninstallation tool could use this 680 data to identify what scripts can safely be removed, and/or identify 681 what scripts would stop working if a particular egg is uninstalled. 682 683
