Skip to content
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

Jump to bottom

Py_GenericAlias is not documented #88558

Closed
ronaldoussoren opened this issue Jun 11, 2021 · 17 comments
Closed

Py_GenericAlias is not documented #88558

ronaldoussoren opened this issue Jun 11, 2021 · 17 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@ronaldoussoren
Copy link
Contributor

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
    Copy link
    Contributor Author

    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.

    @ronaldoussoren ronaldoussoren added 3.9 only security fixes 3.10 only security fixes 3.11 only security fixes labels Jun 11, 2021
    @ronaldoussoren ronaldoussoren added docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error labels Jun 11, 2021
    @Fidget-Spinner
    Copy link
    Member

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

    @ronaldoussoren
    Copy link
    Contributor Author

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

    @gvanrossum
    Copy link
    Member

    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
    Copy link
    Member

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

    @gvanrossum
    Copy link
    Member

    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
    Copy link
    Member

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

    @Fidget-Spinner
    Copy link
    Member

    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
    Copy link
    Member

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

    @Fidget-Spinner
    Copy link
    Member

    (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
    Copy link
    Member

    encukou commented Jun 14, 2021

    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
    Copy link
    Contributor Author

    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
    Copy link
    Member

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

    @gvanrossum
    Copy link
    Member

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

    @miss-islington
    Copy link
    Contributor

    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
    Copy link
    Contributor

    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
    Copy link
    Member

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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    6 participants
    @encukou @ronaldoussoren @JelleZijlstra @gvanrossum @Fidget-Spinner @miss-islington