Skip to content

chore(tags): limit dir / tab-completion in REPL#1011

Merged
henryiii merged 2 commits intopypa:mainfrom
henryiii:henryiii/chore/tags_all
Jan 23, 2026
Merged

chore(tags): limit dir / tab-completion in REPL#1011
henryiii merged 2 commits intopypa:mainfrom
henryiii:henryiii/chore/tags_all

Conversation

@henryiii
Copy link
Copy Markdown
Contributor

@henryiii henryiii commented Dec 9, 2025 •
edited
Loading

This adds __all__ and __dir__ to the tags module. This exports just the public names; type checkers respect __all__, REPL tab completion respects __dir__. It does not stop someone from using an unexported name at runtime. This is much better than trying to use underscores on things like standard imports or deleting things, and it also works for re-exporting. See https://learn.scientific-python.org/development/patterns/exports for details.

Before:

>>> import packaging.tags
>>> dir(packaging.tags)
['Any', 'AppleVersion', 'EXTENSION_SUFFIXES', 'INTERPRETER_SHORT_NAMES', 'Iterable',
 'Iterator', 'PythonVersion', 'Sequence', 'Tag', 'Tuple', '_32_BIT_INTERPRETER',
 '__all__', '__annotations__', '__builtins__', '__cached__', '__conditional_annotations__',
 '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__',
 '_abi3_applies', '_cpython_abis', '_generic_abi', '_generic_platforms',
 '_get_config_var', '_is_threaded_cpython', '_linux_platforms', '_mac_arch',
 '_mac_binary_formats', '_manylinux', '_musllinux', '_normalize_string',
 '_py_interpreter_range', '_version_nodot', 'android_platforms', 'annotations',
 'cast', 'compatible_tags', 'cpython_tags', 'generic_tags', 'interpreter_name',
 'interpreter_version', 'ios_platforms', 'logger', 'logging', 'mac_platforms',
 'parse_tag', 'platform', 'platform_tags', 're', 'struct', 'subprocess', 'sys',
 'sys_tags', 'sysconfig']

After:

>>> import packaging.tags
>>> dir(packaging.tags)
['AppleVersion', 'INTERPRETER_SHORT_NAMES', 'PythonVersion', 'Tag', 'compatible_tags',
 'cpython_tags', 'generic_tags', 'interpreter_name', 'interpreter_version', 'parse_tag',
 'platform_tags', 'sys_tags']

I've skipped exporting mac_platforms, ios_platform, and android_platforms, because _linux_platforms is hidden, but maybe those are public? Ah, nevermind, I do see them in the documentation. Interesting, I'll add them. I could list _linux_platforms here too if we want to, but it's not documented.

If this looks good, I'll work on the other modules.

@henryiii henryiii force-pushed the henryiii/chore/tags_all branch 2 times, most recently from d78fbc3 to 9a27e01 Compare December 9, 2025 04:04
@brettcannon
Copy link
Copy Markdown
Member

brettcannon commented Dec 9, 2025

tab completion respects __dir__.

Tab completion by whom?

@henryiii
Copy link
Copy Markdown
Contributor Author

henryiii commented Dec 9, 2025 •
edited
Loading

Python's old and new REPL and IPython's REPL (at least), are based on dir(item). I think static tab completion, like in VSCode, respects __all__. Edit: no, it doesn't seem to.

@henryiii
Copy link
Copy Markdown
Contributor Author

henryiii commented Dec 9, 2025 •
edited
Loading

New REPL:

Screenshot 2025-12-09 at 2 31 38 PM

(Looks like I forgot to update Python to 3.14.2, embarrassing!)

Old REPL:

Screenshot 2025-12-09 at 2 32 41 PM

(No color now looks so sad)

IPython:

Screenshot 2025-12-09 at 2 33 31 PM

Looks like vscode does not respect __all__, it's still showing me other stuff like Any. But it's not worse, at least. :) And mypy does respect __all__.

@henryiii henryiii force-pushed the henryiii/chore/tags_all branch from 9a27e01 to 496e3ba Compare December 9, 2025 19:40
@henryiii henryiii changed the title chore(tags): limit dir / tab-completion chore(tags): limit dir / tab-completion in REPL Dec 10, 2025
@henryiii henryiii mentioned this pull request Jan 15, 2026
Merged
@notatallshaw
Copy link
Copy Markdown
Member

notatallshaw commented Jan 15, 2026

#1062 has highlighted a real world use case of wanting to more clearly define our Public API, so I'm +1 on using __all__ in more places.

I've not seen this manipulation of __dir__ before, so I'm 0 on that.

@henryiii
Copy link
Copy Markdown
Contributor Author

henryiii commented Jan 15, 2026

Thanks! I'll keep this open till after 26.0 settles down. :)

@henryiii henryiii force-pushed the henryiii/chore/tags_all branch from 496e3ba to 299db62 Compare January 23, 2026 15:21
@henryiii henryiii merged commit 971ae00 into pypa:main Jan 23, 2026
44 checks passed
@henryiii henryiii deleted the henryiii/chore/tags_all branch January 23, 2026 15:47
@henryiii henryiii mentioned this pull request Jan 23, 2026
Merged
@henryiii
Copy link
Copy Markdown
Contributor Author

henryiii commented Jan 23, 2026

pylance does respect __all__, I see warnings in VSCode about using things that are not in __all__ being not publicly exported. 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@notatallshaw notatallshaw notatallshaw approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@henryiii @brettcannon @notatallshaw