[Python-checkins] distutils2: Some updates to markup and content
tarek.ziade
python-checkins at python.org
Thu Aug 19 08:34:11 CEST 2010
tarek.ziade pushed e07412dea5e1 to distutils2:
http://hg.python.org/distutils2/rev/e07412dea5e1
changeset: 527:e07412dea5e1
user: ?ric Araujo <merwok at netwok.org>
date: Mon Aug 09 07:42:14 2010 +0200
summary: Some updates to markup and content
files: docs/source/configfile.rst, docs/source/examples.rst, docs/source/extending.rst, docs/source/introduction.rst, docs/source/metadata.rst, docs/source/setupscript.rst, docs/source/uploading.rst
diff --git a/docs/source/configfile.rst b/docs/source/configfile.rst
--- a/docs/source/configfile.rst
+++ b/docs/source/configfile.rst
@@ -21,11 +21,11 @@
setup script, but before the command-line. This has several useful
consequences:
-.. % (If you have more advanced needs, such as determining which extensions
-.. % to build based on what capabilities are present on the target system,
-.. % then you need the Distutils ``auto-configuration'' facility. This
-.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
-.. % or stable enough yet for real-world use.)
+.. If you have more advanced needs, such as determining which extensions to
+ build based on what capabilities are present on the target system, then you
+ need the Distutils auto-configuration facility. This started to appear in
+ Distutils 0.9 but, as of this writing, isn't mature or stable enough yet
+ for real-world use.
* installers can override some of what you put in :file:`setup.py` by editing
:file:`setup.cfg`
@@ -66,6 +66,8 @@
--swig-opts list of SWIG command line options
[...]
+.. XXX do we want to support ``setup.py --help metadata``?
+
Note that an option spelled :option:`--foo-bar` on the command-line is spelled
:option:`foo_bar` in configuration files.
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -5,14 +5,7 @@
********
This chapter provides a number of basic examples to help get started with
-distutils. Additional information about using distutils can be found in the
-Distutils Cookbook.
-
-
-.. seealso::
-
- `Distutils Cookbook <http://wiki.python.org/moin/Distutils/Cookbook>`_
- Collection of recipes showing how to achieve more control over distutils.
+Distutils2.
.. _pure-mod:
@@ -34,7 +27,7 @@
(In all diagrams in this section, *<root>* will refer to the distribution root
directory.) A minimal setup script to describe this situation would be::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foo',
version='1.0',
py_modules=['foo'],
@@ -57,7 +50,7 @@
and the setup script might be ::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
py_modules=['foo', 'bar'],
@@ -82,7 +75,7 @@
The setup script from the last example could also be written as ::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
packages=[''],
@@ -101,7 +94,7 @@
then you would still specify the root package, but you have to tell the
Distutils where source files in the root package live::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
package_dir={'': 'src'},
@@ -123,7 +116,7 @@
This is in fact the default layout expected by the Distutils, and the one that
requires the least work to describe in your setup script::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
packages=['foobar'],
@@ -142,7 +135,7 @@
an appropriate setup script would be ::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
package_dir={'foobar': 'src'},
@@ -160,7 +153,7 @@
in which case your setup script would be ::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
package_dir={'foobar': ''},
@@ -187,7 +180,7 @@
then the corresponding setup script would be ::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar',
version='1.0',
packages=['foobar', 'foobar.subfoo'],
@@ -214,8 +207,7 @@
If the :mod:`foo` extension belongs in the root package, the setup script for
this could be ::
- from distutils.core import setup
- from distutils.extension import Extension
+ from distutils2.core import setup, Extension
setup(name='foobar',
version='1.0',
ext_modules=[Extension('foo', ['foo.c'])],
@@ -226,25 +218,25 @@
With exactly the same source tree layout, this extension can be put in the
:mod:`foopkg` package simply by changing the name of the extension::
- from distutils.core import setup
- from distutils.extension import Extension
+ from distutils2.core import setup, Extension
setup(name='foobar',
version='1.0',
- ext_modules=[Extension('foopkg.foo', ['foo.c'])],
- )
+ packages=['foopkg'],
+ ext_modules=[Extension('foopkg.foo', ['foo.c'])])
-Checking a package
-==================
-The ``check`` command allows you to verify if your package meta-data
-meet the minimum requirements to build a distribution.
+Checking metadata
+=================
+
+The ``check`` command allows you to verify if your project's metadata
+meets the minimum requirements to build a distribution.
To run it, just call it using your :file:`setup.py` script. If something is
missing, ``check`` will display a warning.
Let's take an example with a simple script::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foobar')
@@ -252,35 +244,39 @@
$ python setup.py check
running check
- warning: check: missing required meta-data: version, url
- warning: check: missing meta-data: either (author and author_email) or
+ warning: check: missing required metadata: version, home_page
+ warning: check: missing metadata: either (author and author_email) or
(maintainer and maintainer_email) must be supplied
If you use the reStructuredText syntax in the ``long_description`` field and
-`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
+`Docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
the syntax is fine with the ``check`` command, using the ``restructuredtext``
option.
For example, if the :file:`setup.py` script is changed like this::
- from distutils.core import setup
+ from distutils2.core import setup
desc = """\
- My description
- =============
+ Welcome to foobar!
+ ===============
- This is the description of the ``foobar`` package.
+ This is the description of the ``foobar`` project.
"""
- setup(name='foobar', version='1', author='tarek',
- author_email='tarek at ziade.org',
- url='http://example.com', long_description=desc)
+ setup(name='foobar',
+ version='1.0',
+ author=u'Tarek Ziadé',
+ author_email='tarek at ziade.org',
+ summary='Foobar utilities'
+ description=desc,
+ home_page='http://example.com')
Where the long description is broken, ``check`` will be able to detect it
by using the :mod:`docutils` parser::
- $ pythontrunk setup.py check --restructuredtext
+ $ python setup.py check --restructuredtext
running check
warning: check: Title underline too short. (line 2)
warning: check: Could not finish the parsing.
@@ -291,15 +287,15 @@
Reading the metadata
====================
-The :func:`distutils.core.setup` function provides a command-line interface
+The :func:`distutils2.core.setup` function provides a command-line interface
that allows you to query the metadata fields of a project through the
:file:`setup.py` script of a given project::
$ python setup.py --name
- distribute
+ foobar
This call reads the ``name`` metadata by running the
-:func:`distutils.core.setup` function. Although, when a source or binary
+:func:`distutils2.core.setup` function. When a source or binary
distribution is created with Distutils, the metadata fields are written
in a static file called :file:`PKG-INFO`. When a Distutils-based project is
installed in Python, the :file:`PKG-INFO` file is copied alongside the modules
@@ -312,7 +308,7 @@
:class:`distutils.dist.DistributionMetadata` class and its
:func:`read_pkg_file` method::
- >>> from distutils.dist import DistributionMetadata
+ >>> from distutils2.dist import DistributionMetadata
>>> metadata = DistributionMetadata()
>>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
>>> metadata.name
@@ -330,9 +326,14 @@
'distribute'
-.. % \section{Multiple extension modules}
-.. % \label{multiple-ext}
+.. XXX These comments have been here for at least ten years. Write the
+ sections or delete the comments (we can maybe ask Greg Ward about
+ the planned contents). (Unindent to make them section titles)
-.. % \section{Putting it all together}
+ .. multiple-ext::
+ Multiple extension modules
+ ==========================
+ Putting it all together
+ =======================
diff --git a/docs/source/extending.rst b/docs/source/extending.rst
--- a/docs/source/extending.rst
+++ b/docs/source/extending.rst
@@ -41,8 +41,8 @@
the new implementations with your :file:`setup.py` script, and cause the
:func:`distutils.core.setup` function use them::
- from distutils.command.build_py import build_py as _build_py
- from distutils.core import setup
+ from distutils2.command.build_py import build_py as _build_py
+ from distutils2.core import setup
class build_py(_build_py):
"""Specialized Python source builder."""
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -1,14 +1,16 @@
.. _distutils-intro:
-****************************
-An Introduction to Distutils
-****************************
+*****************************
+An Introduction to Distutils2
+*****************************
-This document covers using the Distutils to distribute your Python modules,
-concentrating on the role of developer/distributor: if you're looking for
+This document covers using Distutils2 to distribute your Python modules,
+concentrating on the role of developer/distributor; if you're looking for
information on installing Python modules, you should refer to the
:ref:`install-index` chapter.
+Throughout this documentation, the terms "Distutils", "the Distutils" and
+"Distutils2" will be used with the same meaning.
.. _distutils-concepts:
@@ -56,7 +58,7 @@
If all you want to do is distribute a module called :mod:`foo`, contained in a
file :file:`foo.py`, then your setup script can be as simple as this::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='foo',
version='1.0',
py_modules=['foo'],
@@ -113,22 +115,8 @@
python setup.py bdist_wininst
will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
-directory.
-
-Other useful built distribution formats are RPM, implemented by the
-:command:`bdist_rpm` command, Solaris :program:`pkgtool`
-(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
-(:command:`bdist_sdux`). For example, the following command will create an RPM
-file called :file:`foo-1.0.noarch.rpm`::
-
- python setup.py bdist_rpm
-
-(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
-this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
-Mandrake Linux.)
-
-You can find out what distribution formats are available at any time by running
-::
+directory. You can find out what distribution formats are available at any time
+by running ::
python setup.py bdist --help-formats
diff --git a/docs/source/metadata.rst b/docs/source/metadata.rst
--- a/docs/source/metadata.rst
+++ b/docs/source/metadata.rst
@@ -3,21 +3,21 @@
========
Distutils2 provides a :class:`DistributionMetadata` class that can read and
-write Metadata files. This class is compatible with all versions of Metadata:
+write metadata files. This class is compatible with all metadata versions:
-- 1.0 : PEP 241
-- 1.1 : PEP 314
-- 1.2 : PEP 345
+* 1.0: :PEP:`241`
+* 1.1: :PEP:`314`
+* 1.2: :PEP:`345`
-The PEP 345 implementation supports the micro-language for the environment
+The :PEP:`345` implementation supports the micro-language for the environment
markers, and displays warnings when versions that are supposed to be
-PEP 386 are violating the scheme.
+:PEP:`386` are violating the scheme.
Reading metadata
================
-The :class:`DistributionMetadata` class can be instanciated with the path of
+The :class:`DistributionMetadata` class can be instantiated with the path of
the metadata file, and provides a dict-like interface to the values::
>>> from distutils2.metadata import DistributionMetadata
@@ -32,19 +32,19 @@
["pywin32; sys.platform == 'win32'", "Sphinx"]
The fields that supports environment markers can be automatically ignored if
-the object is instanciated using the ``platform_dependant`` option.
+the object is instantiated using the ``platform_dependent`` option.
:class:`DistributionMetadata` will interpret in the case the markers and will
automatically remove the fields that are not compliant with the running
environment. Here's an example under Mac OS X. The win32 dependency
we saw earlier is ignored::
>>> from distutils2.metadata import DistributionMetadata
- >>> metadata = DistributionMetadata('PKG-INFO', platform_dependant=True)
+ >>> metadata = DistributionMetadata('PKG-INFO', platform_dependent=True)
>>> metadata['Requires-Dist']
['bar']
If you want to provide your own execution context, let's say to test the
-Metadata under a particular environment that is not the current environment,
+metadata under a particular environment that is not the current environment,
you can provide your own values in the ``execution_context`` option, which
is the dict that may contain one or more keys of the context the micro-language
expects.
@@ -53,7 +53,7 @@
>>> from distutils2.metadata import DistributionMetadata
>>> context = {'sys.platform': 'win32'}
- >>> metadata = DistributionMetadata('PKG-INFO', platform_dependant=True,
+ >>> metadata = DistributionMetadata('PKG-INFO', platform_dependent=True,
... execution_context=context)
...
>>> metadata['Requires-Dist'] = ["pywin32; sys.platform == 'win32'",
@@ -71,15 +71,15 @@
>>> metadata.write('/to/my/PKG-INFO')
The class will pick the best version for the metadata, depending on the values
-provided. If all the values provided exists in all versions, teh class will
-used :attr:`metadata.PKG_INFO_PREFERRED_VERSION`. It is set by default to 1.0.
+provided. If all the values provided exist in all versions, the class will
+use :attr:`metadata.PKG_INFO_PREFERRED_VERSION`. It is set by default to 1.0.
Conflict checking and best version
==================================
-Some fields in PEP 345 have to follow a version scheme in their versions
-predicate. When the scheme is violated, a warning is emited::
+Some fields in :PEP:`345` have to follow a version scheme in their versions
+predicate. When the scheme is violated, a warning is emitted::
>>> from distutils2.metadata import DistributionMetadata
>>> metadata = DistributionMetadata()
@@ -88,8 +88,4 @@
>>> metadata['Requires-Dist'] = ['Funky (1.2)']
-
-XXX talk about check()
-
-
-
+.. TODO talk about check()
diff --git a/docs/source/setupscript.rst b/docs/source/setupscript.rst
--- a/docs/source/setupscript.rst
+++ b/docs/source/setupscript.rst
@@ -21,7 +21,7 @@
#!/usr/bin/env python
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='Distutils',
version='1.0',
@@ -150,7 +150,7 @@
with :func:`setup`. Thus, the setup script for a module distribution that
contains only this one extension and nothing else might be::
- from distutils.core import setup, Extension
+ from distutils2.core import setup, Extension
setup(name='foo',
version='1.0',
ext_modules=[Extension('foo', ['foo.c'])],
@@ -268,7 +268,7 @@
search path, though, you can find that directory using the Distutils
:mod:`distutils.sysconfig` module::
- from distutils.sysconfig import get_python_inc
+ from distutils2.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
setup(...,
Extension(..., include_dirs=[incdir]),
@@ -670,19 +670,6 @@
],
)
-If you wish to include classifiers in your :file:`setup.py` file and also wish
-to remain backwards-compatible with Python releases prior to 2.2.3, then you can
-include the following code fragment in your :file:`setup.py` before the
-:func:`setup` call. ::
-
- # patch distutils if it can't cope with the "classifiers" or
- # "download_url" keywords
- from sys import version
- if version < '2.2.3':
- from distutils.dist import DistributionMetadata
- DistributionMetadata.classifiers = None
- DistributionMetadata.download_url = None
-
Debugging the setup script
==========================
diff --git a/docs/source/uploading.rst b/docs/source/uploading.rst
--- a/docs/source/uploading.rst
+++ b/docs/source/uploading.rst
@@ -57,7 +57,7 @@
The ``long_description`` field can be attached to a text file located
in the package::
- from distutils.core import setup
+ from distutils2.core import setup
setup(name='Distutils',
long_description=open('README.txt'))
--
Repository URL: http://hg.python.org/distutils2
More information about the Python-checkins
mailing list