diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/intro.rst | 2 | ||||
| -rw-r--r-- | Doc/documenting/markup.rst | 10 | ||||
| -rw-r--r-- | Doc/extending/extending.rst | 2 | ||||
| -rw-r--r-- | Doc/library/2to3.rst | 2 | ||||
| -rw-r--r-- | Doc/library/aifc.rst | 6 | ||||
| -rw-r--r-- | Doc/library/codeop.rst | 2 | ||||
| -rw-r--r-- | Doc/library/configparser.rst | 6 | ||||
| -rw-r--r-- | Doc/library/fileinput.rst | 2 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 6 | ||||
| -rw-r--r-- | Doc/library/http.client.rst | 4 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 2 | ||||
| -rw-r--r-- | Doc/library/locale.rst | 4 | ||||
| -rw-r--r-- | Doc/library/marshal.rst | 2 | ||||
| -rw-r--r-- | Doc/library/os.path.rst | 30 | ||||
| -rw-r--r-- | Doc/library/pickle.rst | 5 | ||||
| -rw-r--r-- | Doc/library/string.rst | 1 | ||||
| -rw-r--r-- | Doc/library/subprocess.rst | 8 | ||||
| -rw-r--r-- | Doc/library/tabnanny.rst | 5 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 2 | ||||
| -rw-r--r-- | Doc/reference/compound_stmts.rst | 2 | ||||
| -rw-r--r-- | Doc/reference/executionmodel.rst | 2 |
21 files changed, 65 insertions, 40 deletions
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 65dbcd7..4b67912 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: ``<stdio.h>``, ``<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 diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index 9bb5193..3577c96 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 8fec680..82cc40b 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 7011f92..90284af 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 182b121..710b14d 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 2c066ef..fb2f326 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 0c8ff65..6f840b9 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -21,10 +21,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 889fdff..76d5d6f 100644 --- a/Doc/library/fileinput.rst +++ b/Doc/library/fileinput.rst @@ -144,7 +144,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 8c0a6ce..c79a8c4 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -359,7 +359,7 @@ are always available. They are listed here in alphabetical order. global and local dictionary, respectively, which may be useful to pass around for use as the second and third argument to :func:`exec`. - .. warning:: + .. note:: The default *locals* act as described for function :func:`locals` below: modifications to the default *locals* dictionary should not be attempted. @@ -591,7 +591,7 @@ are always 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. @@ -1166,7 +1166,7 @@ are always 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/http.client.rst b/Doc/library/http.client.rst index 919b0bf..8ecd7c7 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -52,9 +52,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. .. class:: HTTPResponse(sock[, debuglevel=0][, strict=0]) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 253c303..f002994 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -455,7 +455,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 da3a843..f72a44a 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -377,7 +377,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. @@ -413,7 +413,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 8ef443f..9a2e95d 100644 --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -73,7 +73,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 d04fd09..99d106b 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -23,12 +23,11 @@ applications should use string objects to access all files. their parameters. The result is an object of the same type, if a path or file name is returned. -.. warning:: +.. note:: On Windows, many of these functions do not properly support UNC pathnames. :func:`splitunc` and :func:`ismount` do handle them correctly. - .. note:: Since different operating systems have different path name conventions, there @@ -288,6 +287,33 @@ applications should use string objects to access all files. *unc* will always be the empty string. Availability: Windows. +<<<<<<< .working +======= +.. function:: walk(path, visit, arg) + + Calls the function *visit* with arguments ``(arg, dirname, names)`` for each + directory in the directory tree rooted at *path* (including *path* itself, if it + is a directory). The argument *dirname* specifies the visited directory, the + argument *names* lists the files in the directory (gotten from + ``os.listdir(dirname)``). The *visit* function may modify *names* to influence + the set of directories visited below *dirname*, e.g. to avoid visiting certain + parts of the tree. (The object referred to by *names* must be modified in + place, using :keyword:`del` or slice assignment.) + + .. note:: + + Symbolic links to directories are not treated as subdirectories, and that + :func:`walk` therefore will not visit them. To visit linked directories you must + identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and + invoke :func:`walk` as necessary. + + .. note:: + + This function is deprecated and has been removed in 3.0 in favor of + :func:`os.walk`. + + +>>>>>>> .merge-right.r72009 .. data:: supports_unicode_filenames True if arbitrary Unicode strings can be used as file names (within limitations diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index bb0da80..1c70196 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -66,8 +66,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 @@ -437,6 +437,7 @@ Refer to the section :ref:`pickle-state` for more information about how to use the methods :meth:`__getstate__` and :meth:`__setstate__`. .. note:: + At unpickling time, some methods like :meth:`__getattr__`, :meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the instance. In case those methods rely on some internal invariant being diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 517e209..52bd8f1 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -1,4 +1,3 @@ - :mod:`string` --- Common string operations ========================================== diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index ed9a762..3b6c8cc 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -321,10 +321,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 <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 diff --git a/Doc/library/tabnanny.rst b/Doc/library/tabnanny.rst index f43659f..c5d8236 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 4ecf476..f40dba0 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1085,7 +1085,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 d9d11b5..b8dd17e 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -186,7 +186,7 @@ the built-in function :func:`range` returns an iterator 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 ca8bc2b..92a1b31 100644 --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -222,7 +222,7 @@ selected depending on the class of the instance: it must reference the class of the instance or a base class thereof. The instance can be received by the handler and can carry additional information about the exceptional condition. -.. warning:: +.. note:: Exception messages 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 |