[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Ken Jin  added the comment:

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 :).

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[miss-islington]

miss-islington  added the comment:


New changeset c7e95715ec2f2a16eace7aa35a1eb2f18e8d06ed by Ken Jin in branch 
'3.9':
[3.9] bpo-44392: Add Py_GenericAlias to C API docs (GH-26724) (GH-26757)
https://github.com/python/cpython/commit/c7e95715ec2f2a16eace7aa35a1eb2f18e8d06ed


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Change by Ken Jin :


--
pull_requests: +25342
pull_request: https://github.com/python/cpython/pull/26757

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[miss-islington]

miss-islington  added the comment:


New changeset 84ce737f73136c1de7c4dc92bc096ed6c963e42d by Miss Islington (bot) 
in branch '3.10':
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
https://github.com/python/cpython/commit/84ce737f73136c1de7c4dc92bc096ed6c963e42d


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Guido van Rossum]

Guido van Rossum  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 7.0 -> 8.0
pull_requests: +25341
pull_request: https://github.com/python/cpython/pull/26756

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Guido van Rossum]

Guido van Rossum  added the comment:


New changeset 6773c3eaa735b5061b4a97f2c730703a32d8c9ff by Ken Jin in branch 
'main':
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
https://github.com/python/cpython/commit/6773c3eaa735b5061b4a97f2c730703a32d8c9ff


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Change by Ken Jin :


--
pull_requests: +25325
pull_request: https://github.com/python/cpython/pull/26739

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ronald Oussoren]

Ronald Oussoren  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Petr Viktorin]

Petr Viktorin  added the comment:

> 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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Ken Jin  added the comment:

(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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Guido van Rossum]

Guido van Rossum  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Ken Jin  added the comment:

> 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.

--
nosy: +petr.viktorin

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Guido van Rossum]

Guido van Rossum  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:

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

--
nosy: +Jelle Zijlstra

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Guido van Rossum]

Guido van Rossum  added the comment:

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.

--
nosy: +Guido.van.Rossum

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Change by Ken Jin :


--
keywords: +patch
pull_requests: +25314
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/26724

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ronald Oussoren]

Ronald Oussoren  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ken Jin]

Ken Jin  added the comment:

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

--
nosy: +gvanrossum, kj

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44392] Py_GenericAlias is not documented

[Ronald Oussoren]

New submission from Ronald Oussoren :

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.

--
assignee: docs@python
components: Documentation
messages: 395625
nosy: docs@python, ronaldoussoren
priority: normal
severity: normal
status: open
title: Py_GenericAlias is not documented
type: behavior
versions: Python 3.10, Python 3.11, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com