Pep 376: Use ReST syntax for code, rather than Markdown syntax (#1297)
* PEP 376: Use ReST code syntax for literal characters Without markup, it is very easy to confuse code with adjoining punctuation. * PEP 376: Use ReST syntax for code, rather than Markdown syntax
This commit is contained in:
Petr Viktorin
GitHub
parent
5a9de97e0d
commit
f52d345112
184
pep-0376.txt
184
pep-0376.txt
|
|
@ -42,73 +42,73 @@ How distributions are installed
|
|||
Right now, when a distribution is installed in Python, every element can
|
||||
be installed in a different directory.
|
||||
|
||||
For instance, `Distutils` installs the pure Python code in the `purelib`
|
||||
For instance, ``Distutils`` installs the pure Python code in the ``purelib``
|
||||
directory, which is ``lib/python2.6/site-packages`` for unix-like systems and
|
||||
Mac OS X, or `Lib\site-packages` under Python's installation directory for
|
||||
Mac OS X, or ``Lib\site-packages`` under Python's installation directory for
|
||||
Windows.
|
||||
|
||||
Additionally, the `install_egg_info` subcommand of the Distutils `install`
|
||||
command adds an `.egg-info` file for the project into the `purelib`
|
||||
Additionally, the ``install_egg_info`` subcommand of the Distutils ``install``
|
||||
command adds an ``.egg-info`` file for the project into the ``purelib``
|
||||
directory.
|
||||
|
||||
For example, for the `docutils` distribution, which contains one package an
|
||||
For example, for the ``docutils`` distribution, which contains one package an
|
||||
extra module and executable scripts, three elements are installed in
|
||||
`site-packages`:
|
||||
``site-packages``:
|
||||
|
||||
- `docutils`: The ``docutils`` package.
|
||||
- `roman.py`: An extra module used by `docutils`.
|
||||
- `docutils-0.5-py2.6.egg-info`: A file containing the distribution metadata
|
||||
- ``docutils``: The ``docutils`` package.
|
||||
- ``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.
|
||||
called ``PKG-INFO``, built by the ``sdist`` command.
|
||||
|
||||
Some executable scripts, such as `rst2html.py`, are also added in the
|
||||
`bin` directory of the Python installation.
|
||||
Some executable scripts, such as ``rst2html.py``, are also added in the
|
||||
``bin`` directory of the Python installation.
|
||||
|
||||
Another project called `setuptools` [#setuptools]_ has two other formats
|
||||
to install distributions, called `EggFormats` [#eggformats]_:
|
||||
Another project called ``setuptools`` [#setuptools]_ has two other formats
|
||||
to install distributions, called ``EggFormats`` [#eggformats]_:
|
||||
|
||||
- a self-contained `.egg` directory, that contains all the distribution files
|
||||
and the distribution metadata in a file called `PKG-INFO` in a subdirectory
|
||||
called `EGG-INFO`. `setuptools` creates other files in that directory that can
|
||||
- a self-contained ``.egg`` directory, that contains all the distribution files
|
||||
and the distribution metadata in a file called ``PKG-INFO`` in a subdirectory
|
||||
called ``EGG-INFO``. ``setuptools`` creates other files in that directory that can
|
||||
be considered as complementary metadata.
|
||||
|
||||
- an `.egg-info` directory installed in `site-packages`, that contains the same
|
||||
files `EGG-INFO` has in the `.egg` format.
|
||||
- an ``.egg-info`` directory installed in ``site-packages``, that contains the same
|
||||
files ``EGG-INFO`` has in the ``.egg`` format.
|
||||
|
||||
The first format is automatically used when you install a distribution that
|
||||
uses the ``setuptools.setup`` function in its setup.py file, instead of
|
||||
the ``distutils.core.setup`` one.
|
||||
|
||||
`setuptools` also add a reference to the distribution into an
|
||||
``setuptools`` also add a reference to the distribution into an
|
||||
``easy-install.pth`` file.
|
||||
|
||||
Last, the `setuptools` project provides an executable script called
|
||||
`easy_install` [#easyinstall]_ that installs all distributions, including
|
||||
distutils-based ones in self-contained `.egg` directories.
|
||||
Last, the ``setuptools`` project provides an executable script called
|
||||
``easy_install`` [#easyinstall]_ that installs all distributions, including
|
||||
distutils-based ones in self-contained ``.egg`` directories.
|
||||
|
||||
If you want to have standalone `.egg-info` directories for your distributions,
|
||||
e.g. the second `setuptools` format, you have to force it when you work
|
||||
with a setuptools-based distribution or with the `easy_install` script.
|
||||
You can force it by using the `--single-version-externally-managed` option
|
||||
**or** the `--root` option. This will make the `setuptools` project install
|
||||
If you want to have standalone ``.egg-info`` directories for your distributions,
|
||||
e.g. the second ``setuptools`` format, you have to force it when you work
|
||||
with a setuptools-based distribution or with the ``easy_install`` script.
|
||||
You can force it by using the ``--single-version-externally-managed`` option
|
||||
**or** the ``--root`` option. This will make the ``setuptools`` project install
|
||||
the project like distutils does.
|
||||
|
||||
This option is used by :
|
||||
|
||||
- the `pip` [#pip]_ installer
|
||||
- the ``pip`` [#pip]_ installer
|
||||
- the Fedora packagers [#fedora]_.
|
||||
- the Debian packagers [#debian]_.
|
||||
|
||||
Uninstall information
|
||||
---------------------
|
||||
|
||||
Distutils doesn't provide an `uninstall` command. If you want to uninstall
|
||||
Distutils doesn't provide an ``uninstall`` command. If you want to uninstall
|
||||
a distribution, you have to be a power user and remove the various elements
|
||||
that were installed, and then look over the `.pth` file to clean them if
|
||||
that were installed, and 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
|
||||
distribution and if the distribution's `setup.py` uses Distutils or
|
||||
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
|
||||
|
|
@ -119,8 +119,8 @@ But there's a common behavior: when you install a distribution, files are
|
|||
copied in your system. And it's possible to keep track of these files for
|
||||
later removal.
|
||||
|
||||
Moreover, the Pip project has gained an `uninstall` feature lately. It
|
||||
records all installed files, using the `record` option of the `install`
|
||||
Moreover, the Pip project has gained an ``uninstall`` feature lately. It
|
||||
records all installed files, using the ``record`` option of the ``install``
|
||||
command.
|
||||
|
||||
What this PEP proposes
|
||||
|
|
@ -128,9 +128,9 @@ What this PEP proposes
|
|||
|
||||
To address those issues, this PEP proposes a few changes:
|
||||
|
||||
- A new `.dist-info` structure using a directory, inspired on one format of
|
||||
the `EggFormats` standard from `setuptools`.
|
||||
- New APIs in `pkgutil` to be able to query the information of installed
|
||||
- A new ``.dist-info`` structure using a directory, inspired on one format of
|
||||
the ``EggFormats`` standard from ``setuptools``.
|
||||
- New APIs in ``pkgutil`` to be able to query the information of installed
|
||||
distributions.
|
||||
- An uninstall function and an uninstall script in Distutils.
|
||||
|
||||
|
|
@ -139,19 +139,19 @@ One .dist-info directory per installed distribution
|
|||
===================================================
|
||||
|
||||
This PEP proposes an installation format inspired by one of the options in the
|
||||
`EggFormats` standard, the one that uses a distinct directory located in the
|
||||
``EggFormats`` standard, the one that uses a distinct directory located in the
|
||||
site-packages directory.
|
||||
|
||||
This distinct directory is named as follows::
|
||||
|
||||
name + '-' + version + '.dist-info'
|
||||
|
||||
This `.dist-info` directory can contain these files:
|
||||
This ``.dist-info`` directory can contain these files:
|
||||
|
||||
- `METADATA`: contains metadata, as described in PEP 345, PEP 314 and PEP 241.
|
||||
- `RECORD`: records the list of installed files
|
||||
- `INSTALLER`: records the name of the tool used to install the project
|
||||
- `REQUESTED`: the presence of this file indicates that the project
|
||||
- ``METADATA``: contains metadata, as described in PEP 345, PEP 314 and PEP 241.
|
||||
- ``RECORD``: records the list of installed files
|
||||
- ``INSTALLER``: records the name of the tool used to install the project
|
||||
- ``REQUESTED``: the presence of this file indicates that the project
|
||||
installation was explicitly requested (i.e., not installed as a dependency).
|
||||
|
||||
The METADATA, RECORD and INSTALLER files are mandatory, while REQUESTED may
|
||||
|
|
@ -160,25 +160,25 @@ be missing.
|
|||
This proposal will not impact Python itself because the metadata files are not
|
||||
used anywhere yet in the standard library besides Distutils.
|
||||
|
||||
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
|
||||
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 have no deep consequences.
|
||||
|
||||
|
||||
RECORD
|
||||
------
|
||||
|
||||
A `RECORD` file is added inside the `.dist-info` directory at installation
|
||||
time when installing a source distribution using the `install` command.
|
||||
Notice that when installing a binary distribution created with `bdist` command
|
||||
or a `bdist`-based command, the `RECORD` file will be installed as well since
|
||||
these commands use the `install` command to create binary distributions.
|
||||
A ``RECORD`` file is added inside the ``.dist-info`` directory at installation
|
||||
time when installing a source distribution using the ``install`` command.
|
||||
Notice that when installing a binary distribution created with ``bdist`` command
|
||||
or a ``bdist``-based command, the ``RECORD`` file will be installed as well since
|
||||
these commands use the ``install`` command to create binary distributions.
|
||||
|
||||
The `RECORD` file holds the list of installed files. These correspond
|
||||
to the files listed by the `record` option of the `install` command, and will
|
||||
The ``RECORD`` file holds the list of installed files. These correspond
|
||||
to the files listed by the ``record`` option of the ``install`` command, and will
|
||||
be generated by default. This allows the implementation of an uninstallation
|
||||
feature, as explained later in this PEP. The `install` command also provides
|
||||
an option to prevent the `RECORD` file from being written and this option
|
||||
feature, as explained later in this PEP. The ``install`` command also provides
|
||||
an option to prevent the ``RECORD`` file from being written and this option
|
||||
should be used when creating system packages.
|
||||
|
||||
Third-party installation tools also should not overwrite or delete files
|
||||
|
|
@ -186,12 +186,12 @@ that are not in a RECORD file without prompting or warning.
|
|||
|
||||
This RECORD file is inspired from PEP 262 FILES [#pep262]_.
|
||||
|
||||
The `RECORD` file is a CSV file, composed of records, one line per
|
||||
The ``RECORD`` file is a CSV file, composed of records, one line per
|
||||
installed file. The ``csv`` module is used to read the file, with
|
||||
these options:
|
||||
|
||||
- field delimiter : `,`
|
||||
- quoting char : `"`.
|
||||
- field delimiter : ``,``
|
||||
- quoting char : ``"``.
|
||||
- line terminator : ``os.linesep`` (so ``\r\n`` or ``\n``)
|
||||
|
||||
When a distribution is installed, files can be installed under:
|
||||
|
|
@ -219,10 +219,10 @@ Each record is composed of three elements:
|
|||
- an absolute path, using the local platform separator
|
||||
|
||||
- a hash of the file's contents.
|
||||
Notice that `pyc` and `pyo` generated files don't have any hash because
|
||||
they are automatically produced from `py` files. So checking the hash
|
||||
of the corresponding `py` file is enough to decide if the file and
|
||||
its associated `pyc` or `pyo` files have changed.
|
||||
Notice that ``pyc`` and ``pyo`` generated files don't have any hash because
|
||||
they are automatically produced from ``py`` files. So checking the hash
|
||||
of the corresponding ``py`` file is enough to decide if the file and
|
||||
its associated ``pyc`` or ``pyo`` files have changed.
|
||||
|
||||
The hash is either the empty string or the hash algorithm as named in
|
||||
``hashlib.algorithms_guaranteed``, followed by the equals character
|
||||
|
|
@ -235,7 +235,7 @@ The ``csv`` module is used to generate this file, so the field separator is
|
|||
",". Any "," character found within a field is escaped automatically by
|
||||
``csv``.
|
||||
|
||||
When the file is read, the `U` option is used so the universal newline
|
||||
When the file is read, the ``U`` option is used so the universal newline
|
||||
support (see PEP 278 [#pep278]_) is activated, avoiding any trouble
|
||||
reading a file produced on a platform that uses a different new line
|
||||
terminator.
|
||||
|
|
@ -253,9 +253,9 @@ Here's an example of a RECORD file (extract)::
|
|||
python2.6/site-packages/docutils-0.5.dist-info/METADATA,md5=ovJyUNzXdArGfmVyb0onyA,195
|
||||
lib/python2.6/site-packages/docutils-0.5.dist-info/RECORD,,
|
||||
|
||||
Notice that the `RECORD` file can't contain a hash of itself and is just mentioned here
|
||||
Notice that the ``RECORD`` file can't contain a hash of itself and is just mentioned here
|
||||
|
||||
A project that installs a `config.ini` file in `/etc/myapp` will be added like this::
|
||||
A project that installs a ``config.ini`` file in ``/etc/myapp`` will be added like this::
|
||||
|
||||
/etc/myapp/config.ini,md5=gLfd6IANquzGLhOkW4Mfgg,9544
|
||||
|
||||
|
|
@ -268,16 +268,16 @@ so a file that is copied in c:\MyApp\ will be::
|
|||
INSTALLER
|
||||
---------
|
||||
|
||||
The `install` command has a new option called `installer`. This option
|
||||
The ``install`` command has a new option called ``installer``. This option
|
||||
is the name of the tool used to invoke the installation. It's a normalized
|
||||
lower-case string matching `[a-z0-9_\-\.]`.
|
||||
lower-case string matching ``[a-z0-9_\-\.]``.
|
||||
|
||||
$ python setup.py install --installer=pkg-system
|
||||
|
||||
It defaults to `distutils` if not provided.
|
||||
It defaults to ``distutils`` if not provided.
|
||||
|
||||
When a distribution is installed, the INSTALLER file is generated in the
|
||||
`.dist-info` directory with this value, to keep track of **who** installed the
|
||||
``.dist-info`` directory with this value, to keep track of **who** installed the
|
||||
distribution. The file is a single-line text file.
|
||||
|
||||
|
||||
|
|
@ -315,8 +315,8 @@ Implementation details
|
|||
New functions and classes in pkgutil
|
||||
------------------------------------
|
||||
|
||||
To use the `.dist-info` directory content, we need to add in the standard
|
||||
library a set of APIs. The best place to put these APIs is `pkgutil`.
|
||||
To use the ``.dist-info`` directory content, we need to add in the standard
|
||||
library a set of APIs. The best place to put these APIs is ``pkgutil``.
|
||||
|
||||
Functions
|
||||
~~~~~~~~~
|
||||
|
|
@ -357,8 +357,8 @@ The new functions added in the ``pkgutil`` module are :
|
|||
``name``. If a ``version`` is provided, it will be used to filter the results.
|
||||
Scans all elements in ``sys.path`` and looks for all directories ending with
|
||||
``.dist-info``. Returns a ``Distribution`` corresponding to the
|
||||
``.dist-info`` directory that contains a METADATA that matches `name`
|
||||
for the `name` metadata.
|
||||
``.dist-info`` directory that contains a METADATA that matches ``name``
|
||||
for the ``name`` metadata.
|
||||
|
||||
This function only returns the first result founded, since no more than one
|
||||
values are expected. If the directory is not found, returns None.
|
||||
|
|
@ -376,8 +376,8 @@ Distribution class
|
|||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A new class called ``Distribution`` is created with the path of the
|
||||
`.dist-info` directory provided to the constructor. It reads the metadata
|
||||
contained in `METADATA` when it is instantiated.
|
||||
``.dist-info`` directory provided to the constructor. It reads the metadata
|
||||
contained in ``METADATA`` when it is instantiated.
|
||||
|
||||
``Distribution(path)`` -> instance
|
||||
|
||||
|
|
@ -398,41 +398,41 @@ And following methods:
|
|||
|
||||
- ``get_installed_files(local=False)`` -> iterator of (path, hash, size)
|
||||
|
||||
Iterates over the `RECORD` entries and return a tuple ``(path, hash, size)``
|
||||
Iterates over the ``RECORD`` entries and return a tuple ``(path, hash, size)``
|
||||
for each line. If ``local`` is ``True``, the path is transformed into a
|
||||
local absolute path. Otherwise the raw value from `RECORD` is returned.
|
||||
local absolute path. Otherwise the raw value from ``RECORD`` is returned.
|
||||
|
||||
A local absolute path is an absolute path in which occurrences of '/'
|
||||
have been replaced by the system separator given by ``os.sep``.
|
||||
|
||||
- ``uses(path)`` -> Boolean
|
||||
|
||||
Returns ``True`` if ``path`` is listed in `RECORD`. ``path``
|
||||
Returns ``True`` if ``path`` is listed in ``RECORD``. ``path``
|
||||
can be a local absolute path or a relative '/'-separated path.
|
||||
|
||||
- ``get_distinfo_file(path, binary=False)`` -> file object
|
||||
|
||||
Returns a file located under the `.dist-info` directory.
|
||||
Returns a file located under the ``.dist-info`` directory.
|
||||
|
||||
Returns a ``file`` instance for the file pointed by ``path``.
|
||||
|
||||
``path`` has to be a '/'-separated path relative to the `.dist-info`
|
||||
``path`` has to be a '/'-separated path relative to the ``.dist-info``
|
||||
directory or an absolute path.
|
||||
|
||||
If ``path`` is an absolute path and doesn't start with the `.dist-info`
|
||||
If ``path`` is an absolute path and doesn't start with the ``.dist-info``
|
||||
directory path, a ``DistutilsError`` is raised.
|
||||
|
||||
If ``binary`` is ``True``, opens the file in read-only binary mode (`rb`),
|
||||
otherwise opens it in read-only mode (`r`).
|
||||
If ``binary`` is ``True``, opens the file in read-only binary mode (``rb``),
|
||||
otherwise opens it in read-only mode (``r``).
|
||||
|
||||
- ``get_distinfo_files(local=False)`` -> iterator of paths
|
||||
|
||||
Iterates over the `RECORD` entries and returns paths for each line if the path
|
||||
is pointing to a file located in the `.dist-info` directory or one of its
|
||||
Iterates over the ``RECORD`` entries and returns paths for each line if the path
|
||||
is pointing to a file located in the ``.dist-info`` directory or one of its
|
||||
subdirectories.
|
||||
|
||||
If ``local`` is ``True``, each path is transformed into a
|
||||
local absolute path. Otherwise the raw value from `RECORD` is returned.
|
||||
local absolute path. Otherwise the raw value from ``RECORD`` is returned.
|
||||
|
||||
|
||||
Notice that the API is organized in five classes that work with directories
|
||||
|
|
@ -443,7 +443,7 @@ of the prototype implementation for interested readers [#prototype]_.
|
|||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
Let's use some of the new APIs with our `docutils` example::
|
||||
Let's use some of the new APIs with our ``docutils`` example::
|
||||
|
||||
>>> from pkgutil import get_distribution, get_file_users, distinfo_dirname
|
||||
>>> dist = get_distribution('docutils')
|
||||
|
|
@ -488,7 +488,7 @@ New functions in Distutils
|
|||
--------------------------
|
||||
|
||||
Distutils already provides a very basic way to install a distribution, which
|
||||
is running the `install` command over the `setup.py` script of the
|
||||
is running the ``install`` command over the ``setup.py`` script of the
|
||||
distribution.
|
||||
|
||||
Distutils2 [#pep262]_ will provide a very basic ``uninstall`` function, that
|
||||
|
|
@ -511,8 +511,8 @@ Filtering
|
|||
~~~~~~~~~
|
||||
|
||||
To make it a reference API for third-party projects that wish to control
|
||||
how `uninstall` works, a second callable argument can be used. It's
|
||||
called for each file that is removed. If the callable returns `True`, the
|
||||
how ``uninstall`` works, a second callable argument can be used. It's
|
||||
called for each file that is removed. If the callable returns ``True``, the
|
||||
file is removed. If it returns False, it's left alone.
|
||||
|
||||
Examples::
|
||||
|
|
@ -535,8 +535,8 @@ implement its own uninstall feature.
|
|||
Installer marker
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
As explained earlier in this PEP, the `install` command adds an `INSTALLER`
|
||||
file in the `.dist-info` directory with the name of the installer.
|
||||
As explained earlier in this PEP, the ``install`` command adds an ``INSTALLER``
|
||||
file in the ``.dist-info`` directory with the name of the installer.
|
||||
|
||||
To avoid removing distributions that were installed by another packaging
|
||||
system, the ``uninstall`` function takes an extra argument ``installer`` which
|
||||
|
|
@ -561,7 +561,7 @@ it has to undo at uninstallation time.
|
|||
Adding an Uninstall script
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An `uninstall` script is added in Distutils2. and is used like this::
|
||||
An ``uninstall`` script is added in Distutils2. and is used like this::
|
||||
|
||||
$ python -m distutils2.uninstall projectname
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue