[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