8000 Merge branch 'main' into specialize-calls-to-normal-python-classes · python/cpython@b75b1aa · GitHub
[go: up one dir, main page]
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

File tree

187 files changed

+2888
-968
lines changed

Some content is hidden

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

187 files changed

+2888
-968
lines changed

‎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

‎Doc/library/logging.handlers.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1051,7 +1051,13 @@ possible, while any potentially slow operations (such as sending an email via
10511051
want to override this if you want to use blocking behaviour, or a
10521052
timeout, or a customized queue implementation.
10531053

1054+
.. attribute:: listener
10541055

1056+
When created via configuration using :func:`~logging.config.dictConfig`, this
1057+
attribute will contain a :class:`QueueListener` instance for use with this
1058+
handler. Otherwise, it will be ``None``.
1059+
1060+
.. versionadded:: 3.12
10551061

10561062
.. _queue-listener:
10571063

‎Doc/library/logging.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1164,6 +1164,19 @@ functions.
11641164
This undocumented behaviour was considered a mistake, and was removed in
11651165
Python 3.4, but reinstated in 3.4.2 due to retain backward compatibility.
11661166

1167+
.. function:: getHandlerByName(name)
1168+
1169+
Returns a handler with the specified *name*, or ``None`` if there is no handler
1170+
with that name.
1171+
1172+
.. versionadded:: 3.12
1173+
1174+
.. function:: getHandlerNames()
1175+
1176+
Returns an immutable set of all known handler names.
1177+
1178+
.. versionadded:: 3.12
1179+
11671180
.. function:: makeLogRecord(attrdict)
11681181

11691182
Creates and returns a new :class:`LogRecord` instance whose attributes are

‎Doc/library/mailcap.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,18 @@ standard. However, mailcap files are supported on most Unix systems.
6060
use) to determine whether or not the mailcap line applies. :func:`findmatch`
6161
will automatically check such conditions and skip the entry if the check fails.
6262

63+
.. versionchanged:: 3.11
64+
65+
To prevent security issues with shell metacharacters (symbols that have
66+
special effects in a shell command line), ``findmatch`` will refuse
67+
to inject ASCII characters other than alphanumerics and ``@+=:,./-_``
68+
into the returned command line.
69+
70+
If a disallowed character appears in *filename*, ``findmatch`` will always
71+
return ``(None, None)`` as if no entry was found.
72+
If such a character appears elsewhere (a value in *plist* or in *MIMEtype*),
73+
``findmatch`` will ignore all mailcap entries which use that value.
74+
A :mod:`warning <warnings>` will be raised in either case.
6375

6476
.. function:: getcaps()
6577

0 commit comments

Comments
 (0)
0