[Python-checkins] r45720 - sandbox/trunk/setuptools/doc/formats.txt

phillip.eby python-checkins at python.org
Wed Apr 26 02:10:54 CEST 2006


Author: phillip.eby
Date: Wed Apr 26 02:10:53 2006
New Revision: 45720

Modified:
   sandbox/trunk/setuptools/doc/formats.txt
Log:
Forgot to document script wrappers


Modified: sandbox/trunk/setuptools/doc/formats.txt
==============================================================================
--- sandbox/trunk/setuptools/doc/formats.txt	(original)
+++ sandbox/trunk/setuptools/doc/formats.txt	Wed Apr 26 02:10:53 2006
@@ -152,7 +152,7 @@
 platform if platform-specific C code is included.  The syntax of an
 egg filename is as follows::
 
-    name [ "-" version [ "-py" pyver [ "-" required_platform]]] "." ext
+    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
@@ -368,7 +368,7 @@
 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
+depends on.  For more about `script wrappers`_, see the section below on
 `Installation and Path Management Issues`_.
 
 
@@ -643,3 +643,47 @@
 * 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.
+


More information about the Python-checkins mailing list