[Python-checkins] distutils2: More modernization
tarek.ziade
python-checkins at python.org
Thu Aug 19 08:34:13 CEST 2010
tarek.ziade pushed c03dd6283e94 to distutils2:
http://hg.python.org/distutils2/rev/c03dd6283e94
changeset: 541:c03dd6283e94
user: ?ric Araujo <merwok at netwok.org>
date: Mon Aug 09 17:23:08 2010 +0200
summary: More modernization
files: docs/source/distutils/setupscript.rst, docs/source/distutils/uploading.rst
diff --git a/docs/source/distutils/setupscript.rst b/docs/source/distutils/setupscript.rst
--- a/docs/source/distutils/setupscript.rst
+++ b/docs/source/distutils/setupscript.rst
@@ -13,24 +13,22 @@
module developer is supplied as keyword arguments to :func:`setup`.
Here's a slightly more involved example, which we'll follow for the next couple
-of sections: the Distutils' own setup script. (Keep in mind that although the
-Distutils are included with Python 1.6 and later, they also have an independent
-existence so that Python 1.5.2 users can use them to install other module
-distributions. The Distutils' own setup script, shown here, is used to install
-the project into Python 1.5.2.) ::
+of sections: a setup script that could be used for Distutils2 itself::
#!/usr/bin/env python
- from distutils2.core import setup
+ from distutils2.core import setup, find_packages
- setup(name='Distutils',
+ setup(name='Distutils2',
version='1.0',
- description='Python Distribution Utilities',
- author='Greg Ward',
- author_email='gward at python.net',
- url='http://www.python.org/sigs/distutils-sig/',
- packages=['distutils', 'distutils.command'],
- )
+ summary='Python Distribution Utilities',
+ keywords=['packaging', 'distutils2'],
+ author=u'Tarek Ziadé',
+ author_email='tarek at ziade.org',
+ home_page='http://bitbucket.org/tarek/distutils2/wiki/Home',
+ license='PSF',
+ packages=find_packages())
+
There are only two differences between this and the trivial one-file
distribution presented in section :ref:`distutils-simple-example`: more
@@ -262,6 +260,8 @@
#include <Numerical/arrayobject.h>
+.. TODO check if it's d2.sysconfig or the new sysconfig module now
+
If you must put the :file:`Numerical` include directory right into your header
search path, though, you can find that directory using the Distutils
:mod:`distutils2.sysconfig` module::
@@ -497,7 +497,11 @@
package_data={'mypkg': ['data/*.dat']})
-.. _distutils-additional-files:
+All the files that match ``package_data`` will be added to the ``MANIFEST``
+file if no template is provided. See :ref:`manifest`.
+
+
+.. _distutils2-additional-files:
Installing Additional Files
===========================
@@ -539,11 +543,11 @@
.. _metadata:
-Additional metadata
-===================
+Metadata reference
+==================
The setup script may include additional metadata beyond the name and version.
-This information includes:
+This table describes required and additional information:
+----------------------+---------------------------+-----------------+--------+
| Meta-Data | Description | Value | Notes |
@@ -564,14 +568,13 @@
+----------------------+---------------------------+-----------------+--------+
| ``home_page`` | home page for the project | URL | \(1) |
+----------------------+---------------------------+-----------------+--------+
-| ``summary`` | short, summary | short string | |
-| | description of the | | |
+| ``summary`` | short description of the | short string | |
| | project | | |
+----------------------+---------------------------+-----------------+--------+
| ``description`` | longer description of the | long string | \(5) |
| | project | | |
+----------------------+---------------------------+-----------------+--------+
-| ``download_url`` | location where the | URL | \(4) |
+| ``download_url`` | location where the | URL | |
| | project may be downloaded | | |
+----------------------+---------------------------+-----------------+--------+
| ``classifiers`` | a list of classifiers | list of strings | \(4) |
@@ -593,16 +596,16 @@
Either the author or the maintainer must be identified.
(4)
- The list of fields is available from the `PyPI website
- <http://pypi.python.org/pypi>`_.
+ The list of classifiers is available from the `PyPI website
+ <http://pypi.python.org/pypi>`_. See also :mod:`distutils2.mkpkg`.
(5)
The ``description`` field is used by PyPI when you are registering a
- project, to build its home page.
+ release, to build its PyPI page.
(6)
The ``license`` field is a text indicating the license covering the
- release where the license is not a selection from the "License" Trove
+ distribution where the license is not a selection from the "License" Trove
classifiers. See the ``Classifier`` field. Notice that
there's a ``licence`` distribution option which is deprecated but still
acts as an alias for ``license``.
@@ -617,7 +620,10 @@
'list of strings'
See below.
-.. TODO move text to :mod:`distutils2.version`, leave a link
+In Python 2.x, "string value" means a unicode object. If a byte string (str or
+bytes) is given, it has to be valid ASCII.
+
+.. TODO move this section to the version document, keep a summary, add a link
Encoding the version information is an art in itself. Python projects generally
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
@@ -671,8 +677,10 @@
installation is broken because they don't read all the way down to the bottom
and see that it's a permission problem.
+.. FIXME DISTUTILS_DEBUG is dead, document logging/warnings here
+
On the other hand, this doesn't help the developer to find the cause of the
failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
-to anything except an empty string, and distutils will now print detailed
-information what it is doing, and prints the full traceback in case an exception
-occurs.
+to anything except an empty string, and Distutils2 will now print detailed
+information about what it is doing, and prints the full traceback in case an
+exception occurs.
diff --git a/docs/source/distutils/uploading.rst b/docs/source/distutils/uploading.rst
--- a/docs/source/distutils/uploading.rst
+++ b/docs/source/distutils/uploading.rst
@@ -4,7 +4,7 @@
Uploading Packages to the Package Index
***************************************
-The Python Package Index (PyPI) not only stores the package info, but also the
+The Python Package Index (PyPI) not only stores the package info, but also the
package data if the author of the package wishes to. The distutils command
:command:`upload` pushes the distribution files to PyPI.
@@ -20,19 +20,20 @@
The :command:`upload` command uses the username, password, and repository URL
from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
-file). If a :command:`register` command was previously called in the same command,
-and if the password was entered in the prompt, :command:`upload` will reuse the
-entered password. This is useful if you do not want to store a clear text
-password in the :file:`$HOME/.pypirc` file.
+file). If a :command:`register` command was previously called in the same
+command, and if the password was entered in the prompt, :command:`upload` will
+reuse the entered password. This is useful if you do not want to store a clear
+text password in the :file:`$HOME/.pypirc` file.
-You can specify another PyPI server with the :option:`--repository=*url*` option::
+You can specify another PyPI server with the :option:`--repository=*url*`
+option::
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
See section :ref:`pypirc` for more on defining several servers.
You can use the :option:`--sign` option to tell :command:`upload` to sign each
-uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
+uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
be available for execution on the system :envvar:`PATH`. You can also specify
which key to use for signing using the :option:`--identity=*name*` option.
@@ -45,28 +46,35 @@
PyPI package display
====================
-The ``long_description`` field plays a special role at PyPI. It is used by
+The ``description`` field plays a special role at PyPI. It is used by
the server to display a home page for the registered package.
If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
syntax for this field, PyPI will parse it and display an HTML output for
the package home page.
-The ``long_description`` field can be attached to a text file located
-in the package::
+The ``description`` field can be filled from a text file located in the
+project::
from distutils2.core import setup
- setup(name='Distutils',
- long_description=open('README.txt'))
+ fp = open('README.txt')
+ try:
+ description = fp.read()
+ finally:
+ fp.close()
+
+ setup(name='Distutils2',
+ description=description)
In that case, :file:`README.txt` is a regular reStructuredText text file located
in the root of the package besides :file:`setup.py`.
To prevent registering broken reStructuredText content, you can use the
:program:`rst2html` program that is provided by the :mod:`docutils` package
-and check the ``long_description`` from the command line::
+and check the ``description`` from the command line::
- $ python setup.py --long-description | rst2html.py > output.html
+ $ python setup.py --description | rst2html.py > output.html
-:mod:`docutils` will display a warning if there's something wrong with your syntax.
+:mod:`docutils` will display a warning if there's something wrong with your
+syntax.
--
Repository URL: http://hg.python.org/distutils2
More information about the Python-checkins
mailing list