From 2b96a85df346cb70aec020afe218b1220fd4ada5 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 30 Nov 2023 23:47:18 +0800 Subject: [PATCH 01/22] gh-102468: add document for PyCFunction_New and related functions --- Doc/c-api/structures.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 25cb4ed40f63e7..fd093418cacd30 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -399,6 +399,23 @@ definition with the same method name. slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls. +.. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) + + Turn ``ml`` into a Python callable object. The ``self`` parameter will be + passed as ``self`` parameter to the C function in ``ml->ml_meth`` when + invoked, can be ``NULL``. + +.. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) + + Same as :c:func:``PyCFunction_New``, but also allows setting the function + object's ``__module__`` attribute. ``module`` can be anything. + +.. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) + + Same as :c:func:``PyCFuntion_NewEx``, but accept a ``cls`` parameter, which + will be passed as ``defining_class`` parameter to the C function. Must be + set if :ref:`METH_METHOD` is set in ``ml->ml_flags``. + Accessing attributes of extension types --------------------------------------- From 410c63d8c38430ebb555de3fae57cb346e594389 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 30 Nov 2023 23:59:12 +0800 Subject: [PATCH 02/22] fix lint error --- Doc/c-api/structures.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index fd093418cacd30..f9f1dea9e9e1fc 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -407,12 +407,12 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) - Same as :c:func:``PyCFunction_New``, but also allows setting the function + Same as :c:func:`PyCFunction_New`, but also allows setting the function object's ``__module__`` attribute. ``module`` can be anything. .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Same as :c:func:``PyCFuntion_NewEx``, but accept a ``cls`` parameter, which + Same as :c:func:`PyCFuntion_NewEx`, but accept a ``cls`` parameter, which will be passed as ``defining_class`` parameter to the C function. Must be set if :ref:`METH_METHOD` is set in ``ml->ml_flags``. From 268bf84408aa9520905f427c69b533dcefccda57 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 1 Dec 2023 00:06:44 +0800 Subject: [PATCH 03/22] fix sphinx build on oldest version --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index f9f1dea9e9e1fc..882cb6279ff615 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -414,7 +414,7 @@ definition with the same method name. Same as :c:func:`PyCFuntion_NewEx`, but accept a ``cls`` parameter, which will be passed as ``defining_class`` parameter to the C function. Must be - set if :ref:`METH_METHOD` is set in ``ml->ml_flags``. + set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. Accessing attributes of extension types From 333f3d6b6ab6d1b0023b6e73c405a1aec41c1a29 Mon Sep 17 00:00:00 2001 From: AN Long Date: Wed, 10 Jan 2024 23:16:00 +0800 Subject: [PATCH 04/22] Update Doc/c-api/structures.rst Co-authored-by: Erlend E. Aasland --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 882cb6279ff615..23472cf1eacc81 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -401,7 +401,7 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) - Turn ``ml`` into a Python callable object. The ``self`` parameter will be + Turn *ml* into a Python callable object. The *self* parameter will be passed as ``self`` parameter to the C function in ``ml->ml_meth`` when invoked, can be ``NULL``. From b6e16215228ad1c52cf07138eec0b7ad4393d498 Mon Sep 17 00:00:00 2001 From: AN Long Date: Wed, 10 Jan 2024 23:54:37 +0800 Subject: [PATCH 05/22] add refernce link to the __module__ attr --- Doc/c-api/structures.rst | 4 +++- Doc/reference/datamodel.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 23472cf1eacc81..8a9a6f7a221c65 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -408,7 +408,9 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) Same as :c:func:`PyCFunction_New`, but also allows setting the function - object's ``__module__`` attribute. ``module`` can be anything. + object's ``__module__`` attribute. :attr:`!__module__` should be the name + of the module the function is defined in or ``None`` if unavailable. + See :attr:`function.__module__`. .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index f7d3d2d0bbec23..c87de3338900dc 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -768,7 +768,7 @@ standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes: :attr:`__doc__` is the function's documentation string, or ``None`` if unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is -set to ``None`` (but see the next item); :attr:`__module__` is the name of +set to ``None`` (but see the next item); :attr:`__module__` its the name of the module the function was defined in or ``None`` if unavailable. From f55c207952ca0570f9085a2812012415d1bbbf18 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 11 Jan 2024 00:17:48 +0800 Subject: [PATCH 06/22] update the refcounts --- Doc/data/refcounts.dat | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index ef9ac1617a284b..af11a08f6a1cf8 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -402,6 +402,21 @@ PyContextVar_Reset:int::: PyContextVar_Reset:PyObject*:var:0: PyContextVar_Reset:PyObject*:token:-1: +PyCFunction_New:PyObject*::+1: +PyCFunction_New:PyObject*:ml:0: +PyCFunction_New:PyObject*:self:+1: + +PyCFunction_NewEx:PyObject*::+1: +PyCFunction_NewEx:PyObject*:ml:0: +PyCFunction_NewEx:PyObject*:self:+1: +PyCFunction_NewEx:PyObject*:module:+1: + +PyCMethod_New:PyObject*::+1: +PyCMethod_New:PyObject*:ml:0: +PyCMethod_New:PyObject*:self:+1: +PyCMethod_New:PyObject*:module:+1: +PyCMethod_New:PyObject*:cls:+1: + PyDate_Check:int::: PyDate_Check:PyObject*:ob:0: From c921dee5afd15d4f09728cbedcc0ed5e2b50edc9 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 11 Jan 2024 00:22:07 +0800 Subject: [PATCH 07/22] update the steal refcount to ml in document --- Doc/c-api/structures.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 8a9a6f7a221c65..acdef98caeb0df 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -405,6 +405,10 @@ definition with the same method name. passed as ``self`` parameter to the C function in ``ml->ml_meth`` when invoked, can be ``NULL``. + .. note:: + + This function "steals" a reference to *ml*. + .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) Same as :c:func:`PyCFunction_New`, but also allows setting the function @@ -412,12 +416,20 @@ definition with the same method name. of the module the function is defined in or ``None`` if unavailable. See :attr:`function.__module__`. + .. note:: + + This function "steals" a reference to *ml*. + .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) Same as :c:func:`PyCFuntion_NewEx`, but accept a ``cls`` parameter, which will be passed as ``defining_class`` parameter to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. + .. note:: + + This function "steals" a reference to *ml*. + Accessing attributes of extension types --------------------------------------- From 941d12ceb40bac8d1fb9b7f3028c888d3f68bb28 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 11 Jan 2024 00:23:12 +0800 Subject: [PATCH 08/22] fix a typo --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index acdef98caeb0df..615961337c4138 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -422,7 +422,7 @@ definition with the same method name. .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Same as :c:func:`PyCFuntion_NewEx`, but accept a ``cls`` parameter, which + Same as :c:func:`PyCFunction_NewEx`, but accept a ``cls`` parameter, which will be passed as ``defining_class`` parameter to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. From 2091da47839af0c82baaffb30aeb9493ad26a30d Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 11 Jan 2024 00:23:59 +0800 Subject: [PATCH 09/22] revert the change to datamodel.rst by accident --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index c87de3338900dc..f7d3d2d0bbec23 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -768,7 +768,7 @@ standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes: :attr:`__doc__` is the function's documentation string, or ``None`` if unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is -set to ``None`` (but see the next item); :attr:`__module__` its the name of +set to ``None`` (but see the next item); :attr:`__module__` is the name of the module the function was defined in or ``None`` if unavailable. From 4f4b5b42afccd0927417c06f185505659b55bcb8 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 11 Jan 2024 00:56:02 +0800 Subject: [PATCH 10/22] using italic on the self / ml / cls words --- Doc/c-api/structures.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index e2e270d41175db..8869400a1ef33a 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -402,7 +402,7 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) Turn *ml* into a Python callable object. The *self* parameter will be - passed as ``self`` parameter to the C function in ``ml->ml_meth`` when + passed as *self* parameter to the C function in ``ml->ml_meth`` when invoked, can be ``NULL``. .. note:: @@ -422,7 +422,7 @@ definition with the same method name. .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Same as :c:func:`PyCFunction_NewEx`, but accept a ``cls`` parameter, which + Same as :c:func:`PyCFunction_NewEx`, but accept a **cls** parameter, which will be passed as ``defining_class`` parameter to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. From c2e0da3198397e689ba231289e8f98a1e62019d7 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 12 Jan 2024 21:50:29 +0800 Subject: [PATCH 11/22] Apply suggestions from code review Co-authored-by: Erlend E. Aasland --- Doc/c-api/structures.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 8869400a1ef33a..c85ade7107a9bf 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -402,8 +402,8 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) Turn *ml* into a Python callable object. The *self* parameter will be - passed as *self* parameter to the C function in ``ml->ml_meth`` when - invoked, can be ``NULL``. + passed as the *self* argument to the C function in ``ml->ml_meth`` when + invoked. *self* can be ``NULL``. .. note:: @@ -412,9 +412,11 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) Same as :c:func:`PyCFunction_New`, but also allows setting the function - object's ``__module__`` attribute. :attr:`!__module__` should be the name - of the module the function is defined in or ``None`` if unavailable. - See :attr:`function.__module__`. + object's ``__module__`` attribute from the given *module* argument. + *module* should be the name of the module the function is defined in, + or ``None`` if unavailable. + + .. seealso: :attr:`function.__module__` .. note:: @@ -422,9 +424,9 @@ definition with the same method name. .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Same as :c:func:`PyCFunction_NewEx`, but accept a **cls** parameter, which - will be passed as ``defining_class`` parameter to the C function. Must be - set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. + Same as :c:func:`PyCFunction_NewEx`, but accept a *cls* parameter, which + will be passed as the *defining_class* argument to the C function. + Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. .. note:: From a1e4f0832f9cc355aa62d4fcbb28439c091137d8 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 12 Jan 2024 23:28:41 +0800 Subject: [PATCH 12/22] Update Doc/c-api/structures.rst Co-authored-by: Erlend E. Aasland --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index c85ade7107a9bf..41a2391b1d85e1 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -401,7 +401,7 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) - Turn *ml* into a Python callable object. The *self* parameter will be + Turn *ml* into a Python :term:`callable`. The *self* parameter will be passed as the *self* argument to the C function in ``ml->ml_meth`` when invoked. *self* can be ``NULL``. From 143538bda7e5675e95d5c58f14b1ed8b61c0f070 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 12 Jan 2024 23:35:16 +0800 Subject: [PATCH 13/22] Remote the "steals" note --- Doc/c-api/structures.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 41a2391b1d85e1..51f996314d94bb 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -405,10 +405,6 @@ definition with the same method name. passed as the *self* argument to the C function in ``ml->ml_meth`` when invoked. *self* can be ``NULL``. - .. note:: - - This function "steals" a reference to *ml*. - .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) Same as :c:func:`PyCFunction_New`, but also allows setting the function @@ -418,20 +414,12 @@ definition with the same method name. .. seealso: :attr:`function.__module__` - .. note:: - - This function "steals" a reference to *ml*. - .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) Same as :c:func:`PyCFunction_NewEx`, but accept a *cls* parameter, which will be passed as the *defining_class* argument to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. - .. note:: - - This function "steals" a reference to *ml*. - Accessing attributes of extension types --------------------------------------- From 165a274fad9029efad7aeb88d099ae0fa665ce70 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 12 Jan 2024 23:49:22 +0800 Subject: [PATCH 14/22] Update Doc/c-api/structures.rst Co-authored-by: Erlend E. Aasland --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 51f996314d94bb..66b446f11404de 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -401,7 +401,7 @@ definition with the same method name. .. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) - Turn *ml* into a Python :term:`callable`. The *self* parameter will be + Turn *ml* into a Python :term:`callable` object. The *self* parameter will be passed as the *self* argument to the C function in ``ml->ml_meth`` when invoked. *self* can be ``NULL``. From 895e2b7002235d5763477f4c50ce928b2df964fb Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 12 Jan 2024 23:51:06 +0800 Subject: [PATCH 15/22] Change ml type to PyMethodDef in refcounts.data Co-authored-by: Erlend E. Aasland --- Doc/data/refcounts.dat | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 6ad1f1eb8c30ec..e754ac69d55f51 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -403,16 +403,16 @@ PyContextVar_Reset:PyObject*:var:0: PyContextVar_Reset:PyObject*:token:-1: PyCFunction_New:PyObject*::+1: -PyCFunction_New:PyObject*:ml:0: +PyCFunction_New:PyMethodDef*:ml:0: PyCFunction_New:PyObject*:self:+1: PyCFunction_NewEx:PyObject*::+1: -PyCFunction_NewEx:PyObject*:ml:0: +PyCFunction_NewEx:PyMethodDef*:ml:0: PyCFunction_NewEx:PyObject*:self:+1: PyCFunction_NewEx:PyObject*:module:+1: PyCMethod_New:PyObject*::+1: -PyCMethod_New:PyObject*:ml:0: +PyCMethod_New:PyMethodDef*:ml:0: PyCMethod_New:PyObject*:self:+1: PyCMethod_New:PyObject*:module:+1: PyCMethod_New:PyObject*:cls:+1: From 9ecece814104513dd4c3b81b901f5bb877df2dd1 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 12 Jan 2024 23:51:50 +0800 Subject: [PATCH 16/22] Remove the 0 in refcounts.dat for PyMethodDef --- Doc/data/refcounts.dat | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index e754ac69d55f51..f719ce153b239a 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -403,16 +403,16 @@ PyContextVar_Reset:PyObject*:var:0: PyContextVar_Reset:PyObject*:token:-1: PyCFunction_New:PyObject*::+1: -PyCFunction_New:PyMethodDef*:ml:0: +PyCFunction_New:PyMethodDef*:ml:: PyCFunction_New:PyObject*:self:+1: PyCFunction_NewEx:PyObject*::+1: -PyCFunction_NewEx:PyMethodDef*:ml:0: +PyCFunction_NewEx:PyMethodDef*:ml:: PyCFunction_NewEx:PyObject*:self:+1: PyCFunction_NewEx:PyObject*:module:+1: PyCMethod_New:PyObject*::+1: -PyCMethod_New:PyMethodDef*:ml:0: +PyCMethod_New:PyMethodDef*:ml:: PyCMethod_New:PyObject*:self:+1: PyCMethod_New:PyObject*:module:+1: PyCMethod_New:PyObject*:cls:+1: From 6b59e9840a40935f90dfedcefe75d6fbe192c2aa Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 16 Jan 2024 20:40:06 +0800 Subject: [PATCH 17/22] Using the "equivalent" stuff to document methods --- Doc/c-api/structures.rst | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 66b446f11404de..aa896b0e9a8aee 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -399,26 +399,34 @@ definition with the same method name. slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls. -.. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) +.. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Turn *ml* into a Python :term:`callable` object. The *self* parameter will be - passed as the *self* argument to the C function in ``ml->ml_meth`` when - invoked. *self* can be ``NULL``. + Turn *ml* into a Python :term:`callable` object. The caller must ensure that + *ml* outlives the :term:`callable`. Typically, *ml* is defined as a static + variable. -.. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) + The *self* parameter will be passed as the *self* argument to the C function + in ``ml->ml_meth`` when invoked. *self* can be ``NULL``. - Same as :c:func:`PyCFunction_New`, but also allows setting the function - object's ``__module__`` attribute from the given *module* argument. - *module* should be the name of the module the function is defined in, - or ``None`` if unavailable. + The :term:`callable` object's ``__module__`` attribute can be set from the + given *module* argument. *module* should be a Python string, which will be + used as name of the module the function is defined in. If unavailable, it + can be set to :cost:`None` or ``NULL``. + + The *cls* parameter will be passed as the *defining_class* argument to the C + function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. .. seealso: :attr:`function.__module__` -.. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Same as :c:func:`PyCFunction_NewEx`, but accept a *cls* parameter, which - will be passed as the *defining_class* argument to the C function. - Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. +.. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) + + Equivalent to ``PyCMethod_New(ml, self, module, NULL)``. + + +.. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) + + Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``. Accessing attributes of extension types From 38825c91ef64e757e5f19826cfbb8b56eafbffe6 Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 16 Jan 2024 20:44:01 +0800 Subject: [PATCH 18/22] cost -> const --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index aa896b0e9a8aee..8814c653327afd 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -411,7 +411,7 @@ definition with the same method name. The :term:`callable` object's ``__module__`` attribute can be set from the given *module* argument. *module* should be a Python string, which will be used as name of the module the function is defined in. If unavailable, it - can be set to :cost:`None` or ``NULL``. + can be set to :const:`None` or ``NULL``. The *cls* parameter will be passed as the *defining_class* argument to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. From 7cb109eda9384352b4be9d076877973c2444d99e Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 16 Jan 2024 21:06:33 +0800 Subject: [PATCH 19/22] add versionadded and change the seealso position --- Doc/c-api/structures.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 8814c653327afd..465f37c3ffdd9c 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -413,11 +413,11 @@ definition with the same method name. used as name of the module the function is defined in. If unavailable, it can be set to :const:`None` or ``NULL``. + .. seealso: :attr:`function.__module__` + The *cls* parameter will be passed as the *defining_class* argument to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. - .. seealso: :attr:`function.__module__` - .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) @@ -428,6 +428,8 @@ definition with the same method name. Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``. + .. versionadded:: 3.9 + Accessing attributes of extension types --------------------------------------- From 7f86d2e1fb323f963e857e378d5135495b489d84 Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 16 Jan 2024 21:11:51 +0800 Subject: [PATCH 20/22] Apply the SemBr changes Co-authored-by: Erlend E. Aasland --- Doc/c-api/structures.rst | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 465f37c3ffdd9c..cb540919d98e41 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -401,22 +401,25 @@ definition with the same method name. .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) - Turn *ml* into a Python :term:`callable` object. The caller must ensure that - *ml* outlives the :term:`callable`. Typically, *ml* is defined as a static - variable. + Turn *ml* into a Python :term:`callable` object. + The caller must ensure that *ml* outlives the :term:`callable`. + Typically, *ml* is defined as a static variable. - The *self* parameter will be passed as the *self* argument to the C function - in ``ml->ml_meth`` when invoked. *self* can be ``NULL``. + The *self* parameter will be passed as the *self* argument + to the C function in ``ml->ml_meth`` when invoked. + *self* can be ``NULL``. - The :term:`callable` object's ``__module__`` attribute can be set from the - given *module* argument. *module* should be a Python string, which will be - used as name of the module the function is defined in. If unavailable, it - can be set to :const:`None` or ``NULL``. + The :term:`callable` object's ``__module__`` attribute + can be set from the given *module* argument. + *module* should be a Python string, + which will be used as name of the module the function is defined in. + If unavailable, it can be set to :const:`None` or ``NULL``. .. seealso: :attr:`function.__module__` - The *cls* parameter will be passed as the *defining_class* argument to the C - function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. + The *cls* parameter will be passed as the *defining_class* + argument to the C function. + Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) From acd1b438d564cc2e9db2339345095033d9781c58 Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 16 Jan 2024 21:42:48 +0800 Subject: [PATCH 21/22] fix versionadded --- Doc/c-api/structures.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index cb540919d98e41..81087008911691 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -421,6 +421,8 @@ definition with the same method name. argument to the C function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. + .. versionadded:: 3.9 + .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) @@ -431,8 +433,6 @@ definition with the same method name. Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``. - .. versionadded:: 3.9 - Accessing attributes of extension types --------------------------------------- From ce88086e6298ed37f6d6958726fe2ffebf723d0f Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 16 Jan 2024 22:27:38 +0800 Subject: [PATCH 22/22] fix the seealso --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 81087008911691..86c779472fd244 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -415,7 +415,7 @@ definition with the same method name. which will be used as name of the module the function is defined in. If unavailable, it can be set to :const:`None` or ``NULL``. - .. seealso: :attr:`function.__module__` + .. seealso:: :attr:`function.__module__` The *cls* parameter will be passed as the *defining_class* argument to the C function.