diff --git a/pep-0376.txt b/pep-0376.txt index 2afb63905..75b7222a2 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -174,8 +174,15 @@ Adding a RECORD file in the .egg-info directory 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 @@ Notice that: - `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 @@ empty directories left behind. 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 @@ Examples:: 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 ==================================