8000 Merge branch 'main' into complex-cov · python/cpython@e2bdcec · GitHub
[go: up one dir, main page]
Skip to content

Commit e2bdcec

Browse files
skirpichevskirpichev
committed
Merge branch 'main' into complex-cov
2 parents 86c3647 + e954ac7 commit e2bdcec

File tree

325 files changed

+12808
-8515
lines changed

Some content is hidden

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

325 files changed

+12808
-8515
lines changed

‎.github/CODEOWNERS

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,18 @@ Objects/type* @markshannon
2828
Objects/codeobject.c @markshannon
2929
Objects/frameobject.c @markshannon
3030
Objects/call.c @markshannon
31-
Python/ceval.c @markshannon
31+
Python/ceval*.c @markshannon @gvanrossum
32+
Python/ceval*.h @markshannon @gvanrossum
3233
Python/compile.c @markshannon @iritkatriel
3334
Python/assemble.c @markshannon @iritkatriel
3435
Python/flowgraph.c @markshannon @iritkatriel
3536
Python/ast_opt.c @isidentical
37+
Python/bytecodes.c @markshannon @gvanrossum
38+
Python/optimizer*.c @markshannon @gvanrossum
3639
Lib/test/test_patma.py @brandtbucher
3740
Lib/test/test_peepholer.py @brandtbucher
3841
Lib/test/test_type_*.py @JelleZijlstra
42+
Lib/test/test_capi/test_misc.py @markshannon @gvanrossum
3943

4044
# Exceptions
4145
Lib/traceback.py @iritkatriel
@@ -102,6 +106,9 @@ Include/internal/pycore_time.h @pganssle @abalkin
102106
/Lib/tokenize.py @pablogsal @lysnikolaou
103107
/Lib/test/test_tokenize.py @pablogsal @lysnikolaou
104108

109+
# Code generator
110+
/Tools/cases_generator/ @gvanrossum
111+
105112
# AST
106113
Python/ast.c @isidentical
107114
Parser/asdl.py @isidentical
@@ -151,7 +158,7 @@ Doc/c-api/stable.rst @encukou
151158

152159
**/*idlelib* @terryjreedy
153160

154-
**/*typing* @gvanrossum @JelleZijlstra @AlexWaygood
161+
**/*typing* @JelleZijlstra @AlexWaygood
155162

156163
**/*ftplib @giampaolo
157164
**/*shutil @giampaolo

‎Doc/c-api/bool.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,19 +26,19 @@ are available, however.
2626
.. c:var:: PyObject* Py_False
2727
2828
The Python ``False`` object. This object has no methods and is
29-
`immortal <https://peps.python.org/pep-0683/>`_.
29+
:term:`immortal`.
3030
31-
.. versionchanged:: 3.12
32-
:c:data:`Py_False` is immortal.
31+
.. versionchanged:: 3.12
32+
:c:data:`Py_False` is :term:`immortal`.
3333
3434
3535
.. c:var:: PyObject* Py_True
3636
3737
The Python ``True`` object. This object has no methods and is
38-
`immortal <https://peps.python.org/pep-0683/>`_.
38+
:term:`immortal`.
3939
40-
.. versionchanged:: 3.12
41-
:c:data:`Py_True` is immortal.
40+
.. versionchanged:: 3.12
41+
:c:data:`Py_True` is :term:`immortal`.
4242
4343
4444
.. c:macro:: Py_RETURN_FALSE

‎Doc/c-api/init.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1485,7 +1485,7 @@ otherwise immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared
14851485
because of the refcount. One simple but less-efficient approach around
14861486
this is to use a global lock around all use of some state (or object).
14871487
Alternately, effectively immutable objects (like integers or strings)
1488-
can be made safe in spite of their refcounts by making them "immortal".
1488+
can be made safe in spite of their refcounts by making them :term:`immortal`.
14891489
In fact, this has been done for the builtin singletons, small integers,
14901490
and a number of other builtin objects.
14911491

‎Doc/c-api/init_config.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1170,7 +1170,7 @@ PyConfig
11701170
11711171
.. c:member:: int show_ref_count
11721172
1173-
Show total reference count at exit (excluding immortal objects)?
1173+
Show total reference count at exit (excluding :term:`immortal` objects)?
11741174
11751175
Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
11761176

‎Doc/c-api/none.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,10 @@ same reason.
1616
.. c:var:: PyObject* Py_None
1717
1818
The Python ``None`` object, denoting lack of value. This object has no methods
19-
and is `immortal <https://peps.python.org/pep-0683/>`_.
19+
and is :term:`immortal`.
2020

21-
.. versionchanged:: 3.12
22-
:c:data:`Py_None` is immortal.
21+
.. versionchanged:: 3.12
22+
:c:data:`Py_None` is :term:`immortal`.
2323

2424
.. c:macro:: Py_RETURN_NONE
2525

‎Doc/c-api/refcounting.rst

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ of Python objects.
1717
1818
Note that the returned value may not actually reflect how many
1919
references to the object are actually held. For example, some
20-
objects are "immortal" and have a very high refcount that does not
20+
objects are :term:`immortal` and have a very high refcount that does not
2121
reflect the actual number of references. Consequently, do not rely
2222
on the returned value to be accurate, other than a value of 0 or 1.
2323
@@ -34,9 +34,7 @@ of Python objects.
3434
3535
Set the object *o* reference counter to *refcnt*.
3636
37-
Note that this function has no effect on
38-
`immortal <https://peps.python.org/pep-0683/>`_
39-
objects.
37+
This function has no effect on :term:`immortal` objects.
4038
4139
.. versionadded:: 3.9
4240
@@ -49,6 +47,8 @@ of Python objects.
4947
Indicate taking a new :term:`strong reference` to object *o*,
5048
indicating it is in use and should not be destroyed.
5149
50+
This function has no effect on :term:`immortal` objects.
51+
5252
This function is usually used to convert a :term:`borrowed reference` to a
5353
:term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be
5454
used to create a new :term:`strong reference`.
@@ -113,6 +113,8 @@ of Python objects.
113113
Release a :term:`strong reference` to object *o*, indicating the
114114
reference is no longer used.
115115
116+
This function has no effect on :term:`immortal` objects.
117+
116118
Once the last :term:`strong reference` is released
117119
(i.e. the object's reference count reaches 0),
118120
the object's type's deallocation

‎Doc/c-api/set.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
147147
148148
Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
149149
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
150-
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
150+
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~frozenset.discard`
151151
method, this function does not automatically convert unhashable sets into
152152
temporary frozensets. Raise :exc:`SystemError` if *set* is not an
153153
instance of :class:`set` or its subtype.

‎Doc/c-api/slice.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,7 @@ Ellipsis Object
119119
.. c:var:: PyObject *Py_Ellipsis
120120
121121
The Python ``Ellipsis`` object. This object has no methods. Like
122-
:c:data:`Py_None`, it is an `immortal <https://peps.python.org/pep-0683/>`_.
123-
singleton object.
122+
:c:data:`Py_None`, it is an :term:`immortal` singleton object.
124123
125124
.. versionchanged:: 3.12
126125
:c:data:`Py_Ellipsis` is immortal.

‎Doc/extending/newtypes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table
296296
descriptors that are used at runtime is that any attribute defined this way can
297297
have an associated doc string simply by providing the text in the table. An
298298
application can use the introspection API to retrieve the descriptor from the
299-
class object, and get the doc string using its :attr:`__doc__` attribute.
299+< F438 /span>
class object, and get the doc string using its :attr:`!__doc__` attribute.
300300

301301
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
302302
of ``NULL`` is required.

‎Doc/glossary.rst

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -579,6 +579,16 @@ Glossary
579579
:ref:`idle` is a basic editor and interpreter environment
580580
which ships with the standard distribution of Python.
581581

582+
immortal
583+
If an object is immortal, its reference count is never modified, and
584+
therefore it is never deallocated.
585+
586+
Built-in strings and singletons are immortal objects. For example,
587+
:const:`True` and :const:`None` singletons are immmortal.
588+
589+
See `PEP 683 – Immortal Objects, Using a Fixed Refcount
590+
<https://peps.python.org/pep-0683/>`_ for more information.
591+
582592
immutable
583593
An object with a fixed value. Immutable objects include numbers, strings and
584594
tuples. Such an object cannot be altered. A new object has to
@@ -1056,7 +1066,7 @@ Glossary
10561066
reference count
10571067
The number of references to an object. When the reference count of an
10581068
object drops to zero, it is deallocated. Some objects are
1059-
"immortal" and have reference counts that are never modified, and
1069+
:term:`immortal` and have reference counts that are never modified, and
10601070
therefore the objects are never deallocated. Reference counting is
10611071
generally not visible to Python code, but it is a key element of the
10621072
:term:`CPython` implementation. Programmers can call the

‎Doc/howto/descriptor.rst

Lines changed: 43 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -521,11 +521,11 @@ everyday Python programs.
521521
Descriptor protocol
522522
-------------------
523523

524-
``descr.__get__(self, obj, type=None) -> value``
524+
``descr.__get__(self, obj, type=None)``
525525

526-
``descr.__set__(self, obj, value) -> None``
526+
``descr.__set__(self, obj, value)``
527527

528-
``descr.__delete__(self, obj) -> None``
528+
``descr.__delete__(self, obj)``
529529

530530
That is all there is to it. Define any of these methods and an object is
531531
considered a descriptor and can override default behavior upon being looked up
@@ -1013,17 +1013,23 @@ here is a pure Python equivalent:
10131013
if obj is None:
10141014
return self
10151015
if self.fget is None:
1016-
raise AttributeError(f"property '{self._name}' has no getter")
1016+
raise AttributeError(
1017+
f'property {self._name!r} of {type(obj).__name__!r} object has no getter'
1018+
)
10171019
return self.fget(obj)
10181020

10191021
def __set__(self, obj, value):
10201022
if self.fset is None:
1021-
raise AttributeError(f"property '{self._name}' has no setter")
1023+
raise AttributeError(
1024+
f'property {self._name!r} of {type(obj).__name__!r} object has no setter'
1025+
)
10221026
self.fset(obj, value)
10231027

10241028
def __delete__(self, obj):
10251029
if self.fdel is None:
1026-
raise AttributeError(f"property '{self._name}' has no deleter")
1030+
raise AttributeError(
1031+
f'property {self._name!r} of {type(obj).__name__!r} object has no deleter'
1032+
)
10271033
self.fdel(obj)
10281034

10291035
def getter(self, fget):
@@ -1054,6 +1060,11 @@ here is a pure Python equivalent:
10541060
def delx(self):
10551061
del self.__x
10561062
x = Property(getx, setx, delx, "I'm the 'x' property.")
1063+
no_getter = Property(None, setx, delx, "I'm the 'x' property.")
1064+
no_setter = Property(getx, None, delx, "I'm the 'x' property.")
1065+
no_deleter = Property(getx, setx, None, "I'm the 'x' property.")
1066+
no_doc = Property(getx, setx, delx, None)
1067+
10571068

10581069
# Now do it again but use the decorator style
10591070

@@ -1092,6 +1103,32 @@ here is a pure Python equivalent:
10921103
>>> hasattr(ccc, 'x')
10931104
False
10941105

1106+
>>> cc = CC()
1107+
>>> cc.x = 33
1108+
>>> try:
1109+
... cc.no_getter
1110+
... except AttributeError as e:
1111+
... e.args[0]
1112+
...
1113+
"property 'no_getter' of 'CC' object has no getter"
1114+
1115+
>>> try:
1116+
... cc.no_setter = 33
1117+
... except AttributeError as e:
1118+
... e.args[0]
1119+
...
1120+
"property 'no_setter' of 'CC' object has no setter"
1121+
1122+
>>> try:
1123+
... del cc.no_deleter
1124+
... except AttributeError as e:
1125+
... e.args[0]
1126+
...
1127+
"property 'no_deleter' of 'CC' object has no deleter"
1128+
1129+
>>> CC.no_doc.__doc__ is None
1130+
True
1131+
10951132
The :func:`property` builtin helps whenever a user interface has granted
10961133
attribute access and then subsequent changes require the intervention of a
10971134
method.

‎Doc/howto/isolating-extensions.rst

Lines changed: 97 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -339,12 +339,44 @@ That is, heap types should:
339339
- Define a traverse function using ``Py_tp_traverse``, which
340340
visits the type (e.g. using :c:expr:`Py_VISIT(Py_TYPE(self))`).
341341

342-
Please refer to the :ref:`the documentation <type-structs>` of
342+
Please refer to the the documentation of
343343
:c:macro:`Py_TPFLAGS_HAVE_GC` and :c:member:`~PyTypeObject.tp_traverse`
344344
for additional considerations.
345345

346-
If your traverse function delegates to the ``tp_traverse`` of its base class
347-
(or another type), ensure that ``Py_TYPE(self)`` is visited only once.
346+
The API for defining heap types grew organically, leaving it
347+
somewhat awkward to use in its current state.
348+
The following sections will guide you through common issues.
349+
350+
351+
``tp_traverse`` in Python 3.8 and lower
352+
.......................................
353+
354+
The requirement to visit the type from ``tp_traverse`` was added in Python 3.9.
355+
If you support Python 3.8 and lower, the traverse function must *not*
356+
visit the type, so it must be more complicated::
357+
358+
static int my_traverse(PyObject *self, visitproc visit, void *arg)
359+
{
360+
if (Py_Version >= 0x03090000) {
361+
Py_VISIT(Py_TYPE(self));
362+
}
363+
return 0;
364+
}
365+
366+
Unfortunately, :c:data:`Py_Version` was only added in Python 3.11.
367+
As a replacement, use:
368+
369+
* :c:macro:`PY_VERSION_HEX`, if not using the stable ABI, or
370+
* :py:data:`sys.version_info` (via :c:func:`PySys_GetObject` and
371+
:c:func:`PyArg_ParseTuple`).
372+
373+
374+
Delegating ``tp_traverse``
375+
..........................
376+
377+
If your traverse function delegates to the :c:member:`~PyTypeObject.tp_traverse`
378+
of its base class (or another type), ensure that ``Py_TYPE(self)`` is visited
379+
only once.
348380
Note that only heap type are expected to visit the type in ``tp_traverse``.
349381

350382
For example, if your traverse function includes::
@@ -356,11 +388,70 @@ For example, if your traverse function includes::
356388
if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
357389
// a heap type's tp_traverse already visited Py_TYPE(self)
358390
} else {
359-
Py_VISIT(Py_TYPE(self));
391+
if (Py_Version >= 0x03090000) {
392+
Py_VISIT(Py_TYPE(self));
393+
}
360394
}
361395

362-
It is not necessary to handle the type's reference count in ``tp_new``
363-
and ``tp_clear``.
396+
It is not necessary to handle the type's reference count in
397+
:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_clear`.
398+
399+
400+
Defining ``tp_dealloc``
401+
.......................
402+
403+
If your type has a custom :c:member:`~PyTypeObject.tp_dealloc` function,
404+
it needs to:
405+
406+
- call :c:func:`PyObject_GC_UnTrack` before any fields are invalidated, and
407+
- decrement the reference count of the type.
408+
409+
To keep the type valid while ``tp_free`` is called, the type's refcount needs
410+
to be decremented *after* the instance is deallocated. For example::
411+
412+
static void my_dealloc(PyObject *self)
413+
{
414+
PyObject_GC_UnTrack(self);
415+
...
416+
PyTypeObject *type = Py_TYPE(self);
417+
type->tp_free(self);
418+
Py_DECREF(type);
419+
}
420+
421+
The default ``tp_dealloc`` function does this, so
422+
if your type does *not* override
423+
``tp_dealloc`` you don't need to add it.
424+
425+
426+
Not overriding ``tp_free``
427+
..........................
428+
429+
The :c:member:`~PyTypeObject.tp_free` slot of a heap type must be set to
430+
:c:func:`PyObject_GC_Del`.
431+
This is the default; do not override it.
432+
433+
434+
Avoiding ``PyObject_New``
435+
.........................
436+
437+
GC-tracked objects need to be allocated using GC-aware functions.
438+
439+
If you use use :c:func:`PyObject_New` or :c:func:`PyObject_NewVar`:
440+
441+
- Get and call type's :c:member:`~PyTypeObject.tp_alloc` slot, if possible.
442+
That is, replace ``TYPE *o = PyObject_New(TYPE, typeobj)`` with::
443+
444+
TYPE *o = typeobj->tp_alloc(typeobj, 0);
445+
446+
Replace ``o = PyObject_NewVar(TYPE, typeobj, size)`` with the same,
447+
but use size instead of the 0.
448+
449+
- If the above is not possible (e.g. inside a custom ``tp_alloc``),
450+
call :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`::
451+
452+
TYPE *o = PyObject_GC_New(TYPE, typeobj);
453+
454+
TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);
364455

365456

366457
Module State Access from Classes

0 commit comments

Comments
 (0)
0