README.rst: recommend python -OO compatible usage #515
Conversation
This file contains 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
The current recommended recipe using docstring syntax is incompatible with python -OO mode. https://discuss.python.org/t/stop-ignoring-asserts-when-running-in-optimized-mode/13132/31 Who cares? - `-OO` slightly reduces RAM usage. - If one distributes a script as a self-contained executable, it's tempting to precompile .pyo with docstring stripping for reduced dependencies size. But any files using docopt as recommended will stop working. - It's an easily avoidable "papercut". This mentions the problem in the README, and modifies the default recipe so it's `-OO`-safe. * There is a shorter recipe that also works with -OO: __doc__ = """Naval Fate. ... """ That one feels too "magic" to me though, and really needs a comment for the next programmer to not remove it.
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.
The current recommended recipe using docstring syntax is incompatible with python -OO mode.
TypeError: expected string or bytes-like objecthttps://discuss.python.org/t/stop-ignoring-asserts-when-running-in-optimized-mode/13132/31
Who cares?
-OOslightly reduces RAM usage.-OO...This PR mentions the problem in the README, and modifies the default recipe so it's
-OO-safe.There is a shorter recipe that happens to work with -OO:
That's it! Because syntactically it's an assignment statement, not native docstring syntax, it doesn't get stripped. And it executes after
__doc__is initialized toNoneby (lack of) native docstring syntax, so no conflict.But that feels too "magic" to me (and really requires a comment for the next programmer to not remove it). IMHO the explicit use of a different variable
DOC = ...is clearer, and highlights the independent goals of:docopt()— which can take whatever string you give it;pydoc/help()/ other introspection which may look at.__doc__.Which do you think is better to document?