Skip to content

Conversation

@Avasam
Copy link
Contributor

@Avasam Avasam commented May 31, 2025

Summary of changes

Adds the Command-related overloads from typeshed.

This makes it so that cast is no longer necessary when using those methods.

Only non-deprecated commands that setuptools exposes directly are listed (so nothing that requires importing from distutils directly, and excludes the test command). Private commands are still listed due to setuptools itself using them.

Works towards #2345

Pull Request Checklist

  • Changes have tests (no intended runtime changes, existing runtime and static tests should pass)
  • News fragment added in newsfragments/. (not public facing until py.typed marker is added)
    (See documentation for details)

@Avasam Avasam force-pushed the Merge-commands-overloads-from-typeshed branch from aba5b5f to f15e802 Compare May 31, 2025 22:28
@Avasam Avasam changed the title Merge commands overloads from typeshed Add commands overloads from typeshed Oct 23, 2025
@Avasam Avasam force-pushed the Merge-commands-overloads-from-typeshed branch from f15e802 to b67d72b Compare October 31, 2025 17:29
@Avasam Avasam force-pushed the Merge-commands-overloads-from-typeshed branch 2 times, most recently from 62fb251 to 157f75d Compare January 28, 2026 01:55
@Avasam Avasam force-pushed the Merge-commands-overloads-from-typeshed branch from 157f75d to a723310 Compare January 28, 2026 14:38
@abravalheri
Copy link
Contributor

abravalheri commented Jan 28, 2026

Thank you very much for working on this @Avasam. I really appreciate the effort and the direction that you plan to move the codebase. So I wanted to give you some feedback.

Before proceeding with the review/merge, I would like to hear @jaraco, mostly because this PR introduces a large amount of typing‑related boilerplate. I'm a bit unsure about this level of case‑by‑case expansion. I don't know if it is something we can sustainably maintain in the code-base.

Patterns like case-by-case analysis which require importing every submodule individually and then writing an exhaustive set of overloads tend to break the "single source of truth" principle, and introduce code prone to be brittle. That's my main hesitation, not the idea/intention itself, but the long‑term impact on the codebase.

Ideally, I'd really like to find a solution that gives us better typing coverage without requiring such extensive double/triple bookkeeping.

@Avasam
Copy link
Contributor Author

Avasam commented Jan 28, 2026

It's unfortunate that the Python typing ecosystem doesn't allow dynamically / programmatically generated types (like typescript does where you can do string manipulation to match a type/attribute name and it'll resolve to that type). And I don't think we're gonna get anything close for a long time ^^"

I agree this looks like a lot, but I still want to offer it as it is the most correct result to prevent both false-positives and false-negatives in user code. Trying to make a case for it.
Maintenance-wise:

  • Any removed commands would immediately be flagged by type-checkers in the CI, and easy to cleanup
  • Any added command may or may not be picked-up as missing, depending on how thorough newly written tests are.
    • I don't think adding new commands is a common scenario for setuptools (so it shouldn't be a constant maintenance chore)
    • Even if it is forgotten, it has no runtime impact. And the only affected users will be those using the new command with strict type checking in a way that's not compatible with the base Command class. At which point they can temporarily type-ignore, and open an issue or patch, which can be easily dealt with.
    • You do have to add the new command to more than one place, which is the worst part book-keeping-wise, but I don,t think it's hard do search for the existing command overloads.

Trying to find potential alternatives that are still improvements on the satus-quo / closer to what typeshed does:

  1. setuptools/__init__.py and setuptools/dist.py could use a build-time generated .pyi stubs file similar to what [Waiting for distutils sync] Generate distutils-stubs on install #4861 is currently attempting. This could also be relevant to Type setup method #5021. On one hand there's a slightly increased complexity, but most of the mechanism will already be there with 4861.
  2. Add all of the extra attributes from Command sub-classes to Command. I really don't like this solution. It doesn't solve bookkeeping as modifying a sub-command could modify Command code. Even if done type-only, it would only reduce false-positives (not false-negatives) and would be lying about the actual type.

This also differs from #5021 and #5022 where TypedDicts improvements can likely now allow a more DRY approach.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants