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