Skip to content

Commit 5db0d62

Browse files
mattwang44mattwang44
committed
Deploy preview for PR 1130 🛫
1 parent 9dae552 commit 5db0d62

File tree

575 files changed

+2349
-1961
lines changed

Some content is hidden

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

575 files changed

+2349
-1961
lines changed

‎pr-preview/pr-1130/_sources/c-api/memory.rst.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -656,6 +656,10 @@ This allocator is disabled if Python is configured with the
656656
:option:`--without-pymalloc` option. It can also be disabled at runtime using
657657
the :envvar:`PYTHONMALLOC` environment variable (ex: ``PYTHONMALLOC=malloc``).
658658
659+
Typically, it makes sense to disable the pymalloc allocator when building
660+
Python with AddressSanitizer (:option:`--with-address-sanitizer`) which helps
661+
uncover low level bugs within the C code.
662+
659663
Customize pymalloc Arena Allocator
660664
----------------------------------
661665

‎pr-preview/pr-1130/_sources/howto/free-threading-extensions.rst.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,8 @@ that return :term:`strong references <strong reference>`.
159159
+===================================+===================================+
160160
| :c:func:`PyList_GetItem` | :c:func:`PyList_GetItemRef` |
161161
+-----------------------------------+-----------------------------------+
162+
| :c:func:`PyList_GET_ITEM` | :c:func:`PyList_GetItemRef` |
163+
+-----------------------------------+-----------------------------------+
162164
| :c:func:`PyDict_GetItem` | :c:func:`PyDict_GetItemRef` |
163165
+-----------------------------------+-----------------------------------+
164166
| :c:func:`PyDict_GetItemWithError` | :c:func:`PyDict_GetItemRef` |

‎pr-preview/pr-1130/_sources/howto/logging.rst.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -302,10 +302,10 @@ reading the following sections. If you're ready for that, grab some of your
302302
favourite beverage and carry on.
303303

304304
If your logging needs are simple, then use the above examples to incorporate
305-
logging into your own scripts, and if you run into problems or don't
306-
understand something, please post a question on the comp.lang.python Usenet
307-
group (available at https://groups.google.com/g/comp.lang.python) and you
308-
should receive help before too long.
305+
logging into your own scripts, and if you run into problems or don't understand
306+
something, please post a question in the Help category of the `Python
307+
discussion forum <https://discuss.python.org/c/help/7>`_ and you should receive
308+
help before too long.
309309

310310
Still here? You can carry on reading the next few sections, which provide a
311311
slightly more advanced/in-depth tutorial than the basic one above. After that,

‎pr-preview/pr-1130/_sources/library/argparse.rst.txt

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -415,12 +415,18 @@ arguments they contain. For example::
415415
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
416416
Namespace(f='bar')
417417

418-
Arguments read from a file must by default be one per line (but see also
418+
Arguments read from a file must be one per line by default (but see also
419419
:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
420420
were in the same place as the original file referencing argument on the command
421421
line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
422422
is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
423423

424+
.. note::
425+
426+
Empty lines are treated as empty strings (``''``), which are allowed as values but
427+
not as arguments. Empty lines that are read as arguments will result in an
428+
"unrecognized arguments" error.
429+
424430
:class:`ArgumentParser` uses :term:`filesystem encoding and error handler`
425431
to read the file containing arguments.
426432

‎pr-preview/pr-1130/_sources/library/asyncio-eventloop.rst.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -595,6 +595,12 @@ Opening network connections
595595
to bind the socket locally. The *local_host* and *local_port*
596596
are looked up using :meth:`getaddrinfo`.
597597

598+
.. note::
599+
600+
On Windows, when using the proactor event loop with ``local_addr=None``,
601+
an :exc:`OSError` with :attr:`!errno.WSAEINVAL` will be raised
602+
when running it.
603+
598604
* *remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used
599605
to connect the socket to a remote address. The *remote_host* and
600606
*remote_port* are looked up using :meth:`getaddrinfo`.

‎pr-preview/pr-1130/_sources/library/asyncio-queue.rst.txt

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -102,17 +102,34 @@ Queue
102102

103103
.. method:: shutdown(immediate=False)
104104

105-
Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
105+
Put a :class:`Queue` instance into a shutdown mode.
106+
107+
The queue can no longer grow.
108+
Future calls to :meth:`~Queue.put` raise :exc:`QueueShutDown`.
109+
Currently blocked callers of :meth:`~Queue.put` will be unblocked
110+
and will raise :exc:`QueueShutDown` in the formerly blocked thread.
111+
112+
If *immediate* is false (the default), the queue can be wound
113+
down normally with :meth:`~Queue.get` calls to extract tasks
114+
that have already been loaded.
115+
116+
And if :meth:`~Queue.task_done` is called for each remaining task, a
117+
pending :meth:`~Queue.join` will be unblocked normally.
118+
119+
Once the queue is empty, future calls to :meth:`~Queue.get` will
106120
raise :exc:`QueueShutDown`.
107121

108-
By default, :meth:`~Queue.get` on a shut down queue will only
109-
raise once the queue is empty. Set *immediate* to true to make
110-
:meth:`~Queue.get` raise immediately instead.
122+
If *immediate* is true, the queue is terminated immediately.
123+
The queue is drained to be completely empty and the count
124+
of unfinished tasks is reduced by the number of tasks drained.
125+
If unfinished tasks is zero, callers of :meth:`~Queue.join`
126+
are unblocked. Also, blocked callers of :meth:`~Queue.get`
127+
are unblocked and will raise :exc:`QueueShutDown` because the
128+
queue is empty.
111129

112-
All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
113-
will be unblocked. If *immediate* is true, a task will be marked
114-
as done for each remaining item in the queue, which may unblock
115-
callers of :meth:`~Queue.join`.
130+
Use caution when using :meth:`~Queue.join` with *immediate* set
131+
to true. This unblocks the join even when no work has been done
132+
on the tasks, violating the usual invariant for joining a queue.
116133

117134
.. versionadded:: 3.13
118135

@@ -129,9 +146,6 @@ Queue
129146
call was received for every item that had been :meth:`~Queue.put`
130147
into the queue).
131148

132-
``shutdown(immediate=True)`` calls :meth:`task_done` for each
133-
remaining item in the queue.
134-
135149
Raises :exc:`ValueError` if called more times than there were
136150
items placed in the queue.
137151

‎pr-preview/pr-1130/_sources/library/codecs.rst.txt

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1472,6 +1472,36 @@ to :class:`bytes` mappings. They are not supported by :meth:`bytes.decode`
14721472
Restoration of the aliases for the binary transforms.
14731473

14741474

1475+
.. _standalone-codec-functions:
1476+
1477+
Standalone Codec Functions
1478+
^^^^^^^^^^^^^^^^^^^^^^^^^^
1479+
1480+
The following functions provide encoding and decoding functionality similar to codecs,
1481+
but are not available as named codecs through :func:`codecs.encode` or :func:`codecs.decode`.
1482+
They are used internally (for example, by :mod:`pickle`) and behave similarly to the
1483+
``string_escape`` codec that was removed in Python 3.
1484+
1485+
.. function:: codecs.escape_encode(input, errors=None)
1486+
1487+
Encode *input* using escape sequences. Similar to how :func:`repr` on bytes
1488+
produces escaped byte values.
1489+
1490+
*input* must be a :class:`bytes` object.
1491+
1492+
Returns a tuple ``(output, length)`` where *output* is a :class:`bytes`
1493+
object and *length* is the number of bytes consumed.
1494+
1495+
.. function:: codecs.escape_decode(input, errors=None)
1496+
1497+
Decode *input* from escape sequences back to the original bytes.
1498+
1499+
*input* must be a :term:`bytes-like object`.
1500+
1501+
Returns a tuple ``(output, length)`` where *output* is a :class:`bytes`
1502+
object and *length* is the number of bytes consumed.
1503+
1504+
14751505
.. _text-transforms:
14761506

14771507
Text Transforms

‎pr-preview/pr-1130/_sources/library/concurrent.futures.rst.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,11 @@ that :class:`ProcessPoolExecutor` will not work in the interactive interpreter.
243243
Calling :class:`Executor` or :class:`Future` methods from a callable submitted
244244
to a :class:`ProcessPoolExecutor` will result in deadlock.
245245

246+
Note that the restrictions on functions and arguments needing to picklable as
247+
per :class:`multiprocessing.Process` apply when using :meth:`~Executor.submit`
248+
and :meth:`~Executor.map` on a :class:`ProcessPoolExecutor`. A function defined
249+
in a REPL or a lambda should not be expected to work.
250+
246251
.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)
247252

248253
An :class:`Executor` subclass that executes calls asynchronously using a pool

‎pr-preview/pr-1130/_sources/library/ctypes.rst.txt

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -232,8 +232,24 @@ Fundamental data types
232232
+----------------------+------------------------------------------+----------------------------+
233233
| :class:`c_int` | :c:expr:`int` | int |
234234
+----------------------+------------------------------------------+----------------------------+
235+
| :class:`c_int8` | :c:type:`int8_t` | int |
236+
+----------------------+------------------------------------------+----------------------------+
237+
| :class:`c_int16` | :c:type:`int16_t` | int |
238+
+----------------------+------------------------------------------+----------------------------+
239+
| :class:`c_int32` | :c:type:`int32_t` | int |
240+
+----------------------+------------------------------------------+----------------------------+
241+
| :class:`c_int64` | :c:type:`int64_t` | int |
242+
+----------------------+------------------------------------------+----------------------------+
235243
| :class:`c_uint` | :c:expr:`unsigned int` | int |
236244
+----------------------+------------------------------------------+----------------------------+
245+
| :class:`c_uint8` | :c:type:`uint8_t` | int |
246+
+----------------------+------------------------------------------+----------------------------+
247+
| :class:`c_uint16` | :c:type:`uint16_t` | int |
248+
+----------------------+------------------------------------------+----------------------------+
249+
| :class:`c_uint32` | :c:type:`uint32_t` | int |
250+
+----------------------+------------------------------------------+----------------------------+
251+
| :class:`c_uint64` | :c:type:`uint64_t` | int |
252+
+----------------------+------------------------------------------+----------------------------+
237253
| :class:`c_long` | :c:expr:`long` | int |
238254
+----------------------+------------------------------------------+----------------------------+
239255
| :class:`c_ulong` | :c:expr:`unsigned long` | int |
@@ -2348,7 +2364,7 @@ These are the fundamental ctypes data types:
23482364

23492365
.. class:: c_int8
23502366

2351-
Represents the C 8-bit :c:expr:`signed int` datatype. Usually an alias for
2367+
Represents the C 8-bit :c:expr:`signed int` datatype. It is an alias for
23522368
:class:`c_byte`.
23532369

23542370

@@ -2423,7 +2439,7 @@ These are the fundamental ctypes data types:
24232439

24242440
.. class:: c_uint8
24252441

2426-
Represents the C 8-bit :c:expr:`unsigned int` datatype. Usually an alias for
2442+
Represents the C 8-bit :c:expr:`unsigned int` datatype. It is an alias for
24272443
:class:`c_ubyte`.
24282444

24292445

‎pr-preview/pr-1130/_sources/library/enum.rst.txt

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -504,16 +504,31 @@ Data Types
504504

505505
.. class:: StrEnum
506506

507-
``StrEnum`` is the same as :class:`Enum`, but its members are also strings and can be used
508-
in most of the same places that a string can be used. The result of any string
509-
operation performed on or with a *StrEnum* member is not part of the enumeration.
507+
*StrEnum* is the same as :class:`Enum`, but its members are also strings and
508+
can be used in most of the same places that a string can be used. The result
509+
of any string operation performed on or with a *StrEnum* member is not part
510+
of the enumeration.
511+
512+
>>> from enum import StrEnum, auto
513+
>>> class Color(StrEnum):
514+
... RED = 'r'
515+
... GREEN = 'g'
516+
... BLUE = 'b'
517+
... UNKNOWN = auto()
518+
...
519+
>>> Color.RED
520+
<Color.RED: 'r'>
521+
>>> Color.UNKNOWN
522+
<Color.UNKNOWN: 'unknown'>
523+
>>> str(Color.UNKNOWN)
524+
'unknown'
510525

511526
.. note::
512527

513528
There are places in the stdlib that check for an exact :class:`str`
514529
instead of a :class:`str` subclass (i.e. ``type(unknown) == str``
515530
instead of ``isinstance(unknown, str)``), and in those locations you
516-
will need to use ``str(StrEnum.member)``.
531+
will need to use ``str(MyStrEnum.MY_MEMBER)``.
517532

518533
.. note::
519534

0 commit comments

Comments
 (0)