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

[encukou]

This should make PyType_GetModule, and PyType_FromModuleAndSpec's module argument clearer to people who didn't read the PEP.

Thanks @vstinner and @shihai1991 for asking clarifying questions. Hopefully this will help others.

https://bugs.python.org/issue38787

Automerge-Triggered-By: @encukou

[vstinner]

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.

[encukou]

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.

[vstinner]

I suggest to add a short section about subclassing and defining class at the bottom of https://docs.python.org/dev/c-api/type.html and then add links to this section.

Something similar to https://docs.python.org/dev/library/os.html#file-descriptor-operations which defines what a file descriptor is.

[encukou]

What do you think the section should say? Does it need more detail than:

• The defining class of a method is the class in which the method is defined.
• The module passed to PyType_FromModuleAndSpec is not inherited by subclasses.

A whole section seems like overkill to me.

[vstinner]

What do you think the section should say?

Explain PyType_GetModule(Py_TYPE(self)) issue. Explain how to get the defining class. Maybe add pseudo-code of a function which gets the defining class, in comparison with bad code which uses Py_TYPE(self).

[vstinner]

Ah, maybe also point the right section of the PEP 573 for more information?

[shihai1991]

Ah, maybe also point the right section of the PEP 573 for more information?

+1 IMHO, we don't need explain too much details in docs ; )

[encukou]

Ah, maybe also point the right section of the PEP 573 for more information?

No. The PEP is an immutable document about the design and discussion. It should be superseded by the documentation.

OK. I meant this as a quick fix, but it looks like I'll need more time to write this up.

[vstinner]

According to the length of the following PEP sections, it seems like there are few things to say about defining classes :-)

• https://www.python.org/dev/peps/pep-0573/#defining-class
• https://www.python.org/dev/peps/pep-0573/#passing-the-defining-class-to-extension-methods

[encukou]

I'm now writing a HOWTO on multi-phase init, heap types and avoiding static state, so that everything is explained properly in context. However, this full overview will take a long time to put together.

I agree that the docs in this PR are very terse and technical, but I believe they are an improvement. Consider not blocking the PR on the long explanation.

[encukou]

@vstinner: I've submitted a a longer document with a HOWTO and explanations as PEP 630. I don't think it belongs in the reference docs, though.

Would it be OK to add this PR's change to the documentation?

[vstinner]

LGTM. This change enhances the doc.

[miss-islington]

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

[bedevere-bot]

GH-21984 is a backport of this pull request to the 3.9 branch.

[vstinner]

Thanks @encukou for this PR and the PEP 630!