# Proposed Overhaul of \_\_main\_\_.py Documentation (Doc/library/\_\_main\_\_.rst)

**URL:** <https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344>\
**Category:** Documentation\
**Created:** [June 20, 2021, 4:01am UTC](https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344 "2021-06-20T04:01:29Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![jdevries3133](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jdevries3133/32/4402_2.png) [@jdevries3133](https://discuss.python.org/u/jdevries3133)\
**Post date:** [June 20, 2021, 4:01am UTC](https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344/1 "2021-06-20T04:01:29Z")

</div>

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.

[bpo-17359](https://bugs.python.org/issue17359)  
[bpo-24632](https://bugs.python.org/issue24632)  
[bpo-38452](https://bugs.python.org/issue38452)

I propose a broad overhaul of `Doc/library/ __main__.rst` to address these  
shortcomings and to provide a single source of truth on ` __main__ ` (in  
general!). This is an appropriate place to put this information.  
**Both** the ` __name__ == ' __main__'` and `fooModule/ __main__.py`  
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).

The new `Doc/library/ __main__.rst` should have a new synopsis of, “CLIs,  
import-time behavior, and if \_\_name\_\_ == ‘\_\_main\_\_’”, reflecting its new and  
broader focus.

Additionally, the new docs should have the following distinct sections:

1. Differentiating between \_\_name\_\_ == ‘\_\_main\_\_’ and \_\_main.\_\_.py
2. \_\_main\_\_.py and the -m flag (this is roughly what is there already, although  
it’s not as descriptive as it should be).
3. \_\_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!

---

<div class="post-metadata">

**Author:** ![jdevries3133](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jdevries3133/32/4402_2.png) [@jdevries3133](https://discuss.python.org/u/jdevries3133)\
**Post date:** [June 20, 2021, 1:34pm UTC](https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344/2 "2021-06-20T13:34:54Z")

</div>

\*\*correction: the latest bpo on this topic was [39452](https://bugs.python.org/issue39452), not 38452!

---

<div class="post-metadata">

**Author:** ![jdevries3133](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jdevries3133/32/4402_2.png) [@jdevries3133](https://discuss.python.org/u/jdevries3133)\
**Post date:** [June 30, 2021, 4:32pm UTC](https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344/3 "2021-06-30T16:32:05Z")

</div>

Update:

I decided to press forward with this via [bpo-39452.](https://bugs.python.org/issue39452) Please feel free to contribute to the discussion or provide more code review on the GitHub PR (or the bpo)!

[https://github.com/python/cpython/pull/26883#pullrequestreview-695622615](https://github.com/python/cpython/pull/26883#pullrequestreview-695622615)