gh-144812: Add public argparse group typing protocols

[gaborbernat]

ArgumentParser.add_argument_group() and add_mutually_exclusive_group() return objects whose only name is the private _ArgumentGroup and _MutuallyExclusiveGroup. Code that stores or passes these objects around has no public type to annotate against, so callers reach for the underscore-prefixed implementation classes. A GitHub code search turns up roughly 140 projects doing exactly that. 📦

This exposes two public names, argparse.ArgumentGroup and argparse.MutuallyExclusiveGroup, as structural typing.Protocols that guarantee the add_argument() method callers rely on. Modelling them as protocols rather than aliasing the concrete classes keeps the implementation private and free to evolve, which addresses the concern raised on the issue that typing needs should not turn inner classes into frozen public API. ✨ The protocols are built on first attribute access through the module __getattr__, so import argparse stays off the typing import path — relevant because argparse sits on the start-up path of most CLIs and does not otherwise import typing.

Type checkers read typeshed rather than Lib/argparse.py, so these names take effect for end users once stdlib/argparse.pyi declares the protocols and points the two return types at them. I confirmed that change makes mypy, pyright, ty, and pyrefly all resolve the public names; a matching python/typeshed PR will follow.

• Issue: Make _MutuallyExclusiveGroup a public API in argparse #144812

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32912641 | 📁 Comparing 6ab9015 against main (1c7011d)

  🔍 Preview build  

3 files changed

± library/argparse.html
± whatsnew/3.16.html
± whatsnew/changelog.html

[picnixz]

Please, the issue has not reached a consensus so a PR is still premature.

My concern is that once we expose the protocol publicly, we also can't change the implementation without deprecations (probably?)

I think a 3rd party library would be better in that case. In the same idea as typing_extensions.

Or alternatively, we should follow pathlib.types's idea though I'm not sure it's really the best for all modules in general.

[gaborbernat]

I'm a bit puzzled about the push back here. The only thing we are exposing here is the API that is already documented through the documentation. Should we decide to change that? The typing information through the protocols would be subject to the same deprecation policy as we have for our officially documented public interface on these classes. While the classes themselves are private, the methods to call on this object are documented as public.

[picnixz]

The stdlib has a history of not exposing lots of protocols, except with some exceptions in typing.py and collections.abc. Exposing a protocol is okay but as I said, it will create a friction with any changes we would do on the private interface and would also need to be synchronized with typeshed.

OTOH, if we make argparse a package and add argparse.types as a module with unstable types, then it would be ok I think. Much like pathlib.types. That way, we could avoid friction with the main module and we would not need to have _build_group_protocols and eagerly import typing.

But again, this would still add a maintenance cost. So I would prefer that we discuss this on the issue first. I'm ok with the protocol but _build_group_protocols is overly complex for that IMO.