Skip to content
Merged
Changes from 1 commit
Commits
Show all changes
51 commits
Select commit Hold shift + click to select a range
02e9edf
__main__docs: intro and first secton
jdevries3133 Jun 21, 2021
c95f69b
bpo-44494: rewrite of Doc/library/__main__.rst (first draft)
jdevries3133 Jun 23, 2021
235e866
bpo-44494: add blurb
jdevries3133 Jun 23, 2021
a292ab6
Update __main__.rst
geryogam Jun 30, 2019
d7a1999
Update __main__.rst
geryogam Jun 30, 2019
8398f08
Take Steven d’Aprano’s review into account
geryogam Sep 16, 2020
1fcb2af
Rewrap lines
geryogam Sep 16, 2020
2bde063
Remove trailing whitespaces
geryogam Sep 17, 2020
d29fd2a
bpo-39452: rewrite and expansion of __main__.rst
jdevries3133 Jun 23, 2021
4c60f2c
mention runpy
jdevries3133 Jun 29, 2021
2b5f710
add "design patterns" section, fix section title hierarchies
jdevries3133 Jun 29, 2021
7e495d7
add sentence about console_scripts
jdevries3133 Jun 29, 2021
56afeaa
misc formatting; change "Design Patterns" to "Idiomatic Usage"
jdevries3133 Jun 30, 2021
2a398ef
add section about sys.exit(main()) convention
jdevries3133 Jun 30, 2021
1a9956c
make last paragraph 'idiomatic usage'; add comment about maybe deleting
jdevries3133 Jun 30, 2021
c4b5cea
fix linting error (default context used in comment)
jdevries3133 Jun 30, 2021
1f012b4
revise example so that main() does not take arguments
jdevries3133 Jun 30, 2021
f095362
add console_scripts section, remove bad old example
jdevries3133 Jun 30, 2021
c42b706
minor proofreading changes
jdevries3133 Jun 30, 2021
7fe7f1c
implement changes suggest by @merwok
jdevries3133 Jun 30, 2021
c063da1
fix: typos
jdevries3133 Jun 30, 2021
7c6b451
fix wording, slim down example, add reference to relative import docs
jdevries3133 Jul 7, 2021
06bcb09
respond to review from @pradyunsg
jdevries3133 Jul 21, 2021
80756b3
Merge remote-tracking branch 'upstream/main' into bpo-39452__main__docs
jdevries3133 Jul 31, 2021
647c471
add `import __main__` section
jdevries3133 Aug 1, 2021
457bbc9
revisions and proofreading
jdevries3133 Aug 1, 2021
3d9b3b9
eliminate opinionated section about idiomatic usage of `__main__.py`
jdevries3133 Aug 1, 2021
dd68513
proofread `__main__.py` section
jdevries3133 Aug 1, 2021
6ee7090
Merge branch 'main' of github.com:python/cpython into bpo-39452__main…
jdevries3133 Aug 4, 2021
757b03a
incorporate suggested changes from @Fidget-Spinner
jdevries3133 Aug 10, 2021
8e86468
incorporate suggested changes from @yaseppochi
jdevries3133 Aug 10, 2021
f33a081
fix formatting
jdevries3133 Aug 10, 2021
14bad85
name equals main
jdevries3133 Aug 12, 2021
d150674
Merge branch 'main' of github.com:python/cpython into bpo-39452__main…
jdevries3133 Aug 12, 2021
7b987cb
Merge branch 'bpo-39452__main__docs' of github.com:jdevries3133/cpyth…
jdevries3133 Aug 12, 2021
b9db705
also change reference to name equals main section
jdevries3133 Aug 12, 2021
168c774
implement feedback from @holdenweb, python-dev, and @merwork
jdevries3133 Aug 12, 2021
c450171
fix trailing whitespace
jdevries3133 Aug 12, 2021
077e7a4
Remove .bak file
ambv Aug 24, 2021
eb42489
Thorough editing pass
ambv Aug 24, 2021
7c61e78
Move `__main__.py` section above the `import __main__` section
ambv Aug 24, 2021
45a9425
s/command line/command-line/
ambv Aug 24, 2021
073e9d7
Mention asyncio.__main__
ambv Aug 24, 2021
ccb9004
Restore proper document name
ambv Aug 24, 2021
f8630fa
Use proper .. seealso:: sections.
ambv Aug 24, 2021
1e86e02
Appease `make suspicious`
ambv Aug 24, 2021
9c87442
Spell out examples of top-level code environments
ambv Aug 24, 2021
0d4fc8a
Appease double dot alignment aesthetics
ambv Aug 24, 2021
4e51333
Replace lies with truth
ambv Aug 24, 2021
6f0f82c
Improve flow introducing what "top-level code environment" is
ambv Aug 24, 2021
46e7668
Use module names consistently in example
ambv Aug 24, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Appease double dot alignment aesthetics
  • Loading branch information
ambv committed Aug 24, 2021
commit 0d4fc8a31a05a8c9a6ade86290ab74eec340d4ea
64 changes: 32 additions & 32 deletions Doc/library/__main__.rst
Original file line number Diff line number Diff line change
Expand Up @@ -56,38 +56,38 @@ The top-level code environment can be:

.. code-block:: shell-session

$ python3 helloworld.py
Hello, world!
$ python3 helloworld.py
Hello, world!

* the Python module or package passed to the Python interpreter with the
:option:`-m` argument:

.. code-block:: shell-session

$ python3 -m tarfile
usage: tarfile.py [-h] [-v] (...)
$ python3 -m tarfile
usage: tarfile.py [-h] [-v] (...)

* Python code read by the Python interpreter from standard input:

.. code-block:: shell-session

$ echo "import this" | python3
The Zen of Python, by Tim Peters
$ echo "import this" | python3
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...
Beautiful is better than ugly.
Explicit is better than implicit.
...

* Python code passed to the Python interpreter with the :option:`-c` argument:

.. code-block:: shell-session

$ python3 -c "import this"
The Zen of Python, by Tim Peters
$ python3 -c "import this"
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...
Beautiful is better than ugly.
Explicit is better than implicit.
...

In each of these situations, the top-level module's ``__name__`` is set to
``'__main__'``.
Expand All @@ -103,8 +103,8 @@ an import statement::

.. seealso::

For a more detailed look at how ``__name__`` is set in all situations, see
the tutorial section :ref:`tut-modules`.
For a more detailed look at how ``__name__`` is set in all situations, see
the tutorial section :ref:`tut-modules`.


Idiomatic Usage
Expand Down Expand Up @@ -185,9 +185,9 @@ earlier exemplifies using the ``sys.exit(main())`` convention.

.. seealso::

`Python Packaging User Guide <https://packaging.python.org/>`_
contains a collection of tutorials and references on how to distribute and
install Python packages with modern tools.
`Python Packaging User Guide <https://packaging.python.org/>`_
contains a collection of tutorials and references on how to distribute and
install Python packages with modern tools.


``__main__.py`` in Python Packages
Expand All @@ -210,7 +210,7 @@ directly from the command line using the :option:`-m` flag. For example:

.. code-block:: shell-session

$ python3 -m bandclass
$ python3 -m bandclass

This command will cause ``__main__.py`` to run. How you utilize this mechanism
will depend on the nature of the package you are writing, but in this
Expand Down Expand Up @@ -252,16 +252,16 @@ one mentioned above are preferred.

.. seealso::

See :mod:`venv` for an example of a package with a minimal ``__main__.py``
in the standard library. It doesn't contain a ``if __name__ == '__main__'``
block. You can invoke it with ``python3 -m venv [directory]``.
See :mod:`venv` for an example of a package with a minimal ``__main__.py``
in the standard library. It doesn't contain a ``if __name__ == '__main__'``
block. You can invoke it with ``python3 -m venv [directory]``.

See :mod:`runpy` for more details on the :option:`-m` flag to the
interpreter executable.
See :mod:`runpy` for more details on the :option:`-m` flag to the
interpreter executable.

See :mod:`zipapp` for how to run applications packaged as *.zip* files. In
this case Python looks for a ``__main__.py`` file in the root directory of
the archive.
See :mod:`zipapp` for how to run applications packaged as *.zip* files. In
this case Python looks for a ``__main__.py`` file in the root directory of
the archive.



Expand Down Expand Up @@ -315,17 +315,17 @@ Now, if we started our program, the result would look like this:

.. code-block:: shell-session

$ python3 start.py
Define the variable `my_name`!
$ python3 start.py
Define the variable `my_name`!

The exit code of the program would be 1, indicating an error. Uncommenting the
line with ``my_name = "Dinsdale"`` fixes the program and now it exits with
status code 0, indicating success:

.. code-block:: shell-session

$ python3 start.py
Dinsdale found in file /path/to/start.py
$ python3 start.py
Dinsdale found in file /path/to/start.py

Note that importing ``__main__`` doesn't cause any issues with unintentionally
running top-level code meant for script use which is put in the
Expand Down