[Python-checkins] cpython (merge default -> default): Merge packaging doc fix

Thu Jun 2 16:43:49 CEST 2011

http://hg.python.org/cpython/rev/475bb98ae813
changeset: 70607:475bb98ae813
parent: 70603:b95096303ed2
parent: 70606:4c6d8ecef78d
user: Éric Araujo <merwok at netwok.org>
date: Thu Jun 02 16:43:25 2011 +0200
summary:
 Merge packaging doc fix
files:
 Doc/distutils/index.rst | 10 +-
 Doc/install/index.rst | 56 +++++++++++
 Doc/library/distutils.rst | 15 +-
 Doc/packaging/index.rst | 2 +-
 Doc/tools/sphinxext/indexcontent.html | 4 +-
 Lib/packaging/command/check.py | 2 +-
 Lib/packaging/tests/support.py | 20 ++-
 Lib/packaging/tests/test_command_check.py | 22 +++-
 Lib/packaging/tests/test_manifest.py | 3 -
 9 files changed, 103 insertions(+), 31 deletions(-)

diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -14,6 +14,10 @@
 make Python modules and extensions easily available to a wider audience with
 very little overhead for build/release/install mechanics.
 
+.. deprecated:: 3.3
+ :mod:`packaging` replaces Distutils. See :ref:`packaging-index` and
+ :ref:`packaging-install-index`.
+
 .. toctree::
 :maxdepth: 2
 :numbered:
@@ -36,9 +40,3 @@
 .. toctree::
 
 install.rst
-
-
-.. seealso::
-
- :ref:`packaging-index` and :ref:`packaging-install-index`
- Documentation of Packaging, the new version of Distutils.
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
new file mode 100644
--- /dev/null
+++ b/Doc/install/index.rst
@@ -0,0 +1,56 @@
+.. _packaging-install-index:
+
+******************************
+ Installing Python Projects
+******************************
+
+:Author: The Fellowship of the Packaging
+:Release: |version|
+:Date: |today|
+
+.. TODO: Fill in XXX comments
+
+.. The audience for this document includes people who don't know anything
+ about Python and aren't about to learn the language just in order to
+ install and maintain it for their users, i.e. system administrators.
+ Thus, I have to be sure to explain the basics at some point:
+ sys.path and PYTHONPATH at least. Should probably give pointers to
+ other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
+
+ Finally, it might be useful to include all the material from my "Care
+ and Feeding of a Python Installation" talk in here somewhere. Yow!
+
+.. topic:: Abstract
+
+ This document describes Packaging from the end-user's point of view: it
+ explains how to extend the functionality of a standard Python installation by
+ building and installing third-party Python modules and applications.
+
+
+This guide is split into a simple overview followed by a longer presentation of
+the :program:`pysetup` script, the Python package management tool used to
+build, distribute, search for, install, remove and list Python distributions.
+
+.. TODO integrate install and pysetup instead of duplicating
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ install
+ pysetup
+ pysetup-config
+ pysetup-servers
+
+
+.. seealso::
+
+ :ref:`packaging-index`
+ The manual for developers of Python projects who want to package and
+ distribute them. This describes how to use :mod:`packaging` to make
+ projects easily found and added to an existing Python installation.
+
+ :mod:`packaging`
+ A library reference for developers of packaging tools wanting to use
+ standalone building blocks like :mod:`~packaging.version` or
+ :mod:`~packaging.metadata`, or extend Packaging itself.
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -12,21 +12,24 @@
 100%-pure Python, or may be extension modules written in C, or may be
 collections of Python packages which include modules coded in both Python and C.
 
-This package is discussed in two separate chapters:
+.. deprecated:: 3.3
+ :mod:`packaging` replaces Distutils. See :ref:`packaging-index` and
+ :ref:`packaging-install-index`.
 
 
+User documentation and API reference are provided in another document:
+
 .. seealso::
 
 :ref:`distutils-index`
 The manual for developers and packagers of Python modules. This describes
 how to prepare :mod:`distutils`\ -based packages so that they may be
- easily installed into an existing Python installation.
+ easily installed into an existing Python installation. If also contains
+ instructions for end-users wanting to install a distutils-based package,
+ :ref:`install-index`.
 
- :ref:`install-index`
- An "administrators" manual which includes information on installing
- modules into an existing Python installation. You do not need to be a
- Python programmer to read this manual.
 
+.. trick to silence a Sphinx warning
 
 .. toctree::
 :hidden:
diff --git a/Doc/packaging/index.rst b/Doc/packaging/index.rst
--- a/Doc/packaging/index.rst
+++ b/Doc/packaging/index.rst
@@ -4,7 +4,7 @@
 Distributing Python Projects
 ##############################
 
-:Authors: The Fellowship of The Packaging
+:Authors: The Fellowship of the Packaging
 :Email: distutils-sig at python.org
 :Release: |version|
 :Date: |today|
diff --git a/Doc/tools/sphinxext/indexcontent.html b/Doc/tools/sphinxext/indexcontent.html
--- a/Doc/tools/sphinxext/indexcontent.html
+++ b/Doc/tools/sphinxext/indexcontent.html
@@ -21,9 +21,9 @@
 <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br/>
 <span class="linkdescr">reference for C/C++ programmers</span></p>
 <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Projects</a><br/>
- <span class="linkdescr">information for installers &amp; sys-admins</span></p>
+ <span class="linkdescr">finding and installing modules and applications</span></p>
 <p class="biglink"><a class="biglink" href="{{ pathto("packaging/index") }}">Distributing Python Projects</a><br/>
- <span class="linkdescr">sharing modules with others</span></p>
+ <span class="linkdescr">packaging and distributing modules and applications</span></p>
 <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br/>
 <span class="linkdescr">guide for documentation authors</span></p>
 <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
diff --git a/Lib/packaging/command/check.py b/Lib/packaging/command/check.py
--- a/Lib/packaging/command/check.py
+++ b/Lib/packaging/command/check.py
@@ -32,7 +32,7 @@
 # XXX we could use a special handler for this, but would need to test
 # if it works even if the logger has a too high level
 self._warnings.append((msg, args))
- return logger.warning(self.get_command_name() + msg, *args)
+ return logger.warning('%s: %s' % (self.get_command_name(), msg), *args)
 
 def run(self):
 """Runs the command."""
diff --git a/Lib/packaging/tests/support.py b/Lib/packaging/tests/support.py
--- a/Lib/packaging/tests/support.py
+++ b/Lib/packaging/tests/support.py
@@ -90,17 +90,23 @@
 def get_logs(self, *levels):
 """Return all log messages with level in *levels*.
 
- Without explicit levels given, returns all messages.
- *levels* defaults to all levels. For log calls with arguments (i.e.
- logger.info('bla bla %s', arg)), the messages
- Returns a list.
+ Without explicit levels given, returns all messages. *levels* defaults
+ to all levels. For log calls with arguments (i.e.
+ logger.info('bla bla %r', arg)), the messages will be formatted before
+ being returned (e.g. "bla bla 'thing'").
+
+ Returns a list. Automatically flushes the loghandler after being
+ called.
 
 Example: self.get_logs(logging.WARN, logging.DEBUG).
 """
 if not levels:
- return [log.getMessage() for log in self.loghandler.buffer]
- return [log.getMessage() for log in self.loghandler.buffer
- if log.levelno in levels]
+ messages = [log.getMessage() for log in self.loghandler.buffer]
+ else:
+ messages = [log.getMessage() for log in self.loghandler.buffer
+ if log.levelno in levels]
+ self.loghandler.flush()
+ return messages
 
 
 class TempdirManager:
diff --git a/Lib/packaging/tests/test_command_check.py b/Lib/packaging/tests/test_command_check.py
--- a/Lib/packaging/tests/test_command_check.py
+++ b/Lib/packaging/tests/test_command_check.py
@@ -36,7 +36,6 @@
 # now let's add the required fields
 # and run it again, to make sure we don't get
 # any warning anymore
- self.loghandler.flush()
 metadata = {'home_page': 'xxx', 'author': 'xxx',
 'author_email': 'xxx',
 'name': 'xxx', 'version': '4.2',
@@ -50,8 +49,10 @@
 self.assertRaises(PackagingSetupError, self._run,
 {'name': 'xxx', 'version': 'xxx'}, **{'strict': 1})
 
+ # clear warnings from the previous calls
+ self.loghandler.flush()
+
 # and of course, no error when all metadata fields are present
- self.loghandler.flush()
 cmd = self._run(metadata, strict=True)
 self.assertEqual([], self.get_logs(logging.WARNING))
 
@@ -70,7 +71,6 @@
 'name': 'xxx', 'version': '4.2',
 'requires_python': '2.4',
 }
- self.loghandler.flush()
 cmd = self._run(metadata)
 self.assertEqual([], self.get_logs(logging.WARNING))
 
@@ -85,9 +85,11 @@
 self.assertRaises(PackagingSetupError, self._run, metadata,
 **{'strict': 1})
 
+ # clear warnings from the previous calls
+ self.loghandler.flush()
+
 # now with correct version format again
 metadata['version'] = '4.2'
- self.loghandler.flush()
 cmd = self._run(metadata, strict=True)
 self.assertEqual([], self.get_logs(logging.WARNING))
 
@@ -100,7 +102,6 @@
 cmd.check_restructuredtext()
 self.assertEqual(len(self.get_logs(logging.WARNING)), 1)
 
- self.loghandler.flush()
 pkg_info, dist = self.create_dist(description='title\n=====\n\ntest')
 cmd = check(dist)
 cmd.check_restructuredtext()
@@ -123,6 +124,17 @@
 cmd.check_hooks_resolvable()
 self.assertEqual(len(self.get_logs(logging.WARNING)), 1)
 
+ def test_warn(self):
+ _, dist = self.create_dist()
+ cmd = check(dist)
+ self.assertEqual([], self.get_logs())
+ cmd.warn('hello')
+ self.assertEqual(['check: hello'], self.get_logs())
+ cmd.warn('hello %s', 'world')
+ self.assertEqual(['check: hello world'], self.get_logs())
+ cmd.warn('hello %s %s', 'beautiful', 'world')
+ self.assertEqual(['check: hello beautiful world'], self.get_logs())
+
 
 def test_suite():
 return unittest.makeSuite(CheckTestCase)
diff --git a/Lib/packaging/tests/test_manifest.py b/Lib/packaging/tests/test_manifest.py
--- a/Lib/packaging/tests/test_manifest.py
+++ b/Lib/packaging/tests/test_manifest.py
@@ -50,9 +50,6 @@
 for warning in warnings:
 self.assertIn('no files found matching', warning)
 
- # reset logs for the next assert
- self.loghandler.flush()
-
 # manifest also accepts file-like objects
 with open(MANIFEST) as f:
 manifest.read_template(f)
-- 
Repository URL: http://hg.python.org/cpython
