Skip to content

Commit 19b0956

Browse files
github-actions[bot]github-actions[bot]
committed
deploy: 26ab2a9 
1 parent 8046164 commit 19b0956

File tree

586 files changed

+7724
-6927
lines changed

Some content is hidden

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

586 files changed

+7724
-6927
lines changed

‎.buildinfo

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
22
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: 1211c5592533e8bd95c146e37cb2bd39
3+
config: ca58daa7f9eaf2fe9b9976d62f82e969
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_sources/bugs.rst.txt

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ If you find a bug in this documentation or would like to propose an improvement,
1919
please submit a bug report on the :ref:`tracker <using-the-tracker>`. If you
2020
have a suggestion on how to fix it, include that as well.
2121

22+
You can also open a discussion item on our
23+
`Documentation Discourse forum <https://discuss.python.org/c/documentation/26>`_.
24+
2225
If you're short on time, you can also email documentation bug reports to
2326
docs@python.org (behavioral bugs can be sent to python-list@python.org).
2427
'docs@' is a mailing list run by volunteers; your request will be noticed,
@@ -67,7 +70,7 @@ Click on the "New issue" button in the top bar to report a new issue.
6770
The submission form has two fields, "Title" and "Comment".
6871

6972
For the "Title" field, enter a *very* short description of the problem;
70-
less than ten words is good.
73+
fewer than ten words is good.
7174

7275
In the "Comment" field, describe the problem in detail, including what you
7376
expected to happen and what did happen. Be sure to include whether any

‎_sources/c-api/dict.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Dictionary Objects
8080
8181
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
8282
83-
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
83+
Remove the entry in dictionary *p* with key *key*. *key* must be :term:`hashable`;
8484
if it isn't, :exc:`TypeError` is raised.
8585
If *key* is not in the dictionary, :exc:`KeyError` is raised.
8686
Return ``0`` on success or ``-1`` on failure.

‎_sources/c-api/init.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -709,7 +709,7 @@ Process-wide parameters
709709
.. deprecated:: 3.11
710710
711711
712-
.. c:function:: w_char* Py_GetPythonHome()
712+
.. c:function:: wchar_t* Py_GetPythonHome()
713713
714714
Return the default "home", that is, the value set by a previous call to
715715
:c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`

‎_sources/c-api/module.rst.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -388,15 +388,15 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
388388
389389
.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
390390
391-
Create a new module object, given the definition in *module* and the
391+
Create a new module object, given the definition in *def* and the
392392
ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2`
393393
with *module_api_version* set to :const:`PYTHON_API_VERSION`.
394394
395395
.. versionadded:: 3.5
396396
397397
.. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
398398
399-
Create a new module object, given the definition in *module* and the
399+
Create a new module object, given the definition in *def* and the
400400
ModuleSpec *spec*, assuming the API version *module_api_version*.
401401
If that version does not match the version of the running interpreter,
402402
a :exc:`RuntimeWarning` is emitted.

‎_sources/c-api/object.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,7 @@ Object Protocol
281281
282282
.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
283283
284-
Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
284+
Set a :exc:`TypeError` indicating that ``type(o)`` is not :term:`hashable` and return ``-1``.
285285
This function receives special treatment when stored in a ``tp_hash`` slot,
286286
allowing a type to explicitly indicate to the interpreter that it is not
287287
hashable.

‎_sources/faq/programming.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1979,7 +1979,7 @@ method result will be released right away. The disadvantage is that if
19791979
instances accumulate, so too will the accumulated method results. They
19801980
can grow without bound.
19811981

1982-
The *lru_cache* approach works with methods that have hashable
1982+
The *lru_cache* approach works with methods that have :term:`hashable`
19831983
arguments. It creates a reference to the instance unless special
19841984
efforts are made to pass in weak references.
19851985

‎_sources/howto/logging-cookbook.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2538,7 +2538,7 @@ should be logged, or the ``extra`` keyword parameter to indicate additional
25382538
contextual information to be added to the log). So you cannot directly make
25392539
logging calls using :meth:`str.format` or :class:`string.Template` syntax,
25402540
because internally the logging package uses %-formatting to merge the format
2541-
string and the variable arguments. There would no changing this while preserving
2541+
string and the variable arguments. There would be no changing this while preserving
25422542
backward compatibility, since all logging calls which are out there in existing
25432543
code will be using %-format strings.
25442544

‎_sources/library/abc.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The :mod:`collections` module has some concrete classes that derive from
2121
ABCs; these can, of course, be further derived. In addition, the
2222
:mod:`collections.abc` submodule has some ABCs that can be used to test whether
2323
a class or instance provides a particular interface, for example, if it is
24-
hashable or if it is a mapping.
24+
:term:`hashable` or if it is a mapping.
2525

2626

2727
This module provides the metaclass :class:`ABCMeta` for defining ABCs and

‎_sources/library/argparse.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1854,7 +1854,7 @@ Sub-commands
18541854
...
18551855
>>> # create the top-level parser
18561856
>>> parser = argparse.ArgumentParser()
1857-
>>> subparsers = parser.add_subparsers()
1857+
>>> subparsers = parser.add_subparsers(required=True)
18581858
>>>
18591859
>>> # create the parser for the "foo" command
18601860
>>> parser_foo = subparsers.add_parser('foo')

‎_sources/library/asyncio-eventloop.rst.txt

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -192,12 +192,15 @@ Running and stopping the loop
192192
.. coroutinemethod:: loop.shutdown_default_executor()
193193

194194
Schedule the closure of the default executor and wait for it to join all of
195-
the threads in the :class:`ThreadPoolExecutor`. After calling this method, a
196-
:exc:`RuntimeError` will be raised if :meth:`loop.run_in_executor` is called
197-
while using the default executor.
195+
the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
196+
Once this method has been called,
197+
using the default executor with :meth:`loop.run_in_executor`
198+
will raise a :exc:`RuntimeError`.
198199

199-
Note that there is no need to call this function when
200-
:func:`asyncio.run` is used.
200+
.. note::
201+
202+
Do not call this method when using :func:`asyncio.run`,
203+
as the latter handles default executor shutdown automatically.
201204

202205
.. versionadded:: 3.9
203206

@@ -210,22 +213,23 @@ Scheduling callbacks
210213
Schedule the *callback* :term:`callback` to be called with
211214
*args* arguments at the next iteration of the event loop.
212215

216+
Return an instance of :class:`asyncio.Handle`,
217+
which can be used later to cancel the callback.
218+
213219
Callbacks are called in the order in which they are registered.
214220
Each callback will be called exactly once.
215221

216-
An optional keyword-only *context* argument allows specifying a
222+
The optional keyword-only *context* argument specifies a
217223
custom :class:`contextvars.Context` for the *callback* to run in.
218-
The current context is used when no *context* is provided.
219-
220-
An instance of :class:`asyncio.Handle` is returned, which can be
221-
used later to cancel the callback.
224+
Callbacks use the current context when no *context* is provided.
222225

223-
This method is not thread-safe.
226+
Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe.
224227

225228
.. method:: loop.call_soon_threadsafe(callback, *args, context=None)
226229

227-
A thread-safe variant of :meth:`call_soon`. Must be used to
228-
schedule callbacks *from another thread*.
230+
A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from
231+
another thread, this function *must* be used, since :meth:`call_soon` is not
232+
thread-safe.
229233

230234
Raises :exc:`RuntimeError` if called on a loop that's been closed.
231235
This can happen on a secondary thread when the main application is
@@ -506,8 +510,8 @@ Opening network connections
506510
When a server's IPv4 path and protocol are working, but the server's
507511
IPv6 path and protocol are not working, a dual-stack client
508512
application experiences significant connection delay compared to an
509-
IPv4-only client. This is undesirable because it causes the dual-
510-
stack client to have a worse user experience. This document
513+
IPv4-only client. This is undesirable because it causes the
514+
dual-stack client to have a worse user experience. This document
511515
specifies requirements for algorithms that reduce this user-visible
512516
delay and provides an algorithm.
513517

‎_sources/library/asyncio-stream.rst.txt

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -206,12 +206,20 @@ StreamReader
206206

207207
.. coroutinemethod:: read(n=-1)
208208

209-
Read up to *n* bytes. If *n* is not provided, or set to ``-1``,
210-
read until EOF and return all read bytes.
209+
Read up to *n* bytes from the stream.
211210

211+
If *n* is not provided or set to ``-1``,
212+
read until EOF, then return all read :class:`bytes`.
212213
If EOF was received and the internal buffer is empty,
213214
return an empty ``bytes`` object.
214215

216+
If *n* is ``0``, return an empty ``bytes`` object immediately.
217+
218+
If *n* is positive, return at most *n* available ``bytes``
219+
as soon as at least 1 byte is available in the internal buffer.
220+
If EOF is received before any byte is read, return an empty
221+
``bytes`` object.
222+
215223
.. coroutinemethod:: readline()
216224

217225
Read one line, where "line" is a sequence of bytes

‎_sources/library/asyncio-task.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1097,7 +1097,7 @@ Task Object
10971097
The *limit* argument is passed to :meth:`get_stack` directly.
10981098

10991099
The *file* argument is an I/O stream to which the output
1100-
is written; by default output is written to :data:`sys.stderr`.
1100+
is written; by default output is written to :data:`sys.stdout`.
11011101

11021102
.. method:: get_coro()
11031103

‎_sources/library/cmath.rst.txt

Lines changed: 38 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,27 @@ the function is then applied to the result of the conversion.
1515

1616
.. note::
1717

18-
On platforms with hardware and system-level support for signed
19-
zeros, functions involving branch cuts are continuous on *both*
20-
sides of the branch cut: the sign of the zero distinguishes one
21-
side of the branch cut from the other. On platforms that do not
22-
support signed zeros the continuity is as specified below.
18+
For functions involving branch cuts, we have the problem of deciding how to
19+
define those functions on the cut itself. Following Kahan's "Branch cuts for
20+
complex elementary functions" paper, as well as Annex G of C99 and later C
21+
standards, we use the sign of zero to distinguish one side of the branch cut
22+
from the other: for a branch cut along (a portion of) the real axis we look
23+
at the sign of the imaginary part, while for a branch cut along the
24+
imaginary axis we look at the sign of the real part.
25+
26+
For example, the :func:`cmath.sqrt` function has a branch cut along the
27+
negative real axis. An argument of ``complex(-2.0, -0.0)`` is treated as
28+
though it lies *below* the branch cut, and so gives a result on the negative
29+
imaginary axis::
30+
31+
>>> cmath.sqrt(complex(-2.0, -0.0))
32+
-1.4142135623730951j
33+
34+
But an argument of ``complex(-2.0, 0.0)`` is treated as though it lies above
35+
the branch cut::
36+
37+
>>> cmath.sqrt(complex(-2.0, 0.0))
38+
1.4142135623730951j
2339

2440

2541
Conversions to and from polar coordinates
@@ -44,14 +60,11 @@ rectangular coordinates to polar coordinates and back.
4460

4561
.. function:: phase(x)
4662

47-
Return the phase of *x* (also known as the *argument* of *x*), as a
48-
float. ``phase(x)`` is equivalent to ``math.atan2(x.imag,
49-
x.real)``. The result lies in the range [-\ *π*, *π*], and the branch
50-
cut for this operation lies along the negative real axis,
51-
continuous from above. On systems with support for signed zeros
52-
(which includes most systems in current use), this means that the
53-
sign of the result is the same as the sign of ``x.imag``, even when
54-
``x.imag`` is zero::
63+
Return the phase of *x* (also known as the *argument* of *x*), as a float.
64+
``phase(x)`` is equivalent to ``math.atan2(x.imag, x.real)``. The result
65+
lies in the range [-\ *π*, *π*], and the branch cut for this operation lies
66+
along the negative real axis. The sign of the result is the same as the
67+
sign of ``x.imag``, even when ``x.imag`` is zero::
5568

5669
>>> phase(complex(-1.0, 0.0))
5770
3.141592653589793
@@ -92,8 +105,8 @@ Power and logarithmic functions
92105
.. function:: log(x[, base])
93106

94107
Returns the logarithm of *x* to the given *base*. If the *base* is not
95-
specified, returns the natural logarithm of *x*. There is one branch cut, from 0
96-
along the negative real axis to -∞, continuous from above.
108+
specified, returns the natural logarithm of *x*. There is one branch cut,
109+
from 0 along the negative real axis to -∞.
97110

98111

99112
.. function:: log10(x)
@@ -112,9 +125,9 @@ Trigonometric functions
112125

113126
.. function:: acos(x)
114127

115-
Return the arc cosine of *x*. There are two branch cuts: One extends right from
116-
1 along the real axis to ∞, continuous from below. The other extends left from
117-
-1 along the real axis to -∞, continuous from above.
128+
Return the arc cosine of *x*. There are two branch cuts: One extends right
129+
from 1 along the real axis to ∞. The other extends left from -1 along the
130+
real axis to -∞.
118131

119132

120133
.. function:: asin(x)
@@ -125,9 +138,8 @@ Trigonometric functions
125138
.. function:: atan(x)
126139

127140
Return the arc tangent of *x*. There are two branch cuts: One extends from
128-
``1j`` along the imaginary axis to ``∞j``, continuous from the right. The
129-
other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
130-
from the left.
141+
``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j``
142+
along the imaginary axis to ``-∞j``.
131143

132144

133145
.. function:: cos(x)
@@ -151,23 +163,21 @@ Hyperbolic functions
151163
.. function:: acosh(x)
152164

153165
Return the inverse hyperbolic cosine of *x*. There is one branch cut,
154-
extending left from 1 along the real axis to -∞, continuous from above.
166+
extending left from 1 along the real axis to -∞.
155167

156168

157169
.. function:: asinh(x)
158170

159171
Return the inverse hyperbolic sine of *x*. There are two branch cuts:
160-
One extends from ``1j`` along the imaginary axis to ``∞j``,
161-
continuous from the right. The other extends from ``-1j`` along
162-
the imaginary axis to ``-∞j``, continuous from the left.
172+
One extends from ``1j`` along the imaginary axis to ``∞j``. The other
173+
extends from ``-1j`` along the imaginary axis to ``-∞j``.
163174

164175

165176
.. function:: atanh(x)
166177

167178
Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One
168-
extends from ``1`` along the real axis to ``∞``, continuous from below. The
169-
other extends from ``-1`` along the real axis to ``-∞``, continuous from
170-
above.
179+
extends from ``1`` along the real axis to ``∞``. The other extends from
180+
``-1`` along the real axis to ``-∞``.
171181

172182

173183
.. function:: cosh(x)

‎_sources/library/collections.abc.rst.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
This module provides :term:`abstract base classes <abstract base class>` that
2424
can be used to test whether a class provides a particular interface; for
25-
example, whether it is hashable or whether it is a mapping.
25+
example, whether it is :term:`hashable` or whether it is a mapping.
2626

2727
An :func:`issubclass` or :func:`isinstance` test for an interface works in one
2828
of three ways.
@@ -406,7 +406,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
406406
(3)
407407
The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
408408
for the set; however, :meth:`__hash__` is not defined because not all sets
409-
are hashable or immutable. To add set hashability using mixins,
409+
are :term:`hashable` or immutable. To add set hashability using mixins,
410410
inherit from both :meth:`Set` and :meth:`Hashable`, then define
411411
``__hash__ = Set._hash``.
412412

‎_sources/library/collections.rst.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Python's general purpose built-in containers, :class:`dict`, :class:`list`,
2525
:func:`namedtuple` factory function for creating tuple subclasses with named fields
2626
:class:`deque` list-like container with fast appends and pops on either end
2727
:class:`ChainMap` dict-like class for creating a single view of multiple mappings
28-
:class:`Counter` dict subclass for counting hashable objects
28+
:class:`Counter` dict subclass for counting :term:`hashable` objects
2929
:class:`OrderedDict` dict subclass that remembers the order entries were added
3030
:class:`defaultdict` dict subclass that calls a factory function to supply missing values
3131
:class:`UserDict` wrapper around dictionary objects for easier dict subclassing
@@ -241,7 +241,7 @@ For example::
241241

242242
.. class:: Counter([iterable-or-mapping])
243243

244-
A :class:`Counter` is a :class:`dict` subclass for counting hashable objects.
244+
A :class:`Counter` is a :class:`dict` subclass for counting :term:`hashable` objects.
245245
It is a collection where elements are stored as dictionary keys
246246
and their counts are stored as dictionary values. Counts are allowed to be
247247
any integer value including zero or negative counts. The :class:`Counter`

0 commit comments

Comments
 (0)