Py_GenericAlias is not documented

[ronaldoussoren]

BPO	44392
Nosy	@gvanrossum, @ronaldoussoren, @encukou, @gvanrossum, @JelleZijlstra, @miss-islington, @Fidget-Spinner
PRs	bpo-44392: Add Py_GenericAlias to C API docs #26724 bpo-44392: Fix exported type of Py_GenericAliasType in stable ABI #26739 [3.10] bpo-44392: Add Py_GenericAlias to C API docs (GH-26724) #26756 [3.9] bpo-44392: Add Py_GenericAlias to C API docs (GH-26724) #26757

^{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 = <Date 2021-06-16.15:43:52.503>
created_at = <Date 2021-06-11.09:18:35.375>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = 'Py_GenericAlias is not documented'
updated_at = <Date 2021-06-16.15:43:52.502>
user = 'https://github.com/ronaldoussoren'

bugs.python.org fields:

activity = <Date 2021-06-16.15:43:52.502>
actor = 'kj'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-06-16.15:43:52.503>
closer = 'kj'
components = ['Documentation']
creation = <Date 2021-06-11.09:18:35.375>
creator = 'ronaldoussoren'
dependencies = []
files = []
hgrepos = []
issue_num = 44392
keywords = ['patch']
message_count = 17.0
messages = ['395625', '395630', '395790', '395822', '395826', '395827', '395829', '395831', '395832', '395833', '395839', '395863', '395922', '395923', '395927', '395936', '395940']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'ronaldoussoren', 'petr.viktorin', 'docs@python', 'Guido.van.Rossum', 'JelleZijlstra', 'miss-islington', 'kj']
pr_nums = ['26724', '26739', '26756', '26757']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue44392'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[ronaldoussoren]

Py_GenericAlias seems to be a public API given its name and is mention in the stable ABI list for 3.10 (https://docs.python.org/3.10/c-api/stable.html?highlight=py_genericalias), but the API is not documented.

Likewise for Py_GenericAliasType.

[Fidget-Spinner]

Ronald, may I take this please? Or are you working on something already?

[ronaldoussoren]

I'm not working on this. Feel free to work on a PR.

[gvanrossum]

Hm, maybe it was a mistake to expose this? Remind me what use is made of this from C code? Can we remove this from the stable API during beta? It was never exposed before.

[JelleZijlstra]

It could be useful for C extensions that want to support PEP-585 for their types, such as numpy's array type.

[gvanrossum]

Hm, but is that what they are doing? I assume that they use stub files, since static type checkers don’t introspect the runtime API.

[JelleZijlstra]

They'd still need runtime support from GenericAlias to allow users to write numpy.ndarray[int] at runtime.

[Fidget-Spinner]

maybe it was a mistake to expose this

I was wondering if this was accidentally added at the time too.

Remind me what use is made of this from C code

It's required for a C extension type to implement the class_getitem method properly. Eg. MyCType[int]. The other alternative is for them to import the types.GenericAlias Python constructor and call that, but that seems strange.

Can we remove this from the stable API during beta? It was never exposed before.

Unfortunately, it seems like it has been (accidentally?) exposed since 3.9 :(. I see some 3rd party projects using it already, so I don't know if we can get rid of it so easily:
https://github.com/Nuitka/Nuitka/blob/57fecfe6cc939f4694b57d2efa37d1893c06b85b/nuitka/build/include/nuitka/helper/subscripts.h#L97

CC-ing Petr, seeking advice on the C stable ABI for this please.

[gvanrossum]

Maybe the docs then should contain a more-or-less complete example showing how a 3rd party type should use this?

[Fidget-Spinner]

(Copied over from the PR)

BTW, I also noticed the stable ABI manifest exposes the wrong return type for Py_GenericAliasType. It exposes it as a function when it's a var/type/struct. So I fixed that in the PR too otherwise the docs weren't compiling (I can split that into a separate PR if needed). But that means the exported symbol for Windows is also modified.

[encukou]

Can we remove this from the stable API during beta?

It was added (to PC/python3.def) in 3.9, so removing in 3.10 beta wouldn't be good.
It can be deprecated; should it?

[ronaldoussoren]

Why should this be deprecated at all?

The API is a convenient way to add __class_getitem__ in a way that is consistent with the implementation for builtin types and the stdlib.

I noticed the lack of documentation when I worked on implementing this for PyObjC (an easy first step towards adding type stubs to that project).

For me the alternative to using Py_GenericAlias would be a dummy implementation of __class_getitem__ that just returns self.

[gvanrossum]

New changeset 6773c3e by Ken Jin in branch 'main':
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
6773c3e

[gvanrossum]

Does it need a backport to 3.9 too, since GenericAlias was introduced there?

[miss-islington]

New changeset 84ce737 by Miss Islington (bot) in branch '3.10':
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
84ce737

[miss-islington]

New changeset c7e9571 by Ken Jin in branch '3.9':
[3.9] bpo-44392: Add Py_GenericAlias to C API docs (GH-26724) (GH-26757)
c7e9571

[Fidget-Spinner]

I'm closing this issue as all the relevant PRs have landed. Thanks everyone!

@ronald

Why should this be deprecated at all?

I can't speak for others, but personally I think it's here to stay (for the many reasons raised in the previous messages).

Thanks for catching and reporting this. Improving docs is always fun :).