peps/pep-0365.txt at main · python/peps

Cannot retrieve contributors at this time

128 lines (98 sloc) 4.76 KB

	PEP: 365
	Title: Adding the pkg_resources module
	Version: $Revision$
	Last-Modified: $Date$
	Author: Phillip J. Eby <pje@telecommunity.com>
	Status: Rejected
	Type: Standards Track
	Topic: Packaging
	Content-Type: text/x-rst
	Created: 30-Apr-2007
	Post-History: 30-Apr-2007


	Abstract
	========

	This PEP proposes adding an enhanced version of the ``pkg_resources``
	module to the standard library.

	``pkg_resources`` is a module used to find and manage Python
	package/version dependencies and access bundled files and resources,
	including those inside of zipped ``.egg`` files. Currently,
	``pkg_resources`` is only available through installing the entire
	``setuptools`` distribution, but it does not depend on any other part
	of setuptools; in effect, it comprises the entire runtime support
	library for Python Eggs, and is independently useful.

	In addition, with one feature addition, this module could support
	easy bootstrap installation of several Python package management
	tools, including ``setuptools``, ``workingenv``, and ``zc.buildout``.


	Proposal
	========

	Rather than proposing to include ``setuptools`` in the standard
	library, this PEP proposes only that ``pkg_resources`` be added to the
	standard library for Python 2.6 and 3.0. ``pkg_resources`` is
	considerably more stable than the rest of setuptools, with virtually
	no new features being added in the last 12 months.

	However, this PEP also proposes that a new feature be added to
	``pkg_resources``, before being added to the stdlib. Specifically, it
	should be possible to do something like::

	python -m pkg_resources SomePackage==1.2

	to request downloading and installation of ``SomePackage`` from PyPI.
	This feature would not be a replacement for ``easy_install``;
	instead, it would rely on ``SomePackage`` having pure-Python ``.egg``
	files listed for download via the PyPI XML-RPC API, and the eggs would
	be placed in the ``$PYTHON_EGG_CACHE`` directory, where they would
	not be importable by default. (And no scripts would be installed.)
	However, if the download egg contains installation bootstrap code, it
	will be given a chance to run.

	These restrictions would allow the code to be extremely simple, yet
	still powerful enough to support users downloading package management
	tools such as ``setuptools``, ``workingenv`` and ``zc.buildout``,
	simply by supplying the tool's name on the command line.


	Rationale
	=========

	Many users have requested that ``setuptools`` be included in the
	standard library, to save users needing to go through the awkward
	process of bootstrapping it. However, most of the bootstrapping
	complexity comes from the fact that setuptools-installed code cannot
	use the ``pkg_resources`` runtime module unless setuptools is already
	installed. Thus, installing setuptools requires (in a sense) that
	setuptools already be installed.

	Other Python package management tools, such as ``workingenv`` and
	``zc.buildout``, have similar bootstrapping issues, since they both
	make use of setuptools, but also want to provide users with something
	approaching a "one-step install". The complexity of creating bootstrap
	utilities for these and any other such tools that arise in future, is
	greatly reduced if ``pkg_resources`` is already present, and is also
	able to download pre-packaged eggs from PyPI.

	(It would also mean that setuptools would not need to be installed
	in order to simply use eggs, as opposed to building them.)

	Finally, in addition to providing access to eggs built via setuptools
	or other packaging tools, it should be noted that since Python 2.5,
	the distutils install package metadata (aka ``PKG-INFO``) files that
	can be read by ``pkg_resources`` to identify what distributions are
	already on ``sys.path``. In environments where Python packages are
	installed using system package tools (like RPM), the ``pkg_resources``
	module provides an API for detecting what versions of what packages
	are installed, even if those packages were installed via the distutils
	instead of setuptools.


	Implementation and Documentation
	================================

	The ``pkg_resources`` implementation is maintained in the Python
	SVN repository under ``/sandbox/trunk/setuptools/``; see
	``pkg_resources.py`` and ``pkg_resources.txt``. Documentation for the
	egg format(s) supported by ``pkg_resources`` can be found in
	``doc/formats.txt``. HTML versions of these documents are available
	at:

	* http://peak.telecommunity.com/DevCenter/PkgResources and

	* http://peak.telecommunity.com/DevCenter/EggFormats

	(These HTML versions are for setuptools 0.6; they may not reflect all
	of the changes found in the Subversion trunk's ``.txt`` versions.)


	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: