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

0 commit comments

Comments
 (0)