Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-110631: Fix reST indentation in `Doc/library` (#110685) 

Fix wrong indentation in the Doc/library dir.
This commit is contained in:
Ezio Melotti 2023-10-11 22:24:12 +02:00 committed by GitHub
parent c523ce0f43
commit bb7923f556
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
34 changed files with 917 additions and 910 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
Doc/library/__main__.rst
View File

@ -54,45 +54,45 @@ The top-level code environment can be:
* the scope of an interactive prompt::
>>> __name__
'__main__'
>>> __name__
'__main__'
* the Python module passed to the Python interpreter as a file argument:
.. code-block:: shell-session
.. code-block:: shell-session
$ python helloworld.py
Hello, world!
$ python helloworld.py
Hello, world!
* the Python module or package passed to the Python interpreter with the
:option:`-m` argument:
.. code-block:: shell-session
.. code-block:: shell-session
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)
* Python code read by the Python interpreter from standard input:
.. code-block:: shell-session
.. code-block:: shell-session
$ echo "import this" | python
The Zen of Python, by Tim Peters
$ echo "import this" | python
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
...
Beautiful is better than ugly.
Explicit is better than implicit.
...
* Python code passed to the Python interpreter with the :option:`-c` argument:
.. code-block:: shell-session
.. code-block:: shell-session
$ python -c "import this"
The Zen of Python, by Tim Peters
$ python -c "import this"
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
...
Beautiful is better than ugly.
Explicit is better than implicit.
...
In each of these situations, the top-level module's ``__name__`` is set to
``'__main__'``.
@ -102,9 +102,9 @@ top-level environment by checking its own ``__name__``, which allows a common
idiom for conditionally executing code when the module is not initialized from
an import statement::
if __name__ == '__main__':
# Execute when the module is not initialized from an import statement.
...
if __name__ == '__main__':
# Execute when the module is not initialized from an import statement.
...
.. seealso::

2
Doc/library/_thread.rst
View File

@ -208,7 +208,7 @@ In addition to these methods, lock objects can also be used via the
**Caveats:**
.. index:: pair: module; signal
.. index:: pair: module; signal
* Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt`
exception will be received by an arbitrary thread. (When the :mod:`signal`

9
Doc/library/binascii.rst
View File

@ -57,10 +57,11 @@ The :mod:`binascii` module defines the following functions:
data will raise :exc:`binascii.Error`.
Valid base64:
* Conforms to :rfc:`3548`.
* Contains only characters from the base64 alphabet.
* Contains no excess data after padding (including excess padding, newlines, etc.).
* Does not start with a padding.
* Conforms to :rfc:`3548`.
* Contains only characters from the base64 alphabet.
* Contains no excess data after padding (including excess padding, newlines, etc.).
* Does not start with a padding.
.. versionchanged:: 3.11
Added the *strict_mode* parameter.

78
Doc/library/collections.rst
View File

@ -120,26 +120,26 @@ The class can be used to simulate nested scopes and is useful in templating.
.. seealso::
* The `MultiContext class
<https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py>`_
in the Enthought `CodeTools package
<https://github.com/enthought/codetools>`_ has options to support
writing to any mapping in the chain.
* The `MultiContext class
<https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py>`_
in the Enthought `CodeTools package
<https://github.com/enthought/codetools>`_ has options to support
writing to any mapping in the chain.
* Django's `Context class
<https://github.com/django/django/blob/main/django/template/context.py>`_
for templating is a read-only chain of mappings. It also features
pushing and popping of contexts similar to the
:meth:`~collections.ChainMap.new_child` method and the
:attr:`~collections.ChainMap.parents` property.
* Django's `Context class
<https://github.com/django/django/blob/main/django/template/context.py>`_
for templating is a read-only chain of mappings. It also features
pushing and popping of contexts similar to the
:meth:`~collections.ChainMap.new_child` method and the
:attr:`~collections.ChainMap.parents` property.
* The `Nested Contexts recipe
<https://code.activestate.com/recipes/577434/>`_ has options to control
whether writes and other mutations apply only to the first mapping or to
any mapping in the chain.
* The `Nested Contexts recipe
<https://code.activestate.com/recipes/577434/>`_ has options to control
whether writes and other mutations apply only to the first mapping or to
any mapping in the chain.
* A `greatly simplified read-only version of Chainmap
<https://code.activestate.com/recipes/305268/>`_.
* A `greatly simplified read-only version of Chainmap
<https://code.activestate.com/recipes/305268/>`_.
:class:`ChainMap` Examples and Recipes
@ -429,22 +429,22 @@ or subtracting from an empty counter.
.. seealso::
* `Bag class <https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_
in Smalltalk.
* `Bag class <https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_
in Smalltalk.
* Wikipedia entry for `Multisets <https://en.wikipedia.org/wiki/Multiset>`_.
* Wikipedia entry for `Multisets <https://en.wikipedia.org/wiki/Multiset>`_.
* `C++ multisets <http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm>`_
tutorial with examples.
* `C++ multisets <http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm>`_
tutorial with examples.
* For mathematical operations on multisets and their use cases, see
*Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19*.
* For mathematical operations on multisets and their use cases, see
*Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19*.
* To enumerate all distinct multisets of a given size over a given set of
elements, see :func:`itertools.combinations_with_replacement`::
* To enumerate all distinct multisets of a given size over a given set of
elements, see :func:`itertools.combinations_with_replacement`::
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
:class:`deque` objects
@ -1062,20 +1062,20 @@ fields:
.. seealso::
* See :class:`typing.NamedTuple` for a way to add type hints for named
tuples. It also provides an elegant notation using the :keyword:`class`
keyword::
* See :class:`typing.NamedTuple` for a way to add type hints for named
tuples. It also provides an elegant notation using the :keyword:`class`
keyword::
class Component(NamedTuple):
part_number: int
weight: float
description: Optional[str] = None
class Component(NamedTuple):
part_number: int
weight: float
description: Optional[str] = None
* See :meth:`types.SimpleNamespace` for a mutable namespace based on an
underlying dictionary instead of a tuple.
* See :meth:`types.SimpleNamespace` for a mutable namespace based on an
underlying dictionary instead of a tuple.
* The :mod:`dataclasses` module provides a decorator and functions for
automatically adding generated special methods to user-defined classes.
* The :mod:`dataclasses` module provides a decorator and functions for
automatically adding generated special methods to user-defined classes.
:class:`OrderedDict` objects

270
Doc/library/concurrent.futures.rst
View File

@ -29,83 +29,83 @@ Executor Objects
An abstract class that provides methods to execute calls asynchronously. It
should not be used directly, but through its concrete subclasses.
.. method:: submit(fn, /, *args, **kwargs)
.. method:: submit(fn, /, *args, **kwargs)
Schedules the callable, *fn*, to be executed as ``fn(*args, **kwargs)``
and returns a :class:`Future` object representing the execution of the
callable. ::
Schedules the callable, *fn*, to be executed as ``fn(*args, **kwargs)``
and returns a :class:`Future` object representing the execution of the
callable. ::
with ThreadPoolExecutor(max_workers=1) as executor:
future = executor.submit(pow, 323, 1235)
print(future.result())
with ThreadPoolExecutor(max_workers=1) as executor:
future = executor.submit(pow, 323, 1235)
print(future.result())
.. method:: map(func, *iterables, timeout=None, chunksize=1)
.. method:: map(func, *iterables, timeout=None, chunksize=1)
Similar to :func:`map(func, *iterables) <map>` except:
Similar to :func:`map(func, *iterables) <map>` except:
* the *iterables* are collected immediately rather than lazily;
* the *iterables* are collected immediately rather than lazily;
* *func* is executed asynchronously and several calls to
*func* may be made concurrently.
* *func* is executed asynchronously and several calls to
*func* may be made concurrently.
The returned iterator raises a :exc:`TimeoutError`
if :meth:`~iterator.__next__` is called and the result isn't available
after *timeout* seconds from the original call to :meth:`Executor.map`.
*timeout* can be an int or a float. If *timeout* is not specified or
``None``, there is no limit to the wait time.
The returned iterator raises a :exc:`TimeoutError`
if :meth:`~iterator.__next__` is called and the result isn't available
after *timeout* seconds from the original call to :meth:`Executor.map`.
*timeout* can be an int or a float. If *timeout* is not specified or
``None``, there is no limit to the wait time.
If a *func* call raises an exception, then that exception will be
raised when its value is retrieved from the iterator.
If a *func* call raises an exception, then that exception will be
raised when its value is retrieved from the iterator.
When using :class:`ProcessPoolExecutor`, this method chops *iterables*
into a number of chunks which it submits to the pool as separate
tasks. The (approximate) size of these chunks can be specified by
setting *chunksize* to a positive integer. For very long iterables,
using a large value for *chunksize* can significantly improve
performance compared to the default size of 1. With
:class:`ThreadPoolExecutor`, *chunksize* has no effect.
When using :class:`ProcessPoolExecutor`, this method chops *iterables*
into a number of chunks which it submits to the pool as separate
tasks. The (approximate) size of these chunks can be specified by
setting *chunksize* to a positive integer. For very long iterables,
using a large value for *chunksize* can significantly improve
performance compared to the default size of 1. With
:class:`ThreadPoolExecutor`, *chunksize* has no effect.
.. versionchanged:: 3.5
Added the *chunksize* argument.
.. versionchanged:: 3.5
Added the *chunksize* argument.
.. method:: shutdown(wait=True, *, cancel_futures=False)
.. method:: shutdown(wait=True, *, cancel_futures=False)
Signal the executor that it should free any resources that it is using
when the currently pending futures are done executing. Calls to
:meth:`Executor.submit` and :meth:`Executor.map` made after shutdown will
raise :exc:`RuntimeError`.
Signal the executor that it should free any resources that it is using
when the currently pending futures are done executing. Calls to
:meth:`Executor.submit` and :meth:`Executor.map` made after shutdown will
raise :exc:`RuntimeError`.
If *wait* is ``True`` then this method will not return until all the
pending futures are done executing and the resources associated with the
executor have been freed. If *wait* is ``False`` then this method will
return immediately and the resources associated with the executor will be
freed when all pending futures are done executing. Regardless of the
value of *wait*, the entire Python program will not exit until all
pending futures are done executing.
If *wait* is ``True`` then this method will not return until all the
pending futures are done executing and the resources associated with the
executor have been freed. If *wait* is ``False`` then this method will
return immediately and the resources associated with the executor will be
freed when all pending futures are done executing. Regardless of the
value of *wait*, the entire Python program will not exit until all
pending futures are done executing.
If *cancel_futures* is ``True``, this method will cancel all pending
futures that the executor has not started running. Any futures that
are completed or running won't be cancelled, regardless of the value
of *cancel_futures*.
If *cancel_futures* is ``True``, this method will cancel all pending
futures that the executor has not started running. Any futures that
are completed or running won't be cancelled, regardless of the value
of *cancel_futures*.
If both *cancel_futures* and *wait* are ``True``, all futures that the
executor has started running will be completed prior to this method
returning. The remaining futures are cancelled.
If both *cancel_futures* and *wait* are ``True``, all futures that the
executor has started running will be completed prior to this method
returning. The remaining futures are cancelled.
You can avoid having to call this method explicitly if you use the
:keyword:`with` statement, which will shutdown the :class:`Executor`
(waiting as if :meth:`Executor.shutdown` were called with *wait* set to
``True``)::
You can avoid having to call this method explicitly if you use the
:keyword:`with` statement, which will shutdown the :class:`Executor`
(waiting as if :meth:`Executor.shutdown` were called with *wait* set to
``True``)::
import shutil
with ThreadPoolExecutor(max_workers=4) as e:
e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
e.submit(shutil.copy, 'src4.txt', 'dest4.txt')
import shutil
with ThreadPoolExecutor(max_workers=4) as e:
e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
e.submit(shutil.copy, 'src4.txt', 'dest4.txt')
.. versionchanged:: 3.9
Added *cancel_futures*.
.. versionchanged:: 3.9
Added *cancel_futures*.
ThreadPoolExecutor
@ -361,117 +361,117 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable.
instances are created by :meth:`Executor.submit` and should not be created
directly except for testing.
.. method:: cancel()
.. method:: cancel()
Attempt to cancel the call. If the call is currently being executed or
finished running and cannot be cancelled then the method will return
``False``, otherwise the call will be cancelled and the method will
return ``True``.
Attempt to cancel the call. If the call is currently being executed or
finished running and cannot be cancelled then the method will return
``False``, otherwise the call will be cancelled and the method will
return ``True``.
.. method:: cancelled()
.. method:: cancelled()
Return ``True`` if the call was successfully cancelled.
Return ``True`` if the call was successfully cancelled.
.. method:: running()
.. method:: running()
Return ``True`` if the call is currently being executed and cannot be
cancelled.
Return ``True`` if the call is currently being executed and cannot be
cancelled.
.. method:: done()
.. method:: done()
Return ``True`` if the call was successfully cancelled or finished
running.
Return ``True`` if the call was successfully cancelled or finished
running.
.. method:: result(timeout=None)
.. method:: result(timeout=None)
Return the value returned by the call. If the call hasn't yet completed
then this method will wait up to *timeout* seconds. If the call hasn't
completed in *timeout* seconds, then a
:exc:`TimeoutError` will be raised. *timeout* can be
an int or float. If *timeout* is not specified or ``None``, there is no
limit to the wait time.
Return the value returned by the call. If the call hasn't yet completed
then this method will wait up to *timeout* seconds. If the call hasn't
completed in *timeout* seconds, then a
:exc:`TimeoutError` will be raised. *timeout* can be
an int or float. If *timeout* is not specified or ``None``, there is no
limit to the wait time.
If the future is cancelled before completing then :exc:`.CancelledError`
will be raised.
If the future is cancelled before completing then :exc:`.CancelledError`
will be raised.
If the call raised an exception, this method will raise the same exception.
If the call raised an exception, this method will raise the same exception.
.. method:: exception(timeout=None)
.. method:: exception(timeout=None)
Return the exception raised by the call. If the call hasn't yet
completed then this method will wait up to *timeout* seconds. If the
call hasn't completed in *timeout* seconds, then a
:exc:`TimeoutError` will be raised. *timeout* can be
an int or float. If *timeout* is not specified or ``None``, there is no
limit to the wait time.
Return the exception raised by the call. If the call hasn't yet
completed then this method will wait up to *timeout* seconds. If the
call hasn't completed in *timeout* seconds, then a
:exc:`TimeoutError` will be raised. *timeout* can be
an int or float. If *timeout* is not specified or ``None``, there is no
limit to the wait time.
If the future is cancelled before completing then :exc:`.CancelledError`
will be raised.
If the future is cancelled before completing then :exc:`.CancelledError`
will be raised.
If the call completed without raising, ``None`` is returned.
If the call completed without raising, ``None`` is returned.
.. method:: add_done_callback(fn)
.. method:: add_done_callback(fn)
Attaches the callable *fn* to the future. *fn* will be called, with the
future as its only argument, when the future is cancelled or finishes
running.
Attaches the callable *fn* to the future. *fn* will be called, with the
future as its only argument, when the future is cancelled or finishes
running.
Added callables are called in the order that they were added and are
always called in a thread belonging to the process that added them. If
the callable raises an :exc:`Exception` subclass, it will be logged and
ignored. If the callable raises a :exc:`BaseException` subclass, the
behavior is undefined.
Added callables are called in the order that they were added and are
always called in a thread belonging to the process that added them. If
the callable raises an :exc:`Exception` subclass, it will be logged and
ignored. If the callable raises a :exc:`BaseException` subclass, the
behavior is undefined.
If the future has already completed or been cancelled, *fn* will be
called immediately.
If the future has already completed or been cancelled, *fn* will be
called immediately.
The following :class:`Future` methods are meant for use in unit tests and
:class:`Executor` implementations.
.. method:: set_running_or_notify_cancel()
.. method:: set_running_or_notify_cancel()
This method should only be called by :class:`Executor` implementations
before executing the work associated with the :class:`Future` and by unit
tests.
This method should only be called by :class:`Executor` implementations
before executing the work associated with the :class:`Future` and by unit
tests.
If the method returns ``False`` then the :class:`Future` was cancelled,
i.e. :meth:`Future.cancel` was called and returned ``True``. Any threads
waiting on the :class:`Future` completing (i.e. through
:func:`as_completed` or :func:`wait`) will be woken up.
If the method returns ``False`` then the :class:`Future` was cancelled,
i.e. :meth:`Future.cancel` was called and returned ``True``. Any threads
waiting on the :class:`Future` completing (i.e. through
:func:`as_completed` or :func:`wait`) will be woken up.
If the method returns ``True`` then the :class:`Future` was not cancelled
and has been put in the running state, i.e. calls to
:meth:`Future.running` will return ``True``.
If the method returns ``True`` then the :class:`Future` was not cancelled
and has been put in the running state, i.e. calls to
:meth:`Future.running` will return ``True``.
This method can only be called once and cannot be called after
:meth:`Future.set_result` or :meth:`Future.set_exception` have been
called.
This method can only be called once and cannot be called after
:meth:`Future.set_result` or :meth:`Future.set_exception` have been
called.
.. method:: set_result(result)
.. method:: set_result(result)
Sets the result of the work associated with the :class:`Future` to
*result*.
Sets the result of the work associated with the :class:`Future` to
*result*.
This method should only be used by :class:`Executor` implementations and
unit tests.
This method should only be used by :class:`Executor` implementations and
unit tests.
.. versionchanged:: 3.8
This method raises
:exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is
already done.
.. versionchanged:: 3.8
This method raises
:exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is
already done.
.. method:: set_exception(exception)
.. method:: set_exception(exception)
Sets the result of the work associated with the :class:`Future` to the
:class:`Exception` *exception*.
Sets the result of the work associated with the :class:`Future` to the
:class:`Exception` *exception*.
This method should only be used by :class:`Executor` implementations and
unit tests.
This method should only be used by :class:`Executor` implementations and
unit tests.
.. versionchanged:: 3.8
This method raises
:exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is
already done.
.. versionchanged:: 3.8
This method raises
:exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is
already done.
Module Functions
----------------

86
Doc/library/ctypes.rst
View File

@ -1738,70 +1738,70 @@ See :ref:`ctypes-callback-functions` for examples.
Function prototypes created by these factory functions can be instantiated in
different ways, depending on the type and number of the parameters in the call:
.. function:: prototype(address)
:noindex:
:module:
.. function:: prototype(address)
:noindex:
:module:
Returns a foreign function at the specified address which must be an integer.
Returns a foreign function at the specified address which must be an integer.
.. function:: prototype(callable)
:noindex:
:module:
.. function:: prototype(callable)
:noindex:
:module:
Create a C callable function (a callback function) from a Python *callable*.
Create a C callable function (a callback function) from a Python *callable*.
.. function:: prototype(func_spec[, paramflags])
:noindex:
:module:
.. function:: prototype(func_spec[, paramflags])
:noindex:
:module:
Returns a foreign function exported by a shared library. *func_spec* must
be a 2-tuple ``(name_or_ordinal, library)``. The first item is the name of
the exported function as string, or the ordinal of the exported function
as small integer. The second item is the shared library instance.
Returns a foreign function exported by a shared library. *func_spec* must
be a 2-tuple ``(name_or_ordinal, library)``. The first item is the name of
the exported function as string, or the ordinal of the exported function
as small integer. The second item is the shared library instance.
.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
:noindex:
:module:
.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
:noindex:
:module:
Returns a foreign function that will call a COM method. *vtbl_index* is
the index into the virtual function table, a small non-negative
integer. *name* is name of the COM method. *iid* is an optional pointer to
the interface identifier which is used in extended error reporting.
Returns a foreign function that will call a COM method. *vtbl_index* is
the index into the virtual function table, a small non-negative
integer. *name* is name of the COM method. *iid* is an optional pointer to
the interface identifier which is used in extended error reporting.
COM methods use a special calling convention: They require a pointer to
the COM interface as first argument, in addition to those parameters that
are specified in the :attr:`!argtypes` tuple.
COM methods use a special calling convention: They require a pointer to
the COM interface as first argument, in addition to those parameters that
are specified in the :attr:`!argtypes` tuple.
The optional *paramflags* parameter creates foreign function wrappers with much
more functionality than the features described above.
The optional *paramflags* parameter creates foreign function wrappers with much
more functionality than the features described above.
*paramflags* must be a tuple of the same length as :attr:`~_FuncPtr.argtypes`.
*paramflags* must be a tuple of the same length as :attr:`~_FuncPtr.argtypes`.
Each item in this tuple contains further information about a parameter, it must
be a tuple containing one, two, or three items.
Each item in this tuple contains further information about a parameter, it must
be a tuple containing one, two, or three items.
The first item is an integer containing a combination of direction
flags for the parameter:
The first item is an integer containing a combination of direction
flags for the parameter:
1
Specifies an input parameter to the function.
1
Specifies an input parameter to the function.
2
Output parameter. The foreign function fills in a value.
2
Output parameter. The foreign function fills in a value.
4
Input parameter which defaults to the integer zero.
4
Input parameter which defaults to the integer zero.
The optional second item is the parameter name as string. If this is specified,
the foreign function can be called with named parameters.
The optional second item is the parameter name as string. If this is specified,
the foreign function can be called with named parameters.
The optional third item is the default value for this parameter.
The optional third item is the default value for this parameter.
This example demonstrates how to wrap the Windows ``MessageBoxW`` function so
The following example demonstrates how to wrap the Windows ``MessageBoxW`` function so
that it supports default parameters and named arguments. The C declaration from
the windows header file is this::

6
Doc/library/curses.rst
View File

@ -1771,9 +1771,9 @@ The following table lists mouse button constants used by :meth:`getmouse`:
| .. data:: BUTTON_ALT | Control was down during button state change |
+----------------------------------+---------------------------------------------+
.. versionchanged:: 3.10
The ``BUTTON5_*`` constants are now exposed if they are provided by the
underlying curses library.
.. versionchanged:: 3.10
The ``BUTTON5_*`` constants are now exposed if they are provided by the
underlying curses library.
The following table lists the predefined colors:

12
Doc/library/dialog.rst
View File

@ -27,15 +27,15 @@ functions for creating simple modal dialogs to get a value from the user.
The base class for custom dialogs.
.. method:: body(master)
.. method:: body(master)
Override to construct the dialog's interface and return the widget that
should have initial focus.
Override to construct the dialog's interface and return the widget that
should have initial focus.
.. method:: buttonbox()
.. method:: buttonbox()
Default behaviour adds OK and Cancel buttons. Override for custom button
layouts.
Default behaviour adds OK and Cancel buttons. Override for custom button
layouts.

50
Doc/library/email.contentmanager.rst
View File

@ -32,9 +32,9 @@
To find the handler, look for the following keys in the registry,
stopping with the first one found:
* the string representing the full MIME type (``maintype/subtype``)
* the string representing the ``maintype``
* the empty string
* the string representing the full MIME type (``maintype/subtype``)
* the string representing the ``maintype``
* the empty string
If none of these keys produce a handler, raise a :exc:`KeyError` for the
full MIME type.
@ -55,11 +55,11 @@
look for the following keys in the registry, stopping with the first one
found:
* the type itself (``typ``)
* the type's fully qualified name (``typ.__module__ + '.' +
typ.__qualname__``).
* the type's qualname (``typ.__qualname__``)
* the type's name (``typ.__name__``).
* the type itself (``typ``)
* the type's fully qualified name (``typ.__module__ + '.' +
typ.__qualname__``).
* the type's qualname (``typ.__qualname__``)
* the type's name (``typ.__name__``).
If none of the above match, repeat all of the checks above for each of
the types in the :term:`MRO` (``typ.__mro__``). Finally, if no other key
@ -132,15 +132,15 @@ Currently the email package provides only one concrete content manager,
Add a :mailheader:`Content-Type` header with a ``maintype/subtype``
value.
* For ``str``, set the MIME ``maintype`` to ``text``, and set the
subtype to *subtype* if it is specified, or ``plain`` if it is not.
* For ``bytes``, use the specified *maintype* and *subtype*, or
raise a :exc:`TypeError` if they are not specified.
* For :class:`~email.message.EmailMessage` objects, set the maintype
to ``message``, and set the subtype to *subtype* if it is
specified or ``rfc822`` if it is not. If *subtype* is
``partial``, raise an error (``bytes`` objects must be used to
construct ``message/partial`` parts).
* For ``str``, set the MIME ``maintype`` to ``text``, and set the
subtype to *subtype* if it is specified, or ``plain`` if it is not.
* For ``bytes``, use the specified *maintype* and *subtype*, or
raise a :exc:`TypeError` if they are not specified.
* For :class:`~email.message.EmailMessage` objects, set the maintype
to ``message``, and set the subtype to *subtype* if it is
specified or ``rfc822`` if it is not. If *subtype* is
``partial``, raise an error (``bytes`` objects must be used to
construct ``message/partial`` parts).
If *charset* is provided (which is valid only for ``str``), encode the
string to bytes using the specified character set. The default is
@ -155,14 +155,14 @@ Currently the email package provides only one concrete content manager,
``7bit`` for an input that contains non-ASCII values), raise a
:exc:`ValueError`.
* For ``str`` objects, if *cte* is not set use heuristics to
determine the most compact encoding.
* For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise
an error if a *cte* of ``quoted-printable`` or ``base64`` is
requested for *subtype* ``rfc822``, and for any *cte* other than
``7bit`` for *subtype* ``external-body``. For
``message/rfc822``, use ``8bit`` if *cte* is not specified. For
all other values of *subtype*, use ``7bit``.
* For ``str`` objects, if *cte* is not set use heuristics to
determine the most compact encoding.
* For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise
an error if a *cte* of ``quoted-printable`` or ``base64`` is
requested for *subtype* ``rfc822``, and for any *cte* other than
``7bit`` for *subtype* ``external-body``. For
``message/rfc822``, use ``8bit`` if *cte* is not specified. For
all other values of *subtype*, use ``7bit``.
.. note:: A *cte* of ``binary`` does not actually work correctly yet.
The ``EmailMessage`` object as modified by ``set_content`` is

18
Doc/library/email.policy.rst
View File

@ -557,17 +557,17 @@ more closely to the RFCs relevant to their domains.
With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective API of
the email package is changed from the Python 3.2 API in the following ways:
* Setting a header on a :class:`~email.message.Message` results in that
header being parsed and a header object created.
* Setting a header on a :class:`~email.message.Message` results in that
header being parsed and a header object created.
* Fetching a header value from a :class:`~email.message.Message` results
in that header being parsed and a header object created and
returned.
* Fetching a header value from a :class:`~email.message.Message` results
in that header being parsed and a header object created and
returned.
* Any header object, or any header that is refolded due to the
policy settings, is folded using an algorithm that fully implements the
RFC folding algorithms, including knowing where encoded words are required
and allowed.
* Any header object, or any header that is refolded due to the
policy settings, is folded using an algorithm that fully implements the
RFC folding algorithms, including knowing where encoded words are required
and allowed.
From the application view, this means that any header obtained through the
:class:`~email.message.EmailMessage` is a header object with extra

28
Doc/library/enum.rst
View File

@ -597,8 +597,8 @@ Data Types
If a *Flag* operation is performed with an *IntFlag* member and:
* the result is a valid *IntFlag*: an *IntFlag* is returned
* the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting
* the result is a valid *IntFlag*: an *IntFlag* is returned
* the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting
The *repr()* of unnamed zero-valued flags has changed. It is now:
@ -625,8 +625,8 @@ Data Types
:class:`!ReprEnum` uses the :meth:`repr() <Enum.__repr__>` of :class:`Enum`,
but the :class:`str() <str>` of the mixed-in data type:
* :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
* :meth:`!str.__str__` for :class:`StrEnum`
* :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
* :meth:`!str.__str__` for :class:`StrEnum`
Inherit from :class:`!ReprEnum` to keep the :class:`str() <str>` / :func:`format`
of the mixed-in data type instead of using the
@ -789,13 +789,13 @@ Supported ``_sunder_`` names
- ``_generate_next_value_`` -- used to get an appropriate value for an enum
member; may be overridden
.. note::
.. note::
For standard :class:`Enum` classes the next value chosen is the last value seen
incremented by one.
For standard :class:`Enum` classes the next value chosen is the last value seen
incremented by one.
For :class:`Flag` classes the next value chosen will be the next highest
power-of-two, regardless of the last value seen.
For :class:`Flag` classes the next value chosen will be the next highest
power-of-two, regardless of the last value seen.
.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
.. versionadded:: 3.7 ``_ignore_``
@ -817,11 +817,11 @@ Utilities and Decorators
*auto* instances are only resolved when at the top level of an assignment:
* ``FIRST = auto()`` will work (auto() is replaced with ``1``);
* ``SECOND = auto(), -2`` will work (auto is replaced with ``2``, so ``2, -2`` is
used to create the ``SECOND`` enum member;
* ``THREE = [auto(), -3]`` will *not* work (``<auto instance>, -3`` is used to
create the ``THREE`` enum member)
* ``FIRST = auto()`` will work (auto() is replaced with ``1``);
* ``SECOND = auto(), -2`` will work (auto is replaced with ``2``, so ``2, -2`` is
used to create the ``SECOND`` enum member;
* ``THREE = [auto(), -3]`` will *not* work (``<auto instance>, -3`` is used to
create the ``THREE`` enum member)
.. versionchanged:: 3.11.1

30
Doc/library/functions.rst
View File

@ -1158,8 +1158,8 @@ are always available. They are listed here in alphabetical order.
See also :func:`format` for more information.
.. index::
single: file object; open() built-in function
.. index::
single: file object; open() built-in function
.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
@ -1360,28 +1360,28 @@ are always available. They are listed here in alphabetical order.
.. versionchanged:: 3.3
* The *opener* parameter was added.
* The ``'x'`` mode was added.
* :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
* :exc:`FileExistsError` is now raised if the file opened in exclusive
creation mode (``'x'``) already exists.
* The *opener* parameter was added.
* The ``'x'`` mode was added.
* :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
* :exc:`FileExistsError` is now raised if the file opened in exclusive
creation mode (``'x'``) already exists.
.. versionchanged:: 3.4
* The file is now non-inheritable.
* The file is now non-inheritable.
.. versionchanged:: 3.5
* If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
:exc:`InterruptedError` exception (see :pep:`475` for the rationale).
* The ``'namereplace'`` error handler was added.
* If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
:exc:`InterruptedError` exception (see :pep:`475` for the rationale).
* The ``'namereplace'`` error handler was added.
.. versionchanged:: 3.6
* Support added to accept objects implementing :class:`os.PathLike`.
* On Windows, opening a console buffer may return a subclass of
:class:`io.RawIOBase` other than :class:`io.FileIO`.
* Support added to accept objects implementing :class:`os.PathLike`.
* On Windows, opening a console buffer may return a subclass of
:class:`io.RawIOBase` other than :class:`io.FileIO`.
.. versionchanged:: 3.11
The ``'U'`` mode has been removed.

16
Doc/library/graphlib.rst
View File

@ -37,14 +37,14 @@
In the general case, the steps required to perform the sorting of a given
graph are as follows:
* Create an instance of the :class:`TopologicalSorter` with an optional
initial graph.
* Add additional nodes to the graph.
* Call :meth:`~TopologicalSorter.prepare` on the graph.
* While :meth:`~TopologicalSorter.is_active` is ``True``, iterate over
the nodes returned by :meth:`~TopologicalSorter.get_ready` and
process them. Call :meth:`~TopologicalSorter.done` on each node as it
finishes processing.
* Create an instance of the :class:`TopologicalSorter` with an optional
initial graph.
* Add additional nodes to the graph.
* Call :meth:`~TopologicalSorter.prepare` on the graph.
* While :meth:`~TopologicalSorter.is_active` is ``True``, iterate over
the nodes returned by :meth:`~TopologicalSorter.get_ready` and
process them. Call :meth:`~TopologicalSorter.done` on each node as it
finishes processing.
In case just an immediate sorting of the nodes in the graph is required and
no parallelism is involved, the convenience method

22
Doc/library/idle.rst
View File

@ -439,24 +439,24 @@ the :kbd:`Command` key on macOS.
* Some useful Emacs bindings are inherited from Tcl/Tk:
* :kbd:`C-a` beginning of line
* :kbd:`C-a` beginning of line
* :kbd:`C-e` end of line
* :kbd:`C-e` end of line
* :kbd:`C-k` kill line (but doesn't put it in clipboard)
* :kbd:`C-k` kill line (but doesn't put it in clipboard)
* :kbd:`C-l` center window around the insertion point
* :kbd:`C-l` center window around the insertion point
* :kbd:`C-b` go backward one character without deleting (usually you can
also use the cursor key for this)
* :kbd:`C-b` go backward one character without deleting (usually you can
also use the cursor key for this)
* :kbd:`C-f` go forward one character without deleting (usually you can
also use the cursor key for this)
* :kbd:`C-f` go forward one character without deleting (usually you can
also use the cursor key for this)
* :kbd:`C-p` go up one line (usually you can also use the cursor key for
this)
* :kbd:`C-p` go up one line (usually you can also use the cursor key for
this)
* :kbd:`C-d` delete next character
* :kbd:`C-d` delete next character
Standard keybindings (like :kbd:`C-c` to copy and :kbd:`C-v` to paste)
may work. Keybindings are selected in the Configure IDLE dialog.

27
Doc/library/inspect.rst
View File

@ -1463,10 +1463,11 @@ generator to be determined easily.
Get current state of a generator-iterator.
Possible states are:
* GEN_CREATED: Waiting to start execution.
* GEN_RUNNING: Currently being executed by the interpreter.
* GEN_SUSPENDED: Currently suspended at a yield expression.
* GEN_CLOSED: Execution has completed.
* GEN_CREATED: Waiting to start execution.
* GEN_RUNNING: Currently being executed by the interpreter.
* GEN_SUSPENDED: Currently suspended at a yield expression.
* GEN_CLOSED: Execution has completed.
.. versionadded:: 3.2
@ -1478,10 +1479,11 @@ generator to be determined easily.
``cr_frame`` attributes.
Possible states are:
* CORO_CREATED: Waiting to start execution.
* CORO_RUNNING: Currently being executed by the interpreter.
* CORO_SUSPENDED: Currently suspended at an await expression.
* CORO_CLOSED: Execution has completed.
* CORO_CREATED: Waiting to start execution.
* CORO_RUNNING: Currently being executed by the interpreter.
* CORO_SUSPENDED: Currently suspended at an await expression.
* CORO_CLOSED: Execution has completed.
.. versionadded:: 3.5
@ -1494,10 +1496,11 @@ generator to be determined easily.
``ag_running`` and ``ag_frame`` attributes.
Possible states are:
* AGEN_CREATED: Waiting to start execution.
* AGEN_RUNNING: Currently being executed by the interpreter.
* AGEN_SUSPENDED: Currently suspended at a yield expression.
* AGEN_CLOSED: Execution has completed.
* AGEN_CREATED: Waiting to start execution.
* AGEN_RUNNING: Currently being executed by the interpreter.
* AGEN_SUSPENDED: Currently suspended at a yield expression.
* AGEN_CLOSED: Execution has completed.
.. versionadded:: 3.12

10
Doc/library/io.rst
View File

@ -253,12 +253,12 @@ The implementation of I/O streams is organized as a hierarchy of classes. First
specify the various categories of streams, then concrete classes providing the
standard stream implementations.
.. note::
.. note::
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes. For
example, :class:`BufferedIOBase` provides unoptimized implementations of
:meth:`!readinto` and :meth:`!readline`.
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes. For
example, :class:`BufferedIOBase` provides unoptimized implementations of
:meth:`!readinto` and :meth:`!readline`.
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
defines the basic interface to a stream. Note, however, that there is no

16
Doc/library/logging.config.rst
View File

@ -257,11 +257,11 @@ otherwise, the context is used to determine what to instantiate.
which correspond to the arguments passed to create a
:class:`~logging.Formatter` object:
* ``format``
* ``datefmt``
* ``style``
* ``validate`` (since version >=3.8)
* ``defaults`` (since version >=3.12)
* ``format``
* ``datefmt``
* ``style``
* ``validate`` (since version >=3.8)
* ``defaults`` (since version >=3.12)
An optional ``class`` key indicates the name of the formatter's
class (as a dotted module and class name). The instantiation
@ -544,9 +544,9 @@ valid keyword parameter name, and so will not clash with the names of
the keyword arguments used in the call. The ``'()'`` also serves as a
mnemonic that the corresponding value is a callable.
.. versionchanged:: 3.11
The ``filters`` member of ``handlers`` and ``loggers`` can take
filter instances in addition to ids.
.. versionchanged:: 3.11
The ``filters`` member of ``handlers`` and ``loggers`` can take
filter instances in addition to ids.
You can also specify a special key ``'.'`` whose value is a dictionary is a
mapping of attribute names to values. If found, the specified attributes will

51
Doc/library/lzma.rst
View File

@ -333,19 +333,22 @@ the key ``"id"``, and may contain additional keys to specify filter-dependent
options. Valid filter IDs are as follows:
* Compression filters:
* :const:`FILTER_LZMA1` (for use with :const:`FORMAT_ALONE`)
* :const:`FILTER_LZMA2` (for use with :const:`FORMAT_XZ` and :const:`FORMAT_RAW`)
* :const:`FILTER_LZMA1` (for use with :const:`FORMAT_ALONE`)
* :const:`FILTER_LZMA2` (for use with :const:`FORMAT_XZ` and :const:`FORMAT_RAW`)
* Delta filter:
* :const:`FILTER_DELTA`
* :const:`FILTER_DELTA`
* Branch-Call-Jump (BCJ) filters:
* :const:`FILTER_X86`
* :const:`FILTER_IA64`
* :const:`FILTER_ARM`
* :const:`FILTER_ARMTHUMB`
* :const:`FILTER_POWERPC`
* :const:`FILTER_SPARC`
* :const:`FILTER_X86`
* :const:`FILTER_IA64`
* :const:`FILTER_ARM`
* :const:`FILTER_ARMTHUMB`
* :const:`FILTER_POWERPC`
* :const:`FILTER_SPARC`
A filter chain can consist of up to 4 filters, and cannot be empty. The last
filter in the chain must be a compression filter, and any other filters must be
@ -354,21 +357,21 @@ delta or BCJ filters.
Compression filters support the following options (specified as additional
entries in the dictionary representing the filter):
* ``preset``: A compression preset to use as a source of default values for
options that are not specified explicitly.
* ``dict_size``: Dictionary size in bytes. This should be between 4 KiB and
1.5 GiB (inclusive).
* ``lc``: Number of literal context bits.
* ``lp``: Number of literal position bits. The sum ``lc + lp`` must be at
most 4.
* ``pb``: Number of position bits; must be at most 4.
* ``mode``: :const:`MODE_FAST` or :const:`MODE_NORMAL`.
* ``nice_len``: What should be considered a "nice length" for a match.
This should be 273 or less.
* ``mf``: What match finder to use -- :const:`MF_HC3`, :const:`MF_HC4`,
:const:`MF_BT2`, :const:`MF_BT3`, or :const:`MF_BT4`.
* ``depth``: Maximum search depth used by match finder. 0 (default) means to
select automatically based on other filter options.
* ``preset``: A compression preset to use as a source of default values for
options that are not specified explicitly.
* ``dict_size``: Dictionary size in bytes. This should be between 4 KiB and
1.5 GiB (inclusive).
* ``lc``: Number of literal context bits.
* ``lp``: Number of literal position bits. The sum ``lc + lp`` must be at
most 4.
* ``pb``: Number of position bits; must be at most 4.
* ``mode``: :const:`MODE_FAST` or :const:`MODE_NORMAL`.
* ``nice_len``: What should be considered a "nice length" for a match.
This should be 273 or less.
* ``mf``: What match finder to use -- :const:`MF_HC3`, :const:`MF_HC4`,
:const:`MF_BT2`, :const:`MF_BT3`, or :const:`MF_BT4`.
* ``depth``: Maximum search depth used by match finder. 0 (default) means to
select automatically based on other filter options.
The delta filter stores the differences between bytes, producing more repetitive
input for the compressor in certain circumstances. It supports one option,

24
Doc/library/multiprocessing.rst
View File

@ -2792,20 +2792,20 @@ worker threads rather than worker processes.
Unlike :class:`Pool`, *maxtasksperchild* and *context* cannot be provided.
.. note::
.. note::
A :class:`ThreadPool` shares the same interface as :class:`Pool`, which
is designed around a pool of processes and predates the introduction of
the :class:`concurrent.futures` module. As such, it inherits some
operations that don't make sense for a pool backed by threads, and it
has its own type for representing the status of asynchronous jobs,
:class:`AsyncResult`, that is not understood by any other libraries.
A :class:`ThreadPool` shares the same interface as :class:`Pool`, which
is designed around a pool of processes and predates the introduction of
the :class:`concurrent.futures` module. As such, it inherits some
operations that don't make sense for a pool backed by threads, and it
has its own type for representing the status of asynchronous jobs,
:class:`AsyncResult`, that is not understood by any other libraries.
Users should generally prefer to use
:class:`concurrent.futures.ThreadPoolExecutor`, which has a simpler
interface that was designed around threads from the start, and which
returns :class:`concurrent.futures.Future` instances that are
compatible with many other libraries, including :mod:`asyncio`.
Users should generally prefer to use
:class:`concurrent.futures.ThreadPoolExecutor`, which has a simpler
interface that was designed around threads from the start, and which
returns :class:`concurrent.futures.Future` instances that are
compatible with many other libraries, including :mod:`asyncio`.
.. _multiprocessing-programming:

34
Doc/library/numbers.rst
View File

@ -160,23 +160,23 @@ refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as
of :class:`Complex` (``a : A <: Complex``), and ``b : B <:
Complex``. I'll consider ``a + b``:
1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is
well.
2. If ``A`` falls back to the boilerplate code, and it were to
return a value from :meth:`__add__`, we'd miss the possibility
that ``B`` defines a more intelligent :meth:`__radd__`, so the
boilerplate should return :const:`NotImplemented` from
:meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at
all.)
3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts
``a``, all is well.
4. If it falls back to the boilerplate, there are no more possible
methods to try, so this is where the default implementation
should live.
5. If ``B <: A``, Python tries ``B.__radd__`` before
``A.__add__``. This is ok, because it was implemented with
knowledge of ``A``, so it can handle those instances before
delegating to :class:`Complex`.
1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is
well.
2. If ``A`` falls back to the boilerplate code, and it were to
return a value from :meth:`__add__`, we'd miss the possibility
that ``B`` defines a more intelligent :meth:`__radd__`, so the
boilerplate should return :const:`NotImplemented` from
:meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at
all.)
3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts
``a``, all is well.
4. If it falls back to the boilerplate, there are no more possible
methods to try, so this is where the default implementation
should live.
5. If ``B <: A``, Python tries ``B.__radd__`` before
``A.__add__``. This is ok, because it was implemented with
knowledge of ``A``, so it can handle those instances before
delegating to :class:`Complex`.
If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge,
then the appropriate shared operation is the one involving the built

8
Doc/library/profile.rst
View File

@ -135,11 +135,11 @@ the output by. This only applies when ``-o`` is not supplied.
``-m`` specifies that a module is being profiled instead of a script.
.. versionadded:: 3.7
Added the ``-m`` option to :mod:`cProfile`.
.. versionadded:: 3.7
Added the ``-m`` option to :mod:`cProfile`.
.. versionadded:: 3.8
Added the ``-m`` option to :mod:`profile`.
.. versionadded:: 3.8
Added the ``-m`` option to :mod:`profile`.
The :mod:`pstats` module's :class:`~pstats.Stats` class has a variety of methods
for manipulating and printing the data saved into a profile results file::

2
Doc/library/re.rst
View File

@ -176,7 +176,7 @@ The special characters are:
``x*+``, ``x++`` and ``x?+`` are equivalent to ``(?>x*)``, ``(?>x+)``
and ``(?>x?)`` correspondingly.
.. versionadded:: 3.11
.. versionadded:: 3.11
.. index::
single: {} (curly brackets); in regular expressions

6
Doc/library/shelve.rst
View File

@ -94,9 +94,9 @@ Two additional methods are supported:
Restrictions
------------
.. index::
pair: module; dbm.ndbm
pair: module; dbm.gnu
.. index::
pair: module; dbm.ndbm
pair: module; dbm.gnu
* The choice of which database package will be used (such as :mod:`dbm.ndbm` or
:mod:`dbm.gnu`) depends on which interface is available. Therefore it is not

4
Doc/library/socket.rst
View File

@ -207,14 +207,14 @@ created. Socket addresses are represented as follows:
- *addr* - Optional bytes-like object specifying the hardware physical
address, whose interpretation depends on the device.
.. availability:: Linux >= 2.2.
.. availability:: Linux >= 2.2.
- :const:`AF_QIPCRTR` is a Linux-only socket based interface for communicating
with services running on co-processors in Qualcomm platforms. The address
family is represented as a ``(node, port)`` tuple where the *node* and *port*
are non-negative integers.
.. availability:: Linux >= 4.7.
.. availability:: Linux >= 4.7.
.. versionadded:: 3.8

24
Doc/library/sqlite3.rst
View File

@ -235,11 +235,11 @@ inserted data and retrieved values from it in multiple ways.
* :ref:`sqlite3-howtos` for further reading:
* :ref:`sqlite3-placeholders`
* :ref:`sqlite3-adapters`
* :ref:`sqlite3-converters`
* :ref:`sqlite3-connection-context-manager`
* :ref:`sqlite3-howto-row-factory`
* :ref:`sqlite3-placeholders`
* :ref:`sqlite3-adapters`
* :ref:`sqlite3-converters`
* :ref:`sqlite3-connection-context-manager`
* :ref:`sqlite3-howto-row-factory`
* :ref:`sqlite3-explanation` for in-depth background on transaction control.
@ -529,13 +529,13 @@ Module constants
the default `threading mode <https://sqlite.org/threadsafe.html>`_ the
underlying SQLite library is compiled with. The SQLite threading modes are:
1. **Single-thread**: In this mode, all mutexes are disabled and SQLite is
unsafe to use in more than a single thread at once.
2. **Multi-thread**: In this mode, SQLite can be safely used by multiple
threads provided that no single database connection is used
simultaneously in two or more threads.
3. **Serialized**: In serialized mode, SQLite can be safely used by
multiple threads with no restriction.
1. **Single-thread**: In this mode, all mutexes are disabled and SQLite is
unsafe to use in more than a single thread at once.
2. **Multi-thread**: In this mode, SQLite can be safely used by multiple
threads provided that no single database connection is used
simultaneously in two or more threads.
3. **Serialized**: In serialized mode, SQLite can be safely used by
multiple threads with no restriction.
The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels
are as follows:

22
Doc/library/ssl.rst
View File

@ -1398,18 +1398,18 @@ to speed up repeated connections from the same clients.
Here's a table showing which versions in a client (down the side) can connect
to which versions in a server (along the top):
.. table::
.. table::
======================== ============ ============ ============= ========= =========== ===========
*client* / **server** **SSLv2** **SSLv3** **TLS** [3]_ **TLSv1** **TLSv1.1** **TLSv1.2**
------------------------ ------------ ------------ ------------- --------- ----------- -----------
*SSLv2* yes no no [1]_ no no no
*SSLv3* no yes no [2]_ no no no
*TLS* (*SSLv23*) [3]_ no [1]_ no [2]_ yes yes yes yes
*TLSv1* no no yes yes no no
*TLSv1.1* no no yes no yes no
*TLSv1.2* no no yes no no yes
======================== ============ ============ ============= ========= =========== ===========
======================== ============ ============ ============= ========= =========== ===========
*client* / **server** **SSLv2** **SSLv3** **TLS** [3]_ **TLSv1** **TLSv1.1** **TLSv1.2**
------------------------ ------------ ------------ ------------- --------- ----------- -----------
*SSLv2* yes no no [1]_ no no no
*SSLv3* no yes no [2]_ no no no
*TLS* (*SSLv23*) [3]_ no [1]_ no [2]_ yes yes yes yes
*TLSv1* no no yes yes no no
*TLSv1.1* no no yes no yes no
*TLSv1.2* no no yes no no yes
======================== ============ ============ ============= ========= =========== ===========
.. rubric:: Footnotes
.. [1] :class:`SSLContext` disables SSLv2 with :data:`OP_NO_SSLv2` by default.

6
Doc/library/stdtypes.rst
View File

@ -48,9 +48,9 @@ By default, an object is considered true unless its class defines either a
returns zero, when called with the object. [1]_ Here are most of the built-in
objects considered false:
.. index::
single: None (Built-in object)
single: False (Built-in object)
.. index::
single: None (Built-in object)
single: False (Built-in object)
* constants defined to be false: ``None`` and ``False``

96
Doc/library/string.rst
View File

@ -206,15 +206,15 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
The grammar for a replacement field is as follows:
.. productionlist:: format-string
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: [`identifier` | `digit`+]
attribute_name: `identifier`
element_index: `digit`+ | `index_string`
index_string: <any source character except "]"> +
conversion: "r" | "s" | "a"
format_spec: <described in the next section>
.. productionlist:: format-string
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: [`identifier` | `digit`+]
attribute_name: `identifier`
element_index: `digit`+ | `index_string`
index_string: <any source character except "]"> +
conversion: "r" | "s" | "a"
format_spec: <described in the next section>
In less formal terms, the replacement field can start with a *field_name* that specifies
the object whose value is to be formatted and inserted
@ -332,30 +332,30 @@ affect the :func:`format` function.
The meaning of the various alignment options is as follows:
.. index::
single: < (less); in string formatting
single: > (greater); in string formatting
single: = (equals); in string formatting
single: ^ (caret); in string formatting
.. index::
single: < (less); in string formatting
single: > (greater); in string formatting
single: = (equals); in string formatting
single: ^ (caret); in string formatting
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
| ``'<'`` | Forces the field to be left-aligned within the available |
| | space (this is the default for most objects). |
+---------+----------------------------------------------------------+
| ``'>'`` | Forces the field to be right-aligned within the |
| | available space (this is the default for numbers). |
+---------+----------------------------------------------------------+
| ``'='`` | Forces the padding to be placed after the sign (if any) |
| | but before the digits. This is used for printing fields |
| | in the form '+000000120'. This alignment option is only |
| | valid for numeric types. It becomes the default for |
| | numbers when '0' immediately precedes the field width. |
+---------+----------------------------------------------------------+
| ``'^'`` | Forces the field to be centered within the available |
| | space. |
+---------+----------------------------------------------------------+
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
| ``'<'`` | Forces the field to be left-aligned within the available |
| | space (this is the default for most objects). |
+---------+----------------------------------------------------------+
| ``'>'`` | Forces the field to be right-aligned within the |
| | available space (this is the default for numbers). |
+---------+----------------------------------------------------------+
| ``'='`` | Forces the padding to be placed after the sign (if any) |
| | but before the digits. This is used for printing fields |
| | in the form '+000000120'. This alignment option is only |
| | valid for numeric types. It becomes the default for |
| | numbers when '0' immediately precedes the field width. |
+---------+----------------------------------------------------------+
| ``'^'`` | Forces the field to be centered within the available |
| | space. |
+---------+----------------------------------------------------------+
Note that unless a minimum field width is defined, the field width will always
be the same size as the data to fill it, so that the alignment option has no
@ -364,23 +364,23 @@ meaning in this case.
The *sign* option is only valid for number types, and can be one of the
following:
.. index::
single: + (plus); in string formatting
single: - (minus); in string formatting
single: space; in string formatting
.. index::
single: + (plus); in string formatting
single: - (minus); in string formatting
single: space; in string formatting
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
| ``'+'`` | indicates that a sign should be used for both |
| | positive as well as negative numbers. |
+---------+----------------------------------------------------------+
| ``'-'`` | indicates that a sign should be used only for negative |
| | numbers (this is the default behavior). |
+---------+----------------------------------------------------------+
| space | indicates that a leading space should be used on |
| | positive numbers, and a minus sign on negative numbers. |
+---------+----------------------------------------------------------+
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
| ``'+'`` | indicates that a sign should be used for both |
| | positive as well as negative numbers. |
+---------+----------------------------------------------------------+
| ``'-'`` | indicates that a sign should be used only for negative |
| | numbers (this is the default behavior). |
+---------+----------------------------------------------------------+
| space | indicates that a leading space should be used on |
| | positive numbers, and a minus sign on negative numbers. |
+---------+----------------------------------------------------------+
.. index:: single: z; in string formatting

28
Doc/library/subprocess.rst
View File

@ -666,18 +666,18 @@ functions.
passed to the underlying ``CreateProcess`` function.
*creationflags*, if given, can be one or more of the following flags:
* :data:`CREATE_NEW_CONSOLE`
* :data:`CREATE_NEW_PROCESS_GROUP`
* :data:`ABOVE_NORMAL_PRIORITY_CLASS`
* :data:`BELOW_NORMAL_PRIORITY_CLASS`
* :data:`HIGH_PRIORITY_CLASS`
* :data:`IDLE_PRIORITY_CLASS`
* :data:`NORMAL_PRIORITY_CLASS`
* :data:`REALTIME_PRIORITY_CLASS`
* :data:`CREATE_NO_WINDOW`
* :data:`DETACHED_PROCESS`
* :data:`CREATE_DEFAULT_ERROR_MODE`
* :data:`CREATE_BREAKAWAY_FROM_JOB`
* :data:`CREATE_NEW_CONSOLE`
* :data:`CREATE_NEW_PROCESS_GROUP`
* :data:`ABOVE_NORMAL_PRIORITY_CLASS`
* :data:`BELOW_NORMAL_PRIORITY_CLASS`
* :data:`HIGH_PRIORITY_CLASS`
* :data:`IDLE_PRIORITY_CLASS`
* :data:`NORMAL_PRIORITY_CLASS`
* :data:`REALTIME_PRIORITY_CLASS`
* :data:`CREATE_NO_WINDOW`
* :data:`DETACHED_PROCESS`
* :data:`CREATE_DEFAULT_ERROR_MODE`
* :data:`CREATE_BREAKAWAY_FROM_JOB`
*pipesize* can be used to change the size of the pipe when
:data:`PIPE` is used for *stdin*, *stdout* or *stderr*. The size of the pipe
@ -742,8 +742,8 @@ the timeout expires before the process exits.
Exceptions defined in this module all inherit from :exc:`SubprocessError`.
.. versionadded:: 3.3
The :exc:`SubprocessError` base class was added.
.. versionadded:: 3.3
The :exc:`SubprocessError` base class was added.
.. _subprocess-security:

16
Doc/library/tempfile.rst
View File

@ -115,14 +115,14 @@ The module defines the following user-callable items:
* On Windows, make sure that at least one of the following conditions are
fulfilled:
* *delete* is false
* additional open shares delete access (e.g. by calling :func:`os.open`
with the flag ``O_TEMPORARY``)
* *delete* is true but *delete_on_close* is false. Note, that in this
case the additional opens that do not share delete access (e.g.
created via builtin :func:`open`) must be closed before exiting the
context manager, else the :func:`os.unlink` call on context manager
exit will fail with a :exc:`PermissionError`.
* *delete* is false
* additional open shares delete access (e.g. by calling :func:`os.open`
with the flag ``O_TEMPORARY``)
* *delete* is true but *delete_on_close* is false. Note, that in this
case the additional opens that do not share delete access (e.g.
created via builtin :func:`open`) must be closed before exiting the
context manager, else the :func:`os.unlink` call on context manager
exit will fail with a :exc:`PermissionError`.
On Windows, if *delete_on_close* is false, and the file is created in a
directory for which the user lacks delete access, then the :func:`os.unlink`

30
Doc/library/tkinter.rst
View File

@ -529,24 +529,24 @@ interpreter will fail.
A number of special cases exist:
* Tcl/Tk libraries can be built so they are not thread-aware. In this case,
:mod:`tkinter` calls the library from the originating Python thread, even
if this is different than the thread that created the Tcl interpreter. A global
lock ensures only one call occurs at a time.
* Tcl/Tk libraries can be built so they are not thread-aware. In this case,
:mod:`tkinter` calls the library from the originating Python thread, even
if this is different than the thread that created the Tcl interpreter. A global
lock ensures only one call occurs at a time.
* While :mod:`tkinter` allows you to create more than one instance of a :class:`Tk`
object (with its own interpreter), all interpreters that are part of the same
thread share a common event queue, which gets ugly fast. In practice, don't create
more than one instance of :class:`Tk` at a time. Otherwise, it's best to create
them in separate threads and ensure you're running a thread-aware Tcl/Tk build.
* While :mod:`tkinter` allows you to create more than one instance of a :class:`Tk`
object (with its own interpreter), all interpreters that are part of the same
thread share a common event queue, which gets ugly fast. In practice, don't create
more than one instance of :class:`Tk` at a time. Otherwise, it's best to create
them in separate threads and ensure you're running a thread-aware Tcl/Tk build.
* Blocking event handlers are not the only way to prevent the Tcl interpreter from
reentering the event loop. It is even possible to run multiple nested event loops
or abandon the event loop entirely. If you're doing anything tricky when it comes
to events or threads, be aware of these possibilities.
* Blocking event handlers are not the only way to prevent the Tcl interpreter from
reentering the event loop. It is even possible to run multiple nested event loops
or abandon the event loop entirely. If you're doing anything tricky when it comes
to events or threads, be aware of these possibilities.
* There are a few select :mod:`tkinter` functions that presently work only when
called from the thread that created the Tcl interpreter.
* There are a few select :mod:`tkinter` functions that presently work only when
called from the thread that created the Tcl interpreter.
Handy Reference

728
Doc/library/tkinter.ttk.rst
View File

@ -104,33 +104,33 @@ Standard Options
All the :mod:`ttk` Widgets accept the following options:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+-----------+--------------------------------------------------------------+
| Option | Description |
+===========+==============================================================+
| class | Specifies the window class. The class is used when querying |
| | the option database for the window's other options, to |
| | determine the default bindtags for the window, and to select |
| | the widget's default layout and style. This option is |
| | read-only, and may only be specified when the window is |
| | created. |
+-----------+--------------------------------------------------------------+
| cursor | Specifies the mouse cursor to be used for the widget. If set |
| | to the empty string (the default), the cursor is inherited |
| | for the parent widget. |
+-----------+--------------------------------------------------------------+
| takefocus | Determines whether the window accepts the focus during |
| | keyboard traversal. 0, 1 or an empty string is returned. |
| | If 0 is returned, it means that the window should be skipped |
| | entirely during keyboard traversal. If 1, it means that the |
| | window should receive the input focus as long as it is |
| | viewable. And an empty string means that the traversal |
| | scripts make the decision about whether or not to focus |
| | on the window. |
+-----------+--------------------------------------------------------------+
| style | May be used to specify a custom widget style. |
+-----------+--------------------------------------------------------------+
+-----------+--------------------------------------------------------------+
| Option | Description |
+===========+==============================================================+
| class | Specifies the window class. The class is used when querying |
| | the option database for the window's other options, to |
| | determine the default bindtags for the window, and to select |
| | the widget's default layout and style. This option is |
| | read-only, and may only be specified when the window is |
| | created. |
+-----------+--------------------------------------------------------------+
| cursor | Specifies the mouse cursor to be used for the widget. If set |
| | to the empty string (the default), the cursor is inherited |
| | for the parent widget. |
+-----------+--------------------------------------------------------------+
| takefocus | Determines whether the window accepts the focus during |
| | keyboard traversal. 0, 1 or an empty string is returned. |
| | If 0 is returned, it means that the window should be skipped |
| | entirely during keyboard traversal. If 1, it means that the |
| | window should receive the input focus as long as it is |
| | viewable. And an empty string means that the traversal |
| | scripts make the decision about whether or not to focus |
| | on the window. |
+-----------+--------------------------------------------------------------+
| style | May be used to specify a custom widget style. |
+-----------+--------------------------------------------------------------+
Scrollable Widget Options
@ -139,24 +139,24 @@ Scrollable Widget Options
The following options are supported by widgets that are controlled by a
scrollbar.
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+----------------+---------------------------------------------------------+
| Option | Description |
+================+=========================================================+
| xscrollcommand | Used to communicate with horizontal scrollbars. |
| | |
| | When the view in the widget's window change, the widget |
| | will generate a Tcl command based on the scrollcommand. |
| | |
| | Usually this option consists of the method |
| | :meth:`Scrollbar.set` of some scrollbar. This will cause|
| | the scrollbar to be updated whenever the view in the |
| | window changes. |
+----------------+---------------------------------------------------------+
| yscrollcommand | Used to communicate with vertical scrollbars. |
| | For some more information, see above. |
+----------------+---------------------------------------------------------+
+----------------+---------------------------------------------------------+
| Option | Description |
+================+=========================================================+
| xscrollcommand | Used to communicate with horizontal scrollbars. |
| | |
| | When the view in the widget's window change, the widget |
| | will generate a Tcl command based on the scrollcommand. |
| | |
| | Usually this option consists of the method |
| | :meth:`Scrollbar.set` of some scrollbar. This will cause|
| | the scrollbar to be updated whenever the view in the |
| | window changes. |
+----------------+---------------------------------------------------------+
| yscrollcommand | Used to communicate with vertical scrollbars. |
| | For some more information, see above. |
+----------------+---------------------------------------------------------+
Label Options
@ -165,93 +165,93 @@ Label Options
The following options are supported by labels, buttons and other button-like
widgets.
.. tabularcolumns:: |l|p{0.7\linewidth}|
.. tabularcolumns:: |l|p{0.7\linewidth}|
+--------------+-----------------------------------------------------------+
| Option | Description |
+==============+===========================================================+
| text | Specifies a text string to be displayed inside the widget.|
+--------------+-----------------------------------------------------------+
| textvariable | Specifies a name whose value will be used in place of the |
| | text option resource. |
+--------------+-----------------------------------------------------------+
| underline | If set, specifies the index (0-based) of a character to |
| | underline in the text string. The underline character is |
| | used for mnemonic activation. |
+--------------+-----------------------------------------------------------+
| image | Specifies an image to display. This is a list of 1 or more|
| | elements. The first element is the default image name. The|
| | rest of the list if a sequence of statespec/value pairs as|
| | defined by :meth:`Style.map`, specifying different images |
| | to use when the widget is in a particular state or a |
| | combination of states. All images in the list should have |
| | the same size. |
+--------------+-----------------------------------------------------------+
| compound | Specifies how to display the image relative to the text, |
| | in the case both text and images options are present. |
| | Valid values are: |
| | |
| | * text: display text only |
| | * image: display image only |
| | * top, bottom, left, right: display image above, below, |
| | left of, or right of the text, respectively. |
| | * none: the default. display the image if present, |
| | otherwise the text. |
+--------------+-----------------------------------------------------------+
| width | If greater than zero, specifies how much space, in |
| | character widths, to allocate for the text label, if less |
| | than zero, specifies a minimum width. If zero or |
| | unspecified, the natural width of the text label is used. |
+--------------+-----------------------------------------------------------+
+--------------+-----------------------------------------------------------+
| Option | Description |
+==============+===========================================================+
| text | Specifies a text string to be displayed inside the widget.|
+--------------+-----------------------------------------------------------+
| textvariable | Specifies a name whose value will be used in place of the |
| | text option resource. |
+--------------+-----------------------------------------------------------+
| underline | If set, specifies the index (0-based) of a character to |
| | underline in the text string. The underline character is |
| | used for mnemonic activation. |
+--------------+-----------------------------------------------------------+
| image | Specifies an image to display. This is a list of 1 or more|
| | elements. The first element is the default image name. The|
| | rest of the list if a sequence of statespec/value pairs as|
| | defined by :meth:`Style.map`, specifying different images |
| | to use when the widget is in a particular state or a |
| | combination of states. All images in the list should have |
| | the same size. |
+--------------+-----------------------------------------------------------+
| compound | Specifies how to display the image relative to the text, |
| | in the case both text and images options are present. |
| | Valid values are: |
| | |
| | * text: display text only |
| | * image: display image only |
| | * top, bottom, left, right: display image above, below, |
| | left of, or right of the text, respectively. |
| | * none: the default. display the image if present, |
| | otherwise the text. |
+--------------+-----------------------------------------------------------+
| width | If greater than zero, specifies how much space, in |
| | character widths, to allocate for the text label, if less |
| | than zero, specifies a minimum width. If zero or |
| | unspecified, the natural width of the text label is used. |
+--------------+-----------------------------------------------------------+
Compatibility Options
^^^^^^^^^^^^^^^^^^^^^
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+--------+----------------------------------------------------------------+
| Option | Description |
+========+================================================================+
| state | May be set to "normal" or "disabled" to control the "disabled" |
| | state bit. This is a write-only option: setting it changes the |
| | widget state, but the :meth:`Widget.state` method does not |
| | affect this option. |
+--------+----------------------------------------------------------------+
+--------+----------------------------------------------------------------+
| Option | Description |
+========+================================================================+
| state | May be set to "normal" or "disabled" to control the "disabled" |
| | state bit. This is a write-only option: setting it changes the |
| | widget state, but the :meth:`Widget.state` method does not |
| | affect this option. |
+--------+----------------------------------------------------------------+
Widget States
^^^^^^^^^^^^^
The widget state is a bitmap of independent state flags.
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+------------+-------------------------------------------------------------+
| Flag | Description |
+============+=============================================================+
| active | The mouse cursor is over the widget and pressing a mouse |
| | button will cause some action to occur |
+------------+-------------------------------------------------------------+
| disabled | Widget is disabled under program control |
+------------+-------------------------------------------------------------+
| focus | Widget has keyboard focus |
+------------+-------------------------------------------------------------+
| pressed | Widget is being pressed |
+------------+-------------------------------------------------------------+
| selected | "On", "true", or "current" for things like Checkbuttons and |
| | radiobuttons |
+------------+-------------------------------------------------------------+
| background | Windows and Mac have a notion of an "active" or foreground |
| | window. The *background* state is set for widgets in a |
| | background window, and cleared for those in the foreground |
| | window |
+------------+-------------------------------------------------------------+
| readonly | Widget should not allow user modification |
+------------+-------------------------------------------------------------+
| alternate | A widget-specific alternate display format |
+------------+-------------------------------------------------------------+
| invalid | The widget's value is invalid |
+------------+-------------------------------------------------------------+
+------------+-------------------------------------------------------------+
| Flag | Description |
+============+=============================================================+
| active | The mouse cursor is over the widget and pressing a mouse |
| | button will cause some action to occur |
+------------+-------------------------------------------------------------+
| disabled | Widget is disabled under program control |
+------------+-------------------------------------------------------------+
| focus | Widget has keyboard focus |
+------------+-------------------------------------------------------------+
| pressed | Widget is being pressed |
+------------+-------------------------------------------------------------+
| selected | "On", "true", or "current" for things like Checkbuttons and |
| | radiobuttons |
+------------+-------------------------------------------------------------+
| background | Windows and Mac have a notion of an "active" or foreground |
| | window. The *background* state is set for widgets in a |
| | background window, and cleared for those in the foreground |
| | window |
+------------+-------------------------------------------------------------+
| readonly | Widget should not allow user modification |
+------------+-------------------------------------------------------------+
| alternate | A widget-specific alternate display format |
+------------+-------------------------------------------------------------+
| invalid | The widget's value is invalid |
+------------+-------------------------------------------------------------+
A state specification is a sequence of state names, optionally prefixed with
an exclamation point indicating that the bit is off.
@ -311,43 +311,43 @@ Options
This widget accepts the following specific options:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+-----------------+--------------------------------------------------------+
| Option | Description |
+=================+========================================================+
| exportselection | Boolean value. If set, the widget selection is linked |
| | to the Window Manager selection (which can be returned |
| | by invoking Misc.selection_get, for example). |
+-----------------+--------------------------------------------------------+
| justify | Specifies how the text is aligned within the widget. |
| | One of "left", "center", or "right". |
+-----------------+--------------------------------------------------------+
| height | Specifies the height of the pop-down listbox, in rows. |
+-----------------+--------------------------------------------------------+
| postcommand | A script (possibly registered with Misc.register) that |
| | is called immediately before displaying the values. It |
| | may specify which values to display. |
+-----------------+--------------------------------------------------------+
| state | One of "normal", "readonly", or "disabled". In the |
| | "readonly" state, the value may not be edited directly,|
| | and the user can only selection of the values from the |
| | dropdown list. In the "normal" state, the text field is|
| | directly editable. In the "disabled" state, no |
| | interaction is possible. |
+-----------------+--------------------------------------------------------+
| textvariable | Specifies a name whose value is linked to the widget |
| | value. Whenever the value associated with that name |
| | changes, the widget value is updated, and vice versa. |
| | See :class:`tkinter.StringVar`. |
+-----------------+--------------------------------------------------------+
| values | Specifies the list of values to display in the |
| | drop-down listbox. |
+-----------------+--------------------------------------------------------+
| width | Specifies an integer value indicating the desired width|
| | of the entry window, in average-size characters of the |
| | widget's font. |
+-----------------+--------------------------------------------------------+
+-----------------+--------------------------------------------------------+
| Option | Description |
+=================+========================================================+
| exportselection | Boolean value. If set, the widget selection is linked |
| | to the Window Manager selection (which can be returned |
| | by invoking Misc.selection_get, for example). |
+-----------------+--------------------------------------------------------+
| justify | Specifies how the text is aligned within the widget. |
| | One of "left", "center", or "right". |
+-----------------+--------------------------------------------------------+
| height | Specifies the height of the pop-down listbox, in rows. |
+-----------------+--------------------------------------------------------+
| postcommand | A script (possibly registered with Misc.register) that |
| | is called immediately before displaying the values. It |
| | may specify which values to display. |
+-----------------+--------------------------------------------------------+
| state | One of "normal", "readonly", or "disabled". In the |
| | "readonly" state, the value may not be edited directly,|
| | and the user can only selection of the values from the |
| | dropdown list. In the "normal" state, the text field is|
| | directly editable. In the "disabled" state, no |
| | interaction is possible. |
+-----------------+--------------------------------------------------------+
| textvariable | Specifies a name whose value is linked to the widget |
| | value. Whenever the value associated with that name |
| | changes, the widget value is updated, and vice versa. |
| | See :class:`tkinter.StringVar`. |
+-----------------+--------------------------------------------------------+
| values | Specifies the list of values to display in the |
| | drop-down listbox. |
+-----------------+--------------------------------------------------------+
| width | Specifies an integer value indicating the desired width|
| | of the entry window, in average-size characters of the |
| | widget's font. |
+-----------------+--------------------------------------------------------+
Virtual events
@ -397,7 +397,7 @@ Options
This widget accepts the following specific options:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+----------------------+------------------------------------------------------+
| Option | Description |
@ -473,25 +473,25 @@ Options
This widget accepts the following specific options:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+---------+----------------------------------------------------------------+
| Option | Description |
+=========+================================================================+
| height | If present and greater than zero, specifies the desired height |
| | of the pane area (not including internal padding or tabs). |
| | Otherwise, the maximum height of all panes is used. |
+---------+----------------------------------------------------------------+
| padding | Specifies the amount of extra space to add around the outside |
| | of the notebook. The padding is a list up to four length |
| | specifications left top right bottom. If fewer than four |
| | elements are specified, bottom defaults to top, right defaults |
| | to left, and top defaults to left. |
+---------+----------------------------------------------------------------+
| width | If present and greater than zero, specified the desired width |
| | of the pane area (not including internal padding). Otherwise, |
| | the maximum width of all panes is used. |
+---------+----------------------------------------------------------------+
+---------+----------------------------------------------------------------+
| Option | Description |
+=========+================================================================+
| height | If present and greater than zero, specifies the desired height |
| | of the pane area (not including internal padding or tabs). |
| | Otherwise, the maximum height of all panes is used. |
+---------+----------------------------------------------------------------+
| padding | Specifies the amount of extra space to add around the outside |
| | of the notebook. The padding is a list up to four length |
| | specifications left top right bottom. If fewer than four |
| | elements are specified, bottom defaults to top, right defaults |
| | to left, and top defaults to left. |
+---------+----------------------------------------------------------------+
| width | If present and greater than zero, specified the desired width |
| | of the pane area (not including internal padding). Otherwise, |
| | the maximum width of all panes is used. |
+---------+----------------------------------------------------------------+
Tab Options
@ -499,39 +499,39 @@ Tab Options
There are also specific options for tabs:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+-----------+--------------------------------------------------------------+
| Option | Description |
+===========+==============================================================+
| state | Either "normal", "disabled" or "hidden". If "disabled", then |
| | the tab is not selectable. If "hidden", then the tab is not |
| | shown. |
+-----------+--------------------------------------------------------------+
| sticky | Specifies how the child window is positioned within the pane |
| | area. Value is a string containing zero or more of the |
| | characters "n", "s", "e" or "w". Each letter refers to a |
| | side (north, south, east or west) that the child window will |
| | stick to, as per the :meth:`grid` geometry manager. |
+-----------+--------------------------------------------------------------+
| padding | Specifies the amount of extra space to add between the |
| | notebook and this pane. Syntax is the same as for the option |
| | padding used by this widget. |
+-----------+--------------------------------------------------------------+
| text | Specifies a text to be displayed in the tab. |
+-----------+--------------------------------------------------------------+
| image | Specifies an image to display in the tab. See the option |
| | image described in :class:`Widget`. |
+-----------+--------------------------------------------------------------+
| compound | Specifies how to display the image relative to the text, in |
| | the case both options text and image are present. See |
| | `Label Options`_ for legal values. |
+-----------+--------------------------------------------------------------+
| underline | Specifies the index (0-based) of a character to underline in |
| | the text string. The underlined character is used for |
| | mnemonic activation if :meth:`Notebook.enable_traversal` is |
| | called. |
+-----------+--------------------------------------------------------------+
+-----------+--------------------------------------------------------------+
| Option | Description |
+===========+==============================================================+
| state | Either "normal", "disabled" or "hidden". If "disabled", then |
| | the tab is not selectable. If "hidden", then the tab is not |
| | shown. |
+-----------+--------------------------------------------------------------+
| sticky | Specifies how the child window is positioned within the pane |
| | area. Value is a string containing zero or more of the |
| | characters "n", "s", "e" or "w". Each letter refers to a |
| | side (north, south, east or west) that the child window will |
| | stick to, as per the :meth:`grid` geometry manager. |
+-----------+--------------------------------------------------------------+
| padding | Specifies the amount of extra space to add between the |
| | notebook and this pane. Syntax is the same as for the option |
| | padding used by this widget. |
+-----------+--------------------------------------------------------------+
| text | Specifies a text to be displayed in the tab. |
+-----------+--------------------------------------------------------------+
| image | Specifies an image to display in the tab. See the option |
| | image described in :class:`Widget`. |
+-----------+--------------------------------------------------------------+
| compound | Specifies how to display the image relative to the text, in |
| | the case both options text and image are present. See |
| | `Label Options`_ for legal values. |
+-----------+--------------------------------------------------------------+
| underline | Specifies the index (0-based) of a character to underline in |
| | the text string. The underlined character is used for |
| | mnemonic activation if :meth:`Notebook.enable_traversal` is |
| | called. |
+-----------+--------------------------------------------------------------+
Tab Identifiers
@ -663,36 +663,36 @@ Options
This widget accepts the following specific options:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+----------+---------------------------------------------------------------+
| Option | Description |
+==========+===============================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation |
| | of the progress bar. |
+----------+---------------------------------------------------------------+
| length | Specifies the length of the long axis of the progress bar |
| | (width if horizontal, height if vertical). |
+----------+---------------------------------------------------------------+
| mode | One of "determinate" or "indeterminate". |
+----------+---------------------------------------------------------------+
| maximum | A number specifying the maximum value. Defaults to 100. |
+----------+---------------------------------------------------------------+
| value | The current value of the progress bar. In "determinate" mode, |
| | this represents the amount of work completed. In |
| | "indeterminate" mode, it is interpreted as modulo *maximum*; |
| | that is, the progress bar completes one "cycle" when its value|
| | increases by *maximum*. |
+----------+---------------------------------------------------------------+
| variable | A name which is linked to the option value. If specified, the |
| | value of the progress bar is automatically set to the value of|
| | this name whenever the latter is modified. |
+----------+---------------------------------------------------------------+
| phase | Read-only option. The widget periodically increments the value|
| | of this option whenever its value is greater than 0 and, in |
| | determinate mode, less than maximum. This option may be used |
| | by the current theme to provide additional animation effects. |
+----------+---------------------------------------------------------------+
+----------+---------------------------------------------------------------+
| Option | Description |
+==========+===============================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation |
| | of the progress bar. |
+----------+---------------------------------------------------------------+
| length | Specifies the length of the long axis of the progress bar |
| | (width if horizontal, height if vertical). |
+----------+---------------------------------------------------------------+
| mode | One of "determinate" or "indeterminate". |
+----------+---------------------------------------------------------------+
| maximum | A number specifying the maximum value. Defaults to 100. |
+----------+---------------------------------------------------------------+
| value | The current value of the progress bar. In "determinate" mode, |
| | this represents the amount of work completed. In |
| | "indeterminate" mode, it is interpreted as modulo *maximum*; |
| | that is, the progress bar completes one "cycle" when its value|
| | increases by *maximum*. |
+----------+---------------------------------------------------------------+
| variable | A name which is linked to the option value. If specified, the |
| | value of the progress bar is automatically set to the value of|
| | this name whenever the latter is modified. |
+----------+---------------------------------------------------------------+
| phase | Read-only option. The widget periodically increments the value|
| | of this option whenever its value is greater than 0 and, in |
| | determinate mode, less than maximum. This option may be used |
| | by the current theme to provide additional animation effects. |
+----------+---------------------------------------------------------------+
ttk.Progressbar
@ -734,14 +734,14 @@ Options
This widget accepts the following specific option:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+--------+----------------------------------------------------------------+
| Option | Description |
+========+================================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation of|
| | the separator. |
+--------+----------------------------------------------------------------+
+--------+----------------------------------------------------------------+
| Option | Description |
+========+================================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation of|
| | the separator. |
+--------+----------------------------------------------------------------+
Sizegrip
@ -802,49 +802,49 @@ Options
This widget accepts the following specific options:
.. tabularcolumns:: |l|p{0.7\linewidth}|
.. tabularcolumns:: |l|p{0.7\linewidth}|
+----------------+--------------------------------------------------------+
| Option | Description |
+================+========================================================+
| columns | A list of column identifiers, specifying the number of |
| | columns and their names. |
+----------------+--------------------------------------------------------+
| displaycolumns | A list of column identifiers (either symbolic or |
| | integer indices) specifying which data columns are |
| | displayed and the order in which they appear, or the |
| | string "#all". |
+----------------+--------------------------------------------------------+
| height | Specifies the number of rows which should be visible. |
| | Note: the requested width is determined from the sum |
| | of the column widths. |
+----------------+--------------------------------------------------------+
| padding | Specifies the internal padding for the widget. The |
| | padding is a list of up to four length specifications. |
+----------------+--------------------------------------------------------+
| selectmode | Controls how the built-in class bindings manage the |
| | selection. One of "extended", "browse" or "none". |
| | If set to "extended" (the default), multiple items may |
| | be selected. If "browse", only a single item will be |
| | selected at a time. If "none", the selection will not |
| | be changed. |
| | |
| | Note that the application code and tag bindings can set|
| | the selection however they wish, regardless of the |
| | value of this option. |
+----------------+--------------------------------------------------------+
| show | A list containing zero or more of the following values,|
| | specifying which elements of the tree to display. |
| | |
| | * tree: display tree labels in column #0. |
| | * headings: display the heading row. |
| | |
| | The default is "tree headings", i.e., show all |
| | elements. |
| | |
| | **Note**: Column #0 always refers to the tree column, |
| | even if show="tree" is not specified. |
+----------------+--------------------------------------------------------+
+----------------+--------------------------------------------------------+
| Option | Description |
+================+========================================================+
| columns | A list of column identifiers, specifying the number of |
| | columns and their names. |
+----------------+--------------------------------------------------------+
| displaycolumns | A list of column identifiers (either symbolic or |
| | integer indices) specifying which data columns are |
| | displayed and the order in which they appear, or the |
| | string "#all". |
+----------------+--------------------------------------------------------+
| height | Specifies the number of rows which should be visible. |
| | Note: the requested width is determined from the sum |
| | of the column widths. |
+----------------+--------------------------------------------------------+
| padding | Specifies the internal padding for the widget. The |
| | padding is a list of up to four length specifications. |
+----------------+--------------------------------------------------------+
| selectmode | Controls how the built-in class bindings manage the |
| | selection. One of "extended", "browse" or "none". |
| | If set to "extended" (the default), multiple items may |
| | be selected. If "browse", only a single item will be |
| | selected at a time. If "none", the selection will not |
| | be changed. |
| | |
| | Note that the application code and tag bindings can set|
| | the selection however they wish, regardless of the |
| | value of this option. |
+----------------+--------------------------------------------------------+
| show | A list containing zero or more of the following values,|
| | specifying which elements of the tree to display. |
| | |
| | * tree: display tree labels in column #0. |
| | * headings: display the heading row. |
| | |
| | The default is "tree headings", i.e., show all |
| | elements. |
| | |
| | **Note**: Column #0 always refers to the tree column, |
| | even if show="tree" is not specified. |
+----------------+--------------------------------------------------------+
Item Options
@ -853,27 +853,27 @@ Item Options
The following item options may be specified for items in the insert and item
widget commands.
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+--------+---------------------------------------------------------------+
| Option | Description |
+========+===============================================================+
| text | The textual label to display for the item. |
+--------+---------------------------------------------------------------+
| image | A Tk Image, displayed to the left of the label. |
+--------+---------------------------------------------------------------+
| values | The list of values associated with the item. |
| | |
| | Each item should have the same number of values as the widget |
| | option columns. If there are fewer values than columns, the |
| | remaining values are assumed empty. If there are more values |
| | than columns, the extra values are ignored. |
+--------+---------------------------------------------------------------+
| open | ``True``/``False`` value indicating whether the item's |
| | children should be displayed or hidden. |
+--------+---------------------------------------------------------------+
| tags | A list of tags associated with this item. |
+--------+---------------------------------------------------------------+
+--------+---------------------------------------------------------------+
| Option | Description |
+========+===============================================================+
| text | The textual label to display for the item. |
+--------+---------------------------------------------------------------+
| image | A Tk Image, displayed to the left of the label. |
+--------+---------------------------------------------------------------+
| values | The list of values associated with the item. |
| | |
| | Each item should have the same number of values as the widget |
| | option columns. If there are fewer values than columns, the |
| | remaining values are assumed empty. If there are more values |
| | than columns, the extra values are ignored. |
+--------+---------------------------------------------------------------+
| open | ``True``/``False`` value indicating whether the item's |
| | children should be displayed or hidden. |
+--------+---------------------------------------------------------------+
| tags | A list of tags associated with this item. |
+--------+---------------------------------------------------------------+
Tag Options
@ -881,20 +881,20 @@ Tag Options
The following options may be specified on tags:
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+------------+-----------------------------------------------------------+
| Option | Description |
+============+===========================================================+
| foreground | Specifies the text foreground color. |
+------------+-----------------------------------------------------------+
| background | Specifies the cell or item background color. |
+------------+-----------------------------------------------------------+
| font | Specifies the font to use when drawing text. |
+------------+-----------------------------------------------------------+
| image | Specifies the item image, in case the item's image option |
| | is empty. |
+------------+-----------------------------------------------------------+
+------------+-----------------------------------------------------------+
| Option | Description |
+============+===========================================================+
| foreground | Specifies the text foreground color. |
+------------+-----------------------------------------------------------+
| background | Specifies the cell or item background color. |
+------------+-----------------------------------------------------------+
| font | Specifies the font to use when drawing text. |
+------------+-----------------------------------------------------------+
| image | Specifies the item image, in case the item's image option |
| | is empty. |
+------------+-----------------------------------------------------------+
Column Identifiers
@ -926,19 +926,19 @@ Virtual Events
The Treeview widget generates the following virtual events.
.. tabularcolumns:: |l|L|
.. tabularcolumns:: |l|L|
+--------------------+--------------------------------------------------+
| Event | Description |
+====================+==================================================+
| <<TreeviewSelect>> | Generated whenever the selection changes. |
+--------------------+--------------------------------------------------+
| <<TreeviewOpen>> | Generated just before settings the focus item to |
| | open=True. |
+--------------------+--------------------------------------------------+
| <<TreeviewClose>> | Generated just after setting the focus item to |
| | open=False. |
+--------------------+--------------------------------------------------+
+--------------------+--------------------------------------------------+
| Event | Description |
+====================+==================================================+
| <<TreeviewSelect>> | Generated whenever the selection changes. |
+--------------------+--------------------------------------------------+
| <<TreeviewOpen>> | Generated just before settings the focus item to |
| | open=True. |
+--------------------+--------------------------------------------------+
| <<TreeviewClose>> | Generated just after setting the focus item to |
| | open=False. |
+--------------------+--------------------------------------------------+
The :meth:`Treeview.focus` and :meth:`Treeview.selection` methods can be used
to determine the affected item or items.
@ -986,19 +986,19 @@ ttk.Treeview
The valid options/values are:
* id
id
Returns the column name. This is a read-only option.
* anchor: One of the standard Tk anchor values.
anchor: One of the standard Tk anchor values.
Specifies how the text in this column should be aligned with respect
to the cell.
* minwidth: width
minwidth: width
The minimum width of the column in pixels. The treeview widget will
not make the column any smaller than specified by this option when
the widget is resized or the user drags a column.
* stretch: ``True``/``False``
stretch: ``True``/``False``
Specifies whether the column's width should be adjusted when
the widget is resized.
* width: width
width: width
The width of the column in pixels.
To configure the tree column, call this with column = "#0"
@ -1041,14 +1041,14 @@ ttk.Treeview
The valid options/values are:
* text: text
text: text
The text to display in the column heading.
* image: imageName
image: imageName
Specifies an image to display to the right of the column heading.
* anchor: anchor
anchor: anchor
Specifies how the heading text should be aligned. One of the standard
Tk anchor values.
* command: callback
command: callback
A callback to be invoked when the heading label is pressed.
To configure the tree column heading, call this with column = "#0".
@ -1398,25 +1398,25 @@ option. If you don't know the class name of a widget, use the method
by statespec/value pairs (this is the imagespec), and *kw* may have the
following options:
* border=padding
padding is a list of up to four integers, specifying the left, top,
right, and bottom borders, respectively.
border=padding
padding is a list of up to four integers, specifying the left, top,
right, and bottom borders, respectively.
* height=height
Specifies a minimum height for the element. If less than zero, the
base image's height is used as a default.
height=height
Specifies a minimum height for the element. If less than zero, the
base image's height is used as a default.
* padding=padding
Specifies the element's interior padding. Defaults to border's value
if not specified.
padding=padding
Specifies the element's interior padding. Defaults to border's value
if not specified.
* sticky=spec
Specifies how the image is placed within the final parcel. spec
contains zero or more characters "n", "s", "w", or "e".
sticky=spec
Specifies how the image is placed within the final parcel. spec
contains zero or more characters "n", "s", "w", or "e".
* width=width
Specifies a minimum width for the element. If less than zero, the
base image's width is used as a default.
width=width
Specifies a minimum width for the element. If less than zero, the
base image's width is used as a default.
If "from" is used as the value of *etype*,
:meth:`element_create` will clone an existing
@ -1504,22 +1504,22 @@ uses a simplified version of the pack geometry manager: given an
initial cavity, each element is allocated a parcel. Valid
options/values are:
* side: whichside
Specifies which side of the cavity to place the element; one of
top, right, bottom or left. If omitted, the element occupies the
entire cavity.
side: whichside
Specifies which side of the cavity to place the element; one of
top, right, bottom or left. If omitted, the element occupies the
entire cavity.
* sticky: nswe
Specifies where the element is placed inside its allocated parcel.
sticky: nswe
Specifies where the element is placed inside its allocated parcel.
* unit: 0 or 1
If set to 1, causes the element and all of its descendants to be treated as
a single element for the purposes of :meth:`Widget.identify` et al. It's
used for things like scrollbar thumbs with grips.
unit: 0 or 1
If set to 1, causes the element and all of its descendants to be treated as
a single element for the purposes of :meth:`Widget.identify` et al. It's
used for things like scrollbar thumbs with grips.
* children: [sublayout... ]
Specifies a list of elements to place inside the element. Each
element is a tuple (or other sequence type) where the first item is
the layout name, and the other is a `Layout`_.
children: [sublayout... ]
Specifies a list of elements to place inside the element. Each
element is a tuple (or other sequence type) where the first item is
the layout name, and the other is a `Layout`_.
.. _Layout: `Layouts`_

10
Doc/library/unittest.mock.rst
View File

@ -818,8 +818,8 @@ This applies to :meth:`~Mock.assert_called_with`,
:meth:`~Mock.assert_any_call`. When :ref:`auto-speccing`, it will also
apply to method calls on the mock object.
.. versionchanged:: 3.4
Added signature introspection on specced and autospecced mock objects.
.. versionchanged:: 3.4
Added signature introspection on specced and autospecced mock objects.
.. class:: PropertyMock(*args, **kwargs)
@ -1437,9 +1437,9 @@ patch
.. note::
.. versionchanged:: 3.5
If you are patching builtins in a module then you don't
need to pass ``create=True``, it will be added by default.
.. versionchanged:: 3.5
If you are patching builtins in a module then you don't
need to pass ``create=True``, it will be added by default.
Patch can be used as a :class:`TestCase` class decorator. It works by
decorating each test method in the class. This reduces the boilerplate

12
Doc/library/urllib.request.rst
View File

@ -304,10 +304,10 @@ The following classes are provided:
list of hostname suffixes, optionally with ``:port`` appended, for example
``cern.ch,ncsa.uiuc.edu,some.host:8080``.
.. note::
.. note::
``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set;
see the documentation on :func:`~urllib.request.getproxies`.
``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set;
see the documentation on :func:`~urllib.request.getproxies`.
.. class:: HTTPPasswordMgr()
@ -1525,9 +1525,9 @@ some point in the future.
:mod:`urllib.request` Restrictions
----------------------------------
.. index::
pair: HTTP; protocol
pair: FTP; protocol
.. index::
pair: HTTP; protocol
pair: FTP; protocol
* Currently, only the following protocols are supported: HTTP (versions 0.9 and
1.0), FTP, local files, and data URLs.