From 16a57f6a343d7bacd85e79c3edb64cd832d8a9ac Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 27 Apr 2009 15:29:09 +0000 Subject: [PATCH] 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. --- Doc/c-api/intro.rst | 2 +- Doc/documenting/markup.rst | 10 +++++----- Doc/extending/extending.rst | 2 +- Doc/library/2to3.rst | 2 +- Doc/library/aifc.rst | 6 +++--- Doc/library/codeop.rst | 2 +- Doc/library/configparser.rst | 6 +++--- Doc/library/fileinput.rst | 2 +- Doc/library/functions.rst | 6 +++--- Doc/library/httplib.rst | 4 ++-- Doc/library/inspect.rst | 2 +- Doc/library/locale.rst | 4 ++-- Doc/library/marshal.rst | 2 +- Doc/library/os.path.rst | 4 ++-- Doc/library/pickle.rst | 6 +++--- Doc/library/string.rst | 2 +- Doc/library/subprocess.rst | 8 ++++---- Doc/library/tabnanny.rst | 5 ++--- Doc/library/unittest.rst | 2 +- Doc/reference/compound_stmts.rst | 2 +- Doc/reference/executionmodel.rst | 2 +- 21 files changed, 40 insertions(+), 41 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index e8a3fc4851e..c56000efa4c 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -44,7 +44,7 @@ This implies inclusion of the following standard headers: ````, ````, ````, ````, and ```` (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 diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index 3ca8983ee1f..1d1023a5d13 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -594,11 +594,11 @@ units as well as normal text: .. 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 diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index b3ceb944f0b..d052ec24c65 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -47,7 +47,7 @@ The first line of our file can be:: 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 diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 7011f92b2ba..90284afa1c6 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -354,7 +354,7 @@ and off individually. They are described here in more detail. .. moduleauthor:: Collin Winter -.. warning:: +.. note:: The :mod:`lib2to3` API should be considered unstable and may change drastically in the future. diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst index e3bb51a65c7..062f1f21d24 100644 --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -1,4 +1,3 @@ - :mod:`aifc` --- Read and write AIFF and AIFC files ================================================== @@ -16,10 +15,11 @@ AIFF is Audio Interchange File Format, a format for storing digital audio 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 diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst index 39981cab0d5..674c51fc4b1 100644 --- a/Doc/library/codeop.rst +++ b/Doc/library/codeop.rst @@ -42,7 +42,7 @@ To do just the former: (``'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, diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 0c5bb15ba49..2eeefb0cd63 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -27,10 +27,10 @@ structure similar to what you would find on Microsoft Windows INI files. You 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 diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst index 269d8560f6e..3253a07b417 100644 --- a/Doc/library/fileinput.rst +++ b/Doc/library/fileinput.rst @@ -150,7 +150,7 @@ and the backup file remains around; by default, the extension is ``'.bak'`` and 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. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 078cfad6eeb..9eaffab0d25 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -364,7 +364,7 @@ available. They are listed here in alphabetical order. 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 @@ available. They are listed here in alphabetical order. 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 @@ available. They are listed here in alphabetical order. 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. [#]_ diff --git a/Doc/library/httplib.rst b/Doc/library/httplib.rst index 874fd54aeeb..e48c95c732d 100644 --- a/Doc/library/httplib.rst +++ b/Doc/library/httplib.rst @@ -68,9 +68,9 @@ The module provides the following classes: 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 diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 5af020e9e76..bea12c9f634 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -510,7 +510,7 @@ six items: the frame object, the filename, the line number of the current line, 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 diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index 750fb2e1a32..0366d779665 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -398,7 +398,7 @@ descriptions are taken from the corresponding description in the GNU C library. 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 @@ descriptions are taken from the corresponding description in the GNU C library. 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`. diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst index a9d6ea823f4..84fb138bfba 100644 --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -85,7 +85,7 @@ The module defines these functions: 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. diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 0e7f3765168..2075468d1c8 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -10,7 +10,7 @@ This module implements some useful functions on pathnames. To read or 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 @@ write files see :func:`open`, and for accessing the filesystem see the 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`. diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index f6b7ae42b30..a3e5ad47654 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -77,8 +77,8 @@ The :mod:`pickle` module differs from :mod:`marshal` several significant ways: .. 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 @@ Pickling and unpickling normal class instances :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. diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 6ca08739db6..d17ac7a3ccd 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -599,7 +599,7 @@ They are not available as string methods. 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 diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 685e94199ad..c95566bf20e 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -301,10 +301,10 @@ The following attributes are also available: .. 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 `, + :attr:`.stdout.read ` or :attr:`.stderr.read ` to avoid + deadlocks due to any of the other OS pipe buffers filling up and blocking the + child process. .. attribute:: Popen.stdin diff --git a/Doc/library/tabnanny.rst b/Doc/library/tabnanny.rst index 875f3aac86e..b86971df33b 100644 --- a/Doc/library/tabnanny.rst +++ b/Doc/library/tabnanny.rst @@ -1,4 +1,3 @@ - :mod:`tabnanny` --- Detection of ambiguous indentation ====================================================== @@ -14,9 +13,9 @@ For the time being this module is intended to be called as a script. However it 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. diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 50314cd85ce..6b19c29ace4 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1086,7 +1086,7 @@ Loading and running tests 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 diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 4d7addbbd2b..3c716b286f0 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -178,7 +178,7 @@ function :func:`range` returns a sequence of integers suitable to emulate the 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 diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst index 05f8b928c42..9690a9391b7 100644 --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -231,7 +231,7 @@ Exceptions can also be identified by strings, in which case the :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