add help for __name__

Author: adqm

Doc/tools/extensions/pydoc_topics.py

@@ -70,6 +70,7 @@
     "integers",
     "lambda",
     "lists",
+    "name_equals_main",
     "naming",
     "nonlocal",
     "numbers",

Lib/pydoc.py

@@ -1851,6 +1851,7 @@ def _introdoc():
 
 def collect_dunders(symbols):
     dunders = {
+        '__name__': ('name_equals_main', ''),
         '__main__': ('__main__', ''),
         '__call__': ('callable-types', 'SPECIALMETHODS'),
     }

Lib/pydoc_data/topics.py

@@ -1,4 +1,4 @@
-# Autogenerated by Sphinx on Sat Aug 16 20:05:29 2025
+# Autogenerated by Sphinx on Mon Aug 18 00:55:48 2025
 # as part of the release process.
 
 topics = {
@@ -7211,6 +7211,175 @@ def <lambda>(parameters):
 from left to right and placed into the list object in that order.
 When a comprehension is supplied, the list is constructed from the
 elements resulting from the comprehension.
+''',
+    'name_equals_main': r'''"__name__ == '__main__'"
+************************
+
+When a Python module or package is imported, "__name__" is set to the
+module’s name.  Usually, this is the name of the Python file itself
+without the ".py" extension:
+
+   >>> import configparser
+   >>> configparser.__name__
+   'configparser'
+
+If the file is part of a package, "__name__" will also include the
+parent package’s path:
+
+   >>> from concurrent.futures import process
+   >>> process.__name__
+   'concurrent.futures.process'
+
+However, if the module is executed in the top-level code environment,
+its "__name__" is set to the string "'__main__'".
+
+
+What is the “top-level code environment”?
+=========================================
+
+"__main__" is the name of the environment where top-level code is run.
+“Top-level code” is the first user-specified Python module that starts
+running. It’s “top-level” because it imports all other modules that
+the program needs. Sometimes “top-level code” is called an *entry
+point* to the application.
+
+The top-level code environment can be:
+
+* the scope of an interactive prompt:
+
+     >>> __name__
+     '__main__'
+
+* the Python module passed to the Python interpreter as a file
+  argument:
+
+     $ python helloworld.py
+     Hello, world!
+
+* the Python module or package passed to the Python interpreter with
+  the "-m" argument:
+
+     $ python -m tarfile
+     usage: tarfile.py [-h] [-v] (...)
+
+* Python code read by the Python interpreter from standard input:
+
+     $ echo "import this" | python
+     The Zen of Python, by Tim Peters
+
+     Beautiful is better than ugly.
+     Explicit is better than implicit.
+     ...
+
+* Python code passed to the Python interpreter with the "-c" argument:
+
+     $ python -c "import this"
+     The Zen of Python, by Tim Peters
+
+     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__'".
+
+As a result, a module can discover whether or not it is running in the
+top-level environment by checking its own "__name__", which allows a
+common idiom for conditionally executing code when the module is not
+initialized from an import statement:
+
+   if __name__ == '__main__':
+       # Execute when the module is not initialized from an import statement.
+       ...
+
+See also:
+
+  For a more detailed look at how "__name__" is set in all situations,
+  see the tutorial section Modules.
+
+
+Idiomatic Usage
+===============
+
+Some modules contain code that is intended for script use only, like
+parsing command-line arguments or fetching data from standard input.
+If a module like this was imported from a different module, for
+example to unit test it, the script code would unintentionally execute
+as well.
+
+This is where using the "if __name__ == '__main__'" code block comes
+in handy. Code within this block won’t run unless the module is
+executed in the top-level environment.
+
+Putting as few statements as possible in the block below "if __name__
+== '__main__'" can improve code clarity and correctness. Most often, a
+function named "main" encapsulates the program’s primary behavior:
+
+   # echo.py
+
+   import shlex
+   import sys
+
+   def echo(phrase: str) -> None:
+      """A dummy wrapper around print."""
+      # for demonstration purposes, you can imagine that there is some
+      # valuable and reusable logic inside this function
+      print(phrase)
+
+   def main() -> int:
+       """Echo the input arguments to standard output"""
+       phrase = shlex.join(sys.argv)
+       echo(phrase)
+       return 0
+
+   if __name__ == '__main__':
+       sys.exit(main())  # next section explains the use of sys.exit
+
+Note that if the module didn’t encapsulate code inside the "main"
+function but instead put it directly within the "if __name__ ==
+'__main__'" block, the "phrase" variable would be global to the entire
+module.  This is error-prone as other functions within the module
+could be unintentionally using the global variable instead of a local
+name.  A "main" function solves this problem.
+
+Using a "main" function has the added benefit of the "echo" function
+itself being isolated and importable elsewhere. When "echo.py" is
+imported, the "echo" and "main" functions will be defined, but neither
+of them will be called, because "__name__ != '__main__'".
+
+
+Packaging Considerations
+========================
+
+"main" functions are often used to create command-line tools by
+specifying them as entry points for console scripts.  When this is
+done, pip inserts the function call into a template script, where the
+return value of "main" is passed into "sys.exit()". For example:
+
+   sys.exit(main())
+
+Since the call to "main" is wrapped in "sys.exit()", the expectation
+is that your function will return some value acceptable as an input to
+"sys.exit()"; typically, an integer or "None" (which is implicitly
+returned if your function does not have a return statement).
+
+By proactively following this convention ourselves, our module will
+have the same behavior when run directly (i.e. "python echo.py") as it
+will have if we later package it as a console script entry-point in a
+pip-installable package.
+
+In particular, be careful about returning strings from your "main"
+function. "sys.exit()" will interpret a string argument as a failure
+message, so your program will have an exit code of "1", indicating
+failure, and the string will be written to "sys.stderr".  The
+"echo.py" example from earlier exemplifies using the
+"sys.exit(main())" convention.
+
+See also:
+
+  Python Packaging User Guide contains a collection of tutorials and
+  references on how to distribute and install Python packages with
+  modern tools.
 ''',
     'naming': r'''Naming and binding
 ******************