Skip to content

Commit ed1cfc2

Browse files
authored
Merge branch 'main' into textwrap-long-word
2 parents 19fd626 + c0f3fcf commit ed1cfc2

188 files changed

Lines changed: 6172 additions & 2948 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.

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,16 @@ body:
77
value: |
88
> [!NOTE]
99
> Trivial changes (for example typos) don’t require an issue before opening a PR.
10+
- type: input
11+
id: url
12+
attributes:
13+
label: "Documentation URL"
14+
description: "A link to the relevant documentation page, if applicable."
15+
placeholder: "https://docs.python.org/3/..."
1016
- type: textarea
1117
id: description
1218
attributes:
1319
label: "Documentation"
14-
description: "A clear and concise description of the issue. Include a link to the page."
20+
description: "A clear and concise description of the issue."
1521
validations:
1622
required: true

‎AGENTS.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,16 @@ When acting on this repository, apply the policy's core principles:
1414
- Follow existing coding style and patterns.
1515
- Write tests that exercise the change.
1616
- Keep backwards compatibility with prior releases in mind.
17+
18+
## Opening issues
19+
20+
Do not auto-generate issues with AI tools.
21+
22+
Search GitHub for duplicate issues before opening a new issue. Do not open
23+
duplicates.
24+
25+
```bash
26+
gh search issues --repo python/cpython "<symptom keywords>"
27+
gh search issues --repo python/cpython "<function, module or option name>"
28+
gh issue list --repo python/cpython --state all --label "<topic label>" --search "<short area keywords>"
29+
```

‎Doc/c-api/dict.rst‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -472,11 +472,14 @@ Dictionary objects
472472
473473
.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
474474
475-
This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
476-
``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
477-
back to the iterating over a sequence of key value pairs if the second
478-
argument has no "keys" attribute. Return ``0`` on success or ``-1`` if an
479-
exception was raised.
475+
This is the same as ``PyDict_Merge(a, b, 1)`` in C.
476+
477+
Similar to ``a.update(b)`` in Python, except that this function
478+
does not fall back to the iterating over a sequence of key-value pairs
479+
if *b* is not a mapping.
480+
Use :c:func:`PyDict_MergeFromSeq2` for this case.
481+
482+
Return ``0`` on success or ``-1`` if an exception was raised.
480483
481484
.. note::
482485
@@ -523,6 +526,8 @@ Dictionary objects
523526
as an argument, prefer :c:func:`PyFrozenDict_New` to leave the source
524527
intact.
525528
529+
Does not work for dicts with embedded values.
530+
526531
.. impl-detail::
527532
528533
Works with O(1) complexity.

‎Doc/data/refcounts.dat‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2417,6 +2417,9 @@ PyType_GenericNew:PyObject*:type:0:
24172417
PyType_GenericNew:PyObject*:args:0:
24182418
PyType_GenericNew:PyObject*:kwds:0:
24192419

2420+
PyType_GetDict:PyObject*::+1:
2421+
PyType_GetDict:PyTypeObject*:type:0:
2422+
24202423
PyType_GetFlags:unsigned long:::
24212424
PyType_GetFlags:PyTypeObject*:type:0:
24222425

‎Doc/howto/logging-cookbook.rst‎

Lines changed: 25 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -330,11 +330,10 @@ Suppose you configure logging with the following JSON:
330330
}
331331
}
332332
333-
This configuration does *almost* what we want, except that ``sys.stdout`` would show messages
334-
of severity ``ERROR`` and only events of this severity and higher will be tracked
335-
as well as ``INFO`` and ``WARNING`` messages. To prevent this, we can set up a filter which
336-
excludes those messages and add it to the relevant handler. This can be configured by
337-
adding a ``filters`` section parallel to ``formatters`` and ``handlers``:
333+
This configuration does *almost* what we want, except that ``sys.stdout`` would
334+
also show messages of severity ``ERROR`` and above. To exclude those messages,
335+
we can add a filter to the stdout handler. This can be configured by adding a
336+
``filters`` section parallel to ``formatters`` and ``handlers``:
338337

339338
.. code-block:: json
340339
@@ -562,9 +561,9 @@ One solution is to use a two-part approach. For the first part, attach only a
562561
:class:`QueueHandler` to those loggers which are accessed from
563562
performance-critical threads. They simply write to their queue, which can be
564563
sized to a large enough capacity or initialized with no upper bound to their
565-
size. The write to the queue will typically be accepted quickly, though you
566-
will probably need to catch the :exc:`queue.Full` exception as a precaution
567-
in your code. If you are a library developer who has performance-critical
564+
size. The write to the queue will typically be accepted quickly. If a bounded
565+
queue is full, :class:`QueueHandler` calls :meth:`~logging.Handler.handleError`
566+
with the record. If you are a library developer who has performance-critical
568567
threads in their code, be sure to document this (together with a suggestion to
569568
attach only ``QueueHandlers`` to your loggers) for the benefit of other
570569
developers who will use your code.
@@ -1608,8 +1607,8 @@ application:
16081607
16091608
The most current file is always :file:`logging_rotatingfile_example.out`,
16101609
and each time it reaches the size limit it is renamed with the suffix
1611-
``.1``. Each of the existing backup files is renamed to increment the suffix
1612-
(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased.
1610+
``.1``. Before this happens, the oldest backup (``.5``), if present, is
1611+
deleted and the remaining backups are renamed (``.4`` becomes ``.5``, etc.).
16131612

16141613
Obviously this example sets the log length much too small as an extreme
16151614
example. You would want to set *maxBytes* to an appropriate value.
@@ -1801,7 +1800,7 @@ Before Python 3.2, there were only two places where this creation was done:
18011800
* :func:`makeLogRecord`, which is called with a dictionary containing
18021801
attributes to be added to the LogRecord. This is typically invoked when a
18031802
suitable dictionary has been received over the network (e.g. in pickle form
1804-
via a :class:`~handlers.SocketHandler`, or in JSON form via an
1803+
via a :class:`~handlers.SocketHandler`, or as URL-encoded data via an
18051804
:class:`~handlers.HTTPHandler`).
18061805

18071806
This has usually meant that if you need to do anything special with a
@@ -1827,11 +1826,7 @@ do simply by adding new packages or modules and doing ::
18271826

18281827
logger = logging.getLogger(__name__)
18291828

1830-
at module level). It's probably one too many things to think about. Developers
1831-
could also add the filter to a :class:`~logging.NullHandler` attached to their
1832-
top-level logger, but this would not be invoked if an application developer
1833-
attached a handler to a lower-level library logger --- so output from that
1834-
handler would not reflect the intentions of the library developer.
1829+
at module level). It's probably one too many things to think about.
18351830

18361831
In Python 3.2 and later, :class:`~logging.LogRecord` creation is done through a
18371832
factory, which you can specify. The factory is just a callable you can set with
@@ -1913,15 +1908,15 @@ You can also subclass :class:`QueueListener` to get messages from other kinds
19131908
of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::
19141909

19151910
class ZeroMQSocketListener(QueueListener):
1916-
def __init__(self, uri, /, *handlers, **kwargs):
1917-
self.ctx = kwargs.get('ctx') or zmq.Context()
1911+
def __init__(self, uri, /, *handlers, ctx=None, **kwargs):
1912+
self.ctx = ctx or zmq.Context()
19181913
socket = zmq.Socket(self.ctx, zmq.SUB)
19191914
socket.setsockopt_string(zmq.SUBSCRIBE, '') # subscribe to everything
19201915
socket.connect(uri)
19211916
super().__init__(socket, *handlers, **kwargs)
19221917

1923-
def dequeue(self):
1924-
msg = self.queue.recv_json()
1918+
def dequeue(self, block):
1919+
msg = self.queue.recv_json(flags=0 if block else zmq.NOBLOCK)
19251920
return logging.makeLogRecord(msg)
19261921

19271922
.. _pynng-handlers:
@@ -2245,7 +2240,7 @@ works::
22452240
import logging.config
22462241
import logging.handlers
22472242
from multiprocessing import Process, Queue, Event, current_process
2248-
import os
2243+
from multiprocessing import get_start_method
22492244
import random
22502245
import time
22512246

@@ -2281,13 +2276,8 @@ works::
22812276
logging.config.dictConfig(config)
22822277
listener = logging.handlers.QueueListener(q, MyHandler())
22832278
listener.start()
2284-
if os.name == 'posix':
2285-
# On POSIX, the setup logger will have been configured in the
2286-
# parent process, but should have been disabled following the
2287-
# dictConfig call.
2288-
# On Windows, since fork isn't used, the setup logger won't
2289-
# exist in the child, so it would be created and the message
2290-
# would appear - hence the "if posix" clause.
2279+
if get_start_method() == 'fork':
2280+
# dictConfig disables the setup logger inherited from the parent.
22912281
logger = logging.getLogger('setup')
22922282
logger.critical('Should not appear, because of disabled logger ...')
22932283
stop_event.wait()
@@ -2312,13 +2302,8 @@ works::
23122302
logging.CRITICAL]
23132303
loggers = ['foo', 'foo.bar', 'foo.bar.baz',
23142304
'spam', 'spam.ham', 'spam.ham.eggs']
2315-
if os.name == 'posix':
2316-
# On POSIX, the setup logger will have been configured in the
2317-
# parent process, but should have been disabled following the
2318-
# dictConfig call.
2319-
# On Windows, since fork isn't used, the setup logger won't
2320-
# exist in the child, so it would be created and the message
2321-
# would appear - hence the "if posix" clause.
2305+
if get_start_method() == 'fork':
2306+
# dictConfig disables the setup logger inherited from the parent.
23222307
logger = logging.getLogger('setup')
23232308
logger.critical('Should not appear, because of disabled logger ...')
23242309
for i in range(100):
@@ -2345,9 +2330,7 @@ works::
23452330
}
23462331
# The worker process configuration is just a QueueHandler attached to the
23472332
# root logger, which allows all messages to be sent to the queue.
2348-
# We disable existing loggers to disable the "setup" logger used in the
2349-
# parent process. This is needed on POSIX because the logger will
2350-
# be there in the child following a fork().
2333+
# Disable the parent's "setup" logger if it was inherited via fork.
23512334
config_worker = {
23522335
'version': 1,
23532336
'disable_existing_loggers': True,
@@ -2365,9 +2348,7 @@ works::
23652348
# The listener process configuration shows that the full flexibility of
23662349
# logging configuration is available to dispatch events to handlers however
23672350
# you want.
2368-
# We disable existing loggers to disable the "setup" logger used in the
2369-
# parent process. This is needed on POSIX because the logger will
2370-
# be there in the child following a fork().
2351+
# Disable the parent's "setup" logger if it was inherited via fork.
23712352
config_listener = {
23722353
'version': 1,
23732354
'disable_existing_loggers': True,
@@ -4077,11 +4058,9 @@ How to uniformly handle newlines in logging output
40774058

40784059
Usually, messages that are logged (say to console or file) consist of a single
40794060
line of text. However, sometimes there is a need to handle messages with
4080-
multiple lines - whether because a logging format string contains newlines, or
4081-
logged data contains newlines. If you want to handle such messages uniformly, so
4082-
that each line in the logged message appears uniformly formatted as if it was
4083-
logged separately, you can do this using a handler mixin, as in the following
4084-
snippet:
4061+
multiple lines because the message or its arguments contain newlines.
4062+
To format each line as if it were logged separately, you can use a handler
4063+
mixin, as in the following snippet:
40854064

40864065
.. code-block:: python
40874066

‎Doc/howto/logging.rst‎

Lines changed: 7 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -146,13 +146,6 @@ interpreter, and don't just continue from the session described above::
146146
logger.warning('And this, too')
147147
logger.error('And non-ASCII stuff, too, like Øresund and Malmö')
148148

149-
.. versionchanged:: 3.9
150-
The *encoding* argument was added. In earlier Python versions, or if not
151-
specified, the encoding used is the default value used by :func:`open`. While
152-
not shown in the above example, an *errors* argument can also now be passed,
153-
which determines how encoding errors are handled. For available values and
154-
the default, see the documentation for :func:`open`.
155-
156149
And now if we open the file and look at what we have, we should find the log
157150
messages:
158151

@@ -465,10 +458,9 @@ With the logger object configured, the following methods create log messages:
465458
a message and a level that corresponds to their respective method names. The
466459
message is actually a format string, which may contain the standard string
467460
substitution syntax of ``%s``, ``%d``, ``%f``, and so on. The
468-
rest of their arguments is a list of objects that correspond with the
469-
substitution fields in the message. With regard to ``**kwargs``, the
470-
logging methods care only about a keyword of ``exc_info`` and use it to
471-
determine whether to log exception information.
461+
remaining positional arguments correspond to the substitution fields in the
462+
message. These methods also accept the keyword arguments *exc_info*, *extra*,
463+
*stack_info*, and *stacklevel*, described in :meth:`Logger.debug`.
472464

473465
* :meth:`Logger.exception` creates a log message similar to
474466
:meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a
@@ -1006,9 +998,9 @@ Logged messages are formatted for presentation through instances of the
1006998
use with the % operator and a dictionary.
1007999

10081000
For formatting multiple messages in a batch, instances of
1009-
:class:`BufferingFormatter` can be used. In addition to the format
1010-
string (which is applied to each message in the batch), there is provision for
1011-
header and trailer format strings.
1001+
:class:`BufferingFormatter` can be used. A line formatter formats each record
1002+
in the batch. To add a header or footer, override
1003+
:meth:`~BufferingFormatter.formatHeader` or :meth:`~BufferingFormatter.formatFooter`.
10121004

10131005
When filtering based on logger level and/or handler level is not enough,
10141006
instances of :class:`Filter` can be added to both :class:`Logger` and
@@ -1059,10 +1051,7 @@ In the preceding sections and examples, it has been assumed that the message
10591051
passed when logging the event is a string. However, this is not the only
10601052
possibility. You can pass an arbitrary object as a message, and its
10611053
:meth:`~object.__str__` method will be called when the logging system needs to
1062-
convert it to a string representation. In fact, if you want to, you can avoid
1063-
computing a string representation altogether - for example, the
1064-
:class:`~handlers.SocketHandler` emits an event by pickling it and sending it
1065-
over the wire.
1054+
convert it to a string representation.
10661055

10671056

10681057
Optimization

‎Doc/library/dis.rst‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -817,7 +817,8 @@ not have to be) the original ``STACK[-2]``.
817817

818818
.. opcode:: GET_AWAITABLE (where)
819819

820-
Implements ``STACK[-1] = get_awaitable(STACK[-1])``, where ``get_awaitable(o)``
820+
Replaces ``STACK[-1]`` with ``get_awaitable(STACK[-1])``, ``NULL`` and
821+
``None``, ready for :opcode:`SEND`. ``get_awaitable(o)``
821822
returns ``o`` if ``o`` is a coroutine object or a generator object with
822823
the :data:`~inspect.CO_ITERABLE_COROUTINE` flag, or resolves
823824
``o.__await__``.
@@ -833,6 +834,10 @@ not have to be) the original ``STACK[-2]``.
833834
.. versionchanged:: 3.11
834835
Previously, this instruction did not have an oparg.
835836

837+
.. versionchanged:: next
838+
Also pushes ``NULL`` and ``None``, which were previously pushed by
839+
separate instructions.
840+
836841

837842
.. opcode:: GET_AITER
838843

@@ -846,11 +851,16 @@ not have to be) the original ``STACK[-2]``.
846851

847852
.. opcode:: GET_ANEXT
848853

849-
Implement ``STACK.append(get_awaitable(STACK[-1].__anext__()))`` to the stack.
854+
Implement ``STACK.append(get_awaitable(STACK[-1].__anext__()))`` to the stack,
855+
then push ``NULL`` and ``None``, ready for :opcode:`SEND`.
850856
See ``GET_AWAITABLE`` for details about ``get_awaitable``.
851857

852858
.. versionadded:: 3.5
853859

860+
.. versionchanged:: next
861+
Also pushes ``NULL`` and ``None``, which were previously pushed by
862+
separate instructions.
863+
854864

855865
.. opcode:: END_ASYNC_FOR
856866

‎Doc/library/http.client.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -312,7 +312,7 @@ HTTPConnection Objects
312312
but there is a request body, one of those
313313
header fields will be added automatically. If
314314
*body* is ``None``, the Content-Length header is set to ``0`` for
315-
methods that expect a body (``PUT``, ``POST``, and ``PATCH``). If
315+
methods that expect a body (``PUT``, ``POST``, ``PATCH``, and ``QUERY``). If
316316
*body* is a string or a bytes-like object that is not also a
317317
:term:`file <file object>`, the Content-Length header is
318318
set to its length. Any other type of *body* (files
@@ -369,6 +369,9 @@ HTTPConnection Objects
369369
*continue_timeout* value must be greater than zero, otherwise
370370
:exc:`ValueError` is raised.
371371

372+
.. versionchanged:: next
373+
``QUERY`` was added to the methods that expect a body.
374+
372375
.. method:: HTTPConnection.getresponse(support_continue=False)
373376

374377
Should be called after a request is sent to get the response from the server.

‎Doc/library/http.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ Property Indicates that Details
194194
<HTTPMethod.PATCH>,
195195
<HTTPMethod.POST>,
196196
<HTTPMethod.PUT>,
197+
<HTTPMethod.QUERY>,
197198
<HTTPMethod.TRACE>]
198199

199200
.. _http-methods:
@@ -217,4 +218,5 @@ Method Enum Name Details
217218
``OPTIONS`` ``OPTIONS`` HTTP Semantics :rfc:`9110`, Section 9.3.7
218219
``TRACE`` ``TRACE`` HTTP Semantics :rfc:`9110`, Section 9.3.8
219220
``PATCH`` ``PATCH`` HTTP/1.1 :rfc:`5789`
221+
``QUERY`` ``QUERY`` The HTTP QUERY Method :rfc:`10008`
220222
=========== =================================== ==================================================================

0 commit comments

Comments
 (0)