Update extending/embedding docs to new way to build modules in C

[brettcannon]

BPO	26515
Nosy	@brettcannon, @ncoghlan, @encukou, @ericsnowcurrently, @berkerpeksag
PRs	bpo-26515: Update C API docs to use PyModuleDef_Init() #8682

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-03-09.02:43:41.063>
labels = ['type-feature', '3.9', 'docs']
title = 'Update extending/embedding docs to new way to build modules in C'
updated_at = <Date 2020-12-15.15:36:08.559>
user = 'https://github.com/brettcannon'

bugs.python.org fields:

activity = <Date 2020-12-15.15:36:08.559>
actor = 'petr.viktorin'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-03-09.02:43:41.063>
creator = 'brett.cannon'
dependencies = []
files = []
hgrepos = []
issue_num = 26515
keywords = ['patch']
message_count = 5.0
messages = ['261398', '342668', '359792', '379432', '383069']
nosy_count = 6.0
nosy_names = ['brett.cannon', 'ncoghlan', 'petr.viktorin', 'docs@python', 'eric.snow', 'berker.peksag']
pr_nums = ['8682']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26515'
versions = ['Python 3.9']

[brettcannon]

https://docs.python.org/3/extending/extending.html#a-simple-example uses PyModule_Create() instead of PyModuleDef_Init().

[encukou]

Correct usage of multi-phase init might now get users stuck when they start needing per-module state. See PEP-573 "Module State Access from C Extension Methods" for the (hopefully) last thing that prevents me from generally recommending multi-phase init.

That PEP is on my list for after PRP 590 is done.
Before it's implemented, I'm happy leaving PyModuleDef_Init to experts -- that is, have it in the reference docs only.

[ncoghlan]

Changed target version as per Petr's comment (PEP-573 is close to being accepted for 3.9 - it just needs some editing to improve clarity in the PEP itself, rather than needing any changes to the technical proposal)

[encukou]

There is now PEP-630. Still not done enough to move it out of draft status, but usable for converting simple modules.

[encukou]

PEP-630 is now Active. I believe the vast majority of modules can now be ported, and it should be helpful for early adopters (including CPython stdlib). But there are still Open Issues and the API not battle-tested on all the edge cases.

The PEP is written to be easily integrated into official docs when the time comes.