8000 Merge branch 'main' into argparse-abbrev-subparser · python/cpython@1c0a4de · GitHub
[go: up one dir, main page]
Skip to content

Commit 1c0a4de

Browse files
serhiy-storchakaserhiy-storchaka
authored
Merge branch 'main' into argparse-abbrev-subparser
2 parents 333c23e + 95e92ef commit 1c0a4de

File tree

158 files changed

+2094
-1371
lines changed

Some content is hidden

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

158 files changed

+2094
-1371
lines changed

‎.devcontainer/Dockerfile

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎.devcontainer/devcontainer.json

-3Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
{
2-
"build": {
3-
"dockerfile": "Dockerfile"
4-
},
2+
"image": "ghcr.io/python/devcontainer:2024.09.25.11038928730",
53
"onCreateCommand": [
64
// Install common tooling.
75
"dnf",

‎.github/CODEOWNERS

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,6 @@ Doc/c-api/stable.rst @encukou
207207
**/*bisect* @rhettinger
208208
**/*heapq* @rhettinger
209209
**/*functools* @rhettinger
210-
**/*decimal* @rhettinger
211210

212211
**/*dataclasses* @ericvsmith
213212

‎Doc/c-api/init_config.rst

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1248,19 +1248,24 @@ PyConfig
12481248
12491249
.. c:member:: int perf_profiling
12501250
1251-
Enable compatibility mode with the perf profiler?
1251+
Enable the Linux ``perf`` profiler support?
12521252
1253-
If non-zero, initialize the perf trampoline. See :ref:`perf_profiling`
1254-
for more information.
1253+
If equals to ``1``, enable support for the Linux ``perf`` profiler.
12551254
1256-
Set by :option:`-X perf <-X>` command-line option and by the
1257-
:envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable for perf support
1258-
with stack pointers and :option:`-X perf_jit <-X>` command-line option
1259-
and by the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable for perf
1260-
support with DWARF JIT information.
1255+
If equals to ``2``, enable support for the Linux ``perf`` profiler with
1256+
DWARF JIT support.
1257+
1258+
Set to ``1`` by :option:`-X perf <-X>` command-line option and the
1259+
:envvar:`PYTHONPERFSUPPORT` environment variable.
1260+
1261+
Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and
1262+
the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable.
12611263
12621264
Default: ``-1``.
12631265
1266+
.. seealso::
1267+
See :ref:`perf_profiling` for more information.
1268+
12641269
.. versionadded:: 3.12
12651270
12661271
.. c:member:: int use_environment

‎Doc/c-api/long.rst

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,6 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
159159
.. versionadded:: 3.13
160160
161161
162-
.. XXX alias PyLong_AS_LONG (for now)
163162
.. c:function:: long PyLong_AsLong(PyObject *obj)
164163
165164
.. index::
@@ -181,6 +180,16 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
181180
.. versionchanged:: 3.10
182181
This function will no longer use :meth:`~object.__int__`.
183182
183+
.. c:namespace:: NULL
184+
185+
.. c:function:: long PyLong_AS_LONG(PyObject *obj)
186+
187+
A :term:`soft deprecated` alias.
188+
Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
189+
it can fail with :exc:`OverflowError` or another exception.
190+
191+
.. deprecated:: 3.14
192+
The function is soft deprecated.
184193
185194
.. c:function:: int PyLong_AsInt(PyObject *obj)
186195

‎Doc/c-api/unicode.rst

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,7 @@ These APIs can be used to work with surrogates:
317317
318318
.. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
319319
320-
Join two surrogate characters and return a single :c:type:`Py_UCS4` value.
320+
Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
321321
*high* and *low* are respectively the leading and trailing surrogates in a
322322
surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
323323
be in the range [0xDC00; 0xDFFF].
@@ -338,6 +338,8 @@ APIs:
338338
This is the recommended way to allocate a new Unicode object. Objects
339339
created using this function are not resizable.
340340
341+
On error, set an exception and return ``NULL``.
342+
341343
.. versionadded:: 3.3
342344
343345
@@ -614,6 +616,8 @@ APIs:
614616
615617
Return the length of the Unicode object, in code points.
616618
619+
On error, set an exception and return ``-1``.
620+
617621
.. versionadded:: 3.3
618622
619623
@@ -657,6 +661,8 @@ APIs:
657661
not out of bounds, and that the object can be modified safely (i.e. that it
658662
its reference count is one).
659663
664+
Return ``0`` on success, ``-1`` on error with an exception set.
665+
660666
.. versionadded:: 3.3
661667
662668
@@ -666,6 +672,8 @@ APIs:
666672
Unicode object and the index is not out of bounds, in contrast to
667673
:c:func:`PyUnicode_READ_CHAR`, which performs no error checking.
668674
675+
Return character on success, ``-1`` on error with an exception set.
676+
669677
.. versionadded:: 3.3
670678
671679
@@ -674,6 +682,7 @@ APIs:
674682
675683
Return a substring of *unicode*, from character index *start* (included) to
676684
character index *end* (excluded). Negative indices are not supported.
685+
On error, set an exception and return ``NULL``.
677686
678687
.. versionadded:: 3.3
679688
@@ -990,6 +999,9 @@ These are the UTF-8 codec APIs:
990999
object. Error handling is "strict". Return ``NULL`` if an exception was
9911000
raised by the codec.
9921001
1002+
The function fails if the string contains surrogate code points
1003+
(``U+D800`` - ``U+DFFF``).
1004+
9931005
9941006
.. c:function:: const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
9951007
@@ -1002,6 +1014,9 @@ These are the UTF-8 codec APIs:
10021014
On error, set an exception, set *size* to ``-1`` (if it's not NULL) and
10031015
return ``NULL``.
10041016
1017+
The function fails if the string contains surrogate code points
1018+
(``U+D800`` - ``U+DFFF``).
1019+
10051020
This caches the UTF-8 representation of the string in the Unicode object, and
10061021
subsequent calls will return a pointer to the same buffer. The caller is not
10071022
responsible for deallocating the buffer. The buffer is deallocated and
@@ -1429,8 +1444,9 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
14291444
Compare a Unicode object with a char buffer which is interpreted as
14301445
being UTF-8 or ASCII encoded and return true (``1``) if they are equal,
14311446
or false (``0``) otherwise.
1432-
If the Unicode object contains surrogate characters or
1433-
the C string is not valid UTF-8, false (``0``) is returned.
1447+
If the Unicode object contains surrogate code points
1448+
(``U+D800`` - ``U+DFFF``) or the C string is not valid UTF-8,
1449+
false (``0``) is returned.
14341450
14351451
This function does not raise exceptions.
14361452

‎Doc/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -413,8 +413,8 @@
413413
\let\endVerbatim=\endOriginalVerbatim
414414
\setcounter{tocdepth}{2}
415415
''',
416-
# The paper size ('letter' or 'a4').
417-
'papersize': 'a4',
416+
# The paper size ('letterpaper' or 'a4paper').
417+
'papersize': 'a4paper',
418418
# The font size ('10pt', '11pt' or '12pt').
419419
'pointsize': '10pt',
420420
}

‎Doc/deprecations/pending-removal-in-3.16.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,14 @@ Pending Removal in Python 3.16
1818
Use the ``'w'`` format code (:c:type:`Py_UCS4`)
1919
for Unicode characters instead.
2020

21+
* :mod:`asyncio`:
22+
23+
* :mod:`asyncio`:
24+
:func:`!asyncio.iscoroutinefunction` is deprecated
25+
and will be removed in Python 3.16,
26+
use :func:`inspect.iscoroutinefunction` instead.
27+
(Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
28+
2129
* :mod:`shutil`:
2230

2331
* The :class:`!ExecError` exception

‎Doc/faq/programming.rst

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1613,9 +1613,16 @@ method too, and it must do so carefully. The basic implementation of
16131613
self.__dict__[name] = value
16141614
...
16151615

1616-
Most :meth:`!__setattr__` implementations must modify
1617-
:attr:`self.__dict__ <object.__dict__>` to store
1618-
local state for self without causing an infinite recursion.
1616+
Many :meth:`~object.__setattr__` implementations call :meth:`!object.__setattr__` to set
1617+
an attribute on self without causing infinite recursion::
1618+
1619+
class X:
1620+
def __setattr__(self, name, value):
1621+
# Custom logic here...
1622+
object.__setattr__(self, name, value)
1623+
1624+
Alternatively, it is possible to set attributes by inserting
1625+
entries into :attr:`self.__dict__ <object.__dict__>` directly.
16191626

16201627

16211628
How do I call a method defined in a base class from a derived class that extends it?

‎Doc/howto/sorting.rst

Lines changed: 70 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,14 @@ lists. In contrast, the :func:`sorted` function accepts any iterable.
4747
Key Functions
4848
=============
4949

50-
Both :meth:`list.sort` and :func:`sorted` have a *key* parameter to specify a
51-
function (or other callable) to be called on each list element prior to making
50+
The :meth:`list.sort` method and the functions :func:`sorted`,
51+
:func:`min`, :func:`max`, :func:`heapq.nsmallest`, and
52+
:func:`heapq.nlargest` have a *key* parameter to specify a function (or
53+
other callable) to be called on each list element prior to making
5254
comparisons.
5355

54-
For example, here's a case-insensitive string comparison:
56+
For example, here's a case-insensitive string comparison using
57+
:meth:`str.casefold`:
5558

5659
.. doctest::
5760

@@ -272,6 +275,70 @@ to make it usable as a key function::
272275

273276
sorted(words, key=cmp_to_key(strcoll)) # locale-aware sort order
274277

278+
Strategies For Unorderable Types and Values
279+
===========================================
280+
281+
A number of type and value issues can arise when sorting.
282+
Here are some strategies that can help:
283+
284+
* Convert non-comparable input types to strings prior to sorting:
285+
286+
.. doctest::
287+
288+
>>> data = ['twelve', '11', 10]
289+
>>> sorted(map(str, data))
290+
['10', '11', 'twelve']
291+
292+
This is needed because most cross-type comparisons raise a
293+
:exc:`TypeError`.
294+
295+
* Remove special values prior to sorting:
296+
297+
.. doctest::
298+
299+
>>> from math import isnan
300+
>>> from itertools import filterfalse
301+
>>> data = [3.3, float('nan'), 1.1, 2.2]
302+
>>> sorted(filterfalse(isnan, data))
303+
[1.1, 2.2, 3.3]
304+
305+
This is needed because the `IEEE-754 standard
306+
<https://en.wikipedia.org/wiki/IEEE_754>`_ specifies that, "Every NaN
307+
shall compare unordered with everything, including itself."
308+
309+
Likewise, ``None`` can be stripped from datasets as well:
310+
311+
.. doctest::
312+
313+
>>> data = [3.3, None, 1.1, 2.2]
314+
>>> sorted(x for x in data if x is not None)
315+
[1.1, 2.2, 3.3]
316+
317+
This is needed because ``None`` is not comparable to other types.
318+
319+
* Convert mapping types into sorted item lists before sorting:
320+
321+
.. doctest::
322+
323+
>>> data = [{'a': 1}, {'b': 2}]
324+
>>> sorted(data, key=lambda d: sorted(d.items()))
325+
[{'a': 1}, {'b': 2}]
326+
327+
This is needed because dict-to-dict comparisons raise a
328+
:exc:`TypeError`.
329+
330+
* Convert set types into sorted lists before sorting:
331+
332+
.. doctest::
333+
334+
>>> data = [{'a', 'b', 'c'}, {'b', 'c', 'd'}]
335+
>>> sorted(map(sorted, data))
336+
[['a', 'b', 'c'], ['b', 'c', 'd']]
337+
338+
This is needed because the elements contained in set types do not have a
339+
deterministic order. For example, ``list({'a', 'b'})`` may produce
340+
either ``['a', 'b']`` or ``['b', 'a']``.
341+
275342
Odds and Ends
276343
=============
277344

0 commit comments

Comments
 (0)
0