traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'master' into gen-throw-bpo-39091

This commit is contained in:
Noah 2020-02-16 16:56:48 -06:00 committed by GitHub
parent 335a292930 c33bdbb20c
commit 95254b4a4b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
643 changed files with 16857 additions and 10681 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.azure-pipelines/windows-release/stage-publish-pythonorg.yml
View File

@ -39,11 +39,6 @@ jobs:
artifactName: embed
downloadPath: $(Build.BinariesDirectory)
- powershell: 'gci *embed-arm*.zip | %{ Write-Host "Not publishing: $($_.Name)"; gi $_ } | del'
displayName: 'Prevent publishing ARM/ARM64 packages'
workingDirectory: '$(Build.BinariesDirectory)\embed'
condition: and(succeeded(), not(variables['PublishArmPackages']))
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact from $(BuildToPublish): Doc'
condition: and(succeeded(), variables['BuildToPublish'])
@ -80,6 +75,11 @@ jobs:
buildVersionToDownload: specific
buildId: $(BuildToPublish)
- powershell: 'gci *embed-arm*.zip | %{ Write-Host "Not publishing: $($_.Name)"; gi $_ } | del'
displayName: 'Prevent publishing ARM/ARM64 packages'
workingDirectory: '$(Build.BinariesDirectory)\embed'
condition: and(succeeded(), not(variables['PublishArmPackages']))
- template: ./gpg-sign.yml
parameters:

2
.github/codecov.yml vendored
View File

@ -5,7 +5,7 @@ codecov:
comment: off
ignore:
- "Doc/**/*"
- "Misc/*"
- "Misc/**/*"
- "Mac/**/*"
- "PC/**/*"
- "PCbuild/**/*"

2
.github/workflows/coverage.yml vendored
View File

@ -64,7 +64,7 @@ jobs:
|| true
- name: 'Publish code coverage results'
run: |
./.venv/bin/python -m coverage xml
source ./.venv/bin/activate
bash <(curl -s https://codecov.io/bash)
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

18
.github/workflows/doc.yml vendored
View File

@ -23,17 +23,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: actions/setup-python@v1
with:
python-version: '3.7'
architecture: 'x64'
- name: 'Install Dependencies'
run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
- name: 'Configure CPython'
run: ./configure --with-pydebug
- name: 'Build CPython'
run: make -s -j4
- name: 'Install build dependencies'
run: python -m pip install sphinx==2.2.0 blurb python-docs-theme
run: make -C Doc/ PYTHON=../python venv
- name: 'Build documentation'
run: |
cd Doc
make check suspicious html PYTHON=python
- name: Upload
run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W -j4" doctest suspicious html
- name: 'Upload'
uses: actions/upload-artifact@v1
with:
name: doc-html

89
Doc/c-api/call.rst
View File

@ -35,17 +35,11 @@ To call an object, use :c:func:`PyObject_Call` or other
The Vectorcall Protocol
-----------------------
.. versionadded:: 3.8
.. versionadded:: 3.9
The vectorcall protocol was introduced in :pep:`590` as an additional protocol
for making calls more efficient.
.. warning::
The vectorcall API is provisional and expected to become public in
Python 3.9, with a different names and, possibly, changed semantics.
If you use the it, plan for updating your code for Python 3.9.
As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use *tp_call* directly
@ -69,7 +63,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.
Classes can implement the vectorcall protocol by enabling the
:const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
object structure where a *vectorcallfunc* appears.
This is a pointer to a function with the following signature:
@ -97,7 +91,7 @@ This is a pointer to a function with the following signature:
argument 1 (not 0) in the allocated vector.
The callee must restore the value of ``args[-1]`` before returning.
For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
``args[0]`` may be changed.
Whenever they can do so cheaply (without additional allocation), callers
@ -107,7 +101,20 @@ This is a pointer to a function with the following signature:
To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
function as with any other callable.
:c:func:`_PyObject_Vectorcall` will usually be most efficient.
:c:func:`PyObject_Vectorcall` will usually be most efficient.
.. note::
In CPython 3.8, the vectorcall API and related functions were available
provisionally under names with a leading underscore:
``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
``_PyObject_CallMethodOneArg``.
Additionally, ``PyObject_VectorcallDict`` was available as
``_PyObject_FastCallDict``.
The old names are still defined as aliases of the new, non-underscored names.
Recursion Control
@ -137,9 +144,11 @@ Vectorcall Support API
However, the function ``PyVectorcall_NARGS`` should be used to allow
for future extensions.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.8
.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op)
.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)
If *op* does not support the vectorcall protocol (either because the type
does not or because the specific instance does not), return *NULL*.
@ -147,7 +156,9 @@ Vectorcall Support API
This function never raises an exception.
This is mostly useful to check whether or not *op* supports vectorcall,
which can be done by checking ``_PyVectorcall_Function(op) != NULL``.
which can be done by checking ``PyVectorcall_Function(op) != NULL``.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.8
@ -158,9 +169,11 @@ Vectorcall Support API
This is a specialized function, intended to be put in the
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
and it does not fall back to ``tp_call``.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.8
@ -185,7 +198,7 @@ please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
| :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- |
+------------------------------------------+------------------+--------------------+---------------+
@ -197,15 +210,15 @@ please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallMethodNoArgs` | obj + name | --- | --- |
| :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
| :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
| :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_FastCallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
| :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
| :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
@ -235,7 +248,7 @@ please see individual documentation for details.
.. versionadded:: 3.9
.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)
Call a callable Python object *callable* with exactly 1 positional argument
*arg* and no keyword arguments.
@ -243,6 +256,8 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.9
@ -320,7 +335,7 @@ please see individual documentation for details.
*NULL* on failure.
.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
Call a method of the Python object *obj* without arguments,
where the name of the method is given as a Python string object in *name*.
@ -328,10 +343,12 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.9
.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
Call a method of the Python object *obj* with a single positional argument
*arg*, where the name of the method is given as a Python string object in
@ -340,10 +357,12 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.9
.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a callable Python object *callable*.
The arguments are the same as for :c:type:`vectorcallfunc`.
@ -353,15 +372,11 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
.. note::
This function is not part of the `limited API <stable>`_.
This function is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use the function, plan for updating your code for Python 3.9.
.. versionadded:: 3.9
.. versionadded:: 3.8
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
but with keyword arguments passed as a dictionary *kwdict*.
@ -373,15 +388,11 @@ please see individual documentation for details.
already has a dictionary ready to use for the keyword arguments,
but not a tuple for the positional arguments.
.. note::
This function is not part of the `limited API <stable>`_.
This function is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use the function, plan for updating your code for Python 3.9.
.. versionadded:: 3.9
.. versionadded:: 3.8
.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a method using the vectorcall calling convention. The name of the method
is given as a Python string *name*. The object whose method is called is
@ -390,7 +401,7 @@ please see individual documentation for details.
*nargsf* is the number of positional arguments including *args[0]*,
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
temporarily be changed. Keyword arguments can be passed just like in
:c:func:`_PyObject_Vectorcall`.
:c:func:`PyObject_Vectorcall`.
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
this will call the unbound method object with the full
@ -399,6 +410,8 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the `limited API <stable>`_.
.. versionadded:: 3.9

2
Doc/c-api/code.rst
View File

@ -42,7 +42,7 @@ bound into a function.
.. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positonal-only arguments.
Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positional-only arguments.
.. versionadded:: 3.8

9
Doc/c-api/dict.rst
View File

@ -62,19 +62,20 @@ Dictionary Objects
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
Insert *val* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
``0`` on success or ``-1`` on failure. This function *does not* steal a
reference to *val*.
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyUnicode_FromString()
Insert *value* into the dictionary *p* using *key* as a key. *key* should
Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char\*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
failure. This function *does not* steal a reference to *val*.
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)

3
Doc/c-api/exceptions.rst
View File

@ -983,9 +983,6 @@ Notes:
This is a base class for other standard exceptions.
(2)
This is the same as :exc:`weakref.ReferenceError`.
(3)
Only defined on Windows; protect code that uses this by testing that the
preprocessor macro ``MS_WINDOWS`` is defined.

60
Doc/c-api/init.rst
View File

@ -1048,6 +1048,10 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
Reset all information in a thread state object. The global interpreter lock
must be held.
.. versionchanged:: 3.9
This function now calls the :c:member:`PyThreadState.on_delete` callback.
Previously, that happened in :c:func:`PyThreadState_Delete`.
.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
@ -1110,7 +1114,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
Acquire the global interpreter lock and set the current thread state to
*tstate*, which should not be ``NULL``. The lock must have been created earlier.
*tstate*, which must not be ``NULL``. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.
.. note::
@ -1189,7 +1193,7 @@ It is usually the only Python interpreter in a process. Unlike sub-interpreters
the main interpreter has unique process-global responsibilities like signal
handling. It is also responsible for execution during runtime initialization and
is usually the active interpreter during runtime finalization. The
:c:func:`PyInterpreterState_Main` funtion returns a pointer to its state.
:c:func:`PyInterpreterState_Main` function returns a pointer to its state.
You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
function. You can create and destroy them using the following functions:
@ -1230,15 +1234,31 @@ function. You can create and destroy them using the following functions:
single: Py_FinalizeEx()
single: Py_Initialize()
Extension modules are shared between (sub-)interpreters as follows: the first
time a particular extension is imported, it is initialized normally, and a
(shallow) copy of its module's dictionary is squirreled away. When the same
extension is imported by another (sub-)interpreter, a new module is initialized
and filled with the contents of this copy; the extension's ``init`` function is
not called. Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by calling
:c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that case, the extension's
``initmodule`` function *is* called again.
Extension modules are shared between (sub-)interpreters as follows:
* For modules using multi-phase initialization,
e.g. :c:func:`PyModule_FromDefAndSpec`, a separate module object is
created and initialized for each interpreter.
Only C-level static and global variables are shared between these
module objects.
* For modules using single-phase initialization,
e.g. :c:func:`PyModule_Create`, the first time a particular extension
is imported, it is initialized normally, and a (shallow) copy of its
module's dictionary is squirreled away.
When the same extension is imported by another (sub-)interpreter, a new
module is initialized and filled with the contents of this copy; the
extension's ``init`` function is not called.
Objects in the module's dictionary thus end up shared across
(sub-)interpreters, which might cause unwanted behavior (see
`Bugs and caveats`_ below).
Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by
calling :c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that
case, the extension's ``initmodule`` function *is* called again.
As with multi-phase initialization, this means that only C-level static
and global variables are shared between these modules.
.. index:: single: close() (in module os)
@ -1264,14 +1284,16 @@ process, the insulation between them isn't perfect --- for example, using
low-level file operations like :func:`os.close` they can
(accidentally or maliciously) affect each other's open files. Because of the
way extensions are shared between (sub-)interpreters, some extensions may not
work properly; this is especially likely when the extension makes use of
(static) global variables, or when the extension manipulates its module's
dictionary after its initialization. It is possible to insert objects created
in one sub-interpreter into a namespace of another sub-interpreter; this should
be done with great care to avoid sharing user-defined functions, methods,
instances or classes between sub-interpreters, since import operations executed
by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
modules.
work properly; this is especially likely when using single-phase initialization
or (static) global variables.
It is possible to insert objects created in one sub-interpreter into
a namespace of another (sub-)interpreter; this should be avoided if possible.
Special care should be taken to avoid sharing user-defined functions,
methods, instances or classes between sub-interpreters, since import
operations executed by such objects may affect the wrong (sub-)interpreter's
dictionary of loaded modules. It is equally important to avoid sharing
objects from which the above are reachable.
Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
is delicate, because these APIs assume a bijection between Python thread states

16
Doc/c-api/init_config.rst
View File

@ -466,7 +466,7 @@ PyConfig
.. c:member:: int dev_mode
Development mode: see :option:`-X dev <-X>`.
If non-zero, enable the :ref:`Python Development Mode <devmode>`.
.. c:member:: int dump_refs
@ -627,14 +627,6 @@ PyConfig
``python3 -m MODULE`` argument. Used by :c:func:`Py_RunMain`.
.. c:member:: int show_alloc_count
Show allocation counts at exit?
Set to 1 by :option:`-X showalloccount <-X>` command line option.
Need a special Python build with ``COUNT_ALLOCS`` macro defined.
.. c:member:: int show_ref_count
Show total reference count at exit?
@ -702,6 +694,10 @@ arguments are stripped from ``argv``: see :ref:`Command Line Arguments
The ``xoptions`` options are parsed to set other options: see :option:`-X`
option.
.. versionchanged:: 3.9
The ``show_alloc_count`` field has been removed.
Initialization with PyConfig
----------------------------
@ -757,7 +753,7 @@ configuration, and then override some parameters::
PyConfig config;
PyConfig_InitPythonConfig(&config);
/* Set the program name before reading the configuraton
/* Set the program name before reading the configuration
(decode byte string from the locale encoding).
Implicitly preinitialize Python. */

2
Doc/c-api/iter.rst
View File

@ -29,7 +29,7 @@ something like this::
/* propagate error */
}
while (item = PyIter_Next(iterator)) {
while ((item = PyIter_Next(iterator))) {
/* do something with item */
...
/* release reference when done */

2
Doc/c-api/long.rst
View File

@ -177,7 +177,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
:c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`.
:c:type:`long long`.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.

3
Doc/c-api/mapping.rst
View File

@ -37,7 +37,8 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``o[key] = v``.
See also :c:func:`PyObject_SetItem`.
See also :c:func:`PyObject_SetItem`. This function *does not* steal a
reference to *v*.
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)

3
Doc/c-api/object.rst
View File

@ -331,7 +331,8 @@ Object Protocol
Map the object *key* to the value *v*. Raise an exception and
return ``-1`` on failure; return ``0`` on success. This is the
equivalent of the Python statement ``o[key] = v``.
equivalent of the Python statement ``o[key] = v``. This function *does
not* steal a reference to *v*.
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)

31
Doc/c-api/structures.rst
View File

@ -70,6 +70,21 @@ the definition of all other Python objects.
(((PyObject*)(o))->ob_type)
.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
Return non-zero if the object *o* type is *type*. Return zero otherwise.
Equivalent to: ``Py_TYPE(o) == type``.
.. versionadded:: 3.9
.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
Set the object *o* type to *type*.
.. versionadded:: 3.9
.. c:macro:: Py_REFCNT(o)
This macro is used to access the :attr:`ob_refcnt` member of a Python
@ -79,6 +94,13 @@ the definition of all other Python objects.
(((PyObject*)(o))->ob_refcnt)
.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)
Set the object *o* reference counter to *refcnt*.
.. versionadded:: 3.9
.. c:macro:: Py_SIZE(o)
This macro is used to access the :attr:`ob_size` member of a Python object.
@ -87,6 +109,13 @@ the definition of all other Python objects.
(((PyVarObject*)(o))->ob_size)
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
Set the object *o* size to *size*.
.. versionadded:: 3.9
.. c:macro:: PyObject_HEAD_INIT(type)
This is a macro which expands to initialization values for a new
@ -350,7 +379,7 @@ Accessing attributes of extension types
.. _pymemberdef-offsets:
Heap allocated types (created using :c:func:`PyType_FromSpec` or similar),
``PyMemberDef`` may contain defintitions for the special members
``PyMemberDef`` may contain definitions for the special members
``__dictoffset__`` and ``__weaklistoffset__``, corresponding to
:c:member:`~PyTypeObject.tp_dictoffset` and
:c:member:`~PyTypeObject.tp_weaklistoffset` in type objects.

12
Doc/c-api/type.rst
View File

@ -21,14 +21,14 @@ Type Objects
.. c:function:: int PyType_Check(PyObject *o)
Return true if the object *o* is a type object, including instances of types
derived from the standard type object. Return false in all other cases.
Return non-zero if the object *o* is a type object, including instances of
types derived from the standard type object. Return 0 in all other cases.
.. c:function:: int PyType_CheckExact(PyObject *o)
Return true if the object *o* is a type object, but not a subtype of the
standard type object. Return false in all other cases.
Return non-zero if the object *o* is a type object, but not a subtype of the
standard type object. Return 0 in all other cases.
.. c:function:: unsigned int PyType_ClearCache()
@ -57,8 +57,8 @@ Type Objects
.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
Return true if the type object *o* sets the feature *feature*. Type features
are denoted by single bit flags.
Return non-zero if the type object *o* sets the feature *feature*.
Type features are denoted by single bit flags.
.. c:function:: int PyType_IS_GC(PyTypeObject *o)

54
Doc/c-api/typeobj.rst
View File

@ -148,15 +148,6 @@ Quick Reference
| :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
If :const:`COUNT_ALLOCS` is defined then the following (internal-only)
fields exist as well:
* :c:member:`~PyTypeObject.tp_allocs`
* :c:member:`~PyTypeObject.tp_frees`
* :c:member:`~PyTypeObject.tp_maxalloc`
* :c:member:`~PyTypeObject.tp_prev`
* :c:member:`~PyTypeObject.tp_next`
.. [#slots]
A slot name in parentheses indicates it is (effectively) deprecated.
Names in angle brackets should be treated as read-only.
@ -693,15 +684,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
a more efficient alternative
of the simpler :c:member:`~PyTypeObject.tp_call`.
This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
is set. If so, this must be a positive integer containing the offset in the
instance of a :c:type:`vectorcallfunc` pointer.
The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves
as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
as if :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
falls back to :c:member:`~PyTypeObject.tp_call`.
Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set
Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set
:c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent
with the *vectorcallfunc* function.
This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`.
@ -728,7 +719,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
This field is always inherited.
However, the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag is not
However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
@ -1162,7 +1153,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
type structure.
.. data:: _Py_TPFLAGS_HAVE_VECTORCALL
.. data:: Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements
the :ref:`vectorcall protocol <vectorcall>`.
@ -1172,15 +1163,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This bit is inherited for *static* subtypes if
:c:member:`~PyTypeObject.tp_call` is also inherited.
`Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``.
`Heap types`_ do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.
.. note::
This flag is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use vectorcall, plan for updating your code for Python 3.9.
.. versionadded:: 3.8
.. versionadded:: 3.9
.. c:member:: const char* PyTypeObject.tp_doc
@ -1904,31 +1889,6 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9)
The remaining fields are only defined if the feature test macro
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
documented here for completeness. None of these fields are inherited by
subtypes.
.. c:member:: Py_ssize_t PyTypeObject.tp_allocs
Number of allocations.
.. c:member:: Py_ssize_t PyTypeObject.tp_frees
Number of frees.
.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc
Maximum simultaneously allocated objects.
.. c:member:: PyTypeObject* PyTypeObject.tp_prev
Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
.. c:member:: PyTypeObject* PyTypeObject.tp_next
Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from
any Python thread, not just the thread which created the object (if the object
becomes part of a refcount cycle, that cycle might be collected by a garbage

12
Doc/c-api/unicode.rst
View File

@ -240,6 +240,16 @@ access internal read-only data of Unicode objects:
:c:func:`PyUnicode_nBYTE_DATA` family of macros.
.. c:function:: int PyUnicode_IsIdentifier(PyObject *o)
Return ``1`` if the string is a valid identifier according to the language
definition, section :ref:`identifiers`. Return ``0`` otherwise.
.. versionchanged:: 3.9
The function does not call :c:func:`Py_FatalError` anymore if the string
is not ready.
Unicode Character Properties
""""""""""""""""""""""""""""
@ -978,7 +988,7 @@ have the same semantics as the ones of the built-in :func:`str` string object
constructor.
Setting encoding to ``NULL`` causes the default encoding to be used
which is ASCII. The file system calls should use
which is UTF-8. The file system calls should use
:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
variable should be treated as read-only: on some systems, it will be a

2
Doc/copyright.rst
View File

@ -4,7 +4,7 @@ Copyright
Python and this documentation is:
Copyright © 2001-2019 Python Software Foundation. All rights reserved.
Copyright © 2001-2020 Python Software Foundation. All rights reserved.
Copyright © 2000 BeOpen.com. All rights reserved.

3
Doc/distutils/apiref.rst
View File

@ -1855,6 +1855,9 @@ Subclasses of :class:`Command` must define the following methods.
.. class:: bdist_msi
.. deprecated:: 3.9
Use bdist_wheel (wheel packages) instead.
Builds a `Windows Installer`_ (.msi) binary package.
.. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx

9
Doc/distutils/builtdist.rst
View File

@ -149,6 +149,9 @@ generated by each, are:
.. note::
bdist_wininst is deprecated since Python 3.8.
.. note::
bdist_msi is deprecated since Python 3.9.
The following sections give details on the individual :command:`bdist_\*`
commands.
@ -304,6 +307,9 @@ Creating Windows Installers
.. warning::
bdist_wininst is deprecated since Python 3.8.
.. warning::
bdist_msi is deprecated since Python 3.9.
Executable installers are the natural format for binary distributions on
Windows. They display a nice graphical user interface, display some information
about the module distribution to be installed taken from the metadata in the
@ -468,3 +474,6 @@ installed for all users) and 'force' (meaning always prompt for elevation).
.. note::
bdist_wininst is deprecated since Python 3.8.
.. note::
bdist_msi is deprecated since Python 3.9.

2
Doc/distutils/examples.rst
View File

@ -255,7 +255,7 @@ Running the ``check`` command will display some warnings:
running check
warning: check: missing required meta-data: version, url
warning: check: missing meta-data: either (author and author_email) or
(maintainer and maintainer_email) must be supplied
(maintainer and maintainer_email) should be supplied
If you use the reStructuredText syntax in the ``long_description`` field and

2
Doc/faq/design.rst
View File

@ -148,6 +148,8 @@ variables and instance variables live in two different namespaces, and you need
to tell Python which namespace to use.
.. _why-can-t-i-use-an-assignment-in-an-expression:
Why can't I use an assignment in an expression?
-----------------------------------------------

2
Doc/faq/programming.rst
View File

@ -1019,7 +1019,7 @@ That's a tough one, in general. First, here are a list of things to
remember before diving further:
* Performance characteristics vary across Python implementations. This FAQ
focusses on :term:`CPython`.
focuses on :term:`CPython`.
* Behaviour can vary across operating systems, especially when talking about
I/O or multi-threading.
* You should always find the hot spots in your program *before* attempting to

8
Doc/glossary.rst
View File

@ -824,9 +824,11 @@ Glossary
.. _positional-only_parameter:
* :dfn:`positional-only`: specifies an argument that can be supplied only
by position. Python has no syntax for defining positional-only
parameters. However, some built-in functions have positional-only
parameters (e.g. :func:`abs`).
by position. Positional-only parameters can be defined by including a
``/`` character in the parameter list of the function definition after
them, for example *posonly1* and *posonly2* in the following::
def func(posonly1, posonly2, /, positional_or_keyword): ...
.. _keyword-only_parameter:

6
Doc/howto/functional.rst
View File

@ -1229,9 +1229,9 @@ Text Processing".
Mertz also wrote a 3-part series of articles on functional programming
for IBM's DeveloperWorks site; see
`part 1 <https://www.ibm.com/developerworks/linux/library/l-prog/index.html>`__,
`part 2 <https://www.ibm.com/developerworks/linux/library/l-prog2/index.html>`__, and
`part 3 <https://www.ibm.com/developerworks/linux/library/l-prog3/index.html>`__,
`part 1 <https://developer.ibm.com/articles/l-prog/>`__,
`part 2 <https://developer.ibm.com/tutorials/l-prog2/>`__, and
`part 3 <https://developer.ibm.com/tutorials/l-prog3/>`__,
Python documentation

10
Doc/howto/pyporting.rst
View File

@ -125,7 +125,7 @@ Once you have your code well-tested you are ready to begin porting your code to
Python 3! But to fully understand how your code is going to change and what
you want to look out for while you code, you will want to learn what changes
Python 3 makes in terms of Python 2. Typically the two best ways of doing that
is reading the `"What's New"`_ doc for each release of Python 3 and the
is reading the :ref:`"What's New" <whatsnew-index>` doc for each release of Python 3 and the
`Porting to Python 3`_ book (which is free online). There is also a handy
`cheat sheet`_ from the Python-Future project.
@ -308,10 +308,10 @@ If for some reason that doesn't work then you should make the version check be
against Python 2 and not Python 3. To help explain this, let's look at an
example.
Let's pretend that you need access to a feature of importlib_ that
Let's pretend that you need access to a feature of :mod:`importlib` that
is available in Python's standard library since Python 3.3 and available for
Python 2 through importlib2_ on PyPI. You might be tempted to write code to
access e.g. the ``importlib.abc`` module by doing the following::
access e.g. the :mod:`importlib.abc` module by doing the following::
import sys
@ -432,12 +432,10 @@ can also explicitly state whether your APIs use textual or binary data, helping
to make sure everything functions as expected in both versions of Python.
.. _2to3: https://docs.python.org/3/library/2to3.html
.. _caniusepython3: https://pypi.org/project/caniusepython3
.. _cheat sheet: http://python-future.org/compatible_idioms.html
.. _coverage.py: https://pypi.org/project/coverage
.. _Futurize: http://python-future.org/automatic_conversion.html
.. _importlib: https://docs.python.org/3/library/importlib.html#module-importlib
.. _importlib2: https://pypi.org/project/importlib2
.. _Modernize: https://python-modernize.readthedocs.io/
.. _mypy: http://mypy-lang.org/
@ -453,6 +451,4 @@ to make sure everything functions as expected in both versions of Python.
.. _tox: https://pypi.org/project/tox
.. _trove classifier: https://pypi.org/classifiers
.. _"What's New": https://docs.python.org/3/whatsnew/index.html
.. _Why Python 3 exists: https://snarky.ca/why-python-3-exists

10
Doc/howto/sorting.rst
View File

@ -43,16 +43,18 @@ Key Functions
=============
Both :meth:`list.sort` and :func:`sorted` have a *key* parameter to specify a
function to be called on each list element prior to making comparisons.
function (or other callable) to be called on each list element prior to making
comparisons.
For example, here's a case-insensitive string comparison:
>>> sorted("This is a test string from Andrew".split(), key=str.lower)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']
The value of the *key* parameter should be a function that takes a single argument
and returns a key to use for sorting purposes. This technique is fast because
the key function is called exactly once for each input record.
The value of the *key* parameter should be a function (or other callable) that
takes a single argument and returns a key to use for sorting purposes. This
technique is fast because the key function is called exactly once for each
input record.
A common pattern is to sort complex objects using some of the object's indices
as keys. For example:

2
Doc/includes/custom.c
View File

@ -37,7 +37,7 @@ PyInit_custom(void)
Py_INCREF(&CustomType);
if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
Py_DECREF(&CustomType);
PY_DECREF(m);
Py_DECREF(m);
return NULL;
}

2
Doc/library/2to3.rst
View File

@ -102,7 +102,7 @@ presence of the ``from __future__ import print_function`` compiler directive, it
modifies its internal grammar to interpret :func:`print` as a function. This
change can also be enabled manually with the :option:`!-p` flag. Use
:option:`!-p` to run fixers on code that already has had its print statements
converted.
converted. Also :option:`!-e` can be used to make :func:`exec` a function.
The :option:`!-o` or :option:`!--output-dir` option allows specification of an
alternate directory for processed output files to be written to. The

15
Doc/library/ast.rst
View File

@ -168,7 +168,7 @@ and classes for traversing abstract syntax trees:
back with :func:`ast.parse`.
.. warning::
The produced code string will not necesarily be equal to the original
The produced code string will not necessarily be equal to the original
code that generated the :class:`ast.AST` object.
.. versionadded:: 3.9
@ -194,6 +194,9 @@ and classes for traversing abstract syntax trees:
.. versionchanged:: 3.2
Now allows bytes and set literals.
.. versionchanged:: 3.9
Now supports creating empty sets with ``'set()'``.
.. function:: get_docstring(node, clean=True)
@ -313,7 +316,7 @@ and classes for traversing abstract syntax trees:
class RewriteName(NodeTransformer):
def visit_Name(self, node):
return copy_location(Subscript(
return Subscript(
value=Name(id='data', ctx=Load()),
slice=Index(value=Constant(value=node.id)),
ctx=node.ctx
@ -327,6 +330,14 @@ and classes for traversing abstract syntax trees:
statement nodes), the visitor may also return a list of nodes rather than
just a single node.
If :class:`NodeTransformer` introduces new nodes (that weren't part of
original tree) without giving them location information (such as
:attr:`lineno`), :func:`fix_missing_locations` should be called with
the new sub-tree to recalculate the location information::
tree = ast.parse('foo', mode='eval')
new_tree = fix_missing_locations(RewriteName().visit(tree))
Usually you use the transformer like this::
node = YourTransformer().visit(node)

2
Doc/library/asyncio-dev.rst
View File

@ -25,7 +25,7 @@ There are several ways to enable asyncio debug mode:
* Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``.
* Using the :option:`-X` ``dev`` Python command line option.
* Using the :ref:`Python Development Mode <devmode>`.
* Passing ``debug=True`` to :func:`asyncio.run`.

13
Doc/library/asyncio-eventloop.rst
View File

@ -38,8 +38,10 @@ an event loop:
.. function:: get_event_loop()
Get the current event loop. If there is no current event loop set
in the current OS thread and :func:`set_event_loop` has not yet
Get the current event loop.
If there is no current event loop set in the current OS thread,
the OS thread is main, and :func:`set_event_loop` has not yet
been called, asyncio will create a new event loop and set it as the
current one.
@ -357,7 +359,8 @@ Opening network connections
host=None, port=None, \*, ssl=None, \
family=0, proto=0, flags=0, sock=None, \
local_addr=None, server_hostname=None, \
ssl_handshake_timeout=None)
ssl_handshake_timeout=None, \
happy_eyeballs_delay=None, interleave=None)
Open a streaming transport connection to a given
address specified by *host* and *port*.
@ -446,7 +449,7 @@ Opening network connections
.. versionadded:: 3.8
The *happy_eyeballs_delay* and *interleave* parameters.
Added the *happy_eyeballs_delay* and *interleave* parameters.
.. versionadded:: 3.7
@ -1198,7 +1201,7 @@ Enabling debug mode
.. versionchanged:: 3.7
The new ``-X dev`` command line option can now also be used
The new :ref:`Python Development Mode <devmode>` can now also be used
to enable the debug mode.
.. seealso::

4
Doc/library/asyncio-sync.rst
View File

@ -347,8 +347,8 @@ BoundedSemaphore
---------
.. deprecated:: 3.7
.. versionchanged:: 3.9
Acquiring a lock using ``await lock`` or ``yield from lock`` and/or
:keyword:`with` statement (``with await lock``, ``with (yield from
lock)``) is deprecated. Use ``async with lock`` instead.
lock)``) was removed. Use ``async with lock`` instead.

12
Doc/library/base64.rst
View File

@ -235,12 +235,6 @@ The legacy interface:
.. versionadded:: 3.1
.. function:: decodestring(s)
Deprecated alias of :func:`decodebytes`.
.. deprecated:: 3.1
.. function:: encode(input, output)
@ -261,12 +255,6 @@ The legacy interface:
.. versionadded:: 3.1
.. function:: encodestring(s)
Deprecated alias of :func:`encodebytes`.
.. deprecated:: 3.1
An example usage of the module:

8
Doc/library/binascii.rst
View File

@ -92,6 +92,8 @@ The :mod:`binascii` module defines the following functions:
The string should contain a complete number of binary bytes, or (in case of the
last portion of the binhex4 data) have the remaining bits zero.
.. deprecated:: 3.9
.. function:: rledecode_hqx(data)
@ -104,11 +106,15 @@ The :mod:`binascii` module defines the following functions:
.. versionchanged:: 3.2
Accept only bytestring or bytearray objects as input.
.. deprecated:: 3.9
.. function:: rlecode_hqx(data)
Perform binhex4 style RLE-compression on *data* and return the result.
.. deprecated:: 3.9
.. function:: b2a_hqx(data)
@ -116,6 +122,8 @@ The :mod:`binascii` module defines the following functions:
argument should already be RLE-coded, and have a length divisible by 3 (except
possibly the last fragment).
.. deprecated:: 3.9
.. function:: crc_hqx(data, value)

2
Doc/library/binhex.rst
View File

@ -6,6 +6,8 @@
**Source code:** :source:`Lib/binhex.py`
.. deprecated:: 3.9
--------------
This module encodes and decodes files in binhex4 format, a format allowing

14
Doc/library/bz2.rst
View File

@ -65,7 +65,7 @@ All of the classes in this module may safely be accessed from multiple threads.
Accepts a :term:`path-like object`.
.. class:: BZ2File(filename, mode='r', buffering=None, compresslevel=9)
.. class:: BZ2File(filename, mode='r', *, compresslevel=9)
Open a bzip2-compressed file in binary mode.
@ -81,8 +81,6 @@ All of the classes in this module may safely be accessed from multiple threads.
If *filename* is a file object (rather than an actual file name), a mode of
``'w'`` does not truncate the file, and is instead equivalent to ``'a'``.
The *buffering* argument is ignored. Its use is deprecated since Python 3.0.
If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be an integer between
``1`` and ``9`` specifying the level of compression: ``1`` produces the
least compression, and ``9`` (default) produces the most compression.
@ -110,9 +108,6 @@ All of the classes in this module may safely be accessed from multiple threads.
.. versionadded:: 3.3
.. deprecated:: 3.0
The keyword argument *buffering* was deprecated and is now ignored.
.. versionchanged:: 3.1
Support for the :keyword:`with` statement was added.
@ -138,6 +133,13 @@ All of the classes in this module may safely be accessed from multiple threads.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
.. versionchanged:: 3.9
The *buffering* parameter has been removed. It was ignored and deprecated
since Python 3.0. Pass an open file object to control how the file is
opened.
The *compresslevel* parameter became keyword-only.
Incremental (de)compression
---------------------------

2
Doc/library/code.rst
View File

@ -76,7 +76,7 @@ Interactive Interpreter Objects
Compile and run some source in the interpreter. Arguments are the same as for
:func:`compile_command`; the default for *filename* is ``'<input>'``, and for
*symbol* is ``'single'``. One several things can happen:
*symbol* is ``'single'``. One of several things can happen:
* The input is incorrect; :func:`compile_command` raised an exception
(:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be

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

@ -67,7 +67,7 @@ Executor Objects
.. versionchanged:: 3.5
Added the *chunksize* argument.
.. method:: shutdown(wait=True)
.. 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
@ -82,6 +82,15 @@ Executor Objects
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 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
@ -94,6 +103,9 @@ Executor Objects
e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
e.submit(shutil.copy, 'src4.txt', 'dest4.txt')
.. versionchanged:: 3.9
Added *cancel_futures*.
ThreadPoolExecutor
------------------

15
Doc/library/ctypes.rst
View File

@ -161,13 +161,6 @@ as the ``NULL`` pointer)::
0x1d000000
>>>
.. note::
:mod:`ctypes` may raise a :exc:`ValueError` after calling the function, if
it detects that an invalid number of arguments were passed. This behavior
should not be relied upon. It is deprecated in 3.6.2, and will be removed
in 3.7.
:exc:`ValueError` is raised when you call an ``stdcall`` function with the
``cdecl`` calling convention, or vice versa::
@ -624,7 +617,7 @@ Structure/union alignment and byte order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, Structure and Union fields are aligned in the same way the C
compiler does it. It is possible to override this behavior be specifying a
compiler does it. It is possible to override this behavior by specifying a
:attr:`_pack_` class attribute in the subclass definition. This must be set to a
positive integer and specifies the maximum alignment for the fields. This is
what ``#pragma pack(n)`` also does in MSVC.
@ -922,7 +915,7 @@ attribute later, after the class statement::
... ("next", POINTER(cell))]
>>>
Lets try it. We create two instances of ``cell``, and let them point to each
Let's try it. We create two instances of ``cell``, and let them point to each
other, and finally follow the pointer chain a few times::
>>> c1 = cell()
@ -1125,8 +1118,8 @@ hit the ``NULL`` entry::
>>>
The fact that standard Python has a frozen module and a frozen package
(indicated by the negative size member) is not well known, it is only used for
testing. Try it out with ``import __hello__`` for example.
(indicated by the negative ``size`` member) is not well known, it is only used
for testing. Try it out with ``import __hello__`` for example.
.. _ctypes-surprises:

7
Doc/library/dataclasses.rst
View File

@ -60,8 +60,9 @@ Module-level decorators, classes, and functions
The :func:`dataclass` decorator will add various "dunder" methods to
the class, described below. If any of the added methods already
exist on the class, a :exc:`TypeError` will be raised. The decorator
returns the same class that is called on: no new class is created.
exist on the class, the behavior depends on the parameter, as documented
below. The decorator returns the same class that is called on; no new
class is created.
If :func:`dataclass` is used just as a simple decorator with no parameters,
it acts as if it has the default values documented in this
@ -115,7 +116,7 @@ Module-level decorators, classes, and functions
If the class already defines any of :meth:`__lt__`,
:meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`, then
:exc:`ValueError` is raised.
:exc:`TypeError` is raised.
- ``unsafe_hash``: If ``False`` (the default), a :meth:`__hash__` method
is generated according to how ``eq`` and ``frozen`` are set.

2
Doc/library/datetime.rst
View File

@ -997,8 +997,6 @@ Other constructors, all class methods:
as the inverse operation of :meth:`datetime.isoformat`. A more full-featured
ISO 8601 parser, ``dateutil.parser.isoparse`` is available in the third-party package
`dateutil <https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse>`__.
This does not support parsing arbitrary ISO 8601 strings - it is only intended
as the inverse operation of :meth:`datetime.isoformat`.
Examples::

4
Doc/library/development.rst
View File

@ -18,12 +18,10 @@ The list of modules described in this chapter is:
typing.rst
pydoc.rst
devmode.rst
doctest.rst
unittest.rst
unittest.mock.rst
unittest.mock-examples.rst
2to3.rst
test.rst
See also the Python development mode: the :option:`-X` ``dev`` option and
:envvar:`PYTHONDEVMODE` environment variable.

214
Doc/library/devmode.rst Normal file
View File

@ -0,0 +1,214 @@
.. _devmode:
Python Development Mode
=======================
.. versionadded:: 3.7
The Python Development Mode introduces additional runtime checks that are too
expensive to be enabled by default. It should not be more verbose than the
default if the code is correct; new warnings are only emitted when an issue is
detected.
It can be enabled using the :option:`-X dev <-X>` command line option or by
setting the :envvar:`PYTHONDEVMODE` environment variable to ``1``.
Effects of the Python Development Mode
======================================
Enabling the Python Development Mode is similar to the following command, but
with additional effects described below::
PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python3 -W default -X faulthandler
Effects of the Python Development Mode:
* Add ``default`` :ref:`warning filter <describing-warning-filters>`. The
following warnings are shown:
* :exc:`DeprecationWarning`
* :exc:`ImportWarning`
* :exc:`PendingDeprecationWarning`
* :exc:`ResourceWarning`
Normally, the above warnings are filtered by the default :ref:`warning
filters <describing-warning-filters>`.
It behaves as if the :option:`-W default <-W>` command line option is used.
Use the :option:`-W error <-W>` command line option or set the
:envvar:`PYTHONWARNINGS` environment variable to ``error`` to treat warnings
as errors.
* Install debug hooks on memory allocators to check for:
* Buffer underflow
* Buffer overflow
* Memory allocator API violation
* Unsafe usage of the GIL
See the :c:func:`PyMem_SetupDebugHooks` C function.
It behaves as if the :envvar:`PYTHONMALLOC` environment variable is set to
``debug``.
To enable the Python Development Mode without installing debug hooks on
memory allocators, set the :envvar:`PYTHONMALLOC` environment variable to
``default``.
* Call :func:`faulthandler.enable` at Python startup to install handlers for
the :const:`SIGSEGV`, :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and
:const:`SIGILL` signals to dump the Python traceback on a crash.
It behaves as if the :option:`-X faulthandler <-X>` command line option is
used or if the :envvar:`PYTHONFAULTHANDLER` environment variable is set to
``1``.
* Enable :ref:`asyncio debug mode <asyncio-debug-mode>`. For example,
:mod:`asyncio` checks for coroutines that were not awaited and logs them.
It behaves as if the :envvar:`PYTHONASYNCIODEBUG` environment variable is set
to ``1``.
* Check the *encoding* and *errors* arguments for string encoding and decoding
operations. Examples: :func:`open`, :meth:`str.encode` and
:meth:`bytes.decode`.
By default, for best performance, the *errors* argument is only checked at
the first encoding/decoding error and the *encoding* argument is sometimes
ignored for empty strings.
* The :class:`io.IOBase` destructor logs ``close()`` exceptions.
* Set the :attr:`~sys.flags.dev_mode` attribute of :attr:`sys.flags` to
``True``.
The Python Development Mode does not enable the :mod:`tracemalloc` module by
default, because the overhead cost (to performance and memory) would be too
large. Enabling the :mod:`tracemalloc` module provides additional information
on the origin of some errors. For example, :exc:`ResourceWarning` logs the
traceback where the resource was allocated, and a buffer overflow error logs
the traceback where the memory block was allocated.
The Python Development Mode does not prevent the :option:`-O` command line
option from removing :keyword:`assert` statements nor from setting
:const:`__debug__` to ``False``.
.. versionchanged:: 3.8
The :class:`io.IOBase` destructor now logs ``close()`` exceptions.
.. versionchanged:: 3.9
The *encoding* and *errors* arguments are now checked for string encoding
and decoding operations.
ResourceWarning Example
=======================
Example of a script counting the number of lines of the text file specified in
the command line::
import sys
def main():
fp = open(sys.argv[1])
nlines = len(fp.readlines())
print(nlines)
# The file is closed implicitly
if __name__ == "__main__":
main()
The script does not close the file explicitly. By default, Python does not emit
any warning. Example using README.txt, which has 269 lines:
.. code-block:: shell-session
$ python3 script.py README.txt
269
Enabling the Python Development Mode displays a :exc:`ResourceWarning` warning:
.. code-block:: shell-session
$ python3 -X dev script.py README.txt
269
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README.rst' mode='r' encoding='UTF-8'>
main()
ResourceWarning: Enable tracemalloc to get the object allocation traceback
In addition, enabling :mod:`tracemalloc` shows the line where the file was
opened:
.. code-block:: shell-session
$ python3 -X dev -X tracemalloc=5 script.py README.rst
269
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README.rst' mode='r' encoding='UTF-8'>
main()
Object allocated at (most recent call last):
File "script.py", lineno 10
main()
File "script.py", lineno 4
fp = open(sys.argv[1])
The fix is to close explicitly the file. Example using a context manager::
def main():
# Close the file explicitly when exiting the with block
with open(sys.argv[1]) as fp:
nlines = len(fp.readlines())
print(nlines)
Not closing a resource explicitly can leave a resource open for way longer than
expected; it can cause severe issues upon exiting Python. It is bad in
CPython, but it is even worse in PyPy. Closing resources explicitly makes an
application more deterministic and more reliable.
Bad file descriptor error example
=================================
Script displaying the first line of itself::
import os
def main():
fp = open(__file__)
firstline = fp.readline()
print(firstline.rstrip())
os.close(fp.fileno())
# The file is closed implicitly
main()
By default, Python does not emit any warning:
.. code-block:: shell-session
$ python3 script.py
import os
The Python Development Mode shows a :exc:`ResourceWarning` and logs a "Bad file
descriptor" error when finalizing the file object:
.. code-block:: shell-session
$ python3 script.py
import os
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script.py' mode='r' encoding='UTF-8'>
main()
ResourceWarning: Enable tracemalloc to get the object allocation traceback
Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' encoding='UTF-8'>
Traceback (most recent call last):
File "script.py", line 10, in <module>
main()
OSError: [Errno 9] Bad file descriptor
``os.close(fp.fileno())`` closes the file descriptor. When the file object
finalizer tries to close the file descriptor again, it fails with the ``Bad
file descriptor`` error. A file descriptor must be closed only once. In the
worst case scenario, closing it twice can lead to a crash (see :issue:`18748`
for an example).
The fix is to remove the ``os.close(fp.fileno())`` line, or open the file with
``closefd=False``.

95
Doc/library/dis.rst
View File

@ -859,61 +859,39 @@ All of the following opcodes use their arguments.
.. versionadded:: 3.6
.. opcode:: BUILD_TUPLE_UNPACK (count)
.. opcode:: LIST_TO_TUPLE
Pops *count* iterables from the stack, joins them in a single tuple,
and pushes the result. Implements iterable unpacking in tuple
displays ``(*x, *y, *z)``.
Pops a list from the stack and pushes a tuple containing the same values.
.. versionadded:: 3.5
.. versionadded:: 3.9
.. opcode:: BUILD_TUPLE_UNPACK_WITH_CALL (count)
.. opcode:: LIST_EXTEND (i)
This is similar to :opcode:`BUILD_TUPLE_UNPACK`,
but is used for ``f(*x, *y, *z)`` call syntax. The stack item at position
``count + 1`` should be the corresponding callable ``f``.
Calls ``list.extend(TOS1[-i], TOS)``. Used to build lists.
.. versionadded:: 3.6
.. versionadded:: 3.9
.. opcode:: BUILD_LIST_UNPACK (count)
.. opcode:: SET_UPDATE (i)
This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a list
instead of tuple. Implements iterable unpacking in list
displays ``[*x, *y, *z]``.
Calls ``set.update(TOS1[-i], TOS)``. Used to build sets.
.. versionadded:: 3.5
.. versionadded:: 3.9
.. opcode:: BUILD_SET_UNPACK (count)
.. opcode:: DICT_UPDATE (i)
This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a set
instead of tuple. Implements iterable unpacking in set
displays ``{*x, *y, *z}``.
Calls ``dict.update(TOS1[-i], TOS)``. Used to build dicts.
.. versionadded:: 3.5
.. versionadded:: 3.9
.. opcode:: BUILD_MAP_UNPACK (count)
.. opcode:: DICT_MERGE
Pops *count* mappings from the stack, merges them into a single dictionary,
and pushes the result. Implements dictionary unpacking in dictionary
displays ``{**x, **y, **z}``.
Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
.. versionadded:: 3.5
.. opcode:: BUILD_MAP_UNPACK_WITH_CALL (count)
This is similar to :opcode:`BUILD_MAP_UNPACK`,
but is used for ``f(**x, **y, **z)`` call syntax. The stack item at
position ``count + 2`` should be the corresponding callable ``f``.
.. versionadded:: 3.5
.. versionchanged:: 3.6
The position of the callable is determined by adding 2 to the opcode
argument instead of encoding it in the second byte of the argument.
.. versionadded:: 3.9
.. opcode:: LOAD_ATTR (namei)
@ -927,6 +905,20 @@ All of the following opcodes use their arguments.
``cmp_op[opname]``.
.. opcode:: IS_OP (invert)
Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
.. versionadded:: 3.9
.. opcode:: CONTAINS_OP (invert)
Performs ``in`` comparison, or ``not in`` if ``invert`` is 1.
.. versionadded:: 3.9
.. opcode:: IMPORT_NAME (namei)
Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
@ -961,6 +953,13 @@ All of the following opcodes use their arguments.
.. versionadded:: 3.1
.. opcode:: JUMP_IF_NOT_EXC_MATCH (target)
Tests whether the second value on the stack is an exception matching TOS,
and jumps if it is not. Pops two values from the stack.
.. versionadded:: 3.9
.. opcode:: JUMP_IF_TRUE_OR_POP (target)
@ -1103,10 +1102,6 @@ All of the following opcodes use their arguments.
Calls a callable object with variable set of positional and keyword
arguments. If the lowest bit of *flags* is set, the top of the stack
contains a mapping object containing additional keyword arguments.
Below that is an iterable object containing positional arguments and
a callable object to call. :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and
:opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` can be used for merging multiple
mapping objects and iterables containing arguments.
Before the callable is called, the mapping object and iterable object
are each "unpacked" and their contents passed in as keyword and
positional arguments respectively.
@ -1119,22 +1114,24 @@ All of the following opcodes use their arguments.
.. opcode:: LOAD_METHOD (namei)
Loads a method named ``co_names[namei]`` from TOS object. TOS is popped and
method and TOS are pushed when interpreter can call unbound method directly.
TOS will be used as the first argument (``self``) by :opcode:`CALL_METHOD`.
Otherwise, ``NULL`` and method is pushed (method is bound method or
something else).
Loads a method named ``co_names[namei]`` from the TOS object. TOS is popped.
This bytecode distinguishes two cases: if TOS has a method with the correct
name, the bytecode pushes the unbound method and TOS. TOS will be used as
the first argument (``self``) by :opcode:`CALL_METHOD` when calling the
unbound method. Otherwise, ``NULL`` and the object return by the attribute
lookup are pushed.
.. versionadded:: 3.7
.. opcode:: CALL_METHOD (argc)
Calls a method. *argc* is number of positional arguments.
Calls a method. *argc* is the number of positional arguments.
Keyword arguments are not supported. This opcode is designed to be used
with :opcode:`LOAD_METHOD`. Positional arguments are on top of the stack.
Below them, two items described in :opcode:`LOAD_METHOD` on the stack.
All of them are popped and return value is pushed.
Below them, the two items described in :opcode:`LOAD_METHOD` are on the
stack (either ``self`` and an unbound method object or ``NULL`` and an
arbitrary callable). All of them are popped and the return value is pushed.
.. versionadded:: 3.7

2
Doc/library/ensurepip.rst
View File

@ -74,7 +74,7 @@ options:
script will *not* be installed.
* ``--default-pip``: if a "default pip" installation is requested, the
``pip`` script will be installed in addition to the two regular scripts.
``pip`` script will be installed in addition to the two regular scripts.
Providing both of the script selection options will trigger an exception.

2
Doc/library/enum.rst
View File

@ -55,7 +55,7 @@ helper, :class:`auto`.
.. class:: auto
Instances are replaced with an appropriate value for Enum members.
Instances are replaced with an appropriate value for Enum members. By default, the initial value starts at 1.
.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``

16
Doc/library/exceptions.rst
View File

@ -688,6 +688,10 @@ The following exceptions are used as warning categories; see the
Base class for warnings about deprecated features when those warnings are
intended for other Python developers.
Ignored by the default warning filters, except in the ``__main__`` module
(:pep:`565`). Enabling the :ref:`Python Development Mode <devmode>` shows
this warning.
.. exception:: PendingDeprecationWarning
@ -699,6 +703,9 @@ The following exceptions are used as warning categories; see the
upcoming deprecation is unusual, and :exc:`DeprecationWarning`
is preferred for already active deprecations.
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
.. exception:: SyntaxWarning
@ -720,6 +727,9 @@ The following exceptions are used as warning categories; see the
Base class for warnings about probable mistakes in module imports.
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
.. exception:: UnicodeWarning
@ -733,8 +743,10 @@ The following exceptions are used as warning categories; see the
.. exception:: ResourceWarning
Base class for warnings related to resource usage. Ignored by the default
warning filters.
Base class for warnings related to resource usage.
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
.. versionadded:: 3.2

3
Doc/library/faulthandler.rst
View File

@ -40,6 +40,9 @@ alternatively be passed to :func:`faulthandler.enable`.
The module is implemented in C, so tracebacks can be dumped on a crash or when
Python is deadlocked.
The :ref:`Python Development Mode <devmode>` calls :func:`faulthandler.enable`
at Python startup.
Dumping the traceback
---------------------

8
Doc/library/fcntl.rst
View File

@ -63,6 +63,8 @@ The module defines the following functions:
If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
.. function:: ioctl(fd, request, arg=0, mutate_flag=True)
@ -112,6 +114,8 @@ The module defines the following functions:
>>> buf
array('h', [13341])
.. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
.. function:: flock(fd, operation)
@ -122,6 +126,8 @@ The module defines the following functions:
If the :c:func:`flock` fails, an :exc:`OSError` exception is raised.
.. audit-event:: fcntl.flock fd,operation fcntl.flock
.. function:: lockf(fd, cmd, len=0, start=0, whence=0)
@ -155,6 +161,8 @@ The module defines the following functions:
The default for *len* is 0 which means to lock to the end of the file. The
default for *whence* is also 0.
.. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf
Examples (all on a SVR4 compliant system)::
import struct, fcntl, os

16
Doc/library/fractions.rst
View File

@ -84,6 +84,10 @@ another rational number, or from a string.
The :class:`Fraction` constructor now accepts :class:`float` and
:class:`decimal.Decimal` instances.
.. versionchanged:: 3.9
The :func:`math.gcd` function is now used to normalize the *numerator*
and *denominator*. :func:`math.gcd` always return a :class:`int` type.
Previously, the GCD type depended on *numerator* and *denominator*.
.. attribute:: numerator
@ -172,18 +176,6 @@ another rational number, or from a string.
method can also be accessed through the :func:`round` function.
.. function:: gcd(a, b)
Return the greatest common divisor of the integers *a* and *b*. If either
*a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the
largest integer that divides both *a* and *b*. ``gcd(a,b)`` has the same
sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*. ``gcd(0,
0)`` returns ``0``.
.. deprecated:: 3.5
Use :func:`math.gcd` instead.
.. seealso::
Module :mod:`numbers`

7
Doc/library/ftplib.rst
View File

@ -72,6 +72,9 @@ The module defines the following items:
.. versionchanged:: 3.3
*source_address* parameter was added.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket
.. class:: FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)
@ -105,6 +108,10 @@ The module defines the following items:
:func:`ssl.create_default_context` select the system's trusted CA
certificates for you.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket
Here's a sample session using the :class:`FTP_TLS` class::
>>> ftps = FTP_TLS('ftp.pureftpd.org')

11
Doc/library/functions.rst
View File

@ -892,6 +892,11 @@ are always available. They are listed here in alphabetical order.
sequence (such as a string, bytes, tuple, list, or range) or a collection
(such as a dictionary, set, or frozen set).
.. impl-detail::
``len`` raises :exc:`OverflowError` on lengths larger than
:data:`sys.maxsize`, such as :class:`range(2 ** 100) <range>`.
.. _func-list:
.. class:: list([iterable])
@ -952,7 +957,7 @@ are always available. They are listed here in alphabetical order.
.. _func-memoryview:
.. function:: memoryview(obj)
.. class:: memoryview(obj)
:noindex:
Return a "memory view" object created from the given argument. See
@ -1408,7 +1413,7 @@ are always available. They are listed here in alphabetical order.
.. _func-range:
.. function:: range(stop)
.. class:: range(stop)
range(start, stop[, step])
:noindex:
@ -1655,7 +1660,7 @@ are always available. They are listed here in alphabetical order.
.. _func-tuple:
.. function:: tuple([iterable])
.. class:: tuple([iterable])
:noindex:
Rather than being a function, :class:`tuple` is actually an immutable

200
Doc/library/functools.rst
View File

@ -8,10 +8,16 @@
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
.. moduleauthor:: Łukasz Langa <lukasz@langa.pl>
.. moduleauthor:: Pablo Galindo <pablogsal@gmail.com>
.. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
**Source code:** :source:`Lib/functools.py`
.. testsetup:: default
import functools
from functools import *
--------------
The :mod:`functools` module is for higher-order functions: functions that act on
@ -512,6 +518,184 @@ The :mod:`functools` module defines the following functions:
.. versionadded:: 3.8
.. class:: TopologicalSorter(graph=None)
Provides functionality to topologically sort a graph of hashable nodes.
A topological order is a linear ordering of the vertices in a graph such that
for every directed edge u -> v from vertex u to vertex v, vertex u comes
before vertex v in the ordering. For instance, the vertices of the graph may
represent tasks to be performed, and the edges may represent constraints that
one task must be performed before another; in this example, a topological
ordering is just a valid sequence for the tasks. A complete topological
ordering is possible if and only if the graph has no directed cycles, that
is, if it is a directed acyclic graph.
If the optional *graph* argument is provided it must be a dictionary
representing a directed acyclic graph where the keys are nodes and the values
are iterables of all predecessors of that node in the graph (the nodes that
have edges that point to the value in the key). Additional nodes can be added
to the graph using the :meth:`~TopologicalSorter.add` method.
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.
In case just an immediate sorting of the nodes in the graph is required and
no parallelism is involved, the convenience method
:meth:`TopologicalSorter.static_order` can be used directly:
.. doctest::
>>> graph = {"D": {"B", "C"}, "C": {"A"}, "B": {"A"}}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')
The class is designed to easily support parallel processing of the nodes as
they become ready. For instance::
topological_sorter = TopologicalSorter()
# Add nodes to 'topological_sorter'...
topological_sorter.prepare()
while topological_sorter.is_active():
for node in topological_sorter.get_ready():
# Worker threads or processes take nodes to work on off the
# 'task_queue' queue.
task_queue.put(node)
# When the work for a node is done, workers put the node in
# 'finalized_tasks_queue' so we can get more nodes to work on.
# The definition of 'is_active()' guarantees that, at this point, at
# least one node has been placed on 'task_queue' that hasn't yet
# been passed to 'done()', so this blocking 'get()' must (eventually)
# succeed. After calling 'done()', we loop back to call 'get_ready()'
# again, so put newly freed nodes on 'task_queue' as soon as
# logically possible.
node = finalized_tasks_queue.get()
topological_sorter.done(node)
.. method:: add(node, *predecessors)
Add a new node and its predecessors to the graph. Both the *node* and all
elements in *predecessors* must be hashable.
If called multiple times with the same node argument, the set of
dependencies will be the union of all dependencies passed in.
It is possible to add a node with no dependencies (*predecessors* is not
provided) or to provide a dependency twice. If a node that has not been
provided before is included among *predecessors* it will be automatically
added to the graph with no predecessors of its own.
Raises :exc:`ValueError` if called after :meth:`~TopologicalSorter.prepare`.
.. method:: prepare()
Mark the graph as finished and check for cycles in the graph. If any cycle
is detected, :exc:`CycleError` will be raised, but
:meth:`~TopologicalSorter.get_ready` can still be used to obtain as many
nodes as possible until cycles block more progress. After a call to this
function, the graph cannot be modified, and therefore no more nodes can be
added using :meth:`~TopologicalSorter.add`.
.. method:: is_active()
Returns ``True`` if more progress can be made and ``False`` otherwise.
Progress can be made if cycles do not block the resolution and either
there are still nodes ready that haven't yet been returned by
:meth:`TopologicalSorter.get_ready` or the number of nodes marked
:meth:`TopologicalSorter.done` is less than the number that have been
returned by :meth:`TopologicalSorter.get_ready`.
The :meth:`~TopologicalSorter.__bool__` method of this class defers to
this function, so instead of::
if ts.is_active():
...
if possible to simply do::
if ts:
...
Raises :exc:`ValueError` if called without calling
:meth:`~TopologicalSorter.prepare` previously.
.. method:: done(*nodes)
Marks a set of nodes returned by :meth:`TopologicalSorter.get_ready` as
processed, unblocking any successor of each node in *nodes* for being
returned in the future by a call to :meth:`TopologicalSorter.get_ready`.
Raises :exc:`ValueError` if any node in *nodes* has already been marked as
processed by a previous call to this method or if a node was not added to
the graph by using :meth:`TopologicalSorter.add`, if called without
calling :meth:`~TopologicalSorter.prepare` or if node has not yet been
returned by :meth:`~TopologicalSorter.get_ready`.
.. method:: get_ready()
Returns a ``tuple`` with all the nodes that are ready. Initially it
returns all nodes with no predecessors, and once those are marked as
processed by calling :meth:`TopologicalSorter.done`, further calls will
return all new nodes that have all their predecessors already processed.
Once no more progress can be made, empty tuples are returned.
Raises :exc:`ValueError` if called without calling
:meth:`~TopologicalSorter.prepare` previously.
.. method:: static_order()
Returns an iterable of nodes in a topological order. Using this method
does not require to call :meth:`TopologicalSorter.prepare` or
:meth:`TopologicalSorter.done`. This method is equivalent to::
def static_order(self):
self.prepare()
while self.is_active():
node_group = self.get_ready()
yield from node_group
self.done(*node_group)
The particular order that is returned may depend on the specific order in
which the items were inserted in the graph. For example:
.. doctest::
>>> ts = TopologicalSorter()
>>> ts.add(3, 2, 1)
>>> ts.add(1, 0)
>>> print([*ts.static_order()])
[2, 0, 1, 3]
>>> ts2 = TopologicalSorter()
>>> ts2.add(1, 0)
>>> ts2.add(3, 2, 1)
>>> print([*ts2.static_order()])
[0, 2, 1, 3]
This is due to the fact that "0" and "2" are in the same level in the
graph (they would have been returned in the same call to
:meth:`~TopologicalSorter.get_ready`) and the order between them is
determined by the order of insertion.
If any cycle is detected, :exc:`CycleError` will be raised.
.. versionadded:: 3.9
.. function:: update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
Update a *wrapper* function to look like the *wrapped* function. The optional
@ -621,3 +805,19 @@ differences. For instance, the :attr:`~definition.__name__` and :attr:`__doc__`
are not created automatically. Also, :class:`partial` objects defined in
classes behave like static methods and do not transform into bound methods
during instance attribute look-up.
Exceptions
----------
The :mod:`functools` module defines the following exception classes:
.. exception:: CycleError
Subclass of :exc:`ValueError` raised by :meth:`TopologicalSorter.prepare` if cycles exist
in the working graph. If multiple cycles exist, only one undefined choice among them will
be reported and included in the exception.
The detected cycle can be accessed via the second element in the :attr:`~CycleError.args`
attribute of the exception instance and consists in a list of nodes, such that each node is,
in the graph, an immediate predecessor of the next node in the list. In the reported list,
the first and the last node will be the same, to make it clear that it is cyclic.

21
Doc/library/gc.rst
View File

@ -177,6 +177,27 @@ The :mod:`gc` module provides the following functions:
.. versionadded:: 3.1
.. function:: is_finalized(obj)
Returns ``True`` if the given object has been finalized by the
garbage collector, ``False`` otherwise. ::
>>> x = None
>>> class Lazarus:
... def __del__(self):
... global x
... x = self
...
>>> lazarus = Lazarus()
>>> gc.is_finalized(lazarus)
False
>>> del lazarus
>>> gc.is_finalized(x)
True
.. versionadded:: 3.9
.. function:: freeze()
Freeze all the objects tracked by gc - move them to a permanent generation

4
Doc/library/gettext.rst
View File

@ -724,8 +724,8 @@ implementations, and valuable experience to the creation of this module:
.. [#] The default locale directory is system dependent; for example, on RedHat Linux
it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/locale`.
The :mod:`gettext` module does not try to support these system dependent
defaults; instead its default is :file:`{sys.prefix}/share/locale` (see
:data:`sys.prefix`). For this reason, it is always best to call
defaults; instead its default is :file:`{sys.base_prefix}/share/locale` (see
:data:`sys.base_prefix`). For this reason, it is always best to call
:func:`bindtextdomain` with an explicit absolute path at the start of your
application.

4
Doc/library/http.client.rst
View File

@ -586,8 +586,8 @@ Here is an example session that shows how to ``POST`` requests::
Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The
difference lies only the server side where HTTP server will allow resources to
be created via ``PUT`` request. It should be noted that custom HTTP methods
+are also handled in :class:`urllib.request.Request` by sending the appropriate
+method attribute.Here is an example session that shows how to do ``PUT``
are also handled in :class:`urllib.request.Request` by setting the appropriate
method attribute. Here is an example session that shows how to send a ``PUT``
request using http.client::
>>> # This creates an HTTP message

9
Doc/library/http.server.rst
View File

@ -335,11 +335,14 @@ provides three different variants:
.. attribute:: extensions_map
A dictionary mapping suffixes into MIME types. The default is
signified by an empty string, and is considered to be
``application/octet-stream``. The mapping is used case-insensitively,
A dictionary mapping suffixes into MIME types, contains custom overrides
for the default system mappings. The mapping is used case-insensitively,
and so should contain only lower-cased keys.
.. versionchanged:: 3.9
This dictionary is no longer filled with the default system mappings,
but only contains overrides.
.. attribute:: directory
If not specified, the directory to serve is the current working directory.

15
Doc/library/idle.rst
View File

@ -370,7 +370,8 @@ Paste
Editor windows also have breakpoint functions. Lines with a breakpoint set are
specially marked. Breakpoints only have an effect when running under the
debugger. Breakpoints for a file are saved in the user's .idlerc directory.
debugger. Breakpoints for a file are saved in the user's ``.idlerc``
directory.
Set Breakpoint
Set a breakpoint on the current line.
@ -685,14 +686,14 @@ crash or Keyboard Interrupt (control-C) may fail to connect. Dismissing
the error box or Restart Shell on the Shell menu may fix a temporary problem.
When IDLE first starts, it attempts to read user configuration files in
~/.idlerc/ (~ is one's home directory). If there is a problem, an error
``~/.idlerc/`` (~ is one's home directory). If there is a problem, an error
message should be displayed. Leaving aside random disk glitches, this can
be prevented by never editing the files by hand, using the configuration
dialog, under Options, instead Options. Once it happens, the solution may
be to delete one or more of the configuration files.
If IDLE quits with no message, and it was not started from a console, try
starting from a console (``python -m idlelib)`` and see if a message appears.
starting from a console (``python -m idlelib``) and see if a message appears.
Running user code
^^^^^^^^^^^^^^^^^
@ -863,13 +864,13 @@ Or click the TOC (Table of Contents) button and select a section
header in the opened box.
Help menu entry "Python Docs" opens the extensive sources of help,
including tutorials, available at docs.python.org/x.y, where 'x.y'
including tutorials, available at ``docs.python.org/x.y``, where 'x.y'
is the currently running Python version. If your system
has an off-line copy of the docs (this may be an installation option),
that will be opened instead.
Selected URLs can be added or removed from the help menu at any time using the
General tab of the Configure IDLE dialog .
General tab of the Configure IDLE dialog.
.. _preferences:
@ -878,9 +879,9 @@ Setting preferences
The font preferences, highlighting, keys, and general preferences can be
changed via Configure IDLE on the Option menu.
Non-default user settings are saved in a .idlerc directory in the user's
Non-default user settings are saved in a ``.idlerc`` directory in the user's
home directory. Problems caused by bad user configuration files are solved
by editing or deleting one or more of the files in .idlerc.
by editing or deleting one or more of the files in ``.idlerc``.
On the Font tab, see the text sample for the effect of font face and size
on multiple characters in multiple languages. Edit the sample to add

37
Doc/library/imaplib.rst
View File

@ -30,12 +30,14 @@ Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
base class:
.. class:: IMAP4(host='', port=IMAP4_PORT)
.. class:: IMAP4(host='', port=IMAP4_PORT, timeout=None)
This class implements the actual IMAP4 protocol. The connection is created and
protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
initialized. If *host* is not specified, ``''`` (the local host) is used. If
*port* is omitted, the standard IMAP4 port (143) is used.
*port* is omitted, the standard IMAP4 port (143) is used. The optional *timeout*
parameter specifies a timeout in seconds for the connection attempt.
If timeout is not given or is None, the global default socket timeout is used.
The :class:`IMAP4` class supports the :keyword:`with` statement. When used
like this, the IMAP4 ``LOGOUT`` command is issued automatically when the
@ -50,6 +52,9 @@ base class:
.. versionchanged:: 3.5
Support for the :keyword:`with` statement was added.
.. versionchanged:: 3.9
The optional *timeout* parameter was added.
Three exceptions are defined as attributes of the :class:`IMAP4` class:
@ -78,7 +83,7 @@ There's also a subclass for secure connections:
.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, \
certfile=None, ssl_context=None)
certfile=None, ssl_context=None, timeout=None)
This is a subclass derived from :class:`IMAP4` that connects over an SSL
encrypted socket (to use this class you need a socket module that was compiled
@ -95,8 +100,12 @@ There's also a subclass for secure connections:
mutually exclusive with *ssl_context*, a :class:`ValueError` is raised
if *keyfile*/*certfile* is provided along with *ssl_context*.
The optional *timeout* parameter specifies a timeout in seconds for the
connection attempt. If timeout is not given or is None, the global default
socket timeout is used.
.. versionchanged:: 3.3
*ssl_context* parameter added.
*ssl_context* parameter was added.
.. versionchanged:: 3.4
The class now supports hostname check with
@ -110,6 +119,8 @@ There's also a subclass for secure connections:
:func:`ssl.create_default_context` select the system's trusted CA
certificates for you.
.. versionchanged:: 3.9
The optional *timeout* parameter was added.
The second subclass allows for connections created by a child process:
@ -353,16 +364,22 @@ An :class:`IMAP4` instance has the following methods:
Send ``NOOP`` to server.
.. method:: IMAP4.open(host, port)
.. method:: IMAP4.open(host, port, timeout=None)
Opens socket to *port* at *host*. This method is implicitly called by
the :class:`IMAP4` constructor. The connection objects established by this
method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`,
:meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override
this method.
Opens socket to *port* at *host*. The optional *timeout* parameter
specifies a timeout in seconds for the connection attempt.
If timeout is not given or is None, the global default socket timeout
is used. Also note that if the *timeout* parameter is set to be zero,
it will raise a :class:`ValueError` to reject creating a non-blocking socket.
This method is implicitly called by the :class:`IMAP4` constructor.
The connection objects established by this method will be used in
the :meth:`IMAP4.read`, :meth:`IMAP4.readline`, :meth:`IMAP4.send`,
and :meth:`IMAP4.shutdown` methods. You may override this method.
.. audit-event:: imaplib.open self,host,port imaplib.IMAP4.open
.. versionchanged:: 3.9
The *timeout* parameter was added.
.. method:: IMAP4.partial(message_num, message_part, start, length)

39
Doc/library/importlib.metadata.rst
View File

@ -1,8 +1,8 @@
.. _using:
==========================
Using importlib.metadata
==========================
=================================
Using :mod:`!importlib.metadata`
=================================
.. note::
This functionality is provisional and may deviate from the usual
@ -12,8 +12,8 @@
package metadata. Built in part on Python's import system, this library
intends to replace similar functionality in the `entry point
API`_ and `metadata API`_ of ``pkg_resources``. Along with
``importlib.resources`` in `Python 3.7
and newer`_ (backported as `importlib_resources`_ for older versions of
:mod:`importlib.resources` in Python 3.7
and newer (backported as `importlib_resources`_ for older versions of
Python), this can eliminate the need to use the older and less efficient
``pkg_resources`` package.
@ -21,9 +21,9 @@ By "installed package" we generally mean a third-party package installed into
Python's ``site-packages`` directory via tools such as `pip
<https://pypi.org/project/pip/>`_. Specifically,
it means a package with either a discoverable ``dist-info`` or ``egg-info``
directory, and metadata defined by `PEP 566`_ or its older specifications.
directory, and metadata defined by :pep:`566` or its older specifications.
By default, package metadata can live on the file system or in zip archives on
``sys.path``. Through an extension mechanism, the metadata can live almost
:data:`sys.path`. Through an extension mechanism, the metadata can live almost
anywhere.
@ -134,7 +134,7 @@ Distribution files
You can also get the full set of files contained within a distribution. The
``files()`` function takes a distribution package name and returns all of the
files installed by this distribution. Each file object returned is a
``PackagePath``, a `pathlib.Path`_ derived object with additional ``dist``,
``PackagePath``, a :class:`pathlib.Path` derived object with additional ``dist``,
``size``, and ``hash`` properties as indicated by the metadata. For example::
>>> util = [p for p in files('wheel') if 'util.py' in str(p)][0] # doctest: +SKIP
@ -203,18 +203,18 @@ instance::
>>> d.metadata['License'] # doctest: +SKIP
'MIT'
The full set of available metadata is not described here. See `PEP 566
<https://www.python.org/dev/peps/pep-0566/>`_ for additional details.
The full set of available metadata is not described here. See :pep:`566`
for additional details.
Extending the search algorithm
==============================
Because package metadata is not available through ``sys.path`` searches, or
Because package metadata is not available through :data:`sys.path` searches, or
package loaders directly, the metadata for a package is found through import
system `finders`_. To find a distribution package's metadata,
``importlib.metadata`` queries the list of `meta path finders`_ on
`sys.meta_path`_.
system :ref:`finders <finders-and-loaders>`. To find a distribution package's metadata,
``importlib.metadata`` queries the list of :term:`meta path finders <meta path finder>` on
:data:`sys.meta_path`.
The default ``PathFinder`` for Python includes a hook that calls into
``importlib.metadata.MetadataPathFinder`` for finding distributions
@ -224,7 +224,7 @@ The abstract class :py:class:`importlib.abc.MetaPathFinder` defines the
interface expected of finders by Python's import system.
``importlib.metadata`` extends this protocol by looking for an optional
``find_distributions`` callable on the finders from
``sys.meta_path`` and presents this extended interface as the
:data:`sys.meta_path` and presents this extended interface as the
``DistributionFinder`` abstract base class, which defines this abstract
method::
@ -247,20 +247,13 @@ a custom finder, return instances of this derived ``Distribution`` in the
.. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
.. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api
.. _`Python 3.7 and newer`: https://docs.python.org/3/library/importlib.html#module-importlib.resources
.. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html
.. _`PEP 566`: https://www.python.org/dev/peps/pep-0566/
.. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders
.. _`meta path finders`: https://docs.python.org/3/glossary.html#term-meta-path-finder
.. _`sys.meta_path`: https://docs.python.org/3/library/sys.html#sys.meta_path
.. _`pathlib.Path`: https://docs.python.org/3/library/pathlib.html#pathlib.Path
.. rubric:: Footnotes
.. [#f1] Technically, the returned distribution metadata object is an
`email.message.Message
<https://docs.python.org/3/library/email.message.html#email.message.EmailMessage>`_
:class:`email.message.EmailMessage`
instance, but this is an implementation detail, and not part of the
stable API. You should only use dictionary-like methods and syntax
to access the metadata contents.

22
Doc/library/inspect.rst
View File

@ -624,15 +624,18 @@ function.
.. attribute:: Signature.parameters
An ordered mapping of parameters' names to the corresponding
:class:`Parameter` objects. Parameters appear in strict definition
order, including keyword-only parameters.
An dictionary of :class:`Parameter` objects. Parameters appear in strict
definition order, including keyword-only parameters.
.. versionchanged:: 3.7
Python only explicitly guaranteed that it preserved the declaration
order of keyword-only parameters as of version 3.7, although in practice
this order had always been preserved in Python 3.
.. versionchanged:: 3.9
:attr:`parameters` is now of type :class:`dict`. Formerly, it was of
type :class:`collections.OrderedDict`.
.. attribute:: Signature.return_annotation
The "return" annotation for the callable. If the callable has no "return"
@ -821,10 +824,9 @@ function.
.. attribute:: BoundArguments.arguments
An ordered, mutable mapping (:class:`collections.OrderedDict`) of
parameters' names to arguments' values. Contains only explicitly bound
arguments. Changes in :attr:`arguments` will reflect in :attr:`args` and
:attr:`kwargs`.
An ordered, mutable mapping of parameters' names to arguments' values.
Contains only explicitly bound arguments. Changes in :attr:`arguments`
will reflect in :attr:`args` and :attr:`kwargs`.
Should be used in conjunction with :attr:`Signature.parameters` for any
argument processing purposes.
@ -836,6 +838,10 @@ function.
However, if needed, use :meth:`BoundArguments.apply_defaults` to add
them.
.. versionchanged:: 3.9
:attr:`arguments` is now of type :class:`dict`. Formerly, it was of
type :class:`collections.OrderedDict`.
.. attribute:: BoundArguments.args
A tuple of positional arguments values. Dynamically computed from the
@ -866,7 +872,7 @@ function.
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])
{'a': 'spam', 'b': 'ham', 'args': ()}
.. versionadded:: 3.5

9
Doc/library/json.rst
View File

@ -283,19 +283,18 @@ Basic Usage
instance containing a JSON document) to a Python object using this
:ref:`conversion table <json-to-py-table>`.
The other arguments have the same meaning as in :func:`load`, except
*encoding* which is ignored and deprecated since Python 3.1.
The other arguments have the same meaning as in :func:`load`.
If the data being deserialized is not a valid JSON document, a
:exc:`JSONDecodeError` will be raised.
.. deprecated-removed:: 3.1 3.9
*encoding* keyword argument.
.. versionchanged:: 3.6
*s* can now be of type :class:`bytes` or :class:`bytearray`. The
input encoding should be UTF-8, UTF-16 or UTF-32.
.. versionchanged:: 3.9
The keyword argument *encoding* has been removed.
Encoders and Decoders
---------------------

41
Doc/library/math.rst
View File

@ -213,6 +213,23 @@ Number-theoretic and representation functions
of *x* and are floats.
.. function:: nextafter(x, y)
Return the next floating-point value after *x* towards *y*.
If *x* is equal to *y*, return *y*.
Examples:
* ``math.nextafter(x, math.inf)`` goes up: towards positive infinity.
* ``math.nextafter(x, -math.inf)`` goes down: towards minus infinity.
* ``math.nextafter(x, 0.0)`` goes towards zero.
* ``math.nextafter(x, math.copysign(math.inf, x))`` goes away from zero.
See also :func:`math.ulp`.
.. versionadded:: 3.9
.. function:: perm(n, k=None)
Return the number of ways to choose *k* items from *n* items
@ -269,6 +286,30 @@ Number-theoretic and representation functions
:class:`~numbers.Integral` (usually an integer). Delegates to
:meth:`x.__trunc__() <object.__trunc__>`.
.. function:: ulp(x)
Return the value of the least significant bit of the float *x*:
* If *x* is a NaN (not a number), return *x*.
* If *x* is negative, return ``ulp(-x)``.
* If *x* is a positive infinity, return *x*.
* If *x* is equal to zero, return the smallest positive
*denormalized* representable float (smaller than the minimum positive
*normalized* float, :data:`sys.float_info.min <sys.float_info>`).
* If *x* is equal to the largest positive representable float,
return the value of the least significant bit of *x*, such that the first
float smaller than *x* is ``x - ulp(x)``.
* Otherwise (*x* is a positive finite number), return the value of the least
significant bit of *x*, such that the first float bigger than *x*
is ``x + ulp(x)``.
ULP stands for "Unit in the Last Place".
See also :func:`math.nextafter` and :data:`sys.float_info.epsilon
<sys.float_info>`.
.. versionadded:: 3.9
Note that :func:`frexp` and :func:`modf` have a different call/return pattern
than their C equivalents: they take a single argument and return a pair of

3
Doc/library/mmap.rst
View File

@ -244,7 +244,8 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
.. method:: readline()
Returns a single line, starting at the current file position and up to the
next newline.
next newline. The file position is updated to point after the bytes that were
returned.
.. method:: resize(newsize)

6
Doc/library/msvcrt.rst
View File

@ -42,6 +42,8 @@ File Operations
regions in a file may be locked at the same time, but may not overlap. Adjacent
regions are not merged; they must be unlocked individually.
.. audit-event:: msvcrt.locking fd,mode,nbytes msvcrt.locking
.. data:: LK_LOCK
LK_RLCK
@ -77,12 +79,16 @@ File Operations
and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter
to :func:`os.fdopen` to create a file object.
.. audit-event:: msvcrt.open_osfhandle handle,flags msvcrt.open_osfhandle
.. function:: get_osfhandle(fd)
Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if
*fd* is not recognized.
.. audit-event:: msvcrt.get_osfhandle fd msvcrt.get_osfhandle
.. _msvcrt-console:

2
Doc/library/multiprocessing.rst
View File

@ -2279,7 +2279,7 @@ with the :class:`Pool` class.
.. method:: successful()
Return whether the call completed without raising an exception. Will
raise :exc:`AssertionError` if the result is not ready.
raise :exc:`ValueError` if the result is not ready.
.. versionchanged:: 3.7
If the result is not ready, :exc:`ValueError` is raised instead of

43
Doc/library/nntplib.rst
View File

@ -20,7 +20,7 @@ as well as the older :rfc:`977` and :rfc:`2980`.
Here are two small examples of how it can be used. To list some statistics
about a newsgroup and print the subjects of the last 10 articles::
>>> s = nntplib.NNTP('news.gmane.org')
>>> s = nntplib.NNTP('news.gmane.io')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
Group gmane.comp.python.committers has 1096 articles, range 1 to 1096
@ -44,7 +44,7 @@ about a newsgroup and print the subjects of the last 10 articles::
To post an article from a binary file (this assumes that the article has valid
headers, and that you have right to post on the particular newsgroup)::
>>> s = nntplib.NNTP('news.gmane.org')
>>> s = nntplib.NNTP('news.gmane.io')
>>> f = open('article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
@ -73,7 +73,7 @@ The module itself defines the following classes:
connection when done, e.g.:
>>> from nntplib import NNTP
>>> with NNTP('news.gmane.org') as n:
>>> with NNTP('news.gmane.io') as n:
... n.group('gmane.comp.python.committers')
... # doctest: +SKIP
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
@ -93,6 +93,10 @@ The module itself defines the following classes:
.. versionchanged:: 3.3
Support for the :keyword:`with` statement was added.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket.
.. class:: NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False, [timeout])
Return a new :class:`NNTP_SSL` object, representing an encrypted
@ -122,6 +126,10 @@ The module itself defines the following classes:
:attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
:data:`ssl.HAS_SNI`).
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket.
.. exception:: NNTPError
Derived from the standard exception :exc:`Exception`, this is the base
@ -225,7 +233,7 @@ tuples or objects that the method normally returns will be empty.
of values. On legacy servers which don't understand the ``CAPABILITIES``
command, an empty dictionary is returned instead.
>>> s = NNTP('news.gmane.org')
>>> s = NNTP('news.gmane.io')
>>> 'POST' in s.getcapabilities()
True
@ -534,33 +542,6 @@ them have been superseded by newer commands in :rfc:`3977`.
if available.
.. method:: NNTP.xpath(id)
Return a pair ``(resp, path)``, where *path* is the directory path to the
article with message ID *id*. Most of the time, this extension is not
enabled by NNTP server administrators.
.. deprecated:: 3.3
The XPATH extension is not actively used.
.. XXX deprecated:
.. method:: NNTP.xgtitle(name, *, file=None)
Process an ``XGTITLE`` command, returning a pair ``(response, list)``, where
*list* is a list of tuples containing ``(name, title)``. If the *file* parameter
is supplied, then the output of the ``XGTITLE`` command is stored in a file.
If *file* is a string, then the method will open a file with that name, write
to it then close it. If *file* is a :term:`file object`, then it will start
calling :meth:`write` on it to store the lines of the command output. If *file*
is supplied, then the returned *list* is an empty list. This is an optional NNTP
extension, and may not be supported by all servers.
:rfc:`2980` says "It is suggested that this extension be deprecated". Use
:meth:`descriptions` or :meth:`description` instead.
Utility functions
-----------------

126
Doc/library/os.rst
View File

@ -111,9 +111,9 @@ process and user.
to the environment made after this time are not reflected in ``os.environ``,
except for changes made by modifying ``os.environ`` directly.
If the platform supports the :func:`putenv` function, this mapping may be used
to modify the environment as well as query the environment. :func:`putenv` will
be called automatically when the mapping is modified.
This mapping may be used to modify the environment as well as query the
environment. :func:`putenv` will be called automatically when the mapping
is modified.
On Unix, keys and values use :func:`sys.getfilesystemencoding` and
``'surrogateescape'`` error handler. Use :data:`environb` if you would like
@ -130,14 +130,10 @@ process and user.
cause memory leaks. Refer to the system documentation for
:c:func:`putenv`.
If :func:`putenv` is not provided, a modified copy of this mapping may be
passed to the appropriate process-creation functions to cause child processes
to use a modified environment.
If the platform supports the :func:`unsetenv` function, you can delete items in
this mapping to unset environment variables. :func:`unsetenv` will be called
automatically when an item is deleted from ``os.environ``, and when
one of the :meth:`pop` or :meth:`clear` methods is called.
You can delete items in this mapping to unset environment variables.
:func:`unsetenv` will be called automatically when an item is deleted from
``os.environ``, and when one of the :meth:`pop` or :meth:`clear` methods is
called.
.. data:: environb
@ -439,17 +435,20 @@ process and user.
changes to the environment affect subprocesses started with :func:`os.system`,
:func:`popen` or :func:`fork` and :func:`execv`.
.. availability:: most flavors of Unix, Windows.
Assignments to items in ``os.environ`` are automatically translated into
corresponding calls to :func:`putenv`; however, calls to :func:`putenv`
don't update ``os.environ``, so it is actually preferable to assign to items
of ``os.environ``.
.. note::
On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
cause memory leaks. Refer to the system documentation for putenv.
cause memory leaks. Refer to the system documentation for :c:func:`putenv`.
When :func:`putenv` is supported, assignments to items in ``os.environ`` are
automatically translated into corresponding calls to :func:`putenv`; however,
calls to :func:`putenv` don't update ``os.environ``, so it is actually
preferable to assign to items of ``os.environ``.
.. audit-event:: os.putenv key,value os.putenv
.. versionchanged:: 3.9
The function is now always available.
.. function:: setegid(egid)
@ -638,12 +637,15 @@ process and user.
environment affect subprocesses started with :func:`os.system`, :func:`popen` or
:func:`fork` and :func:`execv`.
When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
automatically translated into a corresponding call to :func:`unsetenv`; however,
calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
preferable to delete items of ``os.environ``.
Deletion of items in ``os.environ`` is automatically translated into a
corresponding call to :func:`unsetenv`; however, calls to :func:`unsetenv`
don't update ``os.environ``, so it is actually preferable to delete items of
``os.environ``.
.. availability:: most flavors of Unix, Windows.
.. audit-event:: os.unsetenv key os.unsetenv
.. versionchanged:: 3.9
The function is now always available and is also available on Windows.
.. _os-newstreams:
@ -768,6 +770,8 @@ as internal buffering of data.
docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this
is equivalent to ``os.chmod(fd, mode)``.
.. audit-event:: os.chmod path,mode,dir_fd os.fchmod
.. availability:: Unix.
@ -778,6 +782,8 @@ as internal buffering of data.
:func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
gid)``.
.. audit-event:: os.chown path,uid,gid,dir_fd os.fchown
.. availability:: Unix.
@ -885,6 +891,8 @@ as internal buffering of data.
:data:`F_ULOCK` or :data:`F_TEST`.
*len* specifies the section of the file to lock.
.. audit-event:: os.lockf fd,cmd,len os.lockf
.. availability:: Unix.
.. versionadded:: 3.3
@ -1605,6 +1613,8 @@ features:
This function can raise :exc:`OSError` and subclasses such as
:exc:`FileNotFoundError`, :exc:`PermissionError`, and :exc:`NotADirectoryError`.
.. audit-event:: os.chdir path os.chdir
.. versionadded:: 3.3
Added support for specifying *path* as a file descriptor
on some platforms.
@ -1633,6 +1643,8 @@ features:
This function can support :ref:`not following symlinks <follow_symlinks>`.
.. audit-event:: os.chflags path,flags os.chflags
.. availability:: Unix.
.. versionadded:: 3.3
@ -1678,6 +1690,8 @@ features:
read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
constants or a corresponding integer value). All other bits are ignored.
.. audit-event:: os.chmod path,mode,dir_fd os.chmod
.. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor,
and the *dir_fd* and *follow_symlinks* arguments.
@ -1698,6 +1712,8 @@ features:
See :func:`shutil.chown` for a higher-level function that accepts names in
addition to numeric ids.
.. audit-event:: os.chown path,uid,gid,dir_fd os.chown
.. availability:: Unix.
.. versionadded:: 3.3
@ -1724,6 +1740,8 @@ features:
descriptor *fd*. The descriptor must refer to an opened directory, not an
open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
.. audit-event:: os.chdir path os.fchdir
.. availability:: Unix.
@ -1748,6 +1766,8 @@ features:
not follow symbolic links. As of Python 3.3, this is equivalent to
``os.chflags(path, flags, follow_symlinks=False)``.
.. audit-event:: os.chflags path,flags os.lchflags
.. availability:: Unix.
.. versionchanged:: 3.6
@ -1761,6 +1781,8 @@ features:
for possible values of *mode*. As of Python 3.3, this is equivalent to
``os.chmod(path, mode, follow_symlinks=False)``.
.. audit-event:: os.chmod path,mode,dir_fd os.lchmod
.. availability:: Unix.
.. versionchanged:: 3.6
@ -1772,6 +1794,8 @@ features:
function will not follow symbolic links. As of Python 3.3, this is equivalent
to ``os.chown(path, uid, gid, follow_symlinks=False)``.
.. audit-event:: os.chown path,uid,gid,dir_fd os.lchown
.. availability:: Unix.
.. versionchanged:: 3.6
@ -1786,6 +1810,8 @@ features:
supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
following symlinks <follow_symlinks>`.
.. audit-event:: os.link src,dst,src_dir_fd,dst_dir_fd os.link
.. availability:: Unix, Windows.
.. versionchanged:: 3.2
@ -1888,6 +1914,8 @@ features:
It is also possible to create temporary directories; see the
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
.. audit-event:: os.mkdir path,mode,dir_fd os.mkdir
.. versionadded:: 3.3
The *dir_fd* argument.
@ -1920,6 +1948,8 @@ features:
This function handles UNC paths correctly.
.. audit-event:: os.mkdir path,mode,dir_fd os.makedirs
.. versionadded:: 3.2
The *exist_ok* parameter.
@ -2085,6 +2115,8 @@ features:
This function is semantically identical to :func:`unlink`.
.. audit-event:: os.remove path,dir_fd os.remove
.. versionadded:: 3.3
The *dir_fd* argument.
@ -2105,6 +2137,8 @@ features:
they are empty. Raises :exc:`OSError` if the leaf directory could not be
successfully removed.
.. audit-event:: os.remove path,dir_fd os.removedirs
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@ -2130,6 +2164,8 @@ features:
If you want cross-platform overwriting of the destination, use :func:`replace`.
.. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.rename
.. versionadded:: 3.3
The *src_dir_fd* and *dst_dir_fd* arguments.
@ -2149,6 +2185,8 @@ features:
This function can fail with the new directory structure made if you lack
permissions needed to remove the leaf directory or file.
.. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.renames
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *old* and *new*.
@ -2164,6 +2202,8 @@ features:
This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
supply :ref:`paths relative to directory descriptors <dir_fd>`.
.. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.replace
.. versionadded:: 3.3
.. versionchanged:: 3.6
@ -2180,6 +2220,8 @@ features:
This function can support :ref:`paths relative to directory descriptors
<dir_fd>`.
.. audit-event:: os.rmdir path,dir_fd os.rmdir
.. versionadded:: 3.3
The *dir_fd* parameter.
@ -2823,6 +2865,8 @@ features:
:exc:`OSError` is raised when the function is called by an unprivileged
user.
.. audit-event:: os.symlink src,dst,dir_fd os.symlink
.. availability:: Unix, Windows.
.. versionchanged:: 3.2
@ -2875,6 +2919,8 @@ features:
traditional Unix name. Please see the documentation for
:func:`remove` for further information.
.. audit-event:: os.remove path,dir_fd os.unlink
.. versionadded:: 3.3
The *dir_fd* parameter.
@ -2912,6 +2958,8 @@ features:
:ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
following symlinks <follow_symlinks>`.
.. audit-event:: os.utime path,times,ns,dir_fd os.utime
.. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor,
and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
@ -3137,6 +3185,8 @@ These functions are all available on Linux only.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. audit-event:: os.getxattr path,attribute os.getxattr
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@ -3151,6 +3201,8 @@ These functions are all available on Linux only.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. audit-event:: os.listxattr path os.listxattr
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@ -3165,6 +3217,8 @@ These functions are all available on Linux only.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. audit-event:: os.removexattr path,attribute os.removexattr
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@ -3188,6 +3242,8 @@ These functions are all available on Linux only.
A bug in Linux kernel versions less than 2.6.39 caused the flags argument
to be ignored on some filesystems.
.. audit-event:: os.setxattr path,attribute,value,flags os.setxattr
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@ -3250,6 +3306,8 @@ to be ignored.
<https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5>`_
for more information about how DLLs are loaded.
.. audit-event:: os.add_dll_directory path os.add_dll_directory
.. availability:: Windows.
.. versionadded:: 3.8
@ -3316,6 +3374,8 @@ to be ignored.
you can check whether or not it is available using :data:`os.supports_fd`.
If it is unavailable, using it will raise a :exc:`NotImplementedError`.
.. audit-event:: os.exec path,args,env os.execl
.. availability:: Unix, Windows.
.. versionadded:: 3.3
@ -3480,6 +3540,8 @@ written in Python, such as a mail server's external command delivery program.
Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using ``fork()`` from a thread.
.. audit-event:: os.fork "" os.fork
.. versionchanged:: 3.8
Calling ``fork()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
@ -3499,6 +3561,8 @@ written in Python, such as a mail server's external command delivery program.
master end of the pseudo-terminal. For a more portable approach, use the
:mod:`pty` module. If an error occurs :exc:`OSError` is raised.
.. audit-event:: os.forkpty "" os.forkpty
.. versionchanged:: 3.8
Calling ``forkpty()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
@ -3525,6 +3589,8 @@ written in Python, such as a mail server's external command delivery program.
See also :func:`signal.pthread_kill`.
.. audit-event:: os.kill pid,sig os.kill
.. versionadded:: 3.2
Windows support.
@ -3537,6 +3603,8 @@ written in Python, such as a mail server's external command delivery program.
Send the signal *sig* to the process group *pgid*.
.. audit-event:: os.killpg pgid,sig os.killpg
.. availability:: Unix.
@ -3672,6 +3740,8 @@ written in Python, such as a mail server's external command delivery program.
:c:data:`POSIX_SPAWN_SETSCHEDPARAM` and :c:data:`POSIX_SPAWN_SETSCHEDULER`
flags.
.. audit-event:: os.posix_spawn path,argv,env os.posix_spawn
.. versionadded:: 3.8
.. availability:: Unix.
@ -3686,6 +3756,8 @@ written in Python, such as a mail server's external command delivery program.
for the *executable* file in the list of directories specified by the
:envvar:`PATH` environment variable (in the same way as for ``execvp(3)``).
.. audit-event:: os.posix_spawn path,argv,env os.posix_spawnp
.. versionadded:: 3.8
.. availability:: See :func:`posix_spawn` documentation.
@ -3786,6 +3858,8 @@ written in Python, such as a mail server's external command delivery program.
L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
.. audit-event:: os.spawn mode,path,args,env os.spawnl
.. availability:: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and
:func:`spawnve` are not thread-safe on Windows; we advise you to use the
@ -3855,6 +3929,8 @@ written in Python, such as a mail server's external command delivery program.
function is not resolved until this function is first called. If the function
cannot be resolved, :exc:`NotImplementedError` will be raised.
.. audit-event:: os.startfile path,operation os.startfile
.. availability:: Windows.
@ -3904,10 +3980,8 @@ written in Python, such as a mail server's external command delivery program.
See the Unix manual page
:manpage:`times(2)` and :manpage:`times(3)` manual page on Unix or `the GetProcessTimes MSDN
<https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes>`
_ on Windows.
On Windows, only :attr:`user` and :attr:`system` are known; the other
attributes are zero.
<https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes>`_
on Windows. On Windows, only :attr:`user` and :attr:`system` are known; the other attributes are zero.
.. availability:: Unix, Windows.

41
Doc/library/pkgutil.rst
View File

@ -227,3 +227,44 @@ support.
then ``None`` is returned. In particular, the :term:`loader` for
:term:`namespace packages <namespace package>` does not support
:meth:`get_data <importlib.abc.ResourceLoader.get_data>`.
.. function:: resolve_name(name)
Resolve a name to an object.
This functionality is used in numerous places in the standard library (see
:issue:`12915`) - and equivalent functionality is also in widely used
third-party packages such as setuptools, Django and Pyramid.
It is expected that *name* will be a string in one of the following
formats, where W is shorthand for a valid Python identifier and dot stands
for a literal period in these pseudo-regexes:
* ``W(.W)*``
* ``W(.W)*:(W(.W)*)?``
The first form is intended for backward compatibility only. It assumes that
some part of the dotted name is a package, and the rest is an object
somewhere within that package, possibly nested inside other objects.
Because the place where the package stops and the object hierarchy starts
can't be inferred by inspection, repeated attempts to import must be done
with this form.
In the second form, the caller makes the division point clear through the
provision of a single colon: the dotted name to the left of the colon is a
package to be imported, and the dotted name to the right is the object
hierarchy within that package. Only one import is needed in this form. If
it ends with the colon, then a module object is returned.
The function will return an object (which might be a module), or raise one
of the following exceptions:
:exc:`ValueError` -- if *name* isn't in a recognised format.
:exc:`ImportError` -- if an import failed when it shouldn't have.
:exc:`AttributeError` -- If a failure occurred when traversing the object
hierarchy within the imported package to get to the desired object.
.. versionadded:: 3.9

5
Doc/library/platform.rst
View File

@ -145,8 +145,8 @@ Cross Platform
.. function:: system()
Returns the system/OS name, e.g. ``'Linux'``, ``'Windows'``, or ``'Java'``. An
empty string is returned if the value cannot be determined.
Returns the system/OS name, such as ``'Linux'``, ``'Darwin'``, ``'Java'``,
``'Windows'``. An empty string is returned if the value cannot be determined.
.. function:: system_alias(system, release, version)
@ -260,4 +260,3 @@ Unix Platforms
using :program:`gcc`.
The file is read and scanned in chunks of *chunksize* bytes.

8
Doc/library/poplib.rst
View File

@ -47,6 +47,9 @@ The :mod:`poplib` module provides two classes:
``poplib.putline`` with arguments ``self`` and ``line``,
where ``line`` is the bytes about to be sent to the remote host.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket.
.. class:: POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)
@ -85,6 +88,10 @@ The :mod:`poplib` module provides two classes:
:func:`ssl.create_default_context` select the system's trusted CA
certificates for you.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket.
One exception is defined as an attribute of the :mod:`poplib` module:
@ -268,4 +275,3 @@ retrieves and prints all messages::
At the end of the module, there is a test section that contains a more extensive
example of usage.

11
Doc/library/profile.rst
View File

@ -525,6 +525,17 @@ Analysis of the profiler data is done using the :class:`~pstats.Stats` class.
ordering are identical to the :meth:`~pstats.Stats.print_callers` method.
.. method:: get_stats_profile()
This method returns an instance of StatsProfile, which contains a mapping
of function names to instances of FunctionProfile. Each FunctionProfile
instance holds information related to the function's profile such as how
long the function took to run, how many times it was called, etc...
.. versionadded:: 3.9
Added the following dataclasses: StatsProfile, FunctionProfile.
Added the following function: get_stats_profile.
.. _deterministic-profiling:
What Is Deterministic Profiling?

1
Doc/library/pty.rst
View File

@ -69,6 +69,7 @@ The :mod:`pty` module defines the following functions:
*select* throws an error on your platform when passed three empty lists. This
is a bug, documented in `issue 26228 <https://bugs.python.org/issue26228>`_.
.. audit-event:: pty.spawn argv pty.spawn
.. versionchanged:: 3.4
:func:`spawn` now returns the status value from :func:`os.waitpid`

2
Doc/library/py_compile.rst
View File

@ -27,7 +27,7 @@ byte-code cache files in the directory containing the source code.
Exception raised when an error occurs while attempting to compile the file.
.. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP)
.. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)
Compile a source file to byte-code and write out the byte-code cache file.
The source code is loaded from the file named *file*. The byte-code is

4
Doc/library/random.rst
View File

@ -343,8 +343,8 @@ Alternative Generator
Notes on Reproducibility
------------------------
Sometimes it is useful to be able to reproduce the sequences given by a pseudo
random number generator. By re-using a seed value, the same sequence should be
Sometimes it is useful to be able to reproduce the sequences given by a
pseudo-random number generator. By re-using a seed value, the same sequence should be
reproducible from run to run as long as multiple threads are not running.
Most of the random module's algorithms and seeding functions are subject to

5
Doc/library/resource.rst
View File

@ -78,6 +78,9 @@ this module for those platforms.
VxWorks only supports setting :data:`RLIMIT_NOFILE`.
.. audit-event:: resource.setrlimit resource,limits resource.setrlimit
.. function:: prlimit(pid, resource[, limits])
Combines :func:`setrlimit` and :func:`getrlimit` in one function and
@ -94,6 +97,8 @@ this module for those platforms.
:exc:`PermissionError` when the user doesn't have ``CAP_SYS_RESOURCE`` for
the process.
.. audit-event:: resource.prlimit pid,resource,limits resource.prlimit
.. availability:: Linux 2.6.36 or later with glibc 2.13 or later.
.. versionadded:: 3.4

3
Doc/library/select.rst
View File

@ -355,6 +355,9 @@ Edge and Level Trigger Polling (epoll) Objects
Remove a registered file descriptor from the epoll object.
.. versionchanged:: 3.9
The method no longer ignores the :data:`~errno.EBADF` error.
.. method:: epoll.poll(timeout=None, maxevents=-1)

20
Doc/library/shutil.rst
View File

@ -67,6 +67,8 @@ Directory and files operations
a new symbolic link will be created instead of copying the
file *src* points to.
.. audit-event:: shutil.copyfile src,dst shutil.copyfile
.. versionchanged:: 3.3
:exc:`IOError` used to be raised instead of :exc:`OSError`.
Added *follow_symlinks* argument.
@ -101,6 +103,8 @@ Directory and files operations
:func:`copymode` cannot modify symbolic links on the local platform, and it
is asked to do so, it will do nothing and return.
.. audit-event:: shutil.copymode src,dst shutil.copymode
.. versionchanged:: 3.3
Added *follow_symlinks* argument.
@ -146,6 +150,8 @@ Directory and files operations
Please see :data:`os.supports_follow_symlinks`
for more information.
.. audit-event:: shutil.copystat src,dst shutil.copystat
.. versionchanged:: 3.3
Added *follow_symlinks* argument and support for Linux extended attributes.
@ -167,6 +173,10 @@ Directory and files operations
To preserve all file metadata from the original, use
:func:`~shutil.copy2` instead.
.. audit-event:: shutil.copyfile src,dst shutil.copy
.. audit-event:: shutil.copymode src,dst shutil.copy
.. versionchanged:: 3.3
Added *follow_symlinks* argument.
Now returns path to the newly created file.
@ -194,6 +204,10 @@ Directory and files operations
Please see :func:`copystat` for more information
about platform support for modifying symbolic link metadata.
.. audit-event:: shutil.copyfile src,dst shutil.copy2
.. audit-event:: shutil.copystat src,dst shutil.copy2
.. versionchanged:: 3.3
Added *follow_symlinks* argument, try to copy extended
file system attributes too (currently Linux only).
@ -342,6 +356,8 @@ Directory and files operations
*copy_function* allows the move to succeed when it is not possible to also
copy the metadata, at the expense of not copying any of the metadata.
.. audit-event:: shutil.move src,dst shutil.move
.. versionchanged:: 3.3
Added explicit symlink handling for foreign filesystems, thus adapting
it to the behavior of GNU's :program:`mv`.
@ -381,6 +397,8 @@ Directory and files operations
See also :func:`os.chown`, the underlying function.
.. audit-event:: shutil.chown path,user,group shutil.chown
.. availability:: Unix.
.. versionadded:: 3.3
@ -632,6 +650,8 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
registered for that extension. In case none is found,
a :exc:`ValueError` is raised.
.. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive
.. versionchanged:: 3.7
Accepts a :term:`path-like object` for *filename* and *extract_dir*.

2
Doc/library/signal.rst
View File

@ -277,6 +277,8 @@ The :mod:`signal` module defines the following functions:
If *signalnum* is 0, then no signal is sent, but error checking is still
performed; this can be used to check if the target thread is still running.
.. audit-event:: signal.pthread_kill thread_id,signalnum signal.pthread_kill
.. availability:: Unix. See the man page :manpage:`pthread_kill(3)` for further
information.

9
Doc/library/site.rst
View File

@ -236,6 +236,13 @@ Module contents
.. versionadded:: 3.2
.. _site-commandline:
Command Line Interface
----------------------
.. program:: site
The :mod:`site` module also provides a way to get the user directories from the
command line:
@ -244,8 +251,6 @@ command line:
$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages
.. program:: site
If it is called without arguments, it will print the contents of
:data:`sys.path` on the standard output, followed by the value of
:data:`USER_BASE` and whether the directory exists, then the same thing for

12
Doc/library/smtplib.rst
View File

@ -70,6 +70,9 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
.. versionadded:: 3.5
The SMTPUTF8 extension (:rfc:`6531`) is now supported.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket
.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, \
certfile=None [, timeout], context=None, \
@ -108,8 +111,12 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
:func:`ssl.create_default_context` select the system's trusted CA
certificates for you.
.. versionchanged:: 3.9
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket
.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None)
.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None,
source_address=None[, timeout])
The LMTP protocol, which is very similar to ESMTP, is heavily based on the
standard SMTP client. It's common to use Unix sockets for LMTP, so our
@ -122,6 +129,9 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
Unix socket, LMTP generally don't support or require any authentication, but
your mileage might vary.
.. versionchanged:: 3.9
The optional *timeout* parameter was added.
A nice selection of exceptions is defined as well:

4
Doc/library/socket.rst
View File

@ -565,7 +565,9 @@ The following functions all create :ref:`socket objects <socket-objects>`.
When :const:`SOCK_NONBLOCK` or :const:`SOCK_CLOEXEC`
bit flags are applied to *type* they are cleared, and
:attr:`socket.type` will not reflect them. They are still passed
to the underlying system `socket()` call. Therefore::
to the underlying system `socket()` call. Therefore,
::
sock = socket.socket(
socket.AF_INET,

44
Doc/library/statistics.rst
View File

@ -734,10 +734,10 @@ of applications in statistics.
:class:`NormalDist` readily solves classic probability problems.
For example, given `historical data for SAT exams
<https://blog.prepscholar.com/sat-standard-deviation>`_ showing that scores
are normally distributed with a mean of 1060 and a standard deviation of 192,
determine the percentage of students with test scores between 1100 and
1200, after rounding to the nearest whole number:
<https://nces.ed.gov/programs/digest/d17/tables/dt17_226.40.asp>`_ showing
that scores are normally distributed with a mean of 1060 and a standard
deviation of 195, determine the percentage of students with test scores
between 1100 and 1200, after rounding to the nearest whole number:
.. doctest::
@ -772,6 +772,42 @@ Carlo simulation <https://en.wikipedia.org/wiki/Monte_Carlo_method>`_:
>>> quantiles(map(model, X, Y, Z)) # doctest: +SKIP
[1.4591308524824727, 1.8035946855390597, 2.175091447274739]
Normal distributions can be used to approximate `Binomial
distributions <http://mathworld.wolfram.com/BinomialDistribution.html>`_
when the sample size is large and when the probability of a successful
trial is near 50%.
For example, an open source conference has 750 attendees and two rooms with a
500 person capacity. There is a talk about Python and another about Ruby.
In previous conferences, 65% of the attendees preferred to listen to Python
talks. Assuming the population preferences haven't changed, what is the
probability that the Python room will stay within its capacity limits?
.. doctest::
>>> n = 750 # Sample size
>>> p = 0.65 # Preference for Python
>>> q = 1.0 - p # Preference for Ruby
>>> k = 500 # Room capacity
>>> # Approximation using the cumulative normal distribution
>>> from math import sqrt
>>> round(NormalDist(mu=n*p, sigma=sqrt(n*p*q)).cdf(k + 0.5), 4)
0.8402
>>> # Solution using the cumulative binomial distribution
>>> from math import comb, fsum
>>> round(fsum(comb(n, r) * p**r * q**(n-r) for r in range(k+1)), 4)
0.8402
>>> # Approximation using a simulation
>>> from random import seed, choices
>>> seed(8675309)
>>> def trial():
... return choices(('Python', 'Ruby'), (p, q), k=n).count('Python')
>>> mean(trial() <= k for i in range(10_000))
0.8398
Normal distributions commonly arise in machine learning problems.
Wikipedia has a `nice example of a Naive Bayesian Classifier

26
Doc/library/stdtypes.rst
View File

@ -1559,8 +1559,8 @@ expression support in the :mod:`re` module).
list of possible encodings, see section :ref:`standard-encodings`.
By default, the *errors* argument is not checked for best performances, but
only used at the first encoding error. Enable the development mode
(:option:`-X` ``dev`` option), or use a debug build, to check *errors*.
only used at the first encoding error. Enable the :ref:`Python Development
Mode <devmode>`, or use a debug build to check *errors*.
.. versionchanged:: 3.1
Support for keyword arguments added.
@ -2416,7 +2416,7 @@ data and are closely related to string objects in a variety of other ways.
A reverse conversion function exists to transform a bytes object into its
hexadecimal representation.
.. method:: hex()
.. method:: hex([sep[, bytes_per_sep]])
Return a string object containing two hexadecimal digits for each
byte in the instance.
@ -2510,7 +2510,7 @@ objects.
A reverse conversion function exists to transform a bytearray object into its
hexadecimal representation.
.. method:: hex()
.. method:: hex([sep[, bytes_per_sep]])
Return a string object containing two hexadecimal digits for each
byte in the instance.
@ -2520,6 +2520,11 @@ objects.
.. versionadded:: 3.5
.. versionchanged:: 3.8
Similar to :meth:`bytes.hex`, :meth:`bytearray.hex` now supports
optional *sep* and *bytes_per_sep* parameters to insert separators
between bytes in the hex output.
Since bytearray objects are sequences of integers (akin to a list), for a
bytearray object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be
a bytearray object of length 1. (This contrasts with text strings, where
@ -2596,8 +2601,8 @@ arbitrary binary data.
list of possible encodings, see section :ref:`standard-encodings`.
By default, the *errors* argument is not checked for best performances, but
only used at the first decoding error. Enable the development mode
(:option:`-X` ``dev`` option), or use a debug build, to check *errors*.
only used at the first decoding error. Enable the :ref:`Python Development
Mode <devmode>`, or use a debug build to check *errors*.
.. note::
@ -3673,7 +3678,7 @@ copying.
in-memory Fortran order is preserved. For non-contiguous views, the
data is converted to C first. *order=None* is the same as *order='C'*.
.. method:: hex()
.. method:: hex([sep[, bytes_per_sep]])
Return a string object containing two hexadecimal digits for each
byte in the buffer. ::
@ -3684,6 +3689,11 @@ copying.
.. versionadded:: 3.5
.. versionchanged:: 3.8
Similar to :meth:`bytes.hex`, :meth:`memoryview.hex` now supports
optional *sep* and *bytes_per_sep* parameters to insert separators
between bytes in the hex output.
.. method:: tolist()
Return the data in the buffer as a list of elements. ::
@ -4351,6 +4361,8 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
Return a reverse iterator over the keys of the dictionary. This is a
shortcut for ``reversed(d.keys())``.
.. versionadded:: 3.8
.. method:: setdefault(key[, default])
If *key* is in the dictionary, return its value. If not, insert *key*

4
Doc/library/struct.rst
View File

@ -259,7 +259,7 @@ Notes:
called to convert the argument to an integer before packing.
.. versionchanged:: 3.2
Use of the :meth:`__index__` method for non-integers is new in 3.2.
Added use of the :meth:`__index__` method for non-integers.
(3)
The ``'n'`` and ``'N'`` conversion codes are only available for the native
@ -312,7 +312,7 @@ When packing a value ``x`` using one of the integer formats (``'b'``,
then :exc:`struct.error` is raised.
.. versionchanged:: 3.1
In 3.0, some of the integer formats wrapped out-of-range values and
Previously, some of the integer formats wrapped out-of-range values and
raised :exc:`DeprecationWarning` instead of :exc:`struct.error`.
The ``'p'`` format character encodes a "Pascal string", meaning a short

12
Doc/library/subprocess.rst
View File

@ -356,14 +356,20 @@ functions.
arguments for additional differences from the default behavior. Unless
otherwise stated, it is recommended to pass *args* as a sequence.
An example of passing some arguments to an external program
as a sequence is::
Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])
On POSIX, if *args* is a string, the string is interpreted as the name or
path of the program to execute. However, this can only be done if not
passing arguments to the program.
.. note::
:meth:`shlex.split` can be useful when determining the correct
tokenization for *args*, especially in complex cases::
It may not be obvious how to break a shell command into a sequence of arguments,
especially in complex cases. :meth:`shlex.split` can illustrate how to
determine the correct tokenization for *args*::
>>> import shlex, subprocess
>>> command_line = input()
@ -774,6 +780,8 @@ Instances of the :class:`Popen` class have the following methods:
Sends the signal *signal* to the child.
Do nothing if the process completed.
.. note::
On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and

51
Doc/library/sys.rst
View File

@ -343,6 +343,8 @@ always available.
.. versionadded:: 3.7
__breakpointhook__
.. versionadded:: 3.8
__unraisablehook__
.. function:: exc_info()
@ -428,9 +430,9 @@ always available.
The :term:`named tuple` *flags* exposes the status of command line
flags. The attributes are read only.
============================= =============================
============================= ================================================================
attribute flag
============================= =============================
============================= ================================================================
:const:`debug` :option:`-d`
:const:`inspect` :option:`-i`
:const:`interactive` :option:`-i`
@ -444,9 +446,9 @@ always available.
:const:`bytes_warning` :option:`-b`
:const:`quiet` :option:`-q`
:const:`hash_randomization` :option:`-R`
:const:`dev_mode` :option:`-X` ``dev``
:const:`utf8_mode` :option:`-X` ``utf8``
============================= =============================
:const:`dev_mode` :option:`-X dev <-X>` (:ref:`Python Development Mode <devmode>`)
:const:`utf8_mode` :option:`-X utf8 <-X>`
============================= ================================================================
.. versionchanged:: 3.2
Added ``quiet`` attribute for the new :option:`-q` flag.
@ -461,8 +463,9 @@ always available.
Added ``isolated`` attribute for :option:`-I` ``isolated`` flag.
.. versionchanged:: 3.7
Added ``dev_mode`` attribute for the new :option:`-X` ``dev`` flag
and ``utf8_mode`` attribute for the new :option:`-X` ``utf8`` flag.
Added the ``dev_mode`` attribute for the new :ref:`Python Development
Mode <devmode>` and the ``utf8_mode`` attribute for the new :option:`-X`
``utf8`` flag.
.. data:: float_info
@ -479,8 +482,10 @@ always available.
+---------------------+----------------+--------------------------------------------------+
| attribute | float.h macro | explanation |
+=====================+================+==================================================+
| :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater |
| | | than 1 that is representable as a float |
| :const:`epsilon` | DBL_EPSILON | difference between 1.0 and the least value |
| | | greater than 1.0 that is representable as a float|
| | | |
| | | See also :func:`math.ulp`. |
+---------------------+----------------+--------------------------------------------------+
| :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
| | | faithfully represented in a float; see below |
@ -488,20 +493,24 @@ always available.
| :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
| | | digits in the significand of a float |
+---------------------+----------------+--------------------------------------------------+
| :const:`max` | DBL_MAX | maximum representable finite float |
| :const:`max` | DBL_MAX | maximum representable positive finite float |
+---------------------+----------------+--------------------------------------------------+
| :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
| :const:`max_exp` | DBL_MAX_EXP | maximum integer *e* such that ``radix**(e-1)`` is|
| | | a representable finite float |
+---------------------+----------------+--------------------------------------------------+
| :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
| :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer *e* such that ``10**e`` is in the|
| | | range of representable finite floats |
+---------------------+----------------+--------------------------------------------------+
| :const:`min` | DBL_MIN | minimum positive normalized float |
| :const:`min` | DBL_MIN | minimum representable positive *normalized* float|
| | | |
| | | Use :func:`math.ulp(0.0) <math.ulp>` to get the |
| | | smallest positive *denormalized* representable |
| | | float. |
+---------------------+----------------+--------------------------------------------------+
| :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
| :const:`min_exp` | DBL_MIN_EXP | minimum integer *e* such that ``radix**(e-1)`` is|
| | | a normalized float |
+---------------------+----------------+--------------------------------------------------+
| :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
| :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer *e* such that ``10**e`` is a |
| | | normalized float |
+---------------------+----------------+--------------------------------------------------+
| :const:`radix` | FLT_RADIX | radix of exponent representation |
@ -1446,9 +1455,15 @@ always available.
for the Windows console, this only applies when
:envvar:`PYTHONLEGACYWINDOWSSTDIO` is also set.
* When interactive, ``stdout`` and ``stderr`` streams are line-buffered.
Otherwise, they are block-buffered like regular text files. You can
override this value with the :option:`-u` command-line option.
* When interactive, the ``stdout`` stream is line-buffered. Otherwise,
it is block-buffered like regular text files. The ``stderr`` stream
is line-buffered in both cases. You can make both streams unbuffered
by passing the :option:`-u` command-line option or setting the
:envvar:`PYTHONUNBUFFERED` environment variable.
.. versionchanged:: 3.9
Non-interactive ``stderr`` is now line-buffered instead of fully
buffered.
.. note::

8
Doc/library/syslog.rst
View File

@ -31,6 +31,8 @@ The module defines the following functions:
If :func:`openlog` has not been called prior to the call to :func:`syslog`,
``openlog()`` will be called with no arguments.
.. audit-event:: syslog.syslog priority,message syslog.syslog
.. function:: openlog([ident[, logoption[, facility]]])
@ -45,6 +47,8 @@ The module defines the following functions:
keyword argument (default is :const:`LOG_USER`) sets the default facility for
messages which do not have a facility explicitly encoded.
.. audit-event:: syslog.openlog ident,logoption,facility syslog.openlog
.. versionchanged:: 3.2
In previous versions, keyword arguments were not allowed, and *ident* was
required. The default for *ident* was dependent on the system libraries,
@ -60,6 +64,8 @@ The module defines the following functions:
:func:`openlog` hasn't already been called), and *ident* and other
:func:`openlog` parameters are reset to defaults.
.. audit-event:: syslog.closelog "" syslog.closelog
.. function:: setlogmask(maskpri)
@ -70,6 +76,8 @@ The module defines the following functions:
``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
*pri*.
.. audit-event:: syslog.setlogmask maskpri syslog.setlogmask
The module defines the following constants:
Priority levels (high to low):

5
Doc/library/tarfile.rst
View File

@ -159,7 +159,10 @@ Some facts and figures:
.. function:: is_tarfile(name)
Return :const:`True` if *name* is a tar archive file, that the :mod:`tarfile`
module can read.
module can read. *name* may be a :class:`str`, file, or file-like object.
.. versionchanged:: 3.9
Support for file and file-like objects.
The :mod:`tarfile` module defines the following exceptions:

2
Doc/library/test.rst
View File

@ -1577,7 +1577,7 @@ script execution tests.
The :mod:`test.support.bytecode_helper` module provides support for testing
and inspecting bytecode generation.
The module defines the follwing class:
The module defines the following class:
.. class:: BytecodeTestCase(unittest.TestCase)

1
Doc/library/threading.rst
View File

@ -497,6 +497,7 @@ All methods are executed atomically.
There is no return value.
.. method:: locked()
Return true if the lock is acquired.

1
Doc/library/time.rst
View File

@ -218,7 +218,6 @@ Functions
Supported clock names and the corresponding functions to read their value
are:
* ``'clock'``: :func:`time.clock`
* ``'monotonic'``: :func:`time.monotonic`
* ``'perf_counter'``: :func:`time.perf_counter`
* ``'process_time'``: :func:`time.process_time`

19
Doc/library/tokenize.rst
View File

@ -278,3 +278,22 @@ The exact token type names can be displayed using the :option:`-e` option:
4,10-4,11: RPAR ')'
4,11-4,12: NEWLINE '\n'
5,0-5,0: ENDMARKER ''
Example of tokenizing a file programmatically, reading unicode
strings instead of bytes with :func:`generate_tokens`::
import tokenize
with tokenize.open('hello.py') as f:
tokens = tokenize.generate_tokens(f.readline)
for token in tokens:
print(token)
Or reading bytes directly with :func:`.tokenize`::
import tokenize
with open('hello.py', 'rb') as f:
tokens = tokenize.tokenize(f.readline)
for token in tokens:
print(token)

5
Doc/library/turtle.rst
View File

@ -1051,6 +1051,11 @@ Filling
Fill the shape drawn after the last call to :func:`begin_fill`.
Whether or not overlap regions for self-intersecting polygons
or multiple shapes are filled depends on the operating system graphics,
type of overlap, and number of overlaps. For example, the Turtle star
above may be either all yellow or have some white regions.
.. doctest::
:skipif: _tkinter is None

8
Doc/library/types.rst
View File

@ -132,7 +132,7 @@ Standard names are defined for the following types:
.. versionadded:: 3.6
.. data:: CodeType
.. class:: CodeType(**kwargs)
.. index:: builtin: compile
@ -143,6 +143,12 @@ Standard names are defined for the following types:
Note that the audited arguments may not match the names or positions
required by the initializer.
.. method:: CodeType.replace(**kwargs)
Return a copy of the code object with new values for the specified fields.
.. versionadded:: 3.8
.. data:: CellType
The type for cell objects: such objects are used as containers for

102
Doc/library/typing.rst
View File

@ -1028,7 +1028,7 @@ The module defines the following classes, functions and decorators:
runtime we intentionally don't check anything (we want this
to be as fast as possible).
.. function:: get_type_hints(obj[, globals[, locals]])
.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False)
Return a dictionary containing type hints for a function, method, module
or class object.
@ -1041,6 +1041,22 @@ The module defines the following classes, functions and decorators:
a dictionary constructed by merging all the ``__annotations__`` along
``C.__mro__`` in reverse order.
The function recursively replaces all ``Annotated[T, ...]`` with ``T``,
unless ``include_extras`` is set to ``True`` (see :class:`Annotated` for
more information). For example::
class Student(NamedTuple):
name: Annotated[str, 'some marker']
get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
'name': Annotated[str, 'some marker']
}
.. versionchanged:: 3.9
Added ``include_extras`` parameter as part of :pep:`593`.
.. function:: get_origin(tp)
.. function:: get_args(tp)
@ -1372,3 +1388,87 @@ The module defines the following classes, functions and decorators:
evaluated, so the second annotation does not need to be enclosed in quotes.
.. versionadded:: 3.5.2
.. data:: Annotated
A type, introduced in :pep:`593` (``Flexible function and variable
annotations``), to decorate existing types with context-specific metadata
(possibly multiple pieces of it, as ``Annotated`` is variadic).
Specifically, a type ``T`` can be annotated with metadata ``x`` via the
typehint ``Annotated[T, x]``. This metadata can be used for either static
analysis or at runtime. If a library (or tool) encounters a typehint
``Annotated[T, x]`` and has no special logic for metadata ``x``, it
should ignore it and simply treat the type as ``T``. Unlike the
``no_type_check`` functionality that currently exists in the ``typing``
module which completely disables typechecking annotations on a function
or a class, the ``Annotated`` type allows for both static typechecking
of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``)
together with runtime access to ``x`` within a specific application.
Ultimately, the responsibility of how to interpret the annotations (if
at all) is the responsibility of the tool or library encountering the
``Annotated`` type. A tool or library encountering an ``Annotated`` type
can scan through the annotations to determine if they are of interest
(e.g., using ``isinstance()``).
When a tool or a library does not support annotations or encounters an
unknown annotation it should just ignore it and treat annotated type as
the underlying type.
It's up to the tool consuming the annotations to decide whether the
client is allowed to have several annotations on one type and how to
merge those annotations.
Since the ``Annotated`` type allows you to put several annotations of
the same (or different) type(s) on any node, the tools or libraries
consuming those annotations are in charge of dealing with potential
duplicates. For example, if you are doing value range analysis you might
allow this::
T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]
Passing ``include_extras=True`` to :func:`get_type_hints` lets one
access the extra annotations at runtime.
The details of the syntax:
* The first argument to ``Annotated`` must be a valid type
* Multiple type annotations are supported (``Annotated`` supports variadic
arguments)::
Annotated[int, ValueRange(3, 10), ctype("char")]
* ``Annotated`` must be called with at least two arguments (
``Annotated[int]`` is not valid)
* The order of the annotations is preserved and matters for equality
checks::
Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
int, ctype("char"), ValueRange(3, 10)
]
* Nested ``Annotated`` types are flattened, with metadata ordered
starting with the innermost annotation::
Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
int, ValueRange(3, 10), ctype("char")
]
* Duplicated annotations are not removed::
Annotated[int, ValueRange(3, 10)] != Annotated[
int, ValueRange(3, 10), ValueRange(3, 10)
]
* ``Annotated`` can be used with nested and generic aliases::
T = TypeVar('T')
Vec = Annotated[List[Tuple[T, T]], MaxLen(10)]
V = Vec[int]
V == Annotated[List[Tuple[int, int]], MaxLen(10)]
.. versionadded:: 3.9

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

@ -854,7 +854,7 @@ object::
.. class:: AsyncMock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)
An asynchronous version of :class:`Mock`. The :class:`AsyncMock` object will
An asynchronous version of :class:`MagicMock`. The :class:`AsyncMock` object will
behave so the object is recognized as an async function, and the result of a
call is an awaitable.
@ -1327,8 +1327,7 @@ patch
.. note::
:func:`patch` is straightforward to use. The key is to do the patching in the
right namespace. See the section `where to patch`_.
The key is to do the patching in the right namespace. See the section `where to patch`_.
.. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)
@ -1401,7 +1400,8 @@ patch
"as"; very useful if :func:`patch` is creating a mock object for you.
:func:`patch` takes arbitrary keyword arguments. These will be passed to
the :class:`Mock` (or *new_callable*) on construction.
:class:`AsyncMock` if the patched object is asynchronous, to
:class:`MagicMock` otherwise or to *new_callable* if specified.
``patch.dict(...)``, ``patch.multiple(...)`` and ``patch.object(...)`` are
available for alternate use-cases.

53
Doc/library/urllib.parse.rst
View File

@ -42,8 +42,8 @@ or on combining URL components into a URL string.
Parse a URL into six components, returning a 6-item :term:`named tuple`. This
corresponds to the general structure of a URL:
``scheme://netloc/path;parameters?query#fragment``.
Each tuple item is a string, possibly empty. The components are not broken up in
smaller parts (for example, the network location is a single string), and %
Each tuple item is a string, possibly empty. The components are not broken up
into smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
result, except for a leading slash in the *path* component, which is retained if
present. For example:
@ -328,22 +328,22 @@ or on combining URL components into a URL string.
.. note::
If *url* is an absolute URL (that is, starting with ``//`` or ``scheme://``),
the *url*'s host name and/or scheme will be present in the result. For example:
If *url* is an absolute URL (that is, it starts with ``//`` or ``scheme://``),
the *url*'s hostname and/or scheme will be present in the result. For example:
.. doctest::
.. doctest::
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
... '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
... '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'
If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and
:func:`urlunsplit`, removing possible *scheme* and *netloc* parts.
If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and
:func:`urlunsplit`, removing possible *scheme* and *netloc* parts.
.. versionchanged:: 3.5
Behaviour updated to match the semantics defined in :rfc:`3986`.
Behavior updated to match the semantics defined in :rfc:`3986`.
.. function:: urldefrag(url)
@ -521,11 +521,11 @@ task isn't already covered by the URL parsing functions above.
Replace special characters in *string* using the ``%xx`` escape. Letters,
digits, and the characters ``'_.-~'`` are never quoted. By default, this
function is intended for quoting the path section of URL. The optional *safe*
parameter specifies additional ASCII characters that should not be quoted
--- its default value is ``'/'``.
function is intended for quoting the path section of a URL. The optional
*safe* parameter specifies additional ASCII characters that should not be
quoted --- its default value is ``'/'``.
*string* may be either a :class:`str` or a :class:`bytes`.
*string* may be either a :class:`str` or a :class:`bytes` object.
.. versionchanged:: 3.7
Moved from :rfc:`2396` to :rfc:`3986` for quoting URL strings. "~" is now
@ -547,7 +547,7 @@ task isn't already covered by the URL parsing functions above.
.. function:: quote_plus(string, safe='', encoding=None, errors=None)
Like :func:`quote`, but also replace spaces by plus signs, as required for
Like :func:`quote`, but also replace spaces with plus signs, as required for
quoting HTML form values when building up a query string to go into a URL.
Plus signs in the original string are escaped unless they are included in
*safe*. It also does not have *safe* default to ``'/'``.
@ -566,12 +566,12 @@ task isn't already covered by the URL parsing functions above.
.. function:: unquote(string, encoding='utf-8', errors='replace')
Replace ``%xx`` escapes by their single-character equivalent.
Replace ``%xx`` escapes with their single-character equivalent.
The optional *encoding* and *errors* parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
:meth:`bytes.decode` method.
*string* may be either a :class:`str` or a :class:`bytes`.
*string* may be either a :class:`str` or a :class:`bytes` object.
*encoding* defaults to ``'utf-8'``.
*errors* defaults to ``'replace'``, meaning invalid sequences are replaced
@ -587,8 +587,8 @@ task isn't already covered by the URL parsing functions above.
.. function:: unquote_plus(string, encoding='utf-8', errors='replace')
Like :func:`unquote`, but also replace plus signs by spaces, as required for
unquoting HTML form values.
Like :func:`unquote`, but also replace plus signs with spaces, as required
for unquoting HTML form values.
*string* must be a :class:`str`.
@ -597,10 +597,10 @@ task isn't already covered by the URL parsing functions above.
.. function:: unquote_to_bytes(string)
Replace ``%xx`` escapes by their single-octet equivalent, and return a
Replace ``%xx`` escapes with their single-octet equivalent, and return a
:class:`bytes` object.
*string* may be either a :class:`str` or a :class:`bytes`.
*string* may be either a :class:`str` or a :class:`bytes` object.
If it is a :class:`str`, unescaped non-ASCII characters in *string*
are encoded into UTF-8 bytes.
@ -631,7 +631,7 @@ task isn't already covered by the URL parsing functions above.
When a sequence of two-element tuples is used as the *query*
argument, the first element of each tuple is a key and the second is a
value. The value element in itself can be a sequence and in that case, if
the optional parameter *doseq* is evaluates to ``True``, individual
the optional parameter *doseq* evaluates to ``True``, individual
``key=value`` pairs separated by ``'&'`` are generated for each element of
the value sequence for the key. The order of parameters in the encoded
string will match the order of parameter tuples in the sequence.
@ -643,11 +643,12 @@ task isn't already covered by the URL parsing functions above.
To reverse this encoding process, :func:`parse_qs` and :func:`parse_qsl` are
provided in this module to parse query strings into Python data structures.
Refer to :ref:`urllib examples <urllib-examples>` to find out how urlencode
method can be used for generating query string for a URL or data for POST.
Refer to :ref:`urllib examples <urllib-examples>` to find out how the
:func:`urllib.parse.urlencode` method can be used for generating the query
string of a URL or data for a POST request.
.. versionchanged:: 3.2
Query parameter supports bytes and string objects.
*query* supports bytes and string objects.
.. versionadded:: 3.5
*quote_via* parameter.

Some files were not shown because too many files have changed in this diff Show More