8000 Merge remote-tracking branch 'upstream/main' into immortal-references · python/cpython@bc28cb0 · GitHub
[go: up one dir, main page]
Skip to content

Commit bc28cb0

Browse files
eduardo-elizondoeduardo-elizondo
committed
Merge remote-tracking branch 'upstream/main' into immortal-references
2 parents c71c742 + bc0a686 commit bc28cb0

File tree

323 files changed

+5575
-10123
lines changed

Some content is hidden

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

323 files changed

+5575
-10123
lines changed

‎.github/CODEOWNERS

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Python/traceback.c @iritkatriel
6363
# bytecode.
6464
**/*import*.c @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
6565
**/*import*.py @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
66-
**/*importlib/resources/* @jaraco @warsaw @brettcannon @FFY00
66+
**/*importlib/resources/* @jaraco @warsaw @FFY00
6767
**/importlib/metadata/* @jaraco @warsaw
6868

6969
# Dates and times
@@ -144,7 +144,7 @@ Lib/ast.py @isidentical
144144
**/*cgi* @ethanfurman
145145
**/*tarfile* @ethanfurman
146146

147-
**/*tomllib* @encukou
147+
**/*tomllib* @encukou @hauntsaninja
148148

149149
**/*sysconfig* @FFY00
150150

@@ -153,7 +153,7 @@ Lib/ast.py @isidentical
153153
**/*osx_support* @python/macos-team
154154

155155
# pathlib
156-
**/*pathlib* @brettcannon
156+
**/*pathlib* @barneygale
157157

158158
# zipfile.Path
159159
**/*zipfile/*_path.py @jaraco

‎.github/workflows/build.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ jobs:
235235
strategy:
236236
fail-fast: false
237237
matrix:
238-
openssl_ver: [1.1.1s, 3.0.7]
238+
openssl_ver: [1.1.1s, 3.0.7, 3.1.0-beta1]
239239
env:
240240
OPENSSL_VER: ${{ matrix.openssl_ver }}
241241
MULTISSL_DIR: ${{ github.workspace }}/multissl

‎.github/workflows/stale.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515

1616
steps:
1717
- name: "Check PRs"
18-
uses: actions/stale@v6
18+
uses: actions/stale@v7
1919
with:
2020
repo-token: ${{ secrets.GITHUB_TOKEN }}
2121
stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity.'

‎Doc/c-api/arg.rst

Lines changed: 35 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,24 +34,39 @@ These formats allow accessing an object as a contiguous chunk of memory.
3434
You don't have to provide raw storage for the returned unicode or bytes
3535
area.
3636

37-
In general, when a format sets a pointer to a buffer, the buffer is
38-
managed by the corresponding Python object, and the buffer shares
39-
the lifetime of this object. You won't have to release any memory yourself.
40-
The only exceptions are ``es``, ``es#``, ``et`` and ``et#``.
41-
42-
However, when a :c:type:`Py_buffer` structure gets filled, the underlying
43-
buffer is locked so that the caller can subsequently use the buffer even
44-
inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data
45-
being resized or destroyed. As a result, **you have to call**
46-
:c:func:`PyBuffer_Release` after you have finished processing the data (or
47-
in any early abort case).
48-
4937
Unless otherwise stated, buffers are not NUL-terminated.
5038

51-
Some formats require a read-only :term:`bytes-like object`, and set a
52-
pointer instead of a buffer structure. They work by checking that
53-
the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is ``NULL``,
54-
which disallows mutable objects such as :class:`bytearray`.
39+
There are three ways strings and buffers can be converted to C:
40+
41+
* Formats such as ``y*`` and ``s*`` fill a :c:type:`Py_buffer` structure.
42+
This locks the underlying buffer so that the caller can subsequently use
43+
the buffer even inside a :c:type:`Py_BEGIN_ALLOW_THREADS`
44+
block without the risk of mutable data being resized or destroyed.
45+
As a result, **you have to call** :c:func:`PyBuffer_Release` after you have
46+
finished processing the data (or in any early abort case).
47+
48+
* The ``es``, ``es#``, ``et`` and ``et#`` formats allocate the result buffer.
49+
**You have to call** :c:func:`PyMem_Free` after you have finished
50+
processing the data (or in any early abort case).
51+
52+
* .. _c-arg-borrowed-buffer:
53+
54+
Other formats take a :class:`str` or a read-only :term:`bytes-like object`,
55+
such as :class:`bytes`, and provide a ``const char *`` pointer to
56+
its buffer.
57+
In this case the buffer is "borrowed": it is managed by the corresponding
58+
Python object, and shares the lifetime of this object.
59+
You won't have to release any memory yourself.
60+
61+
To ensure that the underlying buffer may be safely borrowed, the object's
62+
:c:member:`PyBufferProcs.bf_releasebuffer` field must be ``NULL``.
63+
This disallows common mutable objects such as :class:`bytearray`,
64+
but also some read-only objects such as :class:`memoryview` of
65+
:class:`bytes`.
66+
67+
Besides this ``bf_releasebuffer`` requirement, there is no check to verify
68+
whether the input object is immutable (e.g. whether it would honor a request
69+
for a writable buffer, or whether another thread can mutate the data).
5570

5671
.. note::
5772

@@ -89,7 +104,7 @@ which disallows mutable objects such as :class:`bytearray`.
89104
Unicode objects are converted to C strings using ``'utf-8'`` encoding.
90105

91106
``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, :c:type:`Py_ssize_t`]
92-
Like ``s*``, except that it doesn't accept mutable objects.
107+
Like ``s*``, except that it provides a :ref:`borrowed buffer <c-arg-borrowed-buffer>`.
93108
The result is stored into two C variables,
94109
the first one a pointer to a C string, the second one its length.
95110
The string may contain embedded null bytes. Unicode objects are converted
@@ -108,8 +123,9 @@ which disallows mutable objects such as :class:`bytearray`.
108123
pointer is set to ``NULL``.
109124

110125
``y`` (read-only :term:`bytes-like object`) [const char \*]
111-
This format converts a bytes-like object to a C pointer to a character
112-
string; it does not accept Unicode objects. The bytes buffer must not
126+
This format converts a bytes-like object to a C pointer to a
127+
:ref:`borrowed <c-arg-borrowed-buffer>` character string;
128+
it does not accept Unicode objects. The bytes buffer must not
113129
contain embedded null bytes; if it does, a :exc:`ValueError`
114130
exception is raised.
115131

‎Doc/c-api/init.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1049,7 +1049,7 @@ code, or when embedding the Python interpreter:
10491049
.. versionchanged:: 3.2
10501050
This function cannot be called before :c:func:`Py_Initialize()` anymore.
10511051
1052-
.. deprecated-removed:: 3.9 3.11
1052+
.. deprecated:: 3.9
10531053
10541054
.. index:: module: _thread
10551055
@@ -1063,7 +1063,7 @@ code, or when embedding the Python interpreter:
10631063
.. versionchanged:: 3.7
10641064
The :term:`GIL` is now initialized by :c:func:`Py_Initialize()`.
10651065
1066-
.. deprecated-removed:: 3.9 3.11
1066+
.. deprecated:: 3.9
10671067
10681068
10691069
.. c:function:: PyThreadState* PyEval_SaveThread()

‎Doc/c-api/typeobj.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,7 @@ slot typedefs
452452
| | | |
453453
| | :c:type:`PyObject` * | |
454454
| | :c:type:`Py_ssize_t` | |
455+
| | :c:type:`PyObject` * | |
455456
+-----------------------------+-----------------------------+----------------------+
456457
| :c:type:`objobjproc` | .. line-block:: | int |
457458
| | | |
@@ -2633,7 +2634,7 @@ Slot Type typedefs
26332634
26342635
.. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t)
26352636
2636-
.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t)
2637+
.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *)
26372638
26382639
.. c:type:: int (*objobjproc)(PyObject *, PyObject *)
26392640

‎Doc/copyright.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Copyright
44

55
Python and this documentation is:
66

7-
Copyright © 2001-2022 Python Software Foundation. All rights reserved.
7+
Copyright © 2001-2023 Python Software Foundation. All rights reserved.
88

99
Copyright © 2000 BeOpen.com. All rights reserved.
1010

‎Doc/faq/programming.rst

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,8 @@ Yes. The coding style required for standard library modules is documented as
113113
Core Language
114114
=============
115115

116+
.. _faq-unboundlocalerror:
117+
116118
Why am I getting an UnboundLocalError when the variable has a value?
117119
--------------------------------------------------------------------
118120

@@ -1024,6 +1026,46 @@ What does 'UnicodeDecodeError' or 'UnicodeEncodeError' error mean?
10241026
See the :ref:`unicode-howto`.
10251027

10261028

1029+
.. _faq-programming-raw-string-backslash:
1030+
1031+
Can I end a raw string with an odd number of backslashes?
1032+
---------------------------------------------------------
1033+
1034+
A raw string ending with an odd number of backslashes will escape the string's quote::
1035+
1036+
>>> r'C:\this\will\not\work\'
1037+
File "<stdin>", line 1
1038+
r'C:\this\will\not\work\'
1039+
^
1040+
SyntaxError: unterminated string literal (detected at line 1)
1041+
1042+
There are several workarounds for this. One is to use regular strings and double
1043+
the backslashes::
1044+
1045+
>>> 'C:\\this\\will\\work\\'
1046+
'C:\\this\\will\\work\\'
1047+
1048+
Another is to concatenate a regular string containing an escaped backslash to the
1049+
raw string::
1050+
1051+
>>> r'C:\this\will\work' '\\'
1052+
'C:\\this\\will\\work\\'
1053+
1054+
It is also possible to use :func:`os.path.join` to append a backslash on Windows::
1055+
1056+
>>> os.path.join(r'C:\this\will\work', '')
1057+
'C:\\this\\will\\work\\'
1058+
1059+
Note that while a backslash will "escape" a quote for the purposes of
1060+
determining where the raw string ends, no escaping occurs when interpreting the
1061+
value of the raw string. That is, the backslash remains present in the value of
1062+
the raw string::
1063+
1064+
>>> r'backslash\'preserved'
1065+
"backslash\\'preserved"
1066+
1067+
Also see the specification in the :ref:`language reference <strings>`.
1068+
1027 10000 1069
Performance
10281070
===========
10291071

‎Doc/howto/annotations.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,12 @@ Accessing The Annotations Dict Of An Object In Python 3.10 And Newer
5757
newer is to call :func:`getattr` with three arguments,
5858
for example ``getattr(o, '__annotations__', None)``.
5959

60+
Before Python 3.10, accessing ``__annotations__`` on a class that
61+
defines no annotations but that has a parent class with
62+
annotations would return the parent's ``__annotations__``.
63+
In Python 3.10 and newer, the child class's annotations
64+
will be an empty dict instead.
65+
6066

6167
Accessing The Annotations Dict Of An Object In Python 3.9 And Older
6268
===================================================================

‎Doc/library/argparse.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -765,7 +765,7 @@ The add_argument() method
765765

766766
* type_ - The type to which the command-line argument should be converted.
767767

768-
* choices_ - A container of the allowable values for the argument.
768+
* choices_ - A sequence of the allowable values for the argument.
769769

770770
* required_ - Whether or not the command-line option may be omitted
771771
(optionals only).
@@ -1209,7 +1209,7 @@ choices
12091209
^^^^^^^
12101210

12111211
Some command-line arguments should be selected from a restricted set of values.
1212-
These can be handled by passing a container object as the *choices* keyword
1212+
These can be handled by passing a sequence object as the *choices* keyword
12131213
argument to :meth:`~ArgumentParser.add_argument`. When the command line is
12141214
parsed, argument values will be checked, and an error message will be displayed
12151215
if the argument was not one of the acceptable values::
@@ -1223,9 +1223,9 @@ if the argument was not one of the acceptable values::
12231223
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
12241224
'paper', 'scissors')
12251225

1226-
Note that inclusion in the *choices* container is checked after any type_
1226+
Note that inclusion in the *choices* sequence is checked after any type_
12271227
conversions have been performed, so the type of the objects in the *choices*
1228-
container should match the type_ specified::
1228+
sequence should match the type_ specified::
12291229

12301230
>>> parser = argparse.ArgumentParser(prog='doors.py')
12311231
>>> parser.add_argument('door', type=int, choices=range(1, 4))
@@ -1235,8 +1235,8 @@ container should match the type_ specified::
12351235
usage: doors.py [-h] {1,2,3}
12361236
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
12371237

1238-
Any container can be passed as the *choices* value, so :class:`list` objects,
1239-
:class:`set` objects, and custom containers are all supported.
1238+
Any sequence can be passed as the *choices* value, so :class:`list` objects,
1239+
:class:`tuple` objects, and custom sequences are all supported.
12401240

12411241
Use of :class:`enum.Enum` is not recommended because it is difficult to
12421242
control its appearance in usage, help, and error messages.

‎Doc/library/compileall.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ Public functions
199199

200200
The *stripdir*, *prependdir* and *limit_sl_dest* arguments correspond to
201201
the ``-s``, ``-p`` and ``-e`` options described above.
202-
They may be specified as ``str``, ``bytes`` or :py:class:`os.PathLike`.
202+
They may be specified as ``str`` or :py:class:`os.PathLike`.
203203

204204
If *hardlink_dupes* is true and two ``.pyc`` files with different optimization
205205
level have the same content, use hard links to consolidate duplicate files.
@@ -269,7 +269,7 @@ Public functions
269269

270270
The *stripdir*, *prependdir* and *limit_sl_dest* arguments correspond to
271271
the ``-s``, ``-p`` and ``-e`` options described above.
272-
They may be specified as ``str``, ``bytes`` or :py:class:`os.PathLike`.
272+
They may be specified as ``str`` or :py:class:`os.PathLike`.
273273

274274
If *hardlink_dupes* is true and two ``.pyc`` files with different optimization
275275
level have the same content, use hard links to consolidate duplicate files.

‎Doc/library/curses.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1297,11 +1297,11 @@ the following methods and attributes:
12971297
:meth:`refresh`.
12981298

12991299

1300-
.. method:: window.vline(ch, n)
1301-
window.vline(y, x, ch, n)
1300+
.. method:: window.vline(ch, n[, attr])
1301+
window.vline(y, x, ch, n[, attr])
13021302

13031303
Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
1304-
character *ch*.
1304+
character *ch* with attributes *attr*.
13051305

13061306

13071307
Constants

‎Doc/library/dataclasses.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -552,7 +552,7 @@ parameters to :meth:`__post_init__`. Also see the warning about how
552552
Class variables
553553
---------------
554554

555-
One of two places where :func:`dataclass` actually inspects the type
555+
One of the few places where :func:`dataclass` actually inspects the type
556556
of a field is to determine if a field is a class variable as defined
557557
in :pep:`526`. It does this by checking if the type of the field is
558558
``typing.ClassVar``. If a field is a ``ClassVar``, it is excluded
@@ -563,7 +563,7 @@ module-level :func:`fields` function.
563563
Init-only variables
564564
-------------------
565565

566-
The other place where :func:`dataclass` inspects a type annotation is to
566+
Another place where :func:`dataclass` inspects a type annotation is to
567567
determine if a field is an init-only variable. It does this by seeing
568568
if the type of a field is of type ``dataclasses.InitVar``. If a field
569569
is an ``InitVar``, it is considered a pseudo-field called an init-only

0 commit comments

Comments
 (0)
0