There have been many complaints about the shortcoming of the documentation
towards informing users about
__main__. Both the popular
__name__ == '__main__' construct, and the role of
__main__.py in a python module.
I propose a broad overhaul of
Doc/library/__main__.rst to address these
shortcomings and to provide a single source of truth on
general!). This is an appropriate place to put this information.
__name__ == '__main__' and
constructs reasonably fall under the category of “Python Runtime Services,”
because they both control the way that programs run depending on how they are
used (command-line versus import versus running directly).
Doc/library/__main__.rst should have a new synopsis of, “CLIs,
import-time behavior, and if __name__ == ‘__main__’”, reflecting its new and
Additionally, the new docs should have the following distinct sections:
- Differentiating between __name__ == ‘__main__’ and __main.__.py
- __main__.py and the -m flag (this is roughly what is there already, although
it’s not as descriptive as it should be).
- __name__ and the
if __name__ == '__main__'construct.
If there is interest, I would be happy to open uptake this work on as soon as there is
consensus around this plan. I’m looking forward to hearing what you think!