Skip to content

Commit 5907823

Browse files
github-actions[bot]github-actions[bot]
committed
deploy: 4e1d98e 
1 parent ac2c3cc commit 5907823

File tree

594 files changed

+6491
-5618
lines changed

Some content is hidden

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

594 files changed

+6491
-5618
lines changed

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
5858
Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
5959
hexversion ``0x030a00f0``.
6060

61+
Use this for numeric comparisons, e.g. ``#if PY_VERSION_HEX >= ...``.
62+
6163
This version is also available via the symbol :data:`Py_Version`.
6264

6365
.. c:var:: const unsigned long Py_Version

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

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

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -940,7 +940,7 @@ code, or when embedding the Python interpreter:
940940
.. versionchanged:: 3.2
941941
This function cannot be called before :c:func:`Py_Initialize()` anymore.
942942
943-
.. deprecated-removed:: 3.9 3.11
943+
.. deprecated:: 3.9
944944
945945
.. index:: module: _thread
946946
@@ -954,7 +954,7 @@ code, or when embedding the Python interpreter:
954954
.. versionchanged:: 3.7
955955
The :term:`GIL` is now initialized by :c:func:`Py_Initialize()`.
956956
957-
.. deprecated-removed:: 3.9 3.11
957+
.. deprecated:: 3.9
958958
959959
960960
.. c:function:: PyThreadState* PyEval_SaveThread()

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
9393
underscores after a base specifier and between digits are ignored. If there
9494
are no digits, :exc:`ValueError` will be raised.
9595
96+
.. seealso:: Python methods :meth:`int.to_bytes` and :meth:`int.from_bytes`
97+
to convert a :c:type:`PyLongObject` to/from an array of bytes in base
98+
``256``. You can call those from C using :c:func:`PyObject_CallMethod`.
99+
96100
97101
.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
98102

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

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -247,29 +247,30 @@ Implementing functions and methods
247247
Structure used to describe a method of an extension type. This structure has
248248
four fields:
249249
250-
+------------------+---------------+-------------------------------+
251-
| Field | C Type | Meaning |
252-
+==================+===============+===============================+
253-
| :attr:`ml_name` | const char \* | name of the method |
254-
+------------------+---------------+-------------------------------+
255-
| :attr:`ml_meth` | PyCFunction | pointer to the C |
256-
| | | implementation |
257-
+------------------+---------------+-------------------------------+
258-
| :attr:`ml_flags` | int | flag bits indicating how the |
259-
| | | call should be constructed |
260-
+------------------+---------------+-------------------------------+
261-
| :attr:`ml_doc` | const char \* | points to the contents of the |
262-
| | | docstring |
263-
+------------------+---------------+-------------------------------+
250+
.. c:member:: const char* ml_name
251+
252+
name of the method
253+
254+
.. c:member:: PyCFunction ml_meth
255+
256+
pointer to the C implementation
257+
258+
.. c:member:: int ml_flags
259+
260+
flags bits indicating how the call should be constructed
261+
262+
.. c:member:: const char* ml_doc
263+
264+
points to the contents of the docstring
264265
265-
The :attr:`ml_meth` is a C function pointer. The functions may be of different
266+
The :c:member:`ml_meth` is a C function pointer. The functions may be of different
266267
types, but they always return :c:expr:`PyObject*`. If the function is not of
267268
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
268269
Even though :c:type:`PyCFunction` defines the first parameter as
269270
:c:expr:`PyObject*`, it is common that the method implementation uses the
270271
specific C type of the *self* object.
271272
272-
The :attr:`ml_flags` field is a bitfield which can include the following flags.
273+
The :c:member:`ml_flags` field is a bitfield which can include the following flags.
273274
The individual flags indicate either a calling convention or a binding
274275
convention.
275276

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -450,6 +450,7 @@ slot typedefs
450450
| | | |
451451
| | :c:type:`PyObject` * | |
452452
| | :c:type:`Py_ssize_t` | |
453+
| | :c:type:`PyObject` * | |
453454
+-----------------------------+-----------------------------+----------------------+
454455
| :c:type:`objobjproc` | .. line-block:: | int |
455456
| | | |
@@ -2589,7 +2590,7 @@ Slot Type typedefs
25892590
25902591
.. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t)
25912592
2592-
.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t)
2593+
.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *)
25932594
25942595
.. c:type:: int (*objobjproc)(PyObject *, PyObject *)
25952596

‎_sources/copyright.rst.txt

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

‎_sources/faq/general.rst.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -248,8 +248,8 @@ Are there any published articles about Python that I can reference?
248248

249249
It's probably best to cite your favorite book about Python.
250250

251-
The very first article about Python was written in 1991 and is now quite
252-
outdated.
251+
The `very first article <https://ir.cwi.nl/pub/18204>`_ about Python was
252+
written in 1991 and is now quite outdated.
253253

254254
Guido van Rossum and Jelke de Boer, "Interactively Testing Remote Servers
255255
Using the Python Programming Language", CWI Quarterly, Volume 4, Issue 4

‎_sources/faq/programming.rst.txt

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+
10271069
Performance
10281070
===========
10291071

‎_sources/howto/annotations.rst.txt

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
===================================================================

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

Lines changed: 33 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,7 @@ Suppose you configure logging with the following JSON:
307307
"class": "logging.StreamHandler",
308308
"level": "INFO",
309309
"formatter": "simple",
310-
"stream": "ext://sys.stdout",
310+
"stream": "ext://sys.stdout"
311311
},
312312
"stderr": {
313313
"class": "logging.StreamHandler",
@@ -1131,7 +1131,7 @@ each request is handled by a thread:
11311131
'context can be used to '
11321132
'populate logs')
11331133
aa = ap.add_argument
1134-
aa('--count', '-c', default=100, help='How many requests to simulate')
1134+
aa('--count', '-c', type=int, default=100, help='How many requests to simulate')
11351135
options = ap.parse_args()
11361136
11371137
# Create the dummy webapps and put them in a list which we can use to select
@@ -1982,26 +1982,47 @@ Using a rotator and namer to customize log rotation processing
19821982
--------------------------------------------------------------
19831983

19841984
An example of how you can define a namer and rotator is given in the following
1985-
snippet, which shows zlib-based compression of the log file::
1985+
runnable script, which shows gzip compression of the log file::
1986+
1987+
import gzip
1988+
import logging
1989+
import logging.handlers
1990+
import os
1991+
import shutil
19861992

19871993
def namer(name):
19881994
return name + ".gz"
19891995

19901996
def rotator(source, dest):
1991-
with open(source, "rb") as sf:
1992-
data = sf.read()
1993-
compressed = zlib.compress(data, 9)
1994-
with open(dest, "wb") as df:
1995-
df.write(compressed)
1997+
with open(source, 'rb') as f_in:
1998+
with gzip.open(dest, 'wb') as f_out:
1999+
shutil.copyfileobj(f_in, f_out)
19962000
os.remove(source)
19972001

1998-
rh = logging.handlers.RotatingFileHandler(...)
2002+
2003+
rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, backupCount=5)
19992004
rh.rotator = rotator
20002005
rh.namer = namer
20012006

2002-
These are not "true" .gz files, as they are bare compressed data, with no
2003-
"container" such as you’d find in an actual gzip file. This snippet is just
2004-
for illustration purposes.
2007+
root = logging.getLogger()
2008+
root.setLevel(logging.INFO)
2009+
root.addHandler(rh)
2010+
f = logging.Formatter('%(asctime)s %(message)s')
2011+
rh.setFormatter(f)
2012+
for i in range(1000):
2013+
root.info(f'Message no. {i + 1}')
2014+
2015+
After running this, you will see six new files, five of which are compressed:
2016+
2017+
.. code-block:: shell-session
2018+
2019+
$ ls rotated.log*
2020+
rotated.log rotated.log.2.gz rotated.log.4.gz
2021+
rotated.log.1.gz rotated.log.3.gz rotated.log.5.gz
2022+
$ zcat rotated.log.1.gz
2023+
2023-01-20 02:28:17,767 Message no. 996
2024+
2023-01-20 02:28:17,767 Message no. 997
2025+
2023-01-20 02:28:17,767 Message no. 998
20052026
20062027
A more elaborate multiprocessing example
20072028
----------------------------------------

‎_sources/library/argparse.rst.txt

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

756756
* type_ - The type to which the command-line argument should be converted.
757757

758-
* choices_ - A container of the allowable values for the argument.
758+
* choices_ - A sequence of the allowable values for the argument.
759759

760760
* required_ - Whether or not the command-line option may be omitted
761761
(optionals only).
@@ -1199,7 +1199,7 @@ choices
11991199
^^^^^^^
12001200

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

1216-
Note that inclusion in the *choices* container is checked after any type_
1216+
Note that inclusion in the *choices* sequence is checked after any type_
12171217
conversions have been performed, so the type of the objects in the *choices*
1218-
container should match the type_ specified::
1218+
sequence should match the type_ specified::
12191219

12201220
>>> parser = argparse.ArgumentParser(prog='doors.py')
12211221
>>> parser.add_argument('door', type=int, choices=range(1, 4))
@@ -1225,8 +1225,8 @@ container should match the type_ specified::
12251225
usage: doors.py [-h] {1,2,3}
12261226
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
12271227

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

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

0 commit comments

Comments
 (0)