From 6807a0e314aa5d71651c87220c846dcc20f8fe80 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Tue, 7 Mar 2023 00:25:04 -0800 Subject: [PATCH] Cleanup PEP-697 before acceptance: Clarify in the abstract that this does not apply to all types, things like tuple and int are excluded. But could be done in the future. Fix ``basesize`` vs ``basicsize`` field name typos. Remove the Open Issues section and mention that using a PyType_Spec flag instead of a negative basicsize was rejected and offer an explanation why. (ultimately either way would work with similar impact) --- pep-0697.rst | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/pep-0697.rst b/pep-0697.rst index 951589b8e48..f989d953ca9 100644 --- a/pep-0697.rst +++ b/pep-0697.rst @@ -15,10 +15,15 @@ Abstract ======== Add `Limited C API `__ -for extending types with opaque data, +support for extending some types with opaque data by allowing code to only deal with data specific to a particular (sub)class. -Make the mechanism usable with ``PyHeapTypeObject``. +This mechanism is required to be usable with ``PyHeapTypeObject``. + +This PEP does not propose allowing to extend non-dynamically sized variable +sized objects such as ``tuple`` or ``int`` due to their different memory layout +and perceived lack of demand for doing so. This PEP leaves room to do so in +the future via the same mechanism if ever desired. Motivation @@ -218,7 +223,7 @@ This turned out to be hard to explain, and goes against the idea of decoupling the subclass from the base layout. The new flag will be used to allow safely extending variable-sized types: -creating a type with ``spec->basesize < 0`` and ``base->tp_itemsize > 0`` +creating a type with ``spec->basicsize < 0`` and ``base->tp_itemsize > 0`` will require the flag. Additionally, this PEP proposes a helper function to get the variable-sized @@ -238,10 +243,10 @@ big-picture decision tree. The individual cases are easier to explain in isolation (see the :ref:`reference implementation <697-ref-impl>` for draft docs). -* ``spec->basesize > 0``: No change to the status quo. (The base +* ``spec->basicsize > 0``: No change to the status quo. (The base class layout is known.) -* ``spec->basesize == 0``: (Inheriting the basicsize) +* ``spec->basicsize == 0``: (Inheriting the basicsize) * ``base->tp_itemsize == 0``: The item size is set to ``spec->tp_itemsize``. (No change to status quo.) @@ -252,7 +257,7 @@ big-picture decision tree. * ``spec->itemsize > 0``: The item size is set. (This is hard to use safely, but it's CPython's current behavior.) -* ``spec->basesize < 0``: (Extending the basicsize) +* ``spec->basicsize < 0``: (Extending the basicsize) * ``base->tp_itemsize == 0``: (Extending a fixed-size class) @@ -388,7 +393,7 @@ is set, either on the base or in ``spec->flags``. (See :ref:`697-var-sized` for a full explanation.) Extending a class with positive ``spec->itemsize`` using negative -``spec->basesize`` will fail. +``spec->basicsize`` will fail. Relative member offsets @@ -525,13 +530,10 @@ so it's just a theoretical possibility. Rejected Ideas ============== -None yet. - - -Open Issues -=========== - -Is negative basicsize the way to go? Should this be enabled by a flag instead? +Instead of a negative ``spec->basicsize``, a new ``PyType_Spec`` flag could've +been added. The effect would be the same to any existing code accessing these +internals without up to date knowledge of the change as the meaning of the +field value is changing in this situation. Footnotes