fix(build): keep Click command docstrings in release binaries#1307
Merged
Conversation
edenfunf
requested review from
danielmeppiel and
sergio-sisternes-epam
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes missing Click command help text in PyInstaller-built release binaries by changing the PyInstaller optimization level so Python docstrings are preserved (allowing Click’s documented __doc__ fallback to populate command summaries and detailed help).
Changes:
- Update
build/apm.specto useoptimize=1(strip asserts, keep docstrings) soapm view --helprenders correctly in release binaries. - Add a corresponding entry to
CHANGELOG.mdunder## [Unreleased]describing the fix and trade-off.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
CHANGELOG.md |
Records the fix in the Unreleased “Fixed” section with PR/issue reference. |
build/apm.spec |
Lowers PyInstaller optimization to preserve __doc__ so Click help text is retained in release builds. |
sergio-sisternes-epam
approved these changes
May 13, 2026
sergio-sisternes-epam
added
the
panel-review
sergio-sisternes-epam
added
the
status/accepted
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
sergio-sisternes-epam
added
status/triaged
PyInstaller `optimize=2` (= `python -OO`) was stripping `__doc__` from every Click `@click.command()`. Every other top-level command works around this by setting an explicit `help=` kwarg; `view` was the only one relying on Click's documented docstring fallback, so in release binaries `apm view --help` was missing its description / Fields / Examples and the `view` row in `apm --help` had no summary. Lower the spec to `optimize=1` so asserts are still stripped (the real size/perf benefit) but `__doc__` survives. Click's help-from-docstring fallback works as documented for all current and future commands; the hidden `apm info` alias (which reads `view_cmd.help`) is fixed automatically as a side-effect. Binary grows ~1.4 MB on the bundle. Fixes microsoft#1298
Contributor
Author
|
@sergio-sisternes-epam To resolve the conflict, thank you! |
danielmeppiel
approved these changes
May 14, 2026
This was referenced May 14, 2026
sergio-sisternes-epam
pushed a commit
that referenced
this pull request
May 19, 2026
PyInstaller `optimize=2` (= `python -OO`) was stripping `__doc__` from every Click `@click.command()`. Every other top-level command works around this by setting an explicit `help=` kwarg; `view` was the only one relying on Click's documented docstring fallback, so in release binaries `apm view --help` was missing its description / Fields / Examples and the `view` row in `apm --help` had no summary. Lower the spec to `optimize=1` so asserts are still stripped (the real size/perf benefit) but `__doc__` survives. Click's help-from-docstring fallback works as documented for all current and future commands; the hidden `apm info` alias (which reads `view_cmd.help`) is fixed automatically as a side-effect. Binary grows ~1.4 MB on the bundle. Fixes #1298
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
apm --helpshows theviewrow with no summary, andapm view --helpshows onlyUsage:/Options:with no description, fields, or examples — in release binaries only. Source builds render the help correctly.Reported in #1298 against 0.8.13 (the first release containing
view; the same shape previously affectedoutdatedin #1204 / #1216).Root cause
build/apm.specsets PyInstalleroptimize=2, which ispython -OO— it strips both asserts AND__doc__. Every Click@click.command()that omits an explicithelp=kwarg loses its summary and detailed help in the binary, because Click's documented fallback isfunc.__doc__.The project has been working around this by defensively setting
help=on every command.viewwas the only command that relied on the docstring fallback, so it was the only one broken in v0.13.0;outdatedhit the same trap previously (#1216 patched it the same defensive way).Fix
Lower
optimize=2→optimize=1inbuild/apm.spec.-Ostill strips asserts (the actual perf / size benefit), but__doc__survives, so Click's documented help-from-docstring fallback works as advertised. Theapm infohidden alias (which readsview_cmd.help) is fixed automatically as a side-effect.One-line spec change with a one-line comment recording the trade-off.
Validation
Built two binaries from this branch on Windows (PyInstaller 6.16.0):
optimize=2) reproduces [BUG] Help missing for view command #1298:view$(empty summary) andapm view --helpmissing description / Fields / Examples.optimize=1):apm view --helpis byte-identical to sourceapm view --help(only difference isargv[0]program name inUsage:). All 25 visible commands still have summaries;apm infohidden alias also renders correctly.Functional tests against the fix binary:
apm view <installed-pkg>— renders Rich panelapm view <missing-pkg>— exits 1 with available-package listapm view <pkg> <invalid-field>— exits 1 with valid-field hintapm info <pkg>— works (hidden alias)Test suite (
tests/unit/): 8275 passed, 5 skipped. Pre-existing 3 failures + 2 errors (Windows path absoluteness intest_config_command, missing optionaljsonschemadep) reproduce onorigin/mainwithout this change.Binary size delta: bundle 29.6 MB → 31.0 MB (+1.4 MB / +4.6 %); exe 8.86 MB → 10.1 MB. Trade-off documented in the spec comment.
Fixes #1298