Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b174735

Browse files
smontanarosmontanaro
authored
Merge branch 'main' into gh-25949 
2 parents 5cc4aa4 + 9a91182 commit b174735

109 files changed

Lines changed: 6808 additions & 1875 deletions

File tree

Some content is hidden

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

‎Doc/c-api/function.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,63 @@ There are a few functions specific to Python functions.
118118
must be a dictionary or ``Py_None``.
119119
120120
Raises :exc:`SystemError` and returns ``-1`` on failure.
121+
122+
123+
.. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
124+
125+
Register *callback* as a function watcher for the current interpreter.
126+
Return an ID which may be passed to :c:func:`PyFunction_ClearWatcher`.
127+
In case of error (e.g. no more watcher IDs available),
128+
return ``-1`` and set an exception.
129+
130+
.. versionadded:: 3.12
131+
132+
133+
.. c:function:: int PyFunction_ClearWatcher(int watcher_id)
134+
135+
Clear watcher identified by *watcher_id* previously returned from
136+
:c:func:`PyFunction_AddWatcher` for the current interpreter.
137+
Return ``0`` on success, or ``-1`` and set an exception on error
138+
(e.g. if the given *watcher_id* was never registered.)
139+
140+
.. versionadded:: 3.12
141+
142+
143+
.. c:type:: PyFunction_WatchEvent
144+
145+
Enumeration of possible function watcher events:
146+
- ``PyFunction_EVENT_CREATE``
147+
- ``PyFunction_EVENT_DESTROY``
148+
- ``PyFunction_EVENT_MODIFY_CODE``
149+
- ``PyFunction_EVENT_MODIFY_DEFAULTS``
150+
- ``PyFunction_EVENT_MODIFY_KWDEFAULTS``
151+
152+
.. versionadded:: 3.12
153+
154+
155+
.. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
156+
157+
Type of a function watcher callback function.
158+
159+
If *event* is ``PyFunction_EVENT_CREATE`` or ``PyFunction_EVENT_DESTROY``
160+
then *new_value* will be ``NULL``. Otherwise, *new_value* will hold a
161+
:term:`borrowed reference` to the new value that is about to be stored in
162+
*func* for the attribute that is being modified.
163+
164+
The callback may inspect but must not modify *func*; doing so could have
165+
unpredictable effects, including infinite recursion.
166+
167+
If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked
168+
after `func` has been fully initialized. Otherwise, the callback is invoked
169+
before the modification to *func* takes place, so the prior state of *func*
170+
can be inspected. The runtime is permitted to optimize away the creation of
171+
function objects when possible. In such cases no event will be emitted.
172+
Although this creates the possitibility of an observable difference of
173+
runtime behavior depending on optimization decisions, it does not change
174+
the semantics of the Python code being executed.
175+
176+
If the callback returns with an exception set, it must return ``-1``; this
177+
exception will be printed as an unraisable exception using
178+
:c:func:`PyErr_WriteUnraisable`. Otherwise it should return ``0``.
179+
180+
.. versionadded:: 3.12

‎Doc/c-api/structures.rst‎

Lines changed: 184 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -385,100 +385,223 @@ Accessing attributes of extension types
385385
.. c:type:: PyMemberDef
386386
387387
Structure which describes an attribute of a type which corresponds to a C
388-
struct member. Its fields are:
388+
struct member. Its fields are, in order:
389389
390-
.. c:member:: const char* PyMemberDef.name
390+
.. c:member:: const char* name
391391
392-
Name of the member
392+
Name of the member.
393+
A NULL value marks the end of a ``PyMemberDef[]`` array.
393394
394-
.. c:member:: int PyMemberDef.type
395-
396-
The type of the member in the C struct.
395+
The string should be static, no copy is made of it.
397396
398397
.. c:member:: Py_ssize_t PyMemberDef.offset
399398
400399
The offset in bytes that the member is located on the type’s object struct.
401400
402-
.. c:member:: int PyMemberDef.flags
403-
404-
Flag bits indicating if the field should be read-only or writable.
405-
406-
.. c:member:: const char* PyMemberDef.doc
407-
408-
Points to the contents of the docstring.
409-
410-
:c:member:`PyMemberDef.type` can be one of many ``T_`` macros corresponding to various C
411-
types. When the member is accessed in Python, it will be converted to the
412-
equivalent Python type.
413-
414-
=============== ==================
415-
Macro name C type
416-
=============== ==================
417-
T_SHORT short
418-
T_INT int
419-
T_LONG long
420-
T_FLOAT float
421-
T_DOUBLE double
422-
T_STRING const char \*
423-
T_OBJECT PyObject \*
424-
T_OBJECT_EX PyObject \*
425-
T_CHAR char
426-
T_BYTE char
427-
T_UBYTE unsigned char
428-
T_UINT unsigned int
429-
T_USHORT unsigned short
430-
T_ULONG unsigned long
431-
T_BOOL char
432-
T_LONGLONG long long
433-
T_ULONGLONG unsigned long long
434-
T_PYSSIZET Py_ssize_t
435-
=============== ==================
436-
437-
:c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
438-
:c:macro:`T_OBJECT` returns ``None`` if the member is ``NULL`` and
439-
:c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
440-
:c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
441-
handles use of the :keyword:`del` statement on that attribute more correctly
442-
than :c:macro:`T_OBJECT`.
443-
444-
:c:member:`PyMemberDef.flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
445-
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
446-
:c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8.
447-
Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
448-
members can be deleted. (They are set to ``NULL``).
401+
.. c:member:: int type
402+
403+
The type of the member in the C struct.
404+
See :ref:`PyMemberDef-types` for the possible values.
405+
406+
.. c:member:: int flags
407+
408+
Zero or more of the :ref:`PyMemberDef-flags`, combined using bitwise OR.
409+
410+
.. c:member:: const char* doc
411+
412+
The docstring, or NULL.
413+
The string should be static, no copy is made of it.
414+
Typically, it is defined using :c:macro:`PyDoc_STR`.
415+
416+
By default (when :c:member:`flags` is ``0``), members allow
417+
both read and write access.
418+
Use the :c:macro:`Py_READONLY` flag for read-only access.
419+
Certain types, like :c:macro:`Py_T_STRING`, imply :c:macro:`Py_READONLY`.
420+
Only :c:macro:`Py_T_OBJECT_EX` (and legacy :c:macro:`T_OBJECT`) members can
421+
be deleted.
449422
450423
.. _pymemberdef-offsets:
451424
452-
Heap allocated types (created using :c:func:`PyType_FromSpec` or similar),
453-
``PyMemberDef`` may contain definitions for the special member
454-
``__vectorcalloffset__``, corresponding to
425+
For heap-allocated types (created using :c:func:`PyType_FromSpec` or similar),
426+
``PyMemberDef`` may contain a definition for the special member
427+
``"__vectorcalloffset__"``, corresponding to
455428
:c:member:`~PyTypeObject.tp_vectorcall_offset` in type objects.
456-
These must be defined with ``T_PYSSIZET`` and ``READONLY``, for example::
429+
These must be defined with ``Py_T_PYSSIZET`` and ``Py_READONLY``, for example::
457430
458431
static PyMemberDef spam_type_members[] = {
459-
{"__vectorcalloffset__", T_PYSSIZET, offsetof(Spam_object, vectorcall), READONLY},
432+
{"__vectorcalloffset__", Py_T_PYSSIZET,
433+
offsetof(Spam_object, vectorcall), Py_READONLY},
460434
{NULL} /* Sentinel */
461435
};
462436
437+
(You may need to ``#include <stddef.h>`` for :c:func:`!offsetof`.)
438+
463439
The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and
464-
:c:member:`~PyTypeObject.tp_weaklistoffset` are still supported, but extensions are
465-
strongly encouraged to use ``Py_TPFLAGS_MANAGED_DICT`` and
466-
``Py_TPFLAGS_MANAGED_WEAKREF`` instead.
440+
:c:member:`~PyTypeObject.tp_weaklistoffset` can be defined similarly using
441+
``"__dictoffset__"`` and ``"__weaklistoffset__"`` members, but extensions
442+
are strongly encouraged to use :const:`Py_TPFLAGS_MANAGED_DICT` and
443+
:const:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
467444
445+
.. versionchanged:: 3.12
446+
447+
``PyMemberDef`` is always available.
448+
Previously, it required including ``"structmember.h"``.
468449
469450
.. c:function:: PyObject* PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)
470451
471452
Get an attribute belonging to the object at address *obj_addr*. The
472453
attribute is described by ``PyMemberDef`` *m*. Returns ``NULL``
473454
on error.
474455
456+
.. versionchanged:: 3.12
457+
458+
``PyMember_GetOne`` is always available.
459+
Previously, it required including ``"structmember.h"``.
475460
476461
.. c:function:: int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
477462
478463
Set an attribute belonging to the object at address *obj_addr* to object *o*.
479464
The attribute to set is described by ``PyMemberDef`` *m*. Returns ``0``
480465
if successful and a negative value on failure.
481466
467+
.. versionchanged:: 3.12
468+
469+
``PyMember_SetOne`` is always available.
470+
Previously, it required including ``"structmember.h"``.
471+
472+
.. _PyMemberDef-flags:
473+
474+
Member flags
475+
^^^^^^^^^^^^
476+
477+
The following flags can be used with :c:member:`PyMemberDef.flags`:
478+
479+
.. c:macro:: Py_READONLY
480+
481+
Not writable.
482+
483+
.. c:macro:: Py_AUDIT_READ
484+
485+
Emit an ``object.__getattr__`` :ref:`audit event <audit-events>`
486+
before reading.
487+
488+
.. index::
489+
single: READ_RESTRICTED
490+
single: WRITE_RESTRICTED
491+
single: RESTRICTED
492+
493+
.. versionchanged:: 3.10
494+
495+
The :const:`!RESTRICTED`, :const:`!READ_RESTRICTED` and
496+
:const:`!WRITE_RESTRICTED` macros available with
497+
``#include "structmember.h"`` are deprecated.
498+
:const:`!READ_RESTRICTED` and :const:`!RESTRICTED` are equivalent to
499+
:const:`Py_AUDIT_READ`; :const:`!WRITE_RESTRICTED` does nothing.
500+
501+
.. index::
502+
single: READONLY
503+
504+
.. versionchanged:: 3.12
505+
506+
The :const:`!READONLY` macro was renamed to :const:`Py_READONLY`.
507+
The :const:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
508+
The new names are now always available.
509+
Previously, these required ``#include "structmember.h"``.
510+
The header is still available and it provides the old names.
511+
512+
.. _PyMemberDef-types:
513+
514+
Member types
515+
^^^^^^^^^^^^
516+
517+
:c:member:`PyMemberDef.type` can be one of the following macros corresponding
518+
to various C types.
519+
When the member is accessed in Python, it will be converted to the
520+
equivalent Python type.
521+
When it is set from Python, it will be converted back to the C type.
522+
If that is not possible, an exception such as :exc:`TypeError` or
523+
:exc:`ValueError` is raised.
524+
525+
Unless marked (D), attributes defined this way cannot be deleted
526+
using e.g. :keyword:`del` or :py:func:`delattr`.
527+
528+
================================ ============================= ======================
529+
Macro name C type Python type
530+
================================ ============================= ======================
531+
.. c:macro:: Py_T_BYTE :c:expr:`char` :py:class:`int`
532+
.. c:macro:: Py_T_SHORT :c:expr:`short` :py:class:`int`
533+
.. c:macro:: Py_T_INT :c:expr:`int` :py:class:`int`
534+
.. c:macro:: Py_T_LONG :c:expr:`long` :py:class:`int`
535+
.. c:macro:: Py_T_LONGLONG :c:expr:`long long` :py:class:`int`
536+
.. c:macro:: Py_T_UBYTE :c:expr:`unsigned char` :py:class:`int`
537+
.. c:macro:: Py_T_UINT :c:expr:`unsigned int` :py:class:`int`
538+
.. c:macro:: Py_T_USHORT :c:expr:`unsigned short` :py:class:`int`
539+
.. c:macro:: Py_T_ULONG :c:expr:`unsigned long` :py:class:`int`
540+
.. c:macro:: Py_T_ULONGLONG :c:expr:`unsigned long long` :py:class:`int`
541+
.. c:macro:: Py_T_PYSSIZET :c:expr:`Py_ssize_t` :py:class:`int`
542+
.. c:macro:: Py_T_FLOAT :c:expr:`float` :py:class:`float`
543+
.. c:macro:: Py_T_DOUBLE :c:expr:`double` :py:class:`float`
544+
.. c:macro:: Py_T_BOOL :c:expr:`char` :py:class:`bool`
545+
(written as 0 or 1)
546+
.. c:macro:: Py_T_STRING :c:expr:`const char *` (*) :py:class:`str` (RO)
547+
.. c:macro:: Py_T_STRING_INPLACE :c:expr:`const char[]` (*) :py:class:`str` (RO)
548+
.. c:macro:: Py_T_CHAR :c:expr:`char` (0-127) :py:class:`str` (**)
549+
.. c:macro:: Py_T_OBJECT_EX :c:expr:`PyObject *` :py:class:`object` (D)
550+
================================ ============================= ======================
551+
552+
(*): Zero-terminated, UTF8-encoded C string.
553+
With :c:macro:`!Py_T_STRING` the C representation is a pointer;
554+
with :c:macro:`!Py_T_STRING_INLINE` the string is stored directly
555+
in the structure.
556+
557+
(**): String of length 1. Only ASCII is accepted.
558+
559+
(RO): Implies :c:macro:`Py_READONLY`.
560+
561+
(D): Can be deleted, in which case the pointer is set to ``NULL``.
562+
Reading a ``NULL`` pointer raises :py:exc:`AttributeError`.
563+
564+
.. index::
565+
single: T_BYTE
566+
single: T_SHORT
567+
single: T_INT
568+
single: T_LONG
569+
single: T_LONGLONG
570+
single: T_UBYTE
571+
single: T_USHORT
572+
single: T_UINT
573+
single: T_ULONG
574+
single: T_ULONGULONG
575+
single: T_PYSSIZET
576+
single: T_FLOAT
577+
single: T_DOUBLE
578+
single: T_BOOL
579+
single: T_CHAR
580+
single: T_STRING
581+
single: T_STRING_INPLACE
582+
single: T_OBJECT_EX
583+
single: structmember.h
584+
585+
.. versionadded:: 3.12
586+
587+
In previous versions, the macros were only available with
588+
``#include "structmember.h"`` and were named without the ``Py_`` prefix
589+
(e.g. as ``T_INT``).
590+
The header is still available and contains the old names, along with
591+
the following deprecated types:
592+
593+
.. c:macro:: T_OBJECT
594+
595+
Like ``Py_T_OBJECT_EX``, but ``NULL`` is converted to ``None``.
596+
This results in surprising behavior in Python: deleting the attribute
597+
effectively sets it to ``None``.
598+
599+
.. c:macro:: T_NONE
600+
601+
Always ``None``. Must be used with :c:macro:`Py_READONLY`.
602+
603+
Defining Getters and Setters
604+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
482605
483606
.. c:type:: PyGetSetDef
484607

‎Doc/data/stable_abi.dat‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Doc/extending/newtypes.rst‎

Lines changed: 4 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -286,36 +286,11 @@ be read-only or read-write. The structures in the table are defined as::
286286

287287
For each entry in the table, a :term:`descriptor` will be constructed and added to the
288288
type which will be able to extract a value from the instance structure. The
289-
:attr:`type` field should contain one of the type codes defined in the
290-
:file:`structmember.h` header; the value will be used to determine how to
289+
:attr:`type` field should contain a type code like :c:macro:`Py_T_INT` or
290+
:c:macro:`Py_T_DOUBLE`; the value will be used to determine how to
291291
convert Python values to and from C values. The :attr:`flags` field is used to
292-
store flags which control how the attribute can be accessed.
293-
294-
The following flag constants are defined in :file:`structmember.h`; they may be
295-
combined using bitwise-OR.
296-
297-
+---------------------------+----------------------------------------------+
298-
| Constant | Meaning |
299-
+===========================+==============================================+
300-
| :const:`READONLY` | Never writable. |
301-
+---------------------------+----------------------------------------------+
302-
| :const:`PY_AUDIT_READ` | Emit an ``object.__getattr__`` |
303-
| | :ref:`audit events <audit-events>` before |
304-
| | reading. |
305-
+---------------------------+----------------------------------------------+
306-
307-
.. versionchanged:: 3.10
308-
:const:`RESTRICTED`, :const:`READ_RESTRICTED` and :const:`WRITE_RESTRICTED`
309-
are deprecated. However, :const:`READ_RESTRICTED` is an alias for
310-
:const:`PY_AUDIT_READ`, so fields that specify either :const:`RESTRICTED`
311-
or :const:`READ_RESTRICTED` will also raise an audit event.
312-
313-
.. index::
314-
single: READONLY
315-
single: READ_RESTRICTED
316-
single: WRITE_RESTRICTED
317-
single: RESTRICTED
318-
single: PY_AUDIT_READ
292+
store flags which control how the attribute can be accessed: you can set it to
293+
:c:macro:`Py_READONLY` to prevent Python code from setting it.
319294

320295
An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table to build
321296
descriptors that are used at runtime is that any attribute defined this way can

0 commit comments

Comments
 (0)