[Python-checkins] r73504 - peps/trunk/pep-0376.txt
tarek.ziade
python-checkins at python.org
Mon Jun 22 15:06:56 CEST 2009
Author: tarek.ziade
Date: Mon Jun 22 15:06:55 2009
New Revision: 73504
Log:
renamed project to distribution
Modified:
peps/trunk/pep-0376.txt
Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt (original)
+++ peps/trunk/pep-0376.txt Mon Jun 22 15:06:55 2009
@@ -17,22 +17,33 @@
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 @@
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 @@
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 @@
- `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 @@
---------------------
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 @@
- 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 @@
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 @@
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 @@
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 @@
some `.egg.info` directory.
- ``DistributionDirectories``: manages ``EggInfoDirectory`` instances.
-XXX mention PEP 273
-
Distribution class
------------------
@@ -412,16 +425,16 @@
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 @@
- ``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 @@
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 @@
['/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 @@
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 @@
>>> 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 @@
.. [#eggformats]
http://peak.telecommunity.com/DevCenter/EggFormats
+.. [#pep273]
+ http://www.python.org/dev/peps/pep-0273
+
+.. [distutils]
+ http://docs.python.org/distutils
+
Aknowledgments
==============
More information about the Python-checkins
mailing list