New submission from Jack DeVries <jdevries3...@gmail.com>: I made a proposal on discourse to redraft Doc/library/__main__.rst as it is currently quite terse and there have been a series of bpo's asking for more. See my discourse post:
https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344 ================ 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 bpo-24632 bpo-38452 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: 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! ================ Anyway, I have a first draft ready. I'm sure there will be plenty of feedback, so let it rip! I will open a GitHub PR and attach it to this bpo in just a moment. ---------- assignee: docs@python components: Documentation messages: 396380 nosy: docs@python, jack__d priority: normal severity: normal status: open title: Overhaul of Doc/library/__main__.rst type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue44494> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
