Added some more info on PyModule_GetState doc.

[s3rius]

This PR adds more information on how to use the PyModule_GetState function, clarifying what argument should be passed.

At first glance, people might incorrectly think they need to pass a pointer to a state struct that the function will populate, but that is not the case.

---

📚 Documentation preview 📚: https://cpython-previews--138823.org.readthedocs.build/

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[sobolevn]

Maybe like this?

[sobolevn]

Suggested change

This makes modules safe to use with sub‑interpreters.

This is too specific.

[s3rius]

But isn't it the most useful feature of this function? Otherwise it doesn't makes sense to store per-module state.

[sobolevn]

Maybe instead link to the PEP?

[s3rius]

Added PEP link.

[ZeroIntensity]

Sorry, but I disagree. PEPs shouldn't be used as documentation, because they're solely historical documents and don't receive updates when we change things. I think we should keep the "This makes modules safe to use with sub‑interpreters" sentence, because yes -- that's what this function is for.

[skirpichev]

I suggest leave things as is. There's no issue.

Maybe just add PEP link, indeed.

[s3rius]

@skirpichev, @sobolevn. Intead of all the changes added link to the respective PEP. Can you please take a look once again?

[skirpichev]

I'm still not sure if that's helpful. PEP 489 introduces a lot of API, why mention it just there? And also PyModule_GetState() was added by a different PEP, IIRIC.

[ZeroIntensity]

Please don't solely link to the PEP. I think the original sentence ("This makes modules safe to use with sub‑interpreters") was fine.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[picnixz]

Linking PEPs should be avoided in new documentation because they are historical documents that may not match the runtime. Considering there isn't more informatino to add, and I think, there shouldn't have, I suggest closing this PR.

What may be interesting though is to document when an exception is set by the function. PyModule_GetState returns NULL with an exception set if module is not a module, and returns NULL without an exception set if PyModuleDef.md_state is NULL which, AFAIK, only happens when memory cannot be allocated or m_size is 0:

• If it cannot be allocated, I'mnot even sure we would be able to get to the call of PyModule_GetState.
• If m_size is 0, it means that the module state was really an empty object. So there is no state. And unless you call PyModule_GetState for a module you don't know the state of, then it won't happen. But again, if you call that function for a module you don't know the state of, it doesn't make sense to use it as you get a void *.

Unless we want to document this subtlety, we should close this PR.