Skip to content

Commit b75b1aa

Browse files
markshannonmarkshannon
committed
Merge branch 'main' into specialize-calls-to-normal-python-classes
2 parents 1ee2f1c + cdb73ae commit b75b1aa

187 files changed

Lines changed: 2888 additions & 968 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
highlight_language = 'python3'
4646

4747
# Minimum version of sphinx required
48-
needs_sphinx = '1.8'
48+
needs_sphinx = '3.2'
4949

5050
# Ignore any .rst files in the venv/ directory.
5151
exclude_patterns = ['venv/*', 'README.rst']

‎Doc/faq/design.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -324,8 +324,7 @@ Can Python be compiled to machine code, C or some other language?
324324
`Cython <http://cython.org/>`_ compiles a modified version of Python with
325325
optional annotations into C extensions. `Nuitka <http://www.nuitka.net/>`_ is
326326
an up-and-coming compiler of Python into C++ code, aiming to support the full
327-
Python language. For compiling to Java you can consider
328-
`VOC <https://voc.readthedocs.io>`_.
327+
Python language.
329328

330329

331330
How does Python manage memory?

‎Doc/howto/logging-cookbook.rst‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ Logging Cookbook
77
:Author: Vinay Sajip <vinay_sajip at red-dove dot com>
88

99
This page contains a number of recipes related to logging, which have been found
10-
useful in the past.
10+
useful in the past. For links to tutorial and reference information, please see
11+
:ref:`cookbook-ref-links`.
1112

1213
.. currentmodule:: logging
1314

@@ -3075,3 +3076,23 @@ the :ref:`existing mechanisms <context-info>` for passing contextual
30753076
information into your logs and restrict the loggers created to those describing
30763077
areas within your application (generally modules, but occasionally slightly
30773078
more fine-grained than that).
3079+
3080+
.. _cookbook-ref-links:
3081+
3082+
Other resources
3083+
---------------
3084+
3085+
.. seealso::
3086+
3087+
Module :mod:`logging`
3088+
API reference for the logging module.
3089+
3090+
Module :mod:`logging.config`
3091+
Configuration API for the logging module.
3092+
3093+
Module :mod:`logging.handlers`
3094+
Useful handlers included with the logging module.
3095+
3096+
:ref:`Basic Tutorial <logging-basic-tutorial>`
3097+
3098+
:ref:`Advanced Tutorial <logging-advanced-tutorial>`

‎Doc/howto/logging.rst‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ Logging HOWTO
88

99
.. currentmodule:: logging
1010

11+
This page contains tutorial information. For links to reference information and a
12+
logging cookbook, please see :ref:`tutorial-ref-links`.
13+
1114
Basic Logging Tutorial
1215
----------------------
1316

@@ -336,7 +339,7 @@ favourite beverage and carry on.
336339
If your logging needs are simple, then use the above examples to incorporate
337340
logging into your own scripts, and if you run into problems or don't
338341
understand something, please post a question on the comp.lang.python Usenet
339-
group (available at https://groups.google.com/forum/#!forum/comp.lang.python) and you
342+
group (available at https://groups.google.com/g/comp.lang.python) and you
340343
should receive help before too long.
341344

342345
Still here? You can carry on reading the next few sections, which provide a
@@ -1109,6 +1112,11 @@ Also note that the core logging module only includes the basic handlers. If
11091112
you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
11101113
take up any memory.
11111114

1115+
.. _tutorial-ref-links:
1116+
1117+
Other resources
1118+
---------------
1119+
11121120
.. seealso::
11131121

11141122
Module :mod:`logging`

‎Doc/library/array.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Notes:
5252

5353
.. versionchanged:: 3.9
5454
``array('u')`` now uses ``wchar_t`` as C type instead of deprecated
55-
``Py_UNICODE``. This change doesn't affect to its behavior because
55+
``Py_UNICODE``. This change doesn't affect its behavior because
5656
``Py_UNICODE`` is alias of ``wchar_t`` since Python 3.3.
5757

5858
.. deprecated-removed:: 3.3 4.0

‎Doc/library/asyncio-sync.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@ BoundedSemaphore
345345
Barrier
346346
=======
347347

348-
.. class:: Barrier(parties, action=None)
348+
.. class:: Barrier(parties)
349349

350350
A barrier object. Not thread-safe.
351351

@@ -411,8 +411,8 @@ Barrier
411411
...
412412
async with barrier as position:
413413
if position == 0:
414-
# Only one task print this
415-
print('End of *draining phasis*')
414+
# Only one task prints this
415+
print('End of *draining phase*')
416416

417417
This method may raise a :class:`BrokenBarrierError` exception if the
418418
barrier is broken or reset while a task is waiting.
@@ -429,7 +429,7 @@ Barrier
429429

430430
Put the barrier into a broken state. This causes any active or future
431431
calls to :meth:`wait` to fail with the :class:`BrokenBarrierError`.
432-
Use this for example if one of the taks needs to abort, to avoid infinite
432+
Use this for example if one of the tasks needs to abort, to avoid infinite
433433
waiting tasks.
434434

435435
.. attribute:: parties

‎Doc/library/asyncio-task.rst‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,24 @@ Creating Tasks
226226
.. important::
227227

228228
Save a reference to the result of this function, to avoid
229-
a task disappearing mid execution.
229+
a task disappearing mid execution. The event loop only keeps
230+
weak references to tasks. A task that isn't referenced elsewhere
231+
may get garbage-collected at any time, even before it's done.
232+
For reliable "fire-and-forget" background tasks, gather them in
233+
a collection::
234+
235+
background_tasks = set()
236+
237+
for i in range(10):
238+
task = asyncio.create_task(some_coro(param=i))
239+
240+
# Add task to the set. This creates a strong reference.
241+
background_tasks.add(task)
242+
243+
# To prevent keeping references to finished tasks forever,
244+
# make each task remove its own reference from the set after
245+
# completion:
246+
task.add_done_callback(background_tasks.discard)
230247

231248
.. versionadded:: 3.7
232249

‎Doc/library/dis.rst‎

Lines changed: 29 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@
66

77
**Source code:** :source:`Lib/dis.py`
88

9+
.. testsetup::
10+
11+
import dis
12+
def myfunc(alist):
13+
return len(alist)
14+
915
--------------
1016

1117
The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
@@ -37,16 +43,17 @@ Example: Given the function :func:`myfunc`::
3743
return len(alist)
3844

3945
the following command can be used to display the disassembly of
40-
:func:`myfunc`::
46+
:func:`myfunc`:
4147

42-
>>> dis.dis(myfunc)
43-
1 0 RESUME 0
48+
.. doctest::
4449

45-
2 2 PUSH_NULL
46-
4 LOAD_GLOBAL 1 (NULL + len)
47-
6 LOAD_FAST 0 (alist)
48-
8 CALL 1
49-
18 RETURN_VALUE
50+
>>> dis.dis(myfunc)
51+
2 0 RESUME 0
52+
<BLANKLINE>
53+
3 2 LOAD_GLOBAL 1 (NULL + len)
54+
14 LOAD_FAST 0 (alist)
55+
16 CALL 1
56+
26 RETURN_VALUE
5057

5158
(The "2" is a line number).
5259

@@ -108,14 +115,15 @@ code.
108115
.. versionchanged:: 3.11
109116
Added the ``show_caches`` parameter.
110117

111-
Example::
118+
Example:
119+
120+
.. doctest::
112121

113122
>>> bytecode = dis.Bytecode(myfunc)
114123
>>> for instr in bytecode:
115124
... print(instr.opname)
116125
...
117126
RESUME
118-
PUSH_NULL
119127
LOAD_GLOBAL
120128
LOAD_FAST
121129
CALL
@@ -1034,6 +1042,17 @@ iterations of the loop.
10341042

10351043
Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
10361044

1045+
.. versionchanged:: 3.12
1046+
This opcode is now only used in situations where the local variable is
1047+
guaranteed to be initialized. It cannot raise :exc:`UnboundLocalError`.
1048+
1049+
.. opcode:: LOAD_FAST_CHECK (var_num)
1050+
1051+
Pushes a reference to the local ``co_varnames[var_num]`` onto the stack,
1052+
raising an :exc:`UnboundLocalError` if the local variable has not been
1053+
initialized.
1054+
1055+
.. versionadded:: 3.12
10371056

10381057
.. opcode:: STORE_FAST (var_num)
10391058

‎Doc/library/fcntl.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,12 @@ descriptor.
5050
constants, which allow to duplicate a file descriptor, the latter setting
5151
``FD_CLOEXEC`` flag in addition.
5252

53+
.. versionchanged:: 3.12
54+
On Linux >= 4.5, the :mod:`fcntl` module exposes the ``FICLONE`` and
55+
``FICLONERANGE`` constants, which allow to share some data of one file with
56+
another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and
57+
XFS). This behavior is commonly referred to as "copy-on-write".
58+
5359
The module defines the following functions:
5460

5561

‎Doc/library/logging.config.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -661,6 +661,76 @@ it with :func:`staticmethod`. For example::
661661
You don't need to wrap with :func:`staticmethod` if you're setting the import
662662
callable on a configurator *instance*.
663663

664+
.. _configure-queue:
665+
666+
Configuring QueueHandler and QueueListener
667+
""""""""""""""""""""""""""""""""""""""""""
668+
669+
If you want to configure a :class:`~logging.handlers.QueueHandler`, noting that this
670+
is normally used in conjunction with a :class:`~logging.handlers.QueueListener`, you
671+
can configure both together. After the configuration, the ``QueueListener`` instance
672+
will be available as the :attr:`~logging.handlers.QueueHandler.listener` attribute of
673+
the created handler, and that in turn will be available to you using
674+
:func:`~logging.getHandlerByName` and passing the name you have used for the
675+
``QueueHandler`` in your configuration. The dictionary schema for configuring the pair
676+
is shown in the example YAML snippet below.
677+
678+
.. code-block:: yaml
679+
680+
handlers:
681+
qhand:
682+
class: logging.handlers.QueueHandler
683+
queue: my.module.queue_factory
684+
listener: my.package.CustomListener
685+
handlers:
686+
- hand_name_1
687+
- hand_name_2
688+
...
689+
690+
The ``queue`` and ``listener`` keys are optional.
691+
692+
If the ``queue`` key is present, the corresponding value can be one of the following:
693+
694+
* An actual instance of :class:`queue.Queue` or a subclass thereof. This is of course
695+
only possible if you are constructing or modifying the configuration dictionary in
696+
code.
697+
698+
* A string that resolves to a callable which, when called with no arguments, returns
699+
the :class:`queue.Queue` instance to use. That callable could be a
700+
:class:`queue.Queue` subclass or a function which returns a suitable queue instance,
701+
such as ``my.module.queue_factory()``.
702+
703+
* A dict with a ``'()'`` key which is constructed in the usual way as discussed in
704+
:ref:`logging-config-dict-userdef`. The result of this construction should be a
705+
:class:`queue.Queue` instance.
706+
707+
If the ``queue`` key is absent, a standard unbounded :class:`queue.Queue` instance is
708+
created and used.
709+
710+
If the ``listener`` key is present, the corresponding value can be one of the following:
711+
712+
* A subclass of :class:`logging.handlers.QueueListener`. This is of course only
713+
possible if you are constructing or modifying the configuration dictionary in
714+
code.
715+
716+
* A string which resolves to a class which is a subclass of ``QueueListener``, such as
717+
``'my.package.CustomListener'``.
718+
719+
* A dict with a ``'()'`` key which is constructed in the usual way as discussed in
720+
:ref:`logging-config-dict-userdef`. The result of this construction should be a
721+
callable with the same signature as the ``QueueListener`` initializer.
722+
723+
If the ``listener`` key is absent, :class:`logging.handlers.QueueListener` is used.
724+
725+
The values under the ``handlers`` key are the names of other handlers in the
726+
configuration (not shown in the above snippet) which will be passed to the queue
727+
listener.
728+
729+
Any custom queue handler and listener classes will need to be defined with the same
730+
initialization signatures as :class:`~logging.handlers.QueueHandler` and
731+
:class:`~logging.handlers.QueueListener`.
732+
733+
.. versionadded:: 3.12
664734

665735
.. _logging-config-fileformat:
666736

0 commit comments

Comments
 (0)