iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

using docutils in all examples + polished reST

This commit is contained in:
Tarek Ziadé 2009-06-23 12:14:02 +00:00
parent 98e6c43034
commit c8bc9c1f23
1 changed files with 98 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
pep-0376.txt
View File

@ -32,13 +32,13 @@ 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
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.
See the Distutils [#distutils]_ documentation for more information.
Once installed, the elements are located in various places in the system, like:
@ -64,8 +64,8 @@ Right now, when a distribution is installed in Python, every elements its contai
is installed in various directories.
The pure Python code for instance is installed in the `purelib` directory,
which is located in the Python installation in `lib\python2.6\site-packages`
for example under unix-like systems or Mac OS X, and in `Lib/site-packages`
which is located in the Python installation in ``lib\python2.6\site-packages``
for example under unix-like systems or Mac OS X, and in ``Lib/site-packages``
under Windows. This is done with the Distutils `install` command, which calls
various subcommands.
@ -74,20 +74,21 @@ create an `.egg-info` file in the `purelib` directory.
For example, for the `docutils` distribution, which contains one package an
extra module and executable scripts, three elements will be installed in
`site-packages`::
`site-packages`:
- docutils : the docutils pakage
- roman.py : an extra module used by docutils
- docutils-0.5-py2.6.egg-info : a file containing the distribution metadata
- `docutils` : the ``docutils`` pakage
- `roman.py` : an extra module used by `docutils`
- `docutils-0.5-py2.6.egg-info` : 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.
Some executable scripts such as `rst2html.py` will also be added in the `bin`
directory of the Python installation.
The problem is that many people use `easy_install` (setuptools [#setuptools]_)
or `pip` [#pip]_ to install their packages, and these third-party tools do not
install packages in the same way that Distutils does:
The problem is that many people use `easy_install` (from the `setuptools`
project [#setuptools]_) or `pip` [#pip]_ 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. The `.egg` directory
@ -115,7 +116,7 @@ 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 distribution by
removing a file that was shared among several distributions.
removing a file that is shared among several distributions.
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
@ -161,7 +162,7 @@ file, the change will have no deep consequences.
For example, if the `docutils` package is installed, the elements that
will be installed in `site-packages` will become::
- docutils
- docutils/
- roman.py
- docutils-0.5-py2.6.egg-info/
PKG-INFO
@ -215,7 +216,7 @@ the `excel` dialect, which uses these options to read the file:
- field delimiter : `,`
- quoting char : `"`.
- line terminator : ``os.linesep`` (so `\r\n` or `\r`)
- line terminator : ``os.linesep`` (so ``\r\n`` or ``\r``)
Each record is composed of three elements.
@ -242,33 +243,34 @@ so the field separator will be ",". Any "," characters found within a field
will be escaped automatically by ``csv``.
When the file is read, the `U` option will be used so the universal newline
support (see PEP 278 [pep278]_) will be activated, avoiding any trouble
support (see PEP 278 [#pep278]_) will be activated, avoiding any trouble
reading a file produced on a platform that uses a different new line
terminator.
Example
-------
Back to our `zlib` example, we will have::
Back to our `docutils` example, we will have::
- zlib
- zlib-2.5.2.egg-info/
- docutils/
- roman.py
- docutils-0.5-py2.6.egg-info/
PKG-INFO
RECORD
And the RECORD file will contain::
And the RECORD file will contain (extract)::
zlib/include/zconf.h,b690274f621402dda63bf11ba5373bf2,9544
zlib/include/zlib.h,9c4b84aff68aa55f2e9bf70481b94333,66188
zlib/lib/libz.a,e6d43fb94292411909404b07d0692d46,91128
zlib/share/man/man3/zlib.3,785dc03452f0508ff0678fba2457e0ba,4486
zlib-2.5.2.egg-info/PKG-INFO,6fe57de576d749536082d8e205b77748,195
zlib-2.5.2.egg-info/RECORD
docutils/__init__.py,b690274f621402dda63bf11ba5373bf2,9544
docutils/core.py,9c4b84aff68aa55f2e9bf70481b94333,66188
roman.py,a4b84aff68aa55f2e9bf70481b943D3,234
/usr/local/bin/rst2html.py,a4b84aff68aa55f2e9bf70481b943D3,234
docutils-0.5-py2.6.egg-info/PKG-INFO,6fe57de576d749536082d8e205b77748,195
docutils-0.5-py2.6.egg-info/RECORD
Notice that:
- the `RECORD` file can't contain a hash of itself and is just mentioned here
- `zlib` and `zlib-2.5.2.egg-info` are located in `site-packages` so the file
- `docutils` and `docutils-0.5-py2.6.egg-info` are located in `site-packages` so the file
paths are relative to it.
Adding an INSTALLER file in the .egg-info directory
@ -294,7 +296,7 @@ library a set of APIs. The best place to put these APIs seems to be `pkgutil`.
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]_.
[#pep273]_.
- ``Distribution``: manages an `.egg-info` directory.
- ``ZippedDistribution``: manages an `.egg-info` directory contained in a zip
@ -312,6 +314,10 @@ A new class called ``Distribution`` is created with a the path of the
`.egg-info` directory provided to the contructor. It reads the metadata
contained in `PKG-INFO` when it is instanciated.
``Distribution(path)`` -> instance
Creates a ``Distribution`` instance for the given ``path``.
``Distribution`` provides the following attributes:
- ``name``: The name of the distribution.
@ -362,6 +368,12 @@ ZippedDistribution class
A ``ZippedDistribution`` class is provided. It overrides the ``Distribution``
class so its methods work with an `.egg.info` directory located in a zip file.
``ZippedDistribution(zipfile, path)`` -> instance
Creates a ``ZippedDistribution`` instance for the given relative ``path``
located in the ``zipfile`` file.
Other public methods and attributes are similar to ``Distribution``.
DistributionDirectory class
---------------------------
@ -373,17 +385,17 @@ corresponding to a directory. For each `.egg-info` directory founded in
The class is a ``set`` of ``Distribution`` instances. ``DistributionDirectory``
provides a ``path`` attribute corresponding to the path is was created with.
It also provides two methods besides the ones from ``set``:
``DistributionDirectory(path)`` -> instance
Creates a ``DistributionDirectory`` instance for the given ``path``.
It also provides one extra method besides the ones from ``set``:
- ``get_file_users(path)`` -> Iterator of ``Distribution``.
Returns all ``Distribution`` which uses ``path``, by calling
``Distribution.uses(path)`` on all ``Distribution`` instances.
- ``owner(path)`` -> ``Distribution`` instance or None
If ``path`` is used by only one ``Distribution`` instance, returns it.
Otherwise returns None.
ZippedDistributionDirectory class
---------------------------------
@ -391,21 +403,33 @@ ZippedDistributionDirectory class
A ``ZippedDistributionDirectory`` is provided. It overrides the
``DistributionDirectory`` class so its methods work with a Zip file.
``ZippedDistributionDirectory(path)`` -> instance
Creates a ``ZippedDistributionDirectory`` instance for the given ``path``.
Other public methods and attributes are similar to ``DistributionDirectory``.
DistributionDirectories class
-----------------------------
A new class called ``DistributionDirectories`` is created. It's a collection of
``DistributionDirectory`` and ``ZippedDistributionDirectory`` instances.
The constructor takes one optional argument ``use_cache`` set to ``True`` by
default. When ``True``, ``DistributionDirectories`` will use a global cache
to reduce the numbers of I/O accesses and speed up the lookups.
``DistributionDirectories(paths=None, use_cache=True)`` -> instance
If ``paths`` is not not, it's a sequence of paths the constructor loads
in the instance.
The constructor also takes an optional ``use_cache`` argument.
When it's ``True``, ``DistributionDirectories`` will use a global
cache to reduce the numbers of I/O accesses and speed up the lookups.
The cache is a global mapping containing ``DistributionDirectory`` and
``ZippedDistributionDirectory`` instances. When an ``DistributionDirectories``
object is created, it will use the cache to add an entry for each path it
visits, or reuse existing entries. The cache usage can be disabled at any time
with the ``use_cache`` attribute.
``ZippedDistributionDirectory`` instances. When a
``DistributionDirectories`` object is created, it will use the cache to
add an entry for each path it visits, or reuse existing entries. The
cache usage can be disabled at any time with the ``use_cache`` attribute.
The cache can also be emptied with the global ``purge_cache`` function.
@ -414,7 +438,7 @@ and ``ZippedDistributionDirectory`` instances and the keys are their path
attributes.
``DistributionDirectories`` also provides the following methods besides the ones
from ``dict``::
from ``dict``:
- ``load(*paths)``
@ -478,26 +502,29 @@ to use the cache. Notice that the cache is never emptied explicitely.
Example
-------
Let's use some of the new APIs with our `zlib` example::
Let's use some of the new APIs with our `docutils` example::
>>> from pkgutil import get_distribution, get_file_users
>>> dist = get_distribution('zlib')
>>> dist = get_distribution('docutils')
>>> dist.name
'zlib'
'docutils'
>>> dist.metadata.version
'2.5.2'
'0.5'
>>> for path, hash, size in dist.get_installed_files()::
... print '%s %s %d' % (path, hash, size)
...
zlib/include/zconf.h b690274f621402dda63bf11ba5373bf2 9544
zlib/include/zlib.h 9c4b84aff68aa55f2e9bf70481b94333 66188
zlib/lib/libz.a e6d43fb94292411909404b07d0692d46 91128
zlib/share/man/man3/zlib.3 785dc03452f0508ff0678fba2457e0ba 4486
zlib-2.5.2.egg-info/PKG-INFO 6fe57de576d749536082d8e205b77748 195
zlib-2.5.2.egg-info/RECORD None None
docutils/__init__.py b690274f621402dda63bf11ba5373bf2 9544
docutils/core.py 9c4b84aff68aa55f2e9bf70481b94333 66188
roman.py a4b84aff68aa55f2e9bf70481b943D3 234
/usr/local/bin/rst2html.py a4b84aff68aa55f2e9bf70481b943D3 234
docutils-0.5-py2.6.egg-info/PKG-INFO 6fe57de576d749536082d8e205b77748 195
docutils-0.5-py2.6.egg-info/RECORD None None
>>> dist.uses('zlib/include/zlib.h')
>>> dist.uses('docutils/core.py')
True
>>> dist.uses('/usr/local/bin/rst2html.py')
True
>>> dist.get_egginfo_file('PKG-INFO')
@ -539,9 +566,10 @@ empty directories left behind.
``uninstall`` will return a list of uninstalled files::
>>> from distutils.util import uninstall
>>> uninstall('zlib')
['/opt/local/lib/python2.6/site-packages/zlib/file1',
'/opt/local/lib/python2.6/site-packages/zlib/file2']
>>> uninstall('docutils')
['/opt/local/lib/python2.6/site-packages/docutils/core.py',
...
'/opt/local/lib/python2.6/site-packages/docutils/__init__.py']
If the distribution is not found, a ``DistutilsUninstallError`` will be raised.
@ -559,13 +587,13 @@ Examples::
... logging.info('Removing %s' % path)
... return True
...
>>> uninstall('zlib', _remove_and_log)
>>> uninstall('docutils', _remove_and_log)
>>> def _dry_run(path):
... logging.info('Removing %s (dry run)' % path)
... return False
...
>>> uninstall('zlib', _dry_run)
>>> uninstall('docutils', _dry_run)
Of course, a third-party tool can use ``pkgutil`` APIs to implement
its own uninstall feature.
@ -583,12 +611,12 @@ to ``distutils``.
When called, ``uninstall`` will control that the ``INSTALLER`` file matches
this argument. If not, it will raise a ``DistutilsUninstallError``::
>>> uninstall('zlib')
>>> uninstall('docutils')
Traceback (most recent call last):
...
DistutilsUninstallError: zlib was installed by 'cool-pkg-manager'
DistutilsUninstallError: docutils was installed by 'cool-pkg-manager'
>>> uninstall('zlib', installer='cool-pkg-manager')
>>> uninstall('docutils', 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 distribution it has
@ -607,9 +635,13 @@ provided so people can benefit from these new features.
The plan is to integrate them for Python 2.7 and Python 3.2
References
==========
.. [#distutils]
http://docs.python.org/distutils
.. [#pep262]
http://www.python.org/dev/peps/pep-0262
@ -628,13 +660,10 @@ References
.. [#pep273]
http://www.python.org/dev/peps/pep-0273
.. [#pep2738]
.. [#pep278]
http://www.python.org/dev/peps/pep-0278
.. [distutils]
http://docs.python.org/distutils
Aknowledgments
==============