Skip to content

It Is Hard to Keep Track of the Instructions In the "Isolating Extension Modules" How-to #110812

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.

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

Open
ericsnowcurrently opened this issue Oct 13, 2023 · 6 comments
Labels

Comments

@ericsnowcurrently
Copy link
Member

ericsnowcurrently commented Oct 13, 2023

Documentation

(https://docs.python.org/3/howto/isolating-extensions.html)

This how-to doc contains a lot of useful information. However, it can be difficult to keep track of all the instructions it provides. It is also easy to miss important steps or lose track of everything that needs to be done. I expect that doing something about this would improve the experience of people porting modules to multi-phase init, reducing their frustration.

One thing that could help is a checklist (or two 1) that condenses the instructions throughout the doc into a succinct TODO list. Imagine someone porting a module with the checklist open side-by-side with the code for the module they are porting. That would make it much easier to keep track of what needs to be (or has been) done.

The checklist would probably go in a later section of the doc, possibly at the very bottom. However, we would want a distinct link at the very top of the doc.

CC @encukou

Linked PRs

Footnotes

  1. I expect we would have one checklist for converting a module to multi-phase init and one specifically for converting a static type to a heap type.

@ericsnowcurrently
Copy link
Member Author

@1st1, would something like the checklist I described have helped you much?

encukou added a commit that referenced this issue Nov 16, 2023
…GH-111504)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Nov 16, 2023
…otchas (pythonGH-111504)

(cherry picked from commit 985679f)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Nov 16, 2023
…otchas (pythonGH-111504)

(cherry picked from commit 985679f)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
encukou added a commit that referenced this issue Nov 16, 2023
…gotchas (GH-111504) (GH-112147)

gh-110812: Isolating Extension Modules HOWTO: List GC-related gotchas (GH-111504)
(cherry picked from commit 985679f)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
encukou added a commit that referenced this issue Nov 16, 2023
…gotchas (GH-111504) (GH-112148)

gh-110812: Isolating Extension Modules HOWTO: List GC-related gotchas (GH-111504)
(cherry picked from commit 985679f)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
aisk pushed a commit to aisk/cpython that referenced this issue Feb 11, 2024
…otchas (pythonGH-111504)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
@aisk
Copy link
Contributor

aisk commented Feb 12, 2024

Argument Clinic has a "defining class" converter which is very helpful for getting the defining class and thus the module state.

But it's not mentioned in the How-to document. Should we add it to the How-to? Or is its purpose for other extension developers outside of the CPython codebase, and Argument Clinic is mainly used in the CPython codebase, so there is no need to mention it?

@encukou
Copy link
Member

encukou commented Feb 12, 2024

(Sorry for the now-deleted comment, I misread the question)

Argument Clinic is (currently) for CPython only. The public API is PyCMethod and METH_METHOD, which is mentioned in the howto.

@aisk
Copy link
Contributor

aisk commented Feb 14, 2024

Got it, thanks for the explanation!

@hugovk
Copy link
Member

hugovk commented Feb 14, 2024

The linked PRs are merged, can this issue be closed?

@encukou
Copy link
Member

encukou commented Feb 14, 2024

There's one thing (edit: several things) left for another PR, which I forgot to copy to the issue:

  • a succinct checklist
  • copy-pastable replacement for Py_Version that works for 3.9+.

Glyphack pushed a commit to Glyphack/cpython that referenced this issue Sep 2, 2024
…otchas (pythonGH-111504)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Status: Todo
Development

No branches or pull requests

4 participants