Skip to content

bpo-38787: Clarify docs for PyType_GetModule and warn against common mistake #20215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 27, 2020
Merged

bpo-38787: Clarify docs for PyType_GetModule and warn against common mistake #20215

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9fb06dd
Clarify docs for PyType_GetModule and warn against common mistake
encukou May 19, 2020
f68b438
Fix typo
encukou May 19, 2020
d8d3425
Reword "defining class" in PyType_GetModule docs
encukou May 19, 2020
e3716ba
Kick the CI
encukou Aug 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion Doc/c-api/type.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,13 @@ Type Objects
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.

This function is usually used to get the module in wich a method is defined.
Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
may not return the intended result.
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
are not necessarily defined in the same module as their superclass.
See :c:type:`PyCMethod` to get the defining class.
Copy link
Member

@vstinner vstinner May 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "defining class" is something new to me. PyCMethod mentions it without explining it. Would it be possible to define it somewhere? And then link to it.

Copy link
Member Author

@encukou encukou May 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think the explanation should be in PyCMethod docs, or in METH_METHOD | METH_FASTCALL | METH_KEYWORDS docs?
For the other conventions, the docs for the flags have more detail. But I haven't found a way to link to METH_METHOD | METH_FASTCALL | METH_KEYWORDS.


.. versionadded:: 3.9

.. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
Expand Down Expand Up @@ -151,9 +158,12 @@ The following functions and structs are used to create
If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
If that also is ``NULL``, the new type derives from :class:`object`.

The *module* must be a module object or ``NULL``.
The *module* argument can be used to record the module in which the new
class is defined. It must be a module object or ``NULL``.
If not ``NULL``, the module is associated with the new type and can later be
retreived with :c:func:`PyType_GetModule`.
The associated module is not inherited by subclasses; it must be specified
for each class individually.

This function calls :c:func:`PyType_Ready` on the new type.

Expand Down