C API docs need a clear "defining custom extension types" section

[ncoghlan]

BPO	20224
Nosy	@ncoghlan

^{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 2014-01-12.06:25:11.591>
labels = ['expert-C-API', 'type-feature', 'docs']
title = 'C API docs need a clear "defining custom extension types" section'
updated_at = <Date 2020-06-25.09:39:58.809>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2020-06-25.09:39:58.809>
actor = 'vstinner'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'C API']
creation = <Date 2014-01-12.06:25:11.591>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 20224
keywords = []
message_count = 1.0
messages = ['207927']
nosy_count = 2.0
nosy_names = ['ncoghlan', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue20224'
versions = ['Python 3.3', 'Python 3.4', 'Python 3.5']

[ncoghlan]

The main C API docs don't clearly explain how to define new types, so people almost always cargo cult an existing legacy type definition instead (I know I do).

The extending and embedding docs have a guide (http://docs.python.org/3/extending/newtypes.html), but that describes the old legacy method based on static type declarations. New code should instead use the dynamic mechanism defined in PEP-384 (http://www.python.org/dev/peps/pep-0384/#type-objects).

See also http://docs.python.org/3/c-api/type.html#PyType_FromSpec

Note that PyType_Spec isn't defined in the C API docs *at all*.