Refactor compileall: improve docstrings, add type hints, comments, and tests

[deadlovelll]

Feature or enhancement

Proposal:

Proposal: Refactor compileall module

This proposal aims to improve the compileall module with:

• More informative docstrings for all public functions
• Better inline comments explaining complex logic
• Type hints for function signatures
• Minor PEP8 formatting fixes
• Additional unit tests for new helper functions

The compileall module is currently not very well documented, which makes it harder for both Python users and contributors to understand and maintain. Improving docstrings, comments, and typing will make the module more accessible and maintainable.

No logic changes are intended this is a pure refactoring and documentation improvement.

Feedback welcome — happy to iterate and split this into smaller PRs if needed!

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Linked PRs

• gh-144223: Refactor compileall: improve docstrings, add type hints, comments, and tests #144224

[StanFromIreland]

Type hints for function signatures

See https://discuss.python.org/t/type-annotations-in-the-standard-library/7309 for why we don't allow type annotations in the stdlib.

[deadlovelll]

Type hints for function signatures

See https://discuss.python.org/t/type-annotations-in-the-standard-library/7309 for why we don't allow type annotations in the stdlib.

Okay, i need to remove all type annotations, right?

[terryjreedy]

python/typeshed has annotations for stdlib modules. If it does not already have them for compileall, or they are incomplete, then look there or maybe ask for contribution guidance.

[ZeroIntensity]

The PR, as it currently stands, appears to contain only cosmetic changes, which we don't allow. Usually, with refactoring, we want to actually improve developer experience or code quality, not just adjust the formatting and add comments.

Changing formatting on a scale like this breaks the blame, so it actually adds to the overall maintenance burden in practice. PEP 8 also explicitly says not to reformat just for the sake of it:

Because the code in question predates the introduction of the guideline and there is no other reason to be modifying that code.

The new comments look fairly AI-esque. For us, comments are typically more useful when they document why the code does something, not what it does. (We make exceptions for pieces of code that are especially complicated, such as the dictionary implementation. But those are better suited as one large top-level comment that explains the design as a whole.)

All that said, the docstring changes might be useful. I don't think it's a good idea to add full Google-style docstrings (we should follow PEP 257 if anything), but simple one-line summaries might be nice. Additional information about arguments and return values should be added to the compileall documentation rather than the docstrings. (I do think it would be nice to have the official docs generated from docstrings, but I won't fight that battle right now.)

[picnixz]

The PR appears to be entirely AI. Adding docstring comments also adds a maintenance burden. Better improve rST docs if they are incomplete.

[picnixz]

If you want to improve code coverage, please open a dedicated issue and explicitly state what needs to be done and why.

[picnixz]

The compileall module is currently not very well documented, which makes it harder for both Python users and contributors to understand and maintain

It's not necessarily their role to do it. That's the role of core developers. If something is unclear, this is a doc (rST) issue which should be separate as well.