mirror of https://github.com/python/cpython
Merge doc fixes from 3.5
This commit is contained in:
commit
4659ddc433
|
@ -2165,8 +2165,8 @@ Speaking logging messages
|
|||
-------------------------
|
||||
|
||||
There might be situations when it is desirable to have logging messages rendered
|
||||
in an audible rather than a visible format. This is easy to do if you have text-
|
||||
to-speech (TTS) functionality available in your system, even if it doesn't have
|
||||
in an audible rather than a visible format. This is easy to do if you have
|
||||
text-to-speech (TTS) functionality available in your system, even if it doesn't have
|
||||
a Python binding. Most TTS systems have a command line program you can run, and
|
||||
this can be invoked from a handler using :mod:`subprocess`. It's assumed here
|
||||
that TTS command line programs won't expect to interact with users or take a
|
||||
|
|
|
@ -174,7 +174,7 @@ ArgumentParser objects
|
|||
* conflict_handler_ - The strategy for resolving conflicting optionals
|
||||
(usually unnecessary)
|
||||
|
||||
* add_help_ - Add a -h/--help option to the parser (default: ``True``)
|
||||
* add_help_ - Add a ``-h/--help`` option to the parser (default: ``True``)
|
||||
|
||||
* allow_abbrev_ - Allows long options to be abbreviated if the
|
||||
abbreviation is unambiguous. (default: ``True``)
|
||||
|
@ -211,7 +211,7 @@ The help for this program will display ``myprogram.py`` as the program name
|
|||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
$ cd ..
|
||||
$ python subdir\myprogram.py --help
|
||||
$ python subdir/myprogram.py --help
|
||||
usage: myprogram.py [-h] [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
|
|
|
@ -105,8 +105,8 @@ in :mod:`logging` itself) and defining handlers which are declared either in
|
|||
:param disable_existing_loggers: If specified as ``False``, loggers which
|
||||
exist when this call is made are left
|
||||
enabled. The default is ``True`` because this
|
||||
enables old behaviour in a backward-
|
||||
compatible way. This behaviour is to
|
||||
enables old behaviour in a
|
||||
backward-compatible way. This behaviour is to
|
||||
disable any existing loggers unless they or
|
||||
their ancestors are explicitly named in the
|
||||
logging configuration.
|
||||
|
|
|
@ -946,8 +946,8 @@ possible, while any potentially slow operations (such as sending an email via
|
|||
.. class:: QueueHandler(queue)
|
||||
|
||||
Returns a new instance of the :class:`QueueHandler` class. The instance is
|
||||
initialized with the queue to send messages to. The queue can be any queue-
|
||||
like object; it's used as-is by the :meth:`enqueue` method, which needs
|
||||
initialized with the queue to send messages to. The queue can be any
|
||||
queue-like object; it's used as-is by the :meth:`enqueue` method, which needs
|
||||
to know how to send messages to it.
|
||||
|
||||
|
||||
|
@ -1002,8 +1002,8 @@ possible, while any potentially slow operations (such as sending an email via
|
|||
|
||||
Returns a new instance of the :class:`QueueListener` class. The instance is
|
||||
initialized with the queue to send messages to and a list of handlers which
|
||||
will handle entries placed on the queue. The queue can be any queue-
|
||||
like object; it's passed as-is to the :meth:`dequeue` method, which needs
|
||||
will handle entries placed on the queue. The queue can be any queue-like
|
||||
object; it's passed as-is to the :meth:`dequeue` method, which needs
|
||||
to know how to get messages from it. If ``respect_handler_level`` is ``True``,
|
||||
a handler's level is respected (compared with the level for the message) when
|
||||
deciding whether to pass messages to that handler; otherwise, the behaviour
|
||||
|
|
|
@ -32,8 +32,8 @@ sending a graphics file.
|
|||
|
||||
.. function:: encode(input, output, quotetabs, header=False)
|
||||
|
||||
Encode the contents of the *input* file and write the resulting quoted-
|
||||
printable data to the *output* file. *input* and *output* must be
|
||||
Encode the contents of the *input* file and write the resulting quoted-printable
|
||||
data to the *output* file. *input* and *output* must be
|
||||
:term:`binary file objects <file object>`. *quotetabs*, a flag which controls
|
||||
whether to encode embedded spaces and tabs must be provideda and when true it
|
||||
encodes such embedded whitespace, and when false it leaves them unencoded.
|
||||
|
|
|
@ -1342,8 +1342,8 @@ to sockets.
|
|||
to transmit as opposed to sending the file until EOF is reached. File
|
||||
position is updated on return or also in case of error in which case
|
||||
:meth:`file.tell() <io.IOBase.tell>` can be used to figure out the number of
|
||||
bytes which were sent. The socket must be of :const:`SOCK_STREAM` type. Non-
|
||||
blocking sockets are not supported.
|
||||
bytes which were sent. The socket must be of :const:`SOCK_STREAM` type.
|
||||
Non-blocking sockets are not supported.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
|
|
@ -1637,11 +1637,11 @@ Loading and running tests
|
|||
|
||||
The method optionally resolves *name* relative to the given *module*.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
If an :exc:`ImportError` or :exc:`AttributeError` occurs while traversing
|
||||
*name* then a synthetic test that raises that error when run will be
|
||||
returned. These errors are included in the errors accumulated by
|
||||
self.errors.
|
||||
.. versionchanged:: 3.5
|
||||
If an :exc:`ImportError` or :exc:`AttributeError` occurs while traversing
|
||||
*name* then a synthetic test that raises that error when run will be
|
||||
returned. These errors are included in the errors accumulated by
|
||||
self.errors.
|
||||
|
||||
|
||||
.. method:: loadTestsFromNames(names, module=None)
|
||||
|
|
|
@ -145,8 +145,8 @@ strings. Unicode uses 16-bit numbers to represent characters instead of the
|
|||
8-bit number used by ASCII, meaning that 65,536 distinct characters can be
|
||||
supported.
|
||||
|
||||
The final interface for Unicode support was arrived at through countless often-
|
||||
stormy discussions on the python-dev mailing list, and mostly implemented by
|
||||
The final interface for Unicode support was arrived at through countless
|
||||
often-stormy discussions on the python-dev mailing list, and mostly implemented by
|
||||
Marc-André Lemburg, based on a Unicode string type implementation by Fredrik
|
||||
Lundh. A detailed explanation of the interface was written up as :pep:`100`,
|
||||
"Python Unicode Integration". This article will simply cover the most
|
||||
|
@ -885,8 +885,8 @@ interfaces for processing XML have become common: SAX2 (version 2 of the Simple
|
|||
API for XML) provides an event-driven interface with some similarities to
|
||||
:mod:`xmllib`, and the DOM (Document Object Model) provides a tree-based
|
||||
interface, transforming an XML document into a tree of nodes that can be
|
||||
traversed and modified. Python 2.0 includes a SAX2 interface and a stripped-
|
||||
down DOM interface as part of the :mod:`xml` package. Here we will give a brief
|
||||
traversed and modified. Python 2.0 includes a SAX2 interface and a stripped-down
|
||||
DOM interface as part of the :mod:`xml` package. Here we will give a brief
|
||||
overview of these new interfaces; consult the Python documentation or the source
|
||||
code for complete details. The Python XML SIG is also working on improved
|
||||
documentation.
|
||||
|
|
|
@ -159,8 +159,8 @@ precede any statement that will result in bytecodes being produced.
|
|||
PEP 207: Rich Comparisons
|
||||
=========================
|
||||
|
||||
In earlier versions, Python's support for implementing comparisons on user-
|
||||
defined classes and extension types was quite simple. Classes could implement a
|
||||
In earlier versions, Python's support for implementing comparisons on user-defined
|
||||
classes and extension types was quite simple. Classes could implement a
|
||||
:meth:`__cmp__` method that was given two instances of a class, and could only
|
||||
return 0 if they were equal or +1 or -1 if they weren't; the method couldn't
|
||||
raise an exception or return anything other than a Boolean value. Users of
|
||||
|
@ -465,11 +465,11 @@ Windows being the primary examples; on these systems, it's impossible to
|
|||
distinguish the filenames ``FILE.PY`` and ``file.py``, even though they do store
|
||||
the file's name in its original case (they're case-preserving, too).
|
||||
|
||||
In Python 2.1, the :keyword:`import` statement will work to simulate case-
|
||||
sensitivity on case-insensitive platforms. Python will now search for the first
|
||||
In Python 2.1, the :keyword:`import` statement will work to simulate case-sensitivity
|
||||
on case-insensitive platforms. Python will now search for the first
|
||||
case-sensitive match by default, raising an :exc:`ImportError` if no such file
|
||||
is found, so ``import file`` will not import a module named ``FILE.PY``. Case-
|
||||
insensitive matching can be requested by setting the :envvar:`PYTHONCASEOK`
|
||||
is found, so ``import file`` will not import a module named ``FILE.PY``.
|
||||
Case-insensitive matching can be requested by setting the :envvar:`PYTHONCASEOK`
|
||||
environment variable before starting the Python interpreter.
|
||||
|
||||
.. ======================================================================
|
||||
|
@ -481,8 +481,8 @@ PEP 217: Interactive Display Hook
|
|||
When using the Python interpreter interactively, the output of commands is
|
||||
displayed using the built-in :func:`repr` function. In Python 2.1, the variable
|
||||
:func:`sys.displayhook` can be set to a callable object which will be called
|
||||
instead of :func:`repr`. For example, you can set it to a special pretty-
|
||||
printing function::
|
||||
instead of :func:`repr`. For example, you can set it to a special
|
||||
pretty-printing function::
|
||||
|
||||
>>> # Create a recursive data structure
|
||||
... L = [1,2,3]
|
||||
|
|
|
@ -962,8 +962,8 @@ New and Improved Modules
|
|||
* The new :mod:`hmac` module implements the HMAC algorithm described by
|
||||
:rfc:`2104`. (Contributed by Gerhard Häring.)
|
||||
|
||||
* Several functions that originally returned lengthy tuples now return pseudo-
|
||||
sequences that still behave like tuples but also have mnemonic attributes such
|
||||
* Several functions that originally returned lengthy tuples now return
|
||||
pseudo-sequences that still behave like tuples but also have mnemonic attributes such
|
||||
as memberst_mtime or :attr:`tm_year`. The enhanced functions include
|
||||
:func:`stat`, :func:`fstat`, :func:`statvfs`, and :func:`fstatvfs` in the
|
||||
:mod:`os` module, and :func:`localtime`, :func:`gmtime`, and :func:`strptime` in
|
||||
|
@ -1141,8 +1141,8 @@ Some of the more notable changes are:
|
|||
|
||||
The most significant change is the ability to build Python as a framework,
|
||||
enabled by supplying the :option:`!--enable-framework` option to the configure
|
||||
script when compiling Python. According to Jack Jansen, "This installs a self-
|
||||
contained Python installation plus the OS X framework "glue" into
|
||||
script when compiling Python. According to Jack Jansen, "This installs a
|
||||
self-contained Python installation plus the OS X framework "glue" into
|
||||
:file:`/Library/Frameworks/Python.framework` (or another location of choice).
|
||||
For now there is little immediate added benefit to this (actually, there is the
|
||||
disadvantage that you have to change your PATH to be able to find Python), but
|
||||
|
|
|
@ -86,8 +86,8 @@ The union and intersection of sets can be computed with the :meth:`union` and
|
|||
It's also possible to take the symmetric difference of two sets. This is the
|
||||
set of all elements in the union that aren't in the intersection. Another way
|
||||
of putting it is that the symmetric difference contains all elements that are in
|
||||
exactly one set. Again, there's an alternative notation (``^``), and an in-
|
||||
place version with the ungainly name :meth:`symmetric_difference_update`. ::
|
||||
exactly one set. Again, there's an alternative notation (``^``), and an
|
||||
in-place version with the ungainly name :meth:`symmetric_difference_update`. ::
|
||||
|
||||
>>> S1 = sets.Set([1,2,3,4])
|
||||
>>> S2 = sets.Set([3,4,5,6])
|
||||
|
@ -288,8 +288,8 @@ use characters outside of the usual alphanumerics.
|
|||
PEP 273: Importing Modules from ZIP Archives
|
||||
============================================
|
||||
|
||||
The new :mod:`zipimport` module adds support for importing modules from a ZIP-
|
||||
format archive. You don't need to import the module explicitly; it will be
|
||||
The new :mod:`zipimport` module adds support for importing modules from a
|
||||
ZIP-format archive. You don't need to import the module explicitly; it will be
|
||||
automatically imported if a ZIP archive's filename is added to ``sys.path``.
|
||||
For example:
|
||||
|
||||
|
@ -375,8 +375,8 @@ PEP 278: Universal Newline Support
|
|||
==================================
|
||||
|
||||
The three major operating systems used today are Microsoft Windows, Apple's
|
||||
Macintosh OS, and the various Unix derivatives. A minor irritation of cross-
|
||||
platform work is that these three platforms all use different characters to
|
||||
Macintosh OS, and the various Unix derivatives. A minor irritation of
|
||||
cross-platform work is that these three platforms all use different characters to
|
||||
mark the ends of lines in text files. Unix uses the linefeed (ASCII character
|
||||
10), MacOS uses the carriage return (ASCII character 13), and Windows uses a
|
||||
two-character sequence of a carriage return plus a newline.
|
||||
|
|
|
@ -517,8 +517,8 @@ Sometimes you can see this inaccuracy when the number is printed::
|
|||
>>> 1.1
|
||||
1.1000000000000001
|
||||
|
||||
The inaccuracy isn't always visible when you print the number because the FP-to-
|
||||
decimal-string conversion is provided by the C library, and most C libraries try
|
||||
The inaccuracy isn't always visible when you print the number because the
|
||||
FP-to-decimal-string conversion is provided by the C library, and most C libraries try
|
||||
to produce sensible output. Even if it's not displayed, however, the inaccuracy
|
||||
is still there and subsequent operations can magnify the error.
|
||||
|
||||
|
@ -595,8 +595,8 @@ exponent::
|
|||
...
|
||||
decimal.InvalidOperation: x ** (non-integer)
|
||||
|
||||
You can combine :class:`Decimal` instances with integers, but not with floating-
|
||||
point numbers::
|
||||
You can combine :class:`Decimal` instances with integers, but not with
|
||||
floating-point numbers::
|
||||
|
||||
>>> a + 4
|
||||
Decimal("39.72")
|
||||
|
@ -684,8 +684,8 @@ includes a quick-start tutorial and a reference.
|
|||
Raymond Hettinger, Aahz, and Tim Peters.
|
||||
|
||||
http://www.lahey.com/float.htm
|
||||
The article uses Fortran code to illustrate many of the problems that floating-
|
||||
point inaccuracy can cause.
|
||||
The article uses Fortran code to illustrate many of the problems that
|
||||
floating-point inaccuracy can cause.
|
||||
|
||||
http://speleotrove.com/decimal/
|
||||
A description of a decimal-based representation. This representation is being
|
||||
|
@ -741,8 +741,8 @@ functions in Python's implementation required that the numeric locale remain set
|
|||
to the ``'C'`` locale. Often this was because the code was using the C
|
||||
library's :c:func:`atof` function.
|
||||
|
||||
Not setting the numeric locale caused trouble for extensions that used third-
|
||||
party C libraries, however, because they wouldn't have the correct locale set.
|
||||
Not setting the numeric locale caused trouble for extensions that used third-party
|
||||
C libraries, however, because they wouldn't have the correct locale set.
|
||||
The motivating example was GTK+, whose user interface widgets weren't displaying
|
||||
numbers in the current locale.
|
||||
|
||||
|
@ -918,8 +918,8 @@ Here are all of the changes that Python 2.4 makes to the core Python language.
|
|||
|
||||
(Contributed by Raymond Hettinger.)
|
||||
|
||||
* Encountering a failure while importing a module no longer leaves a partially-
|
||||
initialized module object in ``sys.modules``. The incomplete module object left
|
||||
* Encountering a failure while importing a module no longer leaves a partially-initialized
|
||||
module object in ``sys.modules``. The incomplete module object left
|
||||
behind would fool further imports of the same module into succeeding, leading to
|
||||
confusing errors. (Fixed by Tim Peters.)
|
||||
|
||||
|
@ -1028,8 +1028,8 @@ complete list of changes, or look through the CVS logs for all the details.
|
|||
previous ones left off. (Implemented by Walter Dörwald.)
|
||||
|
||||
* There is a new :mod:`collections` module for various specialized collection
|
||||
datatypes. Currently it contains just one type, :class:`deque`, a double-
|
||||
ended queue that supports efficiently adding and removing elements from either
|
||||
datatypes. Currently it contains just one type, :class:`deque`, a double-ended
|
||||
queue that supports efficiently adding and removing elements from either
|
||||
end::
|
||||
|
||||
>>> from collections import deque
|
||||
|
@ -1485,8 +1485,8 @@ Some of the changes to Python's build process and to the C API are:
|
|||
intended as an aid to people developing the Python core. Providing
|
||||
:option:`!--enable-profiling` to the :program:`configure` script will let you
|
||||
profile the interpreter with :program:`gprof`, and providing the
|
||||
:option:`!--with-tsc` switch enables profiling using the Pentium's Time-Stamp-
|
||||
Counter register. Note that the :option:`!--with-tsc` switch is slightly
|
||||
:option:`!--with-tsc` switch enables profiling using the Pentium's
|
||||
Time-Stamp-Counter register. Note that the :option:`!--with-tsc` switch is slightly
|
||||
misnamed, because the profiling feature also works on the PowerPC platform,
|
||||
though that processor architecture doesn't call that register "the TSC
|
||||
register". (Contributed by Jeremy Hylton.)
|
||||
|
@ -1540,8 +1540,8 @@ code:
|
|||
|
||||
* The :mod:`tarfile` module now generates GNU-format tar files by default.
|
||||
|
||||
* Encountering a failure while importing a module no longer leaves a partially-
|
||||
initialized module object in ``sys.modules``.
|
||||
* Encountering a failure while importing a module no longer leaves a
|
||||
partially-initialized module object in ``sys.modules``.
|
||||
|
||||
* :const:`None` is now a constant; code that binds a new value to the name
|
||||
``None`` is now a syntax error.
|
||||
|
|
|
@ -157,8 +157,8 @@ Here's a small but realistic example::
|
|||
server_log = functools.partial(log, subsystem='server')
|
||||
server_log('Unable to open socket')
|
||||
|
||||
Here's another example, from a program that uses PyGTK. Here a context-
|
||||
sensitive pop-up menu is being constructed dynamically. The callback provided
|
||||
Here's another example, from a program that uses PyGTK. Here a context-sensitive
|
||||
pop-up menu is being constructed dynamically. The callback provided
|
||||
for the menu option is a partially applied version of the :meth:`open_item`
|
||||
method, where the first argument has been provided. ::
|
||||
|
||||
|
@ -171,8 +171,8 @@ method, where the first argument has been provided. ::
|
|||
popup_menu.append( ("Open", open_func, 1) )
|
||||
|
||||
Another function in the :mod:`functools` module is the
|
||||
``update_wrapper(wrapper, wrapped)`` function that helps you write well-
|
||||
behaved decorators. :func:`update_wrapper` copies the name, module, and
|
||||
``update_wrapper(wrapper, wrapped)`` function that helps you write
|
||||
well-behaved decorators. :func:`update_wrapper` copies the name, module, and
|
||||
docstring attribute to a wrapper function so that tracebacks inside the wrapped
|
||||
function are easier to understand. For example, you might write::
|
||||
|
||||
|
@ -297,8 +297,8 @@ can't protect against having your submodule's name being used for a new module
|
|||
added in a future version of Python.
|
||||
|
||||
In Python 2.5, you can switch :keyword:`import`'s behaviour to absolute imports
|
||||
using a ``from __future__ import absolute_import`` directive. This absolute-
|
||||
import behaviour will become the default in a future version (probably Python
|
||||
using a ``from __future__ import absolute_import`` directive. This absolute-import
|
||||
behaviour will become the default in a future version (probably Python
|
||||
2.7). Once absolute imports are the default, ``import string`` will always
|
||||
find the standard library's version. It's suggested that users should begin
|
||||
using absolute imports as much as possible, so it's preferable to begin writing
|
||||
|
@ -602,8 +602,8 @@ be used with the ':keyword:`with`' statement. File objects are one example::
|
|||
... more processing code ...
|
||||
|
||||
After this statement has executed, the file object in *f* will have been
|
||||
automatically closed, even if the :keyword:`for` loop raised an exception part-
|
||||
way through the block.
|
||||
automatically closed, even if the :keyword:`for` loop raised an exception
|
||||
part-way through the block.
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -1558,8 +1558,8 @@ complete list of changes, or look through the SVN logs for all the details.
|
|||
|
||||
You can also pack and unpack data to and from buffer objects directly using the
|
||||
``pack_into(buffer, offset, v1, v2, ...)`` and ``unpack_from(buffer,
|
||||
offset)`` methods. This lets you store data directly into an array or a memory-
|
||||
mapped file.
|
||||
offset)`` methods. This lets you store data directly into an array or a
|
||||
memory-mapped file.
|
||||
|
||||
(:class:`Struct` objects were implemented by Bob Ippolito at the NeedForSpeed
|
||||
sprint. Support for buffer objects was added by Martin Blais, also at the
|
||||
|
@ -2281,8 +2281,8 @@ Acknowledgements
|
|||
|
||||
The author would like to thank the following people for offering suggestions,
|
||||
corrections and assistance with various drafts of this article: Georg Brandl,
|
||||
Nick Coghlan, Phillip J. Eby, Lars Gustäbel, Raymond Hettinger, Ralf W. Grosse-
|
||||
Kunstleve, Kent Johnson, Iain Lowe, Martin von Löwis, Fredrik Lundh, Andrew
|
||||
Nick Coghlan, Phillip J. Eby, Lars Gustäbel, Raymond Hettinger, Ralf W.
|
||||
Grosse-Kunstleve, Kent Johnson, Iain Lowe, Martin von Löwis, Fredrik Lundh, Andrew
|
||||
McNamara, Skip Montanaro, Gustavo Niemeyer, Paul Prescod, James Pryor, Mike
|
||||
Rovner, Scott Weikart, Barry Warsaw, Thomas Wouters.
|
||||
|
||||
|
|
|
@ -290,8 +290,8 @@ be used with the ':keyword:`with`' statement. File objects are one example::
|
|||
... more processing code ...
|
||||
|
||||
After this statement has executed, the file object in *f* will have been
|
||||
automatically closed, even if the :keyword:`for` loop raised an exception part-
|
||||
way through the block.
|
||||
automatically closed, even if the :keyword:`for` loop raised an exception
|
||||
part-way through the block.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
|
@ -100,7 +100,7 @@ Library
|
|||
WeakValueDictionary.pop() when a GC collection happens in another
|
||||
thread.
|
||||
|
||||
- Issue #20191: Fixed a crash in resource.prlimit() when pass a sequence that
|
||||
- Issue #20191: Fixed a crash in resource.prlimit() when passing a sequence that
|
||||
doesn't own its elements as limits.
|
||||
|
||||
- Issue #28779: multiprocessing.set_forkserver_preload() would crash the
|
||||
|
|
|
@ -2234,7 +2234,7 @@ static PyTypeObject defdict_type = {
|
|||
PyDoc_STRVAR(_count_elements_doc,
|
||||
"_count_elements(mapping, iterable) -> None\n\
|
||||
\n\
|
||||
Count elements in the iterable, updating the mappping");
|
||||
Count elements in the iterable, updating the mapping");
|
||||
|
||||
static PyObject *
|
||||
_count_elements(PyObject *self, PyObject *args)
|
||||
|
|
|
@ -1012,7 +1012,7 @@ _io_TextIOWrapper___init___impl(textio *self, PyObject *buffer,
|
|||
errors);
|
||||
if (self->encoder == NULL)
|
||||
goto error;
|
||||
/* Get the normalized named of the codec */
|
||||
/* Get the normalized name of the codec */
|
||||
res = _PyObject_GetAttrId(codec_info, &PyId_name);
|
||||
if (res == NULL) {
|
||||
if (PyErr_ExceptionMatches(PyExc_AttributeError))
|
||||
|
|
|
@ -2231,7 +2231,7 @@ odictvalues_new(PyObject *od)
|
|||
|
||||
|
||||
/* ----------------------------------------------
|
||||
MutableMappping implementations
|
||||
MutableMapping implementations
|
||||
|
||||
Mapping:
|
||||
|
||||
|
|
Loading…
Reference in New Issue