[Python-checkins] r73239 - peps/trunk/pep-0376.txt

[tarek.ziade]

Author: tarek.ziade
Date: Fri Jun  5 10:35:30 2009
New Revision: 73239

Log:
added the installer marker + more details from feedback

Modified:
   peps/trunk/pep-0376.txt

Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt	(original)
+++ peps/trunk/pep-0376.txt	Fri Jun  5 10:35:30 2009
@@ -174,8 +174,15 @@
 A `RECORD` file will be added inside the `.egg-info` directory at installation
 time. The `RECORD` file will hold the list of installed files. These correspond
 to the files listed by the `record` option of the `install` command, and will
-always be generated. This will allow uninstallation, as explained later in this
-PEP. This RECORD file is inspired from PEP 262 FILES [#pep262]_.
+be generated by default. This will allow uninstallation, as explained later in this
+PEP. The `install` command will also provide an option to prevent the `RECORD`
+file from being written and this option should be used when creating system 
+packages.
+
+Third-party installation tools also should not overwrite or delete files
+that are not in a RECORD file without prompting or warning.
+
+This RECORD file is inspired from PEP 262 FILES [#pep262]_.
 
 The RECORD format
 -----------------
@@ -227,6 +234,21 @@
 - `zlib` and `zlib-2.5.2.egg-info` are located in `site-packages` so the file
   paths are relative to it.
 
+Adding an INSTALLER file in the .egg-info directory
+===================================================
+
+The `install` command will have a new option called `installer`. This option
+is the name of the tool used to invoke the installation. It's an normalized
+lower-case string matching `[a-z0-9_\-\.]`. 
+
+    $ python setup.py install --installer=pkg-system
+
+It will default to `distutils` if not provided.
+
+When a project is installed, the INSTALLER file is generated in the 
+`.egg-info` directory with this value, to keep track of **who** installed the 
+project. The file is a single-line text file.
+
 New APIs in pkgutil
 ===================
 
@@ -453,6 +475,9 @@
 
 If the project is not found, a ``DistutilsUninstallError`` will be raised.
 
+Filtering
+---------
+
 To make it a reference API for third-party projects that wish to control
 how `uninstall` works, a second callable argument can be used. It will be
 called for each file that is removed. If the callable returns `True`, the
@@ -475,6 +500,32 @@
 Of course, a third-party tool can use ``pkgutil`` APIs to implement
 its own uninstall feature.
 
+Installer marker
+----------------
+
+As explained earlier in this PEP, the `install` command adds an `INSTALLER`
+file in the `.egg-info` directory with the name of the installer.
+
+To avoid removing projects that where installed by another packaging system,
+the ``uninstall`` function takes an extra argument ``installer`` which default
+to ``distutils``.
+
+When called, ``uninstall`` will control that the ``INSTALLER`` file matches 
+this argument. If not, it will raise a ``DistutilsUninstallError``::
+
+    >>> uninstall('zlib')
+    Traceback (most recent call last):
+    ...
+    DistutilsUninstallError: zlib was installed by 'cool-pkg-manager'
+
+    >>> uninstall('zlib', installer='cool-pkg-manager')
+
+This allows a third-party application to use the ``uninstall`` function 
+and make sure it's the only program that can remove a project it has
+previously installed. This is useful when a third-party program that relies
+on Distutils APIs does extra steps on the system at installation time,
+it has to undo at uninstallation time.
+
 Backward compatibility and roadmap
 ==================================