diff --git a/pep-0376.txt b/pep-0376.txt index a67a05cf1..ac68c6952 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -17,22 +17,33 @@ Abstract This PEP proposes various enhancements for Distutils: - A new format for the .egg-info structure. -- Some APIs to read the meta-data of a project +- Some APIs to read the meta-data of a distribution - A replacement PEP 262 - An uninstall feature Definitions =========== -A **project** is a distribution of one or several files, which can be Python -modules, extensions or data. It is distributed using a `setup.py` script -with Distutils and/or Setuptools. The `setup.py` script indicates where each -elements should be installed. +A **distribution** is a collection of files, which can be Python modules, +extensions or data. A distribution is managed by a special module called +`setup.py` which contains a call to the `distutils.core.setup` function. +The arguments passed to that function describe the distribution, like +its `name`, its `version`, and so on. + +Disutils provides among other things **commands** that can be called +through the shell using the `setup.py` script. A `sdist` command is provided +for instance, to create a source distribution archive. An `install` command +is also provided, to perform an installation of the distribution in the Python +installation the script is invoked with:: + + $ python setup.py install + +See the Distutils [distutils]_ documentation for more information. Once installed, the elements are located in various places in the system, like: -- in Python's site-packages (Python modules, Python modules organized into packages, - Extensions, etc.) +- in Python's site-packages (Python modules, Python modules organized into + packages, Extensions, etc.) - in Python's `include` directory. - in Python's `bin` or `Script` directory. - etc. @@ -40,15 +51,16 @@ Once installed, the elements are located in various places in the system, like: Rationale ========= -There are two problems right now in the way projects are installed in Python: +There are two problems right now in the way distributions are installed in +Python: - There are too many ways to do it. -- There is no API to get the metadata of installed projects. +- There is no API to get the metadata of installed distributions. -How projects are installed --------------------------- +How distributions are installed +------------------------------- -Right now, when a project is installed in Python, every elements its contains +Right now, when a distribution is installed in Python, every elements its contains is installed in various directories. The pure Python code for instance is installed in the `purelib` directory, @@ -60,14 +72,14 @@ various subcommands. The `install_egg_info` subcommand is called during this process, in order to create an `.egg-info` file in the `purelib` directory. -For example, if the `zlib` project (which contains one package) is installed, -two elements will be installed in `site-packages`:: +For example, if the `zlib` distribution (which contains one package) is +installed, two elements will be installed in `site-packages`:: - zlib - zlib-2.5.2-py2.4.egg-info Where `zlib` is a Python package, and `zlib-2.5.2-py2.4.egg-info` is -a file containing the project metadata as described in PEP 314 [#pep314]_. +a file containing the distribution metadata as described in PEP 314 [#pep314]_. This file corresponds to the file called `PKG-INFO`, built by the `sdist` command. @@ -78,12 +90,12 @@ install packages in the same way that Distutils does: - `easy_install` creates an `EGG-INFO` directory inside an `.egg` directory, and adds a `PKG-INFO` file inside this directory. The `.egg` directory - contains in that case all the elements of the project that are supposed to - be installed in `site-packages`, and is placed in the `site-packages` + contains in that case all the elements of the distribution that are supposed + to be installed in `site-packages`, and is placed in the `site-packages` directory. - `pip` creates an `.egg-info` directory inside the `site-packages` directory - and adds a `PKG-INFO` file inside it. Elements of the project are then + and adds a `PKG-INFO` file inside it. Elements of the distribution are then installed in various places like Distutils does. They both add other files in the `EGG-INFO` or `.egg-info` directory, and @@ -93,17 +105,18 @@ Uninstall information --------------------- Distutils doesn't provide any `uninstall` command. If you want to uninstall -a project, you have to be a power user and remove the various elements that -were installed. Then look over the `.pth` file to clean them if necessary. +a distribution, you have to be a power user and remove the various elements +that were installed. Then look over the `.pth` file to clean them if necessary. And the process differs, depending on the tools you have used to install the -project, and if the project's `setup.py` uses Distutils or Setuptools. +distribution, and if the distribution's `setup.py` uses Distutils or +Setuptools. Under some circumstances, you might not be able to know for sure that you -have removed everything, or that you didn't break another project by -removing a file that was shared among several projects. +have removed everything, or that you didn't break another distribution by +removing a file that was shared among several distributions. -But there's common behavior: when you install a project, files are copied +But there's common behavior: when you install a distribution, files are copied in your system. And there's a way to keep track of theses files, so to remove them. @@ -115,7 +128,7 @@ To address those issues, this PEP proposes a few changes: - a new `.egg-info` structure using a directory, based on one form of the `EggFormats` standard from `setuptools` [#eggformats]_. - new APIs in `pkgutil` to be able to query the information of installed - projects. + distributions. - a de-facto replacement for PEP 262 - an uninstall function in Distutils. @@ -131,7 +144,7 @@ Notice that this change is based on the standard proposed by `EggFormats`. Although, this standard proposes two ways to install files : - a self-contained directory that can be zipped or left unzipped and that - contains the project files *and* the `.egg-info` directory. + contains the distribution files *and* the `.egg-info` directory. - a distinct `.egg-info` directory located in the site-packages directory. @@ -259,9 +272,9 @@ lower-case string matching `[a-z0-9_\-\.]`. It will default to `distutils` if not provided. -When a project is installed, the INSTALLER file is generated in the +When a distribution 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. +distribution. The file is a single-line text file. New APIs in pkgutil =================== @@ -269,7 +282,9 @@ New APIs in pkgutil To use the `.egg-info` directory content, we need to add in the standard library a set of APIs. The best place to put these APIs seems to be `pkgutil`. -The API is organized in five classes: +The API is organized in five classes that work with directories and Zip files +(so its works with files included in Zip files, see PEP 273 for more details +[pep273]_. - ``Distribution``: manages an `.egg-info` directory. - ``ZippedDistribution``: manages an `.egg-info` directory contained in a zip @@ -280,8 +295,6 @@ The API is organized in five classes: some `.egg.info` directory. - ``DistributionDirectories``: manages ``EggInfoDirectory`` instances. -XXX mention PEP 273 - Distribution class ------------------ @@ -412,16 +425,16 @@ from ``dict``:: Iterates over all ``Distribution`` and ``ZippedDistribution`` contained in ``DistributionDirectory`` and ``ZippedDistributionDirectory`` instances. -- ``get_distribution(project_name)`` -> ``Distribution`` (or +- ``get_distribution(dist_name)`` -> ``Distribution`` (or ``ZippedDistribution``) or None. Returns a ``Distribution`` (or ``ZippedDistribution``) instance for the - given project name. If not found, returns None. + given distribution name. If not found, returns None. - ``get_file_users(path)`` -> Iterator of ``Distribution`` (or ``ZippedDistribution``) instances. - Iterates over all projects to find out which project uses the file. + Iterates over all distributions to find out which distributions use the file. Returns ``Distribution`` (or ``ZippedDistribution``) instances. .egg-info functions @@ -450,7 +463,7 @@ The new functions added in the ``pkgutil`` are : - ``get_file_users(path)`` -> iterator of ``Distribution`` (or ``ZippedDistribution``) instances. - Iterates over all projects to find out which project uses ``path``. + Iterates over all distributions to find out which distributions uses ``path``. ``path`` can be a local absolute path or a relative '/'-separated path. All these functions use the same global instance of ``DistributionDirectories`` @@ -507,12 +520,13 @@ standard and will fullfill the requirements described in PEP 262, like the Adding an Uninstall function ============================ -Distutils already provides a very basic way to install a project, which is running -the `install` command over the `setup.py` script of the distribution. +Distutils already provides a very basic way to install a distribution, which +is running the `install` command over the `setup.py` script of the +distribution. Distutils will provide a very basic ``uninstall`` function, that will be added -in ``distutils.util`` and will take the name of the project to uninstall as -its argument. ``uninstall`` will use the APIs desribed earlier and remove all +in ``distutils.util`` and will take the name of the distribution to uninstall +as its argument. ``uninstall`` will use the APIs desribed earlier and remove all unique files, as long as their hash didn't change. Then it will remove empty directories left behind. @@ -523,7 +537,7 @@ empty directories left behind. ['/opt/local/lib/python2.6/site-packages/zlib/file1', '/opt/local/lib/python2.6/site-packages/zlib/file2'] -If the project is not found, a ``DistutilsUninstallError`` will be raised. +If the distribution is not found, a ``DistutilsUninstallError`` will be raised. Filtering --------- @@ -556,7 +570,7 @@ 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, +To avoid removing distributions that where installed by another packaging system, the ``uninstall`` function takes an extra argument ``installer`` which default to ``distutils``. @@ -571,7 +585,7 @@ this argument. If not, it will raise a ``DistutilsUninstallError``:: >>> 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 +and make sure it's the only program that can remove a distribution 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. @@ -605,6 +619,12 @@ References .. [#eggformats] http://peak.telecommunity.com/DevCenter/EggFormats +.. [#pep273] + http://www.python.org/dev/peps/pep-0273 + +.. [distutils] + http://docs.python.org/distutils + Aknowledgments ==============