started the work on PEP 376 for Distutils
This commit is contained in:
Tarek Ziadé
parent
a5645d6955
commit
03e4ec6740
|
|
@ -0,0 +1,248 @@
|
|||
PEP: 376
|
||||
Title: Changing the .egg-info structure
|
||||
Version: $Revision:$
|
||||
Last-Modified: $Date:$
|
||||
Author: Tarek Ziadé <tarek@ziade.org>
|
||||
Status: Draft
|
||||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 22-Feb-2009
|
||||
Python-Version: 2.7, 3.1
|
||||
Post-History:
|
||||
|
||||
.. contents::
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
This PEP proposes various enhancements for Distutils:
|
||||
|
||||
- a new format for the .egg-info structure.
|
||||
- an install script to install 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 different ways to install a package in
|
||||
Python nowadays
|
||||
|
||||
- There is no way to uninstall a package.
|
||||
|
||||
- There is no API to get the metadata of installed
|
||||
packages.
|
||||
|
||||
How packages are installed
|
||||
--------------------------
|
||||
|
||||
Right now, when a package is installed in Python, using the
|
||||
Distutils `install` command, the `install_egg_info` subcommand is
|
||||
called in order to create an `.egg-info` file in the site-packages directory,
|
||||
right beside the package itself.
|
||||
|
||||
For example, if the `zlib` package is installed, two elements
|
||||
will be installed in `site-packages`::
|
||||
|
||||
- zlib
|
||||
- zlib-2.5.2-py2.6.egg-info
|
||||
|
||||
Where `zlib` is the package itself, and `zlib-2.5.2-py2.6.egg-info` is
|
||||
a file containing the package metadata as described in PEP 314.
|
||||
|
||||
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.
|
||||
|
||||
- `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.
|
||||
|
||||
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
|
||||
per installed package, which may lead to slow initialisation of Python.
|
||||
|
||||
The uninstall command
|
||||
---------------------
|
||||
|
||||
Python doesn't provide any `uninstall` command. If you want to uninstall
|
||||
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.
|
||||
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.
|
||||
And there's a way to keep track of theses file, so to remove them.
|
||||
|
||||
Installing a package
|
||||
--------------------
|
||||
|
||||
There are too many different ways to install a package in Python:
|
||||
|
||||
- by hand, by getting a distribution and running the install command
|
||||
- using `easy_install`, the script provided by setuptools
|
||||
- using `pip`
|
||||
|
||||
The problem is: they do no install the package the same way,
|
||||
and Python should provide one and only one way to do it.
|
||||
|
||||
What this PEP proposes
|
||||
----------------------
|
||||
|
||||
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
|
||||
|
||||
.egg-info becomes a directory
|
||||
=============================
|
||||
|
||||
The first change would be to make `.egg-info` become a directory and
|
||||
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
|
||||
`PKG-INFO` file, the change will be small.
|
||||
|
||||
For example, if the `zlib` package is installed, two elements
|
||||
will be installed in `site-packages`::
|
||||
|
||||
- zlib
|
||||
- zlib-2.5.2-py2.6.egg-info/
|
||||
PKG-INFO
|
||||
|
||||
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
|
||||
=====================================================
|
||||
|
||||
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`
|
||||
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
|
||||
explained later in this PEP.
|
||||
|
||||
The `install` command will record by default installed files in the
|
||||
RECORD file.
|
||||
|
||||
The `sdist` module will introduce an `EGG_INFO_FILES` constant to list
|
||||
all files located in the `.egg-info` directory::
|
||||
|
||||
from collections import namedtuple
|
||||
|
||||
EggInfos = namedtuple('EggInfo', 'manifest record pkg_info')
|
||||
|
||||
# files added in egg-info
|
||||
EGG_INFO_FILES = EggInfos('MANIFEST', 'RECORD', 'PKG-INFO')
|
||||
|
||||
Back to our `zlib` example, we will have::
|
||||
|
||||
- zlib
|
||||
- zlib-2.5.2-py2.6.egg-info/
|
||||
PKG-INFO
|
||||
MANIFEST
|
||||
RECORD
|
||||
|
||||
New functions 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 new functions added in the package are :
|
||||
|
||||
- get_egg_info(pkg_name) -> directory or None
|
||||
|
||||
Scans all site-packages directories and look for all `pkg_name*.egg-info`
|
||||
directory. If founded, returns the path. If the directory is not found,
|
||||
returns None.
|
||||
|
||||
- get_metadata(pkg_name) -> DistributionMetadata or None
|
||||
|
||||
Uses `get_egg_info` to get the `PKG-INFO` file, and returns a
|
||||
`DistributionMetadata` instance that contains the metadata.
|
||||
This will require a small change in `DistributionMetadata` (see #4908).
|
||||
|
||||
- get_egg_info_file(pkg_name, filename) -> file object or None
|
||||
|
||||
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`
|
||||
|
||||
Let's use it over our `zlib` example::
|
||||
|
||||
>>> from pkgutil import get_egg_info, get_metadata, get_egg_info_file
|
||||
>>> get_egg_info('zlib')
|
||||
'/opt/local/lib/python2.6/site-packages/zlib-2.5.2-py2.6.egg-info'
|
||||
>>> metadata = get_metadata('zlib')
|
||||
>>> metadata.version
|
||||
'2.5.2'
|
||||
>>> from distutils.dist import EGG_INFO_FILES
|
||||
>>> get_metadata('zlib', EGG_INFO_FILES.manifest).read()
|
||||
some
|
||||
...
|
||||
files
|
||||
|
||||
Adding an install and an uninstall script
|
||||
=========================================
|
||||
|
||||
`easy_install` and `pip` does basically the same work, besides other features
|
||||
that are not discussed here.
|
||||
|
||||
- they look for the package at PyPI
|
||||
- they download it and build it
|
||||
- they install it inside the site-packages directory
|
||||
- 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::
|
||||
|
||||
$ 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
|
||||
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
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
coding: utf-8
|
||||
End:
|
||||
|
||||
Loading…
Reference in New Issue