[Python-checkins] r72009 - in python/trunk/Doc: c-api/intro.rst documenting/markup.rst extending/extending.rst library/2to3.rst library/aifc.rst library/codeop.rst library/configparser.rst library/fileinput.rst library/functions.rst library/httplib.rst library/inspect.rst library/locale.rst library/marshal.rst library/os.path.rst library/pickle.rst library/string.rst library/subprocess.rst library/tabnanny.rst library/unittest.rst reference/compound_stmts.rst reference/executionmodel.rst
georg.brandl
python-checkins at python.org
Mon Apr 27 17:29:10 CEST 2009
Author: georg.brandl
Date: Mon Apr 27 17:29:09 2009
New Revision: 72009
Log:
Demote warnings to notices where appropriate, following the goal that as few "red box" warnings
should clutter the docs as possible. Part 1: stuff that gets merged to Py3k.
Modified:
python/trunk/Doc/c-api/intro.rst
python/trunk/Doc/documenting/markup.rst
python/trunk/Doc/extending/extending.rst
python/trunk/Doc/library/2to3.rst
python/trunk/Doc/library/aifc.rst
python/trunk/Doc/library/codeop.rst
python/trunk/Doc/library/configparser.rst
python/trunk/Doc/library/fileinput.rst
python/trunk/Doc/library/functions.rst
python/trunk/Doc/library/httplib.rst
python/trunk/Doc/library/inspect.rst
python/trunk/Doc/library/locale.rst
python/trunk/Doc/library/marshal.rst
python/trunk/Doc/library/os.path.rst
python/trunk/Doc/library/pickle.rst
python/trunk/Doc/library/string.rst
python/trunk/Doc/library/subprocess.rst
python/trunk/Doc/library/tabnanny.rst
python/trunk/Doc/library/unittest.rst
python/trunk/Doc/reference/compound_stmts.rst
python/trunk/Doc/reference/executionmodel.rst
Modified: python/trunk/Doc/c-api/intro.rst
==============================================================================
--- python/trunk/Doc/c-api/intro.rst (original)
+++ python/trunk/Doc/c-api/intro.rst Mon Apr 27 17:29:09 2009
@@ -44,7 +44,7 @@
``<string.h>``, ``<errno.h>``, ``<limits.h>``, and ``<stdlib.h>`` (if
available).
-.. warning::
+.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
Modified: python/trunk/Doc/documenting/markup.rst
==============================================================================
--- python/trunk/Doc/documenting/markup.rst (original)
+++ python/trunk/Doc/documenting/markup.rst Mon Apr 27 17:29:09 2009
@@ -594,11 +594,11 @@
.. describe:: warning
- An important bit of information about an API that a user should be very aware
- of when using whatever bit of API the warning pertains to. The content of
- the directive should be written in complete sentences and include all
- appropriate punctuation. This differs from ``note`` in that it is recommended
- over ``note`` for information regarding security.
+ An important bit of information about an API that a user should be aware of
+ when using whatever bit of API the warning pertains to. The content of the
+ directive should be written in complete sentences and include all appropriate
+ punctuation. This should only be chosen over ``note`` for information
+ regarding the possibility of crashes, data loss, or security implications.
.. describe:: versionadded
Modified: python/trunk/Doc/extending/extending.rst
==============================================================================
--- python/trunk/Doc/extending/extending.rst (original)
+++ python/trunk/Doc/extending/extending.rst Mon Apr 27 17:29:09 2009
@@ -47,7 +47,7 @@
which pulls in the Python API (you can add a comment describing the purpose of
the module and a copyright notice if you like).
-.. warning::
+.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
Modified: python/trunk/Doc/library/2to3.rst
==============================================================================
--- python/trunk/Doc/library/2to3.rst (original)
+++ python/trunk/Doc/library/2to3.rst Mon Apr 27 17:29:09 2009
@@ -354,7 +354,7 @@
.. moduleauthor:: Collin Winter
-.. warning::
+.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
Modified: python/trunk/Doc/library/aifc.rst
==============================================================================
--- python/trunk/Doc/library/aifc.rst (original)
+++ python/trunk/Doc/library/aifc.rst Mon Apr 27 17:29:09 2009
@@ -1,4 +1,3 @@
-
:mod:`aifc` --- Read and write AIFF and AIFC files
==================================================
@@ -16,10 +15,11 @@
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
-.. warning::
+.. note::
Some operations may only work under IRIX; these will raise :exc:`ImportError`
- when attempting to import the :mod:`cl` module, which is only available on IRIX.
+ when attempting to import the :mod:`cl` module, which is only available on
+ IRIX.
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
Modified: python/trunk/Doc/library/codeop.rst
==============================================================================
--- python/trunk/Doc/library/codeop.rst (original)
+++ python/trunk/Doc/library/codeop.rst Mon Apr 27 17:29:09 2009
@@ -42,7 +42,7 @@
(``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
other value will cause :exc:`ValueError` to be raised.
- .. warning::
+ .. note::
It is possible (but not likely) that the parser stops parsing with a
successful outcome before reaching the end of the source; in this case,
Modified: python/trunk/Doc/library/configparser.rst
==============================================================================
--- python/trunk/Doc/library/configparser.rst (original)
+++ python/trunk/Doc/library/configparser.rst Mon Apr 27 17:29:09 2009
@@ -27,10 +27,10 @@
can use this to write Python programs which can be customized by end users
easily.
-.. warning::
+.. note::
- This library does *not* interpret or write the value-type prefixes used in the
- Windows Registry extended version of INI syntax.
+ This library does *not* interpret or write the value-type prefixes used in
+ the Windows Registry extended version of INI syntax.
The configuration file consists of sections, led by a ``[section]`` header and
followed by ``name: value`` entries, with continuations in the style of
Modified: python/trunk/Doc/library/fileinput.rst
==============================================================================
--- python/trunk/Doc/library/fileinput.rst (original)
+++ python/trunk/Doc/library/fileinput.rst Mon Apr 27 17:29:09 2009
@@ -150,7 +150,7 @@
it is deleted when the output file is closed. In-place filtering is disabled
when standard input is read.
-.. warning::
+.. note::
The current implementation does not work for MS-DOS 8+3 filesystems.
Modified: python/trunk/Doc/library/functions.rst
==============================================================================
--- python/trunk/Doc/library/functions.rst (original)
+++ python/trunk/Doc/library/functions.rst Mon Apr 27 17:29:09 2009
@@ -364,7 +364,7 @@
If both dictionaries are omitted, the expression is executed in the environment
where :func:`execfile` is called. The return value is ``None``.
- .. warning::
+ .. note::
The default *locals* act as described for function :func:`locals` below:
modifications to the default *locals* dictionary should not be attempted. Pass
@@ -633,7 +633,7 @@
Update and return a dictionary representing the current local symbol table.
- .. warning::
+ .. note::
The contents of this dictionary should not be modified; changes may not affect
the values of local variables used by the interpreter.
@@ -1363,7 +1363,7 @@
else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
to the object's symbol table.
- .. warning::
+ .. note::
The returned dictionary should not be modified:
the effects on the corresponding symbol table are undefined. [#]_
Modified: python/trunk/Doc/library/httplib.rst
==============================================================================
--- python/trunk/Doc/library/httplib.rst (original)
+++ python/trunk/Doc/library/httplib.rst Mon Apr 27 17:29:09 2009
@@ -68,9 +68,9 @@
formatted file that contains your private key. *cert_file* is a PEM formatted
certificate chain file.
- .. warning::
+ .. note::
- This does not do any certificate verification!
+ This does not do any certificate verification.
.. versionadded:: 2.0
Modified: python/trunk/Doc/library/inspect.rst
==============================================================================
--- python/trunk/Doc/library/inspect.rst (original)
+++ python/trunk/Doc/library/inspect.rst Mon Apr 27 17:29:09 2009
@@ -510,7 +510,7 @@
the function name, a list of lines of context from the source code, and the
index of the current line within that list.
-.. warning::
+.. note::
Keeping references to frame objects, as found in the first element of the frame
records these functions return, can cause your program to create reference
Modified: python/trunk/Doc/library/locale.rst
==============================================================================
--- python/trunk/Doc/library/locale.rst (original)
+++ python/trunk/Doc/library/locale.rst Mon Apr 27 17:29:09 2009
@@ -398,7 +398,7 @@
Return name of the n-th day of the week.
- .. warning::
+ .. note::
This follows the US convention of :const:`DAY_1` being Sunday, not the
international convention (ISO 8601) that Monday is the first day of the week.
@@ -434,7 +434,7 @@
Return a regular expression that can be used with the regex function to
recognize a positive response to a yes/no question.
- .. warning::
+ .. note::
The expression is in the syntax suitable for the :cfunc:`regex` function from
the C library, which might differ from the syntax used in :mod:`re`.
Modified: python/trunk/Doc/library/marshal.rst
==============================================================================
--- python/trunk/Doc/library/marshal.rst (original)
+++ python/trunk/Doc/library/marshal.rst Mon Apr 27 17:29:09 2009
@@ -85,7 +85,7 @@
file must be an open file object opened in binary mode (``'rb'`` or
``'r+b'``).
- .. warning::
+ .. note::
If an object containing an unsupported type was marshalled with :func:`dump`,
:func:`load` will substitute ``None`` for the unmarshallable type.
Modified: python/trunk/Doc/library/os.path.rst
==============================================================================
--- python/trunk/Doc/library/os.path.rst (original)
+++ python/trunk/Doc/library/os.path.rst Mon Apr 27 17:29:09 2009
@@ -10,7 +10,7 @@
write files see :func:`open`, and for accessing the filesystem see the
:mod:`os` module.
-.. warning::
+.. note::
On Windows, many of these functions do not properly support UNC pathnames.
:func:`splitunc` and :func:`ismount` do handle them correctly.
@@ -317,7 +317,7 @@
identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and
invoke :func:`walk` as necessary.
- .. warning::
+ .. note::
This function is deprecated and has been removed in 3.0 in favor of
:func:`os.walk`.
Modified: python/trunk/Doc/library/pickle.rst
==============================================================================
--- python/trunk/Doc/library/pickle.rst (original)
+++ python/trunk/Doc/library/pickle.rst Mon Apr 27 17:29:09 2009
@@ -77,8 +77,8 @@
.. warning::
The :mod:`pickle` module is not intended to be secure against erroneous or
- maliciously constructed data. Never unpickle data received from an untrusted or
- unauthenticated source.
+ maliciously constructed data. Never unpickle data received from an untrusted
+ or unauthenticated source.
Note that serialization is a more primitive notion than persistence; although
:mod:`pickle` reads and writes file objects, it does not handle the issue of
@@ -453,7 +453,7 @@
:meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
dictionary and these methods can do what they want. [#]_
- .. warning::
+ .. note::
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
value, the :meth:`__setstate__` method will not be called.
Modified: python/trunk/Doc/library/string.rst
==============================================================================
--- python/trunk/Doc/library/string.rst (original)
+++ python/trunk/Doc/library/string.rst Mon Apr 27 17:29:09 2009
@@ -599,7 +599,7 @@
map each character in *from* into the character at the same position in *to*;
*from* and *to* must have the same length.
- .. warning::
+ .. note::
Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
arguments; in some locales, these don't have the same length. For case
Modified: python/trunk/Doc/library/subprocess.rst
==============================================================================
--- python/trunk/Doc/library/subprocess.rst (original)
+++ python/trunk/Doc/library/subprocess.rst Mon Apr 27 17:29:09 2009
@@ -301,10 +301,10 @@
.. warning::
- Use :meth:`communicate` rather than :meth:`.stdin.write`,
- :meth:`.stdout.read` or :meth:`.stderr.read` to avoid deadlocks due
- to any of the other OS pipe buffers filling up and blocking the child
- process.
+ Use :meth:`communicate` rather than :attr:`.stdin.write <stdin>`,
+ :attr:`.stdout.read <stdout>` or :attr:`.stderr.read <stderr>` to avoid
+ deadlocks due to any of the other OS pipe buffers filling up and blocking the
+ child process.
.. attribute:: Popen.stdin
Modified: python/trunk/Doc/library/tabnanny.rst
==============================================================================
--- python/trunk/Doc/library/tabnanny.rst (original)
+++ python/trunk/Doc/library/tabnanny.rst Mon Apr 27 17:29:09 2009
@@ -1,4 +1,3 @@
-
:mod:`tabnanny` --- Detection of ambiguous indentation
======================================================
@@ -14,9 +13,9 @@
is possible to import it into an IDE and use the function :func:`check`
described below.
-.. warning::
+.. note::
- The API provided by this module is likely to change in future releases; such
+ The API provided by this module is likely to change in future releases; such
changes may not be backward compatible.
Modified: python/trunk/Doc/library/unittest.rst
==============================================================================
--- python/trunk/Doc/library/unittest.rst (original)
+++ python/trunk/Doc/library/unittest.rst Mon Apr 27 17:29:09 2009
@@ -1086,7 +1086,7 @@
creates an instance of the class for each test method defined for the
class.
- .. warning::
+ .. note::
While using a hierarchy of :class:`TestCase`\ -derived classes can be
convenient in sharing fixtures and helper functions, defining test
Modified: python/trunk/Doc/reference/compound_stmts.rst
==============================================================================
--- python/trunk/Doc/reference/compound_stmts.rst (original)
+++ python/trunk/Doc/reference/compound_stmts.rst Mon Apr 27 17:29:09 2009
@@ -178,7 +178,7 @@
effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
``[0, 1, 2]``.
-.. warning::
+.. note::
.. index::
single: loop; over mutable sequence
Modified: python/trunk/Doc/reference/executionmodel.rst
==============================================================================
--- python/trunk/Doc/reference/executionmodel.rst (original)
+++ python/trunk/Doc/reference/executionmodel.rst Mon Apr 27 17:29:09 2009
@@ -231,7 +231,7 @@
:keyword:`except` clause is selected by object identity. An arbitrary value can
be raised along with the identifying string which can be passed to the handler.
-.. warning::
+.. note::
Messages to exceptions are not part of the Python API. Their contents may
change from one version of Python to the next without warning and should not be
More information about the Python-checkins
mailing list