From 6ff2ea56e7828da84dd6da4bb32964a1e19e81f7 Mon Sep 17 00:00:00 2001 From: alvyjudy Date: Sun, 10 May 2020 14:20:56 -0400 Subject: doc: rename formats.txt as python-eggs.txt --- docs/formats.txt | 679 --------------------------------------------------- docs/python_eggs.txt | 679 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 679 insertions(+), 679 deletions(-) delete mode 100644 docs/formats.txt create mode 100644 docs/python_eggs.txt (limited to 'docs') diff --git a/docs/formats.txt b/docs/formats.txt deleted file mode 100644 index 6c0456de..00000000 --- a/docs/formats.txt +++ /dev/null @@ -1,679 +0,0 @@ -===================================== -The Internal Structure of Python Eggs -===================================== - -STOP! This is not the first document you should read! - - - -.. contents:: **Table of Contents** - - ----------------------- -Eggs and their Formats ----------------------- - -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. - -There are two basic formats currently implemented for Python eggs: - -1. ``.egg`` format: a directory or zipfile *containing* the project's - code and resources, along with an ``EGG-INFO`` subdirectory that - contains the project's metadata - -2. ``.egg-info`` format: a file or directory placed *adjacent* to the - project's code and resources, that directly contains the project's - metadata. - -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. - -The ``.egg`` 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. - -The ``.egg-info`` 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. ``site-packages``). Placing the metadata -in that same directory simplifies the installation process, since it -isn't necessary to create ``.pth`` files or otherwise modify -``sys.path`` to include each installed egg. - -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 ``.egg`` files or directories to a target -location, but it cannot do this for ``.egg-info`` 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 ``.egg-info`` format does not currently -include a way to list the files that were installed. (This may change -in a future version.) - - -Code and Resources -================== - -The layout of the code and resources is dictated by Python's normal -import layout, relative to the egg's "base location". - -For the ``.egg`` format, the base location is the ``.egg`` itself. That -is, adding the ``.egg`` filename or directory name to ``sys.path`` -makes its contents importable. - -For the ``.egg-info`` format, however, the base location is the -directory that *contains* the ``.egg-info``, and thus it is the -directory that must be added to ``sys.path`` to make the egg importable. -(Note that this means that the "normal" installation of a package to a -``sys.path`` directory is sufficient to make it an "egg" if it has an -``.egg-info`` file or directory installed alongside of it.) - - -Project Metadata -================= - -If eggs contained only code and resources, there would of course be -no difference between them and any other directory or zip file on -``sys.path``. Thus, metadata must also be included, using a metadata -file or directory. - -For the ``.egg`` format, the metadata is placed in an ``EGG-INFO`` -subdirectory, directly within the ``.egg`` file or directory. For the -``.egg-info`` format, metadata is stored directly within the -``.egg-info`` directory itself. - -The minimum project metadata that all eggs must have is a standard -Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the -metadata directory appropriate to the format. Because it's possible for -this to be the only metadata file included, ``.egg-info`` format eggs -are not required to be a directory; they can just be a ``.egg-info`` -file that directly contains the ``PKG-INFO`` metadata. This eliminates -the need to create a directory just to store one file. This option is -*not* available for ``.egg`` formats, since setuptools always includes -other metadata. (In fact, setuptools itself never generates -``.egg-info`` files, either; the support for using files was added so -that the requirement could easily be satisfied by other tools, such -as distutils). - -In addition to the ``PKG-INFO`` file, an egg's metadata directory may -also include files and directories representing various forms of -optional standard metadata (see the section on `Standard Metadata`_, -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. - - -Filename-Embedded Metadata -========================== - -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:: - - name ["-" version ["-py" pyver ["-" required_platform]]] "." ext - -The "name" and "version" should be escaped using the ``to_filename()`` -function provided by ``pkg_resources``, after first processing them with -``safe_name()`` and ``safe_version()`` 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 ``pkg_resources`` manual.) - -The "pyver" string is the Python major version, as found in the first -3 characters of ``sys.version``. "required_platform" is essentially -a distutils ``get_platform()`` string, but with enhancements to properly -distinguish Mac OS versions. (See the ``get_build_platform()`` -documentation in the "Platform Utilities" section of the -``pkg_resources`` manual for more details.) - -Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate -for the egg's format. - -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. - -Setuptools, however, only includes the version number in the filename -when an ``.egg`` file is built using the ``bdist_egg`` command, or when -an ``.egg-info`` directory is being installed by the -``install_egg_info`` 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. - -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.) - - -Egg Links -========= - -In addition to the ``.egg`` and ``.egg-info`` formats, there is a third -egg-related extension that you may encounter on occasion: ``.egg-link`` -files. - -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 ``.egg-link`` file in ``/path/to/app/plugins``, that -tells the egg runtime system where to find the actual egg (the user's -project source directory and its ``.egg-info`` subdirectory). - -``.egg-link`` files are named following the format for ``.egg`` and -``.egg-info`` names, but only the project name is included; no version, -Python version, or platform information is included. When the runtime -searches for available eggs, ``.egg-link`` files are opened and the -actual egg file/directory name is read from them. - -Each ``.egg-link`` 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 ``.egg``, or else it -should be the parent directory of one or more ``.egg-info`` format eggs. - -As of setuptools 0.6c6, the path may be specified as a platform-independent -(i.e. ``/``-separated) relative path from the directory containing the -``.egg-link`` 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. - - ------------------ -Standard Metadata ------------------ - -In addition to the minimum required ``PKG-INFO`` 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. - -Most of these files and directories are generated via "egg-info -writers" during execution of the setuptools ``egg_info`` command, and -are listed in the ``egg_info.writers`` entry point group defined by -setuptools' own ``setup.py`` file. - -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 ``egg_info`` -command. It is up to project authors to document these new metadata -formats, if they create any. - - -``.txt`` File Formats -===================== - -Files described in this section that have ``.txt`` 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 ``#`` (comment symbol). (This -is the parsing format defined by the ``yield_lines()`` function of -the ``pkg_resources`` module.) - -All ``.txt`` 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 -``.ini`` format. Note that this does *not* imply that the lines within -the sections follow an ``.ini`` 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. - -Sectioned files can be parsed using the ``split_sections()`` function; -see the "Parsing Utilities" section of the ``pkg_resources`` manual for -for details. - - -Dependency Metadata -=================== - - -``requires.txt`` ----------------- - -This is a "sectioned" text file. Each section is a sequence of -"requirements", as parsed by the ``parse_requirements()`` function; -please see the ``pkg_resources`` manual for the complete requirement -parsing syntax. - -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 ``install_requires`` -keyword to ``setup()``). - -The remaining (named) sections describe the project's "extra" -requirements, as specified using the ``extras_require`` keyword to -``setup()``. The section name is the name of the optional feature, and -the section body lists that feature's dependencies. - -Note that it is not normally necessary to inspect this file directly; -``pkg_resources.Distribution`` objects have a ``requires()`` method -that can be used to obtain ``Requirement`` objects describing the -project's core and optional dependencies. - - -``setup_requires.txt`` ----------------------- - -Much like ``requires.txt`` except represents the requirements -specified by the ``setup_requires`` parameter to the Distribution. - - -``dependency_links.txt`` ------------------------- - -A list of dependency URLs, one per line, as specified using the -``dependency_links`` keyword to ``setup()``. These may be direct -download URLs, or the URLs of web pages containing direct download -links. Please see the setuptools manual for more information on -specifying this option. - - -``depends.txt`` -- Obsolete, do not create! -------------------------------------------- - -This file follows an identical format to ``requires.txt``, 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 ``setup()`` information -without overwriting an existing hand-created ``depends.txt``, if one -was already present in the project's source ``.egg-info`` directory. - - -``namespace_packages.txt`` -- Namespace Package Metadata -======================================================== - -A list of namespace package names, one per line, as supplied to the -``namespace_packages`` keyword to ``setup()``. Please see the manuals -for setuptools and ``pkg_resources`` for more information about -namespace packages. - - -``entry_points.txt`` -- "Entry Point"/Plugin Metadata -===================================================== - -This is a "sectioned" text file, whose contents encode the -``entry_points`` keyword supplied to ``setup()``. All sections are -named, as the section names specify the entry point groups in which the -corresponding section's entry points are registered. - -Each section is a sequence of "entry point" lines, each parseable using -the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources`` -manual for the complete entry point parsing syntax. - -Note that it is not necessary to parse this file directly; the -``pkg_resources`` module provides a variety of APIs to locate and load -entry points automatically. Please see the setuptools and -``pkg_resources`` manuals for details on the nature and uses of entry -points. - - -The ``scripts`` Subdirectory -============================ - -This directory is currently only created for ``.egg`` files built by -the setuptools ``bdist_egg`` command. It will contain copies of all -of the project's "traditional" scripts (i.e., those specified using the -``scripts`` keyword to ``setup()``). This is so that they can be -reconstituted when an ``.egg`` file is installed. - -The scripts are placed here using the distutils' standard -``install_scripts`` command, so any ``#!`` 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 `script wrappers`_, see the section below on -`Installation and Path Management Issues`_. - - -Zip Support Metadata -==================== - - -``native_libs.txt`` -------------------- - -A list of C extensions and other dynamic link libraries contained in -the egg, one per line. Paths are ``/``-separated and relative to the -egg's base location. - -This file is generated as part of ``bdist_egg`` processing, and as such -only appears in ``.egg`` files (and ``.egg`` 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 `Zip File Issues`_ section below for more -information on library and resource extraction from ``.egg`` files. - - -``eager_resources.txt`` ------------------------ - -A list of resource files and/or directories, one per line, as specified -via the ``eager_resources`` keyword to ``setup()``. Paths are -``/``-separated and relative to the egg's base location. - -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 ``native_libs.txt`` are extracted. Please -see the setuptools manual for details on what this feature is used for -and how it works, as well as the `Zip File Issues`_ section below. - - -``zip-safe`` and ``not-zip-safe`` ---------------------------------- - -These are zero-length files, and either one or the other should exist. -If ``zip-safe`` exists, it means that the project will work properly -when installed as an ``.egg`` zipfile, and conversely the existence of -``not-zip-safe`` means the project should not be installed as an -``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()`` -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. - -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 -``zip-safe`` or ``not-zip-safe`` file.) - -Note that these flag files appear only in ``.egg`` files generated by -``bdist_egg``, and in ``.egg`` directories created by unpacking such an -``.egg`` file. - - - -``top_level.txt`` -- Conflict Management Metadata -================================================= - -This file is a list of the top-level module or package names provided -by the project, one Python identifier per line. - -Subpackages are not included; a project containing both a ``foo.bar`` -and a ``foo.baz`` would include only one line, ``foo``, in its -``top_level.txt``. - -This data is used by ``pkg_resources`` at runtime to issue a warning if -an egg is added to ``sys.path`` when its contained packages may have -already been imported. - -(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.) - - -``SOURCES.txt`` -- Source Files Manifest -======================================== - -This file is roughly equivalent to the distutils' ``MANIFEST`` file. -The differences are as follows: - -* The filenames always use ``/`` as a path separator, which must be - converted back to a platform-specific path whenever they are read. - -* The file is automatically generated by setuptools whenever the - ``egg_info`` or ``sdist`` commands are run, and it is *not* - user-editable. - -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 *source* 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. - -In other words, ``SOURCES.txt`` has little or no runtime value for being -included in distributed eggs, and it is possible that future versions of -the ``bdist_egg`` and ``install_egg_info`` 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. - - ------------------------------- -Other Technical Considerations ------------------------------- - - -Zip File Issues -=============== - -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 ``.egg`` 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. - -To address these issues, the ``pkg_resources`` 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. - -The cache directory is determined by the ``pkg_resources`` API; please -see the ``set_cache_path()`` and ``get_default_cache()`` documentation -for details. - - -The Extraction Process ----------------------- - -Resources are extracted to a cache subdirectory whose name is based -on the enclosing ``.egg`` 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 -``mkstemp(".$extract",target_dir)``, 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.) - -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. - -If the resource requested for extraction is listed in the -``native_libs.txt`` or ``eager_resources.txt`` metadata files, then -*all* resources listed in *either* 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. - - -Extension Import Wrappers -------------------------- - -Since Python's built-in zip import feature does not support loading -C extension modules from zipfiles, the setuptools ``bdist_egg`` command -generates special import wrappers to make it work. - -The wrappers are ``.py`` files (along with corresponding ``.pyc`` -and/or ``.pyo`` 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, ``foomodule.so`` will get a corresponding ``foo.py``, while -``bar/baz.pyd`` will get a corresponding ``bar/baz.py``. - -These wrapper files contain a short stanza of Python code that asks -``pkg_resources`` for the filename of the corresponding C extension, -then reloads the module using the obtained filename. This will cause -``pkg_resources`` 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. - -Note, by the way, that ``.egg`` 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. - - -Installation and Path Management Issues -======================================= - -Python's initial setup of ``sys.path`` is very dependent on the Python -version and installation platform, as well as how Python was started -(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter). -In fact, Python also provides only two relatively robust ways to affect -``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH`` -environment variable, and ``.pth`` files. - -However, with no cross-platform way to safely and persistently change -environment variables, this leaves ``.pth`` files as EasyInstall's only -real option for persistent configuration of ``sys.path``. - -But ``.pth`` files are rather strictly limited in what they are allowed -to do normally. They add directories only to the *end* of ``sys.path``, -after any locally-installed ``site-packages`` directory, and they are -only processed *in* the ``site-packages`` directory to start with. - -This is a double whammy for users who lack write access to that -directory, because they can't create a ``.pth`` file that Python will -read, and even if a sympathetic system administrator adds one for them -that calls ``site.addsitedir()`` to allow some other directory to -contain ``.pth`` files, they won't be able to install newer versions of -anything that's installed in the systemwide ``site-packages``, because -their paths will still be added *after* ``site-packages``. - -So EasyInstall applies two workarounds to solve these problems. - -The first is that EasyInstall leverages ``.pth`` files' "import" feature -to manipulate ``sys.path`` and ensure that anything EasyInstall adds -to a ``.pth`` file will always appear before both the standard library -and the local ``site-packages`` directories. Thus, it is always -possible for a user who can write a Python-read ``.pth`` file to ensure -that their packages come first in their own environment. - -Second, when installing to a ``PYTHONPATH`` directory (as opposed to -a "site" directory like ``site-packages``) EasyInstall will also install -a special version of the ``site`` module. Because it's in a -``PYTHONPATH`` directory, this module will get control before the -standard library version of ``site`` does. It will record the state of -``sys.path`` before invoking the "real" ``site`` module, and then -afterwards it processes any ``.pth`` files found in ``PYTHONPATH`` -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 ``PYTHONPATH`` and -``.pth``-prescribed sequence. - -The net result of these changes is that ``sys.path`` order will be -as follows at runtime: - -1. The ``sys.argv[0]`` directory, or an empty string if no script - is being executed. - -2. All eggs installed by EasyInstall in any ``.pth`` file in each - ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order, - then normal ``.pth`` processing order (which is to say alphabetical - by ``.pth`` filename, then by the order of listing within each - ``.pth`` file). - -3. All eggs installed by EasyInstall in any ``.pth`` file in each "site" - directory (such as ``site-packages``), following the same ordering - rules as for the ones on ``PYTHONPATH``. - -4. The ``PYTHONPATH`` directories themselves, in their original order - -5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not* - eggs installed by EasyInstall, again following the same relative - ordering rules. - -6. The standard library and "site" directories, along with the contents - of any ``.pth`` files found in the "site" directories. - -Notice that sections 1, 4, and 6 comprise the "normal" Python setup for -``sys.path``. Sections 2 and 3 are inserted to support eggs, and -section 5 emulates what the "normal" semantics of ``.pth`` files on -``PYTHONPATH`` would be if Python natively supported them. - -For further discussion of the tradeoffs that went into this design, as -well as notes on the actual magic inserted into ``.pth`` files to make -them do these things, please see also the following messages to the -distutils-SIG mailing list: - -* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html -* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html - - -Script Wrappers ---------------- - -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. - -The format of this marker line is:: - - "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n" - -The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or -``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated -sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT`` -wrappers, there are two strings: the project version requirement, and -the script name (as a filename within the ``scripts`` metadata -directory). For ``ENTRY-SCRIPT`` 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.) - -In each case, the project version requirement string will be a string -parseable with the ``pkg_resources`` modules' ``Requirement.parse()`` -classmethod. The only difference between a ``SCRIPT`` wrapper and a -``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original -source script in the project's source tree, and is created when the -"setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other -hand, uses the "installed" script written to the ``EGG-INFO/scripts`` -subdirectory of the corresponding ``.egg`` zipfile or directory. -(``.egg-info`` eggs do not have script wrappers associated with them, -except in the "setup.py develop" case.) - -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. - diff --git a/docs/python_eggs.txt b/docs/python_eggs.txt new file mode 100644 index 00000000..6c0456de --- /dev/null +++ b/docs/python_eggs.txt @@ -0,0 +1,679 @@ +===================================== +The Internal Structure of Python Eggs +===================================== + +STOP! This is not the first document you should read! + + + +.. contents:: **Table of Contents** + + +---------------------- +Eggs and their Formats +---------------------- + +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. + +There are two basic formats currently implemented for Python eggs: + +1. ``.egg`` format: a directory or zipfile *containing* the project's + code and resources, along with an ``EGG-INFO`` subdirectory that + contains the project's metadata + +2. ``.egg-info`` format: a file or directory placed *adjacent* to the + project's code and resources, that directly contains the project's + metadata. + +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. + +The ``.egg`` 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. + +The ``.egg-info`` 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. ``site-packages``). Placing the metadata +in that same directory simplifies the installation process, since it +isn't necessary to create ``.pth`` files or otherwise modify +``sys.path`` to include each installed egg. + +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 ``.egg`` files or directories to a target +location, but it cannot do this for ``.egg-info`` 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 ``.egg-info`` format does not currently +include a way to list the files that were installed. (This may change +in a future version.) + + +Code and Resources +================== + +The layout of the code and resources is dictated by Python's normal +import layout, relative to the egg's "base location". + +For the ``.egg`` format, the base location is the ``.egg`` itself. That +is, adding the ``.egg`` filename or directory name to ``sys.path`` +makes its contents importable. + +For the ``.egg-info`` format, however, the base location is the +directory that *contains* the ``.egg-info``, and thus it is the +directory that must be added to ``sys.path`` to make the egg importable. +(Note that this means that the "normal" installation of a package to a +``sys.path`` directory is sufficient to make it an "egg" if it has an +``.egg-info`` file or directory installed alongside of it.) + + +Project Metadata +================= + +If eggs contained only code and resources, there would of course be +no difference between them and any other directory or zip file on +``sys.path``. Thus, metadata must also be included, using a metadata +file or directory. + +For the ``.egg`` format, the metadata is placed in an ``EGG-INFO`` +subdirectory, directly within the ``.egg`` file or directory. For the +``.egg-info`` format, metadata is stored directly within the +``.egg-info`` directory itself. + +The minimum project metadata that all eggs must have is a standard +Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the +metadata directory appropriate to the format. Because it's possible for +this to be the only metadata file included, ``.egg-info`` format eggs +are not required to be a directory; they can just be a ``.egg-info`` +file that directly contains the ``PKG-INFO`` metadata. This eliminates +the need to create a directory just to store one file. This option is +*not* available for ``.egg`` formats, since setuptools always includes +other metadata. (In fact, setuptools itself never generates +``.egg-info`` files, either; the support for using files was added so +that the requirement could easily be satisfied by other tools, such +as distutils). + +In addition to the ``PKG-INFO`` file, an egg's metadata directory may +also include files and directories representing various forms of +optional standard metadata (see the section on `Standard Metadata`_, +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. + + +Filename-Embedded Metadata +========================== + +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:: + + name ["-" version ["-py" pyver ["-" required_platform]]] "." ext + +The "name" and "version" should be escaped using the ``to_filename()`` +function provided by ``pkg_resources``, after first processing them with +``safe_name()`` and ``safe_version()`` 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 ``pkg_resources`` manual.) + +The "pyver" string is the Python major version, as found in the first +3 characters of ``sys.version``. "required_platform" is essentially +a distutils ``get_platform()`` string, but with enhancements to properly +distinguish Mac OS versions. (See the ``get_build_platform()`` +documentation in the "Platform Utilities" section of the +``pkg_resources`` manual for more details.) + +Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate +for the egg's format. + +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. + +Setuptools, however, only includes the version number in the filename +when an ``.egg`` file is built using the ``bdist_egg`` command, or when +an ``.egg-info`` directory is being installed by the +``install_egg_info`` 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. + +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.) + + +Egg Links +========= + +In addition to the ``.egg`` and ``.egg-info`` formats, there is a third +egg-related extension that you may encounter on occasion: ``.egg-link`` +files. + +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 ``.egg-link`` file in ``/path/to/app/plugins``, that +tells the egg runtime system where to find the actual egg (the user's +project source directory and its ``.egg-info`` subdirectory). + +``.egg-link`` files are named following the format for ``.egg`` and +``.egg-info`` names, but only the project name is included; no version, +Python version, or platform information is included. When the runtime +searches for available eggs, ``.egg-link`` files are opened and the +actual egg file/directory name is read from them. + +Each ``.egg-link`` 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 ``.egg``, or else it +should be the parent directory of one or more ``.egg-info`` format eggs. + +As of setuptools 0.6c6, the path may be specified as a platform-independent +(i.e. ``/``-separated) relative path from the directory containing the +``.egg-link`` 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. + + +----------------- +Standard Metadata +----------------- + +In addition to the minimum required ``PKG-INFO`` 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. + +Most of these files and directories are generated via "egg-info +writers" during execution of the setuptools ``egg_info`` command, and +are listed in the ``egg_info.writers`` entry point group defined by +setuptools' own ``setup.py`` file. + +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 ``egg_info`` +command. It is up to project authors to document these new metadata +formats, if they create any. + + +``.txt`` File Formats +===================== + +Files described in this section that have ``.txt`` 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 ``#`` (comment symbol). (This +is the parsing format defined by the ``yield_lines()`` function of +the ``pkg_resources`` module.) + +All ``.txt`` 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 +``.ini`` format. Note that this does *not* imply that the lines within +the sections follow an ``.ini`` 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. + +Sectioned files can be parsed using the ``split_sections()`` function; +see the "Parsing Utilities" section of the ``pkg_resources`` manual for +for details. + + +Dependency Metadata +=================== + + +``requires.txt`` +---------------- + +This is a "sectioned" text file. Each section is a sequence of +"requirements", as parsed by the ``parse_requirements()`` function; +please see the ``pkg_resources`` manual for the complete requirement +parsing syntax. + +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 ``install_requires`` +keyword to ``setup()``). + +The remaining (named) sections describe the project's "extra" +requirements, as specified using the ``extras_require`` keyword to +``setup()``. The section name is the name of the optional feature, and +the section body lists that feature's dependencies. + +Note that it is not normally necessary to inspect this file directly; +``pkg_resources.Distribution`` objects have a ``requires()`` method +that can be used to obtain ``Requirement`` objects describing the +project's core and optional dependencies. + + +``setup_requires.txt`` +---------------------- + +Much like ``requires.txt`` except represents the requirements +specified by the ``setup_requires`` parameter to the Distribution. + + +``dependency_links.txt`` +------------------------ + +A list of dependency URLs, one per line, as specified using the +``dependency_links`` keyword to ``setup()``. These may be direct +download URLs, or the URLs of web pages containing direct download +links. Please see the setuptools manual for more information on +specifying this option. + + +``depends.txt`` -- Obsolete, do not create! +------------------------------------------- + +This file follows an identical format to ``requires.txt``, 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 ``setup()`` information +without overwriting an existing hand-created ``depends.txt``, if one +was already present in the project's source ``.egg-info`` directory. + + +``namespace_packages.txt`` -- Namespace Package Metadata +======================================================== + +A list of namespace package names, one per line, as supplied to the +``namespace_packages`` keyword to ``setup()``. Please see the manuals +for setuptools and ``pkg_resources`` for more information about +namespace packages. + + +``entry_points.txt`` -- "Entry Point"/Plugin Metadata +===================================================== + +This is a "sectioned" text file, whose contents encode the +``entry_points`` keyword supplied to ``setup()``. All sections are +named, as the section names specify the entry point groups in which the +corresponding section's entry points are registered. + +Each section is a sequence of "entry point" lines, each parseable using +the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources`` +manual for the complete entry point parsing syntax. + +Note that it is not necessary to parse this file directly; the +``pkg_resources`` module provides a variety of APIs to locate and load +entry points automatically. Please see the setuptools and +``pkg_resources`` manuals for details on the nature and uses of entry +points. + + +The ``scripts`` Subdirectory +============================ + +This directory is currently only created for ``.egg`` files built by +the setuptools ``bdist_egg`` command. It will contain copies of all +of the project's "traditional" scripts (i.e., those specified using the +``scripts`` keyword to ``setup()``). This is so that they can be +reconstituted when an ``.egg`` file is installed. + +The scripts are placed here using the distutils' standard +``install_scripts`` command, so any ``#!`` 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 `script wrappers`_, see the section below on +`Installation and Path Management Issues`_. + + +Zip Support Metadata +==================== + + +``native_libs.txt`` +------------------- + +A list of C extensions and other dynamic link libraries contained in +the egg, one per line. Paths are ``/``-separated and relative to the +egg's base location. + +This file is generated as part of ``bdist_egg`` processing, and as such +only appears in ``.egg`` files (and ``.egg`` 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 `Zip File Issues`_ section below for more +information on library and resource extraction from ``.egg`` files. + + +``eager_resources.txt`` +----------------------- + +A list of resource files and/or directories, one per line, as specified +via the ``eager_resources`` keyword to ``setup()``. Paths are +``/``-separated and relative to the egg's base location. + +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 ``native_libs.txt`` are extracted. Please +see the setuptools manual for details on what this feature is used for +and how it works, as well as the `Zip File Issues`_ section below. + + +``zip-safe`` and ``not-zip-safe`` +--------------------------------- + +These are zero-length files, and either one or the other should exist. +If ``zip-safe`` exists, it means that the project will work properly +when installed as an ``.egg`` zipfile, and conversely the existence of +``not-zip-safe`` means the project should not be installed as an +``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()`` +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. + +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 +``zip-safe`` or ``not-zip-safe`` file.) + +Note that these flag files appear only in ``.egg`` files generated by +``bdist_egg``, and in ``.egg`` directories created by unpacking such an +``.egg`` file. + + + +``top_level.txt`` -- Conflict Management Metadata +================================================= + +This file is a list of the top-level module or package names provided +by the project, one Python identifier per line. + +Subpackages are not included; a project containing both a ``foo.bar`` +and a ``foo.baz`` would include only one line, ``foo``, in its +``top_level.txt``. + +This data is used by ``pkg_resources`` at runtime to issue a warning if +an egg is added to ``sys.path`` when its contained packages may have +already been imported. + +(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.) + + +``SOURCES.txt`` -- Source Files Manifest +======================================== + +This file is roughly equivalent to the distutils' ``MANIFEST`` file. +The differences are as follows: + +* The filenames always use ``/`` as a path separator, which must be + converted back to a platform-specific path whenever they are read. + +* The file is automatically generated by setuptools whenever the + ``egg_info`` or ``sdist`` commands are run, and it is *not* + user-editable. + +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 *source* 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. + +In other words, ``SOURCES.txt`` has little or no runtime value for being +included in distributed eggs, and it is possible that future versions of +the ``bdist_egg`` and ``install_egg_info`` 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. + + +------------------------------ +Other Technical Considerations +------------------------------ + + +Zip File Issues +=============== + +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 ``.egg`` 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. + +To address these issues, the ``pkg_resources`` 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. + +The cache directory is determined by the ``pkg_resources`` API; please +see the ``set_cache_path()`` and ``get_default_cache()`` documentation +for details. + + +The Extraction Process +---------------------- + +Resources are extracted to a cache subdirectory whose name is based +on the enclosing ``.egg`` 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 +``mkstemp(".$extract",target_dir)``, 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.) + +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. + +If the resource requested for extraction is listed in the +``native_libs.txt`` or ``eager_resources.txt`` metadata files, then +*all* resources listed in *either* 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. + + +Extension Import Wrappers +------------------------- + +Since Python's built-in zip import feature does not support loading +C extension modules from zipfiles, the setuptools ``bdist_egg`` command +generates special import wrappers to make it work. + +The wrappers are ``.py`` files (along with corresponding ``.pyc`` +and/or ``.pyo`` 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, ``foomodule.so`` will get a corresponding ``foo.py``, while +``bar/baz.pyd`` will get a corresponding ``bar/baz.py``. + +These wrapper files contain a short stanza of Python code that asks +``pkg_resources`` for the filename of the corresponding C extension, +then reloads the module using the obtained filename. This will cause +``pkg_resources`` 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. + +Note, by the way, that ``.egg`` 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. + + +Installation and Path Management Issues +======================================= + +Python's initial setup of ``sys.path`` is very dependent on the Python +version and installation platform, as well as how Python was started +(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter). +In fact, Python also provides only two relatively robust ways to affect +``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH`` +environment variable, and ``.pth`` files. + +However, with no cross-platform way to safely and persistently change +environment variables, this leaves ``.pth`` files as EasyInstall's only +real option for persistent configuration of ``sys.path``. + +But ``.pth`` files are rather strictly limited in what they are allowed +to do normally. They add directories only to the *end* of ``sys.path``, +after any locally-installed ``site-packages`` directory, and they are +only processed *in* the ``site-packages`` directory to start with. + +This is a double whammy for users who lack write access to that +directory, because they can't create a ``.pth`` file that Python will +read, and even if a sympathetic system administrator adds one for them +that calls ``site.addsitedir()`` to allow some other directory to +contain ``.pth`` files, they won't be able to install newer versions of +anything that's installed in the systemwide ``site-packages``, because +their paths will still be added *after* ``site-packages``. + +So EasyInstall applies two workarounds to solve these problems. + +The first is that EasyInstall leverages ``.pth`` files' "import" feature +to manipulate ``sys.path`` and ensure that anything EasyInstall adds +to a ``.pth`` file will always appear before both the standard library +and the local ``site-packages`` directories. Thus, it is always +possible for a user who can write a Python-read ``.pth`` file to ensure +that their packages come first in their own environment. + +Second, when installing to a ``PYTHONPATH`` directory (as opposed to +a "site" directory like ``site-packages``) EasyInstall will also install +a special version of the ``site`` module. Because it's in a +``PYTHONPATH`` directory, this module will get control before the +standard library version of ``site`` does. It will record the state of +``sys.path`` before invoking the "real" ``site`` module, and then +afterwards it processes any ``.pth`` files found in ``PYTHONPATH`` +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 ``PYTHONPATH`` and +``.pth``-prescribed sequence. + +The net result of these changes is that ``sys.path`` order will be +as follows at runtime: + +1. The ``sys.argv[0]`` directory, or an empty string if no script + is being executed. + +2. All eggs installed by EasyInstall in any ``.pth`` file in each + ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order, + then normal ``.pth`` processing order (which is to say alphabetical + by ``.pth`` filename, then by the order of listing within each + ``.pth`` file). + +3. All eggs installed by EasyInstall in any ``.pth`` file in each "site" + directory (such as ``site-packages``), following the same ordering + rules as for the ones on ``PYTHONPATH``. + +4. The ``PYTHONPATH`` directories themselves, in their original order + +5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not* + eggs installed by EasyInstall, again following the same relative + ordering rules. + +6. The standard library and "site" directories, along with the contents + of any ``.pth`` files found in the "site" directories. + +Notice that sections 1, 4, and 6 comprise the "normal" Python setup for +``sys.path``. Sections 2 and 3 are inserted to support eggs, and +section 5 emulates what the "normal" semantics of ``.pth`` files on +``PYTHONPATH`` would be if Python natively supported them. + +For further discussion of the tradeoffs that went into this design, as +well as notes on the actual magic inserted into ``.pth`` files to make +them do these things, please see also the following messages to the +distutils-SIG mailing list: + +* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html +* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html + + +Script Wrappers +--------------- + +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. + +The format of this marker line is:: + + "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n" + +The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or +``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated +sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT`` +wrappers, there are two strings: the project version requirement, and +the script name (as a filename within the ``scripts`` metadata +directory). For ``ENTRY-SCRIPT`` 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.) + +In each case, the project version requirement string will be a string +parseable with the ``pkg_resources`` modules' ``Requirement.parse()`` +classmethod. The only difference between a ``SCRIPT`` wrapper and a +``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original +source script in the project's source tree, and is created when the +"setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other +hand, uses the "installed" script written to the ``EGG-INFO/scripts`` +subdirectory of the corresponding ``.egg`` zipfile or directory. +(``.egg-info`` eggs do not have script wrappers associated with them, +except in the "setup.py develop" case.) + +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. + -- cgit v1.2.1