[Python-checkins] cpython (merge default -> default): Merge packaging doc fix
eric.araujo
python-checkins at python.org
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 & 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
More information about the Python-checkins
mailing list