From f464bd118bbc5bcc851bcc61d3e74a4b17bfb5a4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 28 Feb 2009 14:22:01 +0000 Subject: [PATCH] Fix a few formal and grammatical issues. --- pep-0376.txt | 57 +++++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/pep-0376.txt b/pep-0376.txt index 80bddece5..ef559a19f 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -10,7 +10,6 @@ Created: 22-Feb-2009 Python-Version: 2.7, 3.1 Post-History: -.. contents:: Abstract ======== @@ -21,19 +20,18 @@ This PEP proposes various enhancements for Distutils: - An install script to install a package in Python. - An uninstall script to uninstall a package in Python. + Rationale ========= There are three problems right now in the way packages are installed in Python: -- There are too many ways to install a package in - Python. +- There are too many ways to install a package in Python. - There is no way to uninstall a package. -- There is no API to get the metadata of installed - packages. +- There is no API to get the metadata of installed packages. How packages are installed -------------------------- @@ -56,14 +54,14 @@ This file corresponds to the file called `PKG-INFO`, built by the `sdist` command. The problem is that many people use `easy_install` (setuptools) or `pip` -to install their packages. And these third-party tool does not install -the packages the same way Distutils does. +to install their packages, and these third-party tools do not 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, amongst other files. - `pip` creates an `.egg-info` directory inside the site-packages directory - besides the package, and adds an `PKG-INFO` file inside it. + besides the package, and adds a `PKG-INFO` file inside it. They both add other files in the `EGG-INFO` or `.egg-info` directory, and create or modify `.pth` files. `pip` also creates one `.pth` file @@ -77,11 +75,11 @@ a package, you have to be a power user and remove the package directory from the right site-packages directory, then look over the right pth files. And this method differs, depending on the tools you are using. -The worst is that you depend on the way the packager created his package. +The worst issue is that you depend on the way the packager created his package. When you call `python setup.py install`, it will not be installed the same way depending on the tool used by the packager (distutils or setuptools). -But there's a common behavior : files are copied in your installation. +But there's common behavior: files are copied in your installation. And there's a way to keep track of theses file, so to remove them. Installing a package @@ -93,7 +91,7 @@ There are too many different ways to install a package in Python: - using `easy_install`, the script provided by setuptools - using `pip` -The problem is: they do no install the package the same way, +The problem is: they do not install the package the same way, and Python should provide one and only one way to do it. What this PEP proposes @@ -104,20 +102,21 @@ To address those issues, this PEP proposes a few changes: - a new `.egg-info` structure using a directory; - a list of elements this directory holds; - some new functions in `pkgutil` -- adding an install and an uninstall script +- addition of an install and an uninstall script + .egg-info becomes a directory ============================= -The first change would be to make `.egg-info` become a directory and +The first change would be to make `.egg-info` a directory and let it hold the `PKG-INFO` file built by the `write_pkg_file` method. This change will not impact Python itself, because this file is not used anywhere yet in the standard library. So there's no need of deprecation. -Although, it will impact the `setuptools` and `pip` project, but given -the fact that they already works with a directory that contains a +Although it will impact the `setuptools` and `pip` projects, but given +the fact that they already work with a directory that contains a `PKG-INFO` file, the change will be small. For example, if the `zlib` package is installed, two elements @@ -130,6 +129,7 @@ will be installed in `site-packages`:: To be able to implement this change, the impacted code in Distutils is the `install_egg_info` command. + Adding MANIFEST and RECORD in the .egg-info directory ===================================================== @@ -137,12 +137,12 @@ Some files can be added inside the `.egg-info` directory at installation time. They will all be UPPERCASE files. - the `MANIFEST` file built by the `sdist` command. Notice that - some fixes were made lately on the default files added in `MANIFEST` + some fixes were made lately on the default file names added in `MANIFEST` when `MANIFEST.in` is not provided (see #2279 for instance). - 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, like + command, and will always be generated. This will allow uninstall, as explained later in this PEP. The `install` command will record by default installed files in the @@ -168,6 +168,7 @@ Back to our `zlib` example, we will have:: XXX See if we want to keep the 2.5.2-py2.6 part + New functions in pkgutil ======================== @@ -178,10 +179,10 @@ The new functions added in the package are : - get_egg_info(pkg_name) -> path or None - Scans all site-packages directories and look for all `pkg_name.egg-info` - directory. Returns the directory path that contains a PKG-INFO that matches + Scans all site-packages directories and looks for all `pkg_name.egg-info` + directories. Returns the directory path that contains a PKG-INFO that matches `pkg_name` for the `name` metadata. Notice that there should be at most - one result. If moe that one path matches the pkg_name, a DistutilsError + one result. If more than one path matches the pkg_name, a DistutilsError is raised. If the directory is not found, returns None. @@ -197,9 +198,9 @@ The new functions added in the package are : Uses `get_egg_info` and gets any file inside the directory, pointed by filename. - filename is any value founded in `distutils.sdist.EGG_INFO_FILES` + filename can be any value found in `distutils.sdist.EGG_INFO_FILES`. -Let's use it over our `zlib` example:: +Let's use it with our `zlib` example:: >>> from pkgutil import get_egg_info, get_metadata, get_egg_info_file >>> get_egg_info('zlib') @@ -213,6 +214,7 @@ Let's use it over our `zlib` example:: ... files + Adding an install and an uninstall script ========================================= @@ -225,24 +227,26 @@ that are not discussed here. - they add an entry in a .pth file A new script called `install.py` is added in a new directory called `scripts` -in Distutils, and let people run an installation using:: +in Distutils, and lets people run an installation using:: - $ python -m 'distutils.scripts.install' zlib + $ python -m distutils.scripts.install zlib -An uninstall command is added as well, that removes the files recorded -in the RECORD file. This removal will warn on file that no longer exists +An uninstall command is added as well that removes the files recorded +in the RECORD file. This removal will warn on files that no longer exist and will not take care of side effects, like the removal of a file used by another element of the system. XXX work to be done here : specification of the two commands (probably a mix of easy_install and pip) + Copyright ========= This document has been placed in the public domain. + .. Local Variables: mode: indented-text @@ -251,4 +255,3 @@ This document has been placed in the public domain. fill-column: 70 coding: utf-8 End: -