Skip to content

Commit 45fb260

Browse files
aiskaisk
committed
Merge remote-tracking branch 'upstream/main' into hkey-compare-doc
2 parents 6958ada + 248ce9f commit 45fb260

File tree

74 files changed

+2743
-2038
lines changed

Some content is hidden

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

74 files changed

+2743
-2038
lines changed

‎Doc/c-api/conversion.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ The return value (*rv*) for these functions should be interpreted as follows:
4141
``rv + 1`` bytes would have been needed to succeed. ``str[size-1]`` is ``'\0'``
4242
in this case.
4343
44-
* When ``rv < 0``, "something bad happened." ``str[size-1]`` is ``'\0'`` in
44+
* When ``rv < 0``, the output conversion failed and ``str[size-1]`` is ``'\0'`` in
4545
this case too, but the rest of *str* is undefined. The exact cause of the error
4646
depends on the underlying platform.
4747

‎Doc/c-api/dict.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Dictionary Objects
5050
5151
.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
5252
53-
Determine if dictionary *p* contains *key*. If an item in *p* is matches
53+
Determine if dictionary *p* contains *key*. If an item in *p* matches
5454
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
5555
This is equivalent to the Python expression ``key in p``.
5656
@@ -198,7 +198,7 @@ Dictionary Objects
198198
.. c:function:: int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)
199199
200200
Remove *key* from dictionary *p* and optionally return the removed value.
201-
Do not raise :exc:`KeyError` if the key missing.
201+
Do not raise :exc:`KeyError` if the key is missing.
202202
203203
- If the key is present, set *\*result* to a new reference to the removed
204204
value if *result* is not ``NULL``, and return ``1``.
@@ -207,7 +207,7 @@ Dictionary Objects
207207
- On error, raise an exception and return ``-1``.
208208
209209
Similar to :meth:`dict.pop`, but without the default value and
210-
not raising :exc:`KeyError` if the key missing.
210+
not raising :exc:`KeyError` if the key is missing.
211211
212212
.. versionadded:: 3.13
213213

‎Doc/c-api/typeobj.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1260,7 +1260,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
12601260
This bit indicates that instances of the class have a :attr:`~object.__dict__`
12611261
attribute, and that the space for the dictionary is managed by the VM.
12621262

1263-
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
1263+
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` must also be set.
12641264

12651265
The type traverse function must call :c:func:`PyObject_VisitManagedDict`
12661266
and its clear function must call :c:func:`PyObject_ClearManagedDict`.
@@ -1278,6 +1278,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
12781278
This bit indicates that instances of the class should be weakly
12791279
referenceable.
12801280

1281+
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` must also be set.
1282+
12811283
.. versionadded:: 3.12
12821284

12831285
**Inheritance:**

‎Doc/extending/newtypes.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -560,6 +560,8 @@ For an object to be weakly referenceable, the extension type must set the
560560
field. The legacy :c:member:`~PyTypeObject.tp_weaklistoffset` field should
561561
be left as zero.
562562

563+
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
564+
563565
Concretely, here is how the statically declared type object would look::
564566

565567
static PyTypeObject TrivialType = {

‎Doc/library/argparse.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -638,6 +638,11 @@ by setting ``color`` to ``False``::
638638
... help='an integer for the accumulator')
639639
>>> parser.parse_args(['--help'])
640640

641+
Note that when ``color=True``, colored output depends on both environment
642+
variables and terminal capabilities. However, if ``color=False``, colored
643+
output is always disabled, even if environment variables like ``FORCE_COLOR``
644+
are set.
645+
641646
.. versionadded:: 3.14
642647

643648

‎Doc/library/calendar.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -710,8 +710,7 @@ The following options are accepted:
710710
.. option:: month
711711

712712
The month of the specified :option:`year` to print the calendar for.
713-
Must be a number between 1 and 12,
714-
and may only be used in text mode.
713+
Must be a number between 1 and 12.
715714
Defaults to printing a calendar for the full year.
716715

717716

‎Doc/library/html.parser.rst‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,18 @@
1515
This module defines a class :class:`HTMLParser` which serves as the basis for
1616
parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
1717

18-
.. class:: HTMLParser(*, convert_charrefs=True)
18+
.. class:: HTMLParser(*, convert_charrefs=True, scripting=False)
1919

2020
Create a parser instance able to parse invalid markup.
2121

22-
If *convert_charrefs* is ``True`` (the default), all character
23-
references (except the ones in ``script``/``style`` elements) are
22+
If *convert_charrefs* is true (the default), all character
23+
references (except the ones in elements like ``script`` and ``style``) are
2424
automatically converted to the corresponding Unicode characters.
2525

26+
If *scripting* is false (the default), the content of the ``noscript``
27+
element is parsed normally; if it's true, it's returned as is without
28+
being parsed.
29+
2630
An :class:`.HTMLParser` instance is fed HTML data and calls handler methods
2731
when start tags, end tags, text, comments, and other markup elements are
2832
encountered. The user should subclass :class:`.HTMLParser` and override its
@@ -37,6 +41,9 @@ parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
3741
.. versionchanged:: 3.5
3842
The default value for argument *convert_charrefs* is now ``True``.
3943

44+
.. versionchanged:: 3.14.1
45+
Added the *scripting* parameter.
46+
4047

4148
Example HTML Parser Application
4249
-------------------------------
@@ -161,24 +168,24 @@ implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`):
161168
.. method:: HTMLParser.handle_data(data)
162169

163170
This method is called to process arbitrary data (e.g. text nodes and the
164-
content of ``<script>...</script>`` and ``<style>...</style>``).
171+
content of elements like ``script`` and ``style``).
165172

166173

167174
.. method:: HTMLParser.handle_entityref(name)
168175

169176
This method is called to process a named character reference of the form
170177
``&name;`` (e.g. ``&gt;``), where *name* is a general entity reference
171-
(e.g. ``'gt'``). This method is never called if *convert_charrefs* is
172-
``True``.
178+
(e.g. ``'gt'``).
179+
This method is only called if *convert_charrefs* is false.
173180

174181

175182
.. method:: HTMLParser.handle_charref(name)
176183

177184
This method is called to process decimal and hexadecimal numeric character
178185
references of the form :samp:`&#{NNN};` and :samp:`&#x{NNN};`. For example, the decimal
179186
equivalent for ``&gt;`` is ``&#62;``, whereas the hexadecimal is ``&#x3E;``;
180-
in this case the method will receive ``'62'`` or ``'x3E'``. This method
181-
is never called if *convert_charrefs* is ``True``.
187+
in this case the method will receive ``'62'`` or ``'x3E'``.
188+
This method is only called if *convert_charrefs* is false.
182189

183190

184191
.. method:: HTMLParser.handle_comment(data)
@@ -292,8 +299,8 @@ Parsing an element with a few attributes and a title:
292299
Data : Python
293300
End tag : h1
294301

295-
The content of ``script`` and ``style`` elements is returned as is, without
296-
further parsing:
302+
The content of elements like ``script`` and ``style`` is returned as is,
303+
without further parsing:
297304

298305
.. doctest::
299306

@@ -304,10 +311,10 @@ further parsing:
304311
End tag : style
305312

306313
>>> parser.feed('<script type="text/javascript">'
307-
... 'alert("<strong>hello!</strong>");</script>')
314+
... 'alert("<strong>hello! &#9786;</strong>");</script>')
308315
Start tag: script
309316
attr: ('type', 'text/javascript')
310-
Data : alert("<strong>hello!</strong>");
317+
Data : alert("<strong>hello! &#9786;</strong>");
311318
End tag : script
312319

313320
Parsing comments:
@@ -336,7 +343,7 @@ correct char (note: these 3 references are all equivalent to ``'>'``):
336343

337344
Feeding incomplete chunks to :meth:`~HTMLParser.feed` works, but
338345
:meth:`~HTMLParser.handle_data` might be called more than once
339-
(unless *convert_charrefs* is set to ``True``):
346+
if *convert_charrefs* is false:
340347

341348
.. doctest::
342349

‎Doc/library/importlib.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1013,6 +1013,36 @@ find and load modules.
10131013
:exc:`ImportError` is raised.
10141014

10151015

1016+
.. class:: NamespacePath(name, path, path_finder)
1017+
1018+
Represents a :term:`namespace package`'s path (:attr:`module.__path__`).
1019+
1020+
When its ``__path__`` value is accessed it will be recomputed if necessary.
1021+
This keeps it in-sync with the global state (:attr:`sys.modules`).
1022+
1023+
The *name* argument is the name of the namespace module.
1024+
1025+
The *path* argument is the initial path value.
1026+
1027+
The *path_finder* argument is the callable used to recompute the path value.
1028+
The callable has the same signature as :meth:`importlib.abc.MetaPathFinder.find_spec`.
1029+
1030+
When the parent's :attr:`module.__path__` attribute is updated, the path
1031+
value is recomputed.
1032+
1033+
If the parent module is missing from :data:`sys.modules`, then
1034+
:exc:`ModuleNotFoundError` will be raised.
1035+
1036+
For top-level modules, the parent module's path is :data:`sys.path`.
1037+
1038+
.. note::
1039+
1040+
:meth:`PathFinder.invalidate_caches` invalidates :class:`NamespacePath`,
1041+
forcing the path value to be recomputed next time it is accessed.
1042+
1043+
.. versionadded:: next
1044+
1045+
10161046
.. class:: SourceFileLoader(fullname, path)
10171047

10181048
A concrete implementation of :class:`importlib.abc.SourceLoader` by

‎Doc/library/math.integer.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
:mod:`math.integer` --- integer-specific mathematics functions
2+
==============================================================
3+
4+
.. module:: math.integer
5+
:synopsis: Integer-specific mathematics functions.
6+
7+
.. versionadded:: next
8+
9+
--------------
10+
11+
This module provides access to the mathematical functions defined for integer arguments.
12+
These functions accept integers and objects that implement the
13+
:meth:`~object.__index__` method which is used to convert the object to an integer
14+
number.
15+
16+
The following functions are provided by this module. All return values are
17+
computed exactly and are integers.
18+
19+
20+
.. function:: comb(n, k, /)
21+
22+
Return the number of ways to choose *k* items from *n* items without repetition
23+
and without order.
24+
25+
Evaluates to ``n! / (k! * (n - k)!)`` when ``k <= n`` and evaluates
26+
to zero when ``k > n``.
27+
28+
Also called the binomial coefficient because it is equivalent
29+
to the coefficient of k-th term in polynomial expansion of
30+
``(1 + x)ⁿ``.
31+
32+
Raises :exc:`ValueError` if either of the arguments are negative.
33+
34+
35+
.. function:: factorial(n, /)
36+
37+
Return factorial of the nonnegative integer *n*.
38+
39+
40+
.. function:: gcd(*integers)
41+
42+
Return the greatest common divisor of the specified integer arguments.
43+
If any of the arguments is nonzero, then the returned value is the largest
44+
positive integer that is a divisor of all arguments. If all arguments
45+
are zero, then the returned value is ``0``. ``gcd()`` without arguments
46+
returns ``0``.
47+
48+
49+
.. function:: isqrt(n, /)
50+
51+
Return the integer square root of the nonnegative integer *n*. This is the
52+
floor of the exact square root of *n*, or equivalently the greatest integer
53+
*a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
54+
55+
For some applications, it may be more convenient to have the least integer
56+
*a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
57+
the exact square root of *n*. For positive *n*, this can be computed using
58+
``a = 1 + isqrt(n - 1)``.
59+
60+
61+
.. |nbsp| unicode:: 0xA0
62+
:trim:
63+
64+
65+
.. function:: lcm(*integers)
66+
67+
Return the least common multiple of the specified integer arguments.
68+
If all arguments are nonzero, then the returned value is the smallest
69+
positive integer that is a multiple of all arguments. If any of the arguments
70+
is zero, then the returned value is ``0``. ``lcm()`` without arguments
71+
returns ``1``.
72+
73+
74+
.. function:: perm(n, k=None, /)
75+
76+
Return the number of ways to choose *k* items from *n* items
77+
without repetition and with order.
78+
79+
Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
80+
to zero when ``k > n``.
81+
82+
If *k* is not specified or is ``None``, then *k* defaults to *n*
83+
and the function returns ``n!``.
84+
85+
Raises :exc:`ValueError` if either of the arguments are negative.

0 commit comments

Comments
 (0)