Generalize export-functions hook: scan entire package directory, include all functions, add --strict#1628
Generalize export-functions hook: scan entire package directory, include all functions, add --strict#1628
Conversation
Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/f28bf4d2-0a29-421e-9322-10081aeec8af Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
…e docstrings Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/2927dcf9-6699-49b6-8758-fd7ac587c972 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
…unctions.txt) Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/fc6c5b3c-a0ec-4bdd-9b7a-929b0cd79c29 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
hooks/export-functions.py
Outdated
|
|
||
| # The modules to scan for public functions with docstrings. | ||
| # Add entries here to include additional modules in the reference. | ||
| MODULES: list[_Entry] = [ |
There was a problem hiding this comment.
@copilot don't hard code modules. Scan all modules in the relevant package directory (accept this as an option to the CLI call for this hook, similar to the export-module-tree hook).
We should aim to keep this hook module totally general - not have usethis specifics.
Similarly, include a "--strict" CLI arg to fail the hook if there are functions without docstrings.
Please make sure you include ALL functions.,including ones with leading underscores.
There was a problem hiding this comment.
Done in ac06c66. The hook now:
- Accepts
--source-root(the root package directory) and scans all.pyfiles recursively — no hardcoded module list - Includes ALL functions, including private ones with leading
_ - Derives module names from file paths relative to the source root's parent (same pattern as
export-module-tree) - Adds
--strictto fail when any function is missing a docstring
The .pre-commit-config.yaml invocation now passes --source-root=src/usethis --output-file=docs/functions.txt. docs/functions.txt expanded from 26 to 576 lines covering every function in the package.
… include all functions, add --strict Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/6b62b5f0-931f-451c-b79f-b08e4845040f Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
|
Feels like this was a bit confused based on the order I triggered the PRs. Still could try and improve the skills here but I can't be bothered. |
hooks/export-functions.pywas tightly coupled to the usethis project — first via hard-coded section headings, then via a hard-coded list of specific modules to scan. The hook is now fully general and can be applied to any Python package without modification.Changes
hooks/export-functions.py: Completely rewritten to be project-agnostic:_Entrydataclass and all hard-coded module lists--source-rootCLI argument (accepts the root package directory, mirroringexport-module-tree's interface) — the hook recursively scans all.pyfiles under it_)--strictCLI flag: fails the hook when any function is missing a docstring.pre-commit-config.yaml: Updatedexport-functionsargs to["--source-root=src/usethis", "--output-file=docs/functions.txt"]docs/functions.txt: Regenerated — expanded from 26 lines to 576 lines covering every function in the packageAGENTS.md: Updated<!-- sync:docs/functions.txt -->block to matchTwo source docstrings fixed to avoid prettier-incompatible markdown syntax (
__eq__reworded, double RST backticks changed to single markdown backticks) socheck-doc-syncpasses cleanly after prettier runs📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.