python-docs-el/library/__main__.po at 3.13 · python/python-docs-el

548 lines (475 loc) · 15.8 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2024, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
"Project-Id-Version: Python 3.12\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-11-27 09:00+0200\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: library/__main__.rst:2
msgid ":mod:`!__main__` --- Top-level code environment"
#: library/__main__.rst:10
"In Python, the special name ``__main__`` is used for two important "
"constructs:"
#: library/__main__.rst:12
"the name of the top-level environment of the program, which can be checked "
"using the ``__name__ == '__main__'`` expression; and"
#: library/__main__.rst:14
msgid "the ``__main__.py`` file in Python packages."
#: library/__main__.rst:16
"Both of these mechanisms are related to Python modules; how users interact "
"with them and how they interact with each other.  They are explained in "
"detail below.  If you're new to Python modules, see the tutorial section :"
"ref:`tut-modules` for an introduction."
#: library/__main__.rst:25
msgid "``__name__ == '__main__'``"
#: library/__main__.rst:27
"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::"
#: library/__main__.rst:31
">>> import configparser\n"
">>> configparser.__name__\n"
"'configparser'"
#: library/__main__.rst:35
"If the file is part of a package, ``__name__`` will also include the parent "
"package's path::"
#: library/__main__.rst:38
">>> from concurrent.futures import process\n"
">>> process.__name__\n"
"'concurrent.futures.process'"
#: library/__main__.rst:42
"However, if the module is executed in the top-level code environment, its "
"``__name__`` is set to the string ``'__main__'``."
#: library/__main__.rst:46
msgid "What is the \"top-level code environment\"?"
#: library/__main__.rst:48
"``__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."
#: library/__main__.rst:53
msgid "The top-level code environment can be:"
#: library/__main__.rst:55
msgid "the scope of an interactive prompt::"
#: library/__main__.rst:57
">>> __name__\n"
"'__main__'"
#: library/__main__.rst:60
msgid "the Python module passed to the Python interpreter as a file argument:"
#: library/__main__.rst:62
"$ python helloworld.py\n"
"Hello, world!"
#: library/__main__.rst:67
"the Python module or package passed to the Python interpreter with the :"
"option:`-m` argument:"
#: library/__main__.rst:70
"$ python -m tarfile\n"
"usage: tarfile.py [-h] [-v] (...)"
#: library/__main__.rst:75
msgid "Python code read by the Python interpreter from standard input:"
#: library/__main__.rst:77
"$ echo \"import this\" | python\n"
"The Zen of Python, by Tim Peters\n"
"Beautiful is better than ugly.\n"
"Explicit is better than implicit.\n"
#: library/__main__.rst:86
"Python code passed to the Python interpreter with the :option:`-c` argument:"
#: library/__main__.rst:88
"$ python -c \"import this\"\n"
"The Zen of Python, by Tim Peters\n"
"Beautiful is better than ugly.\n"
"Explicit is better than implicit.\n"
#: library/__main__.rst:97
"In each of these situations, the top-level module's ``__name__`` is set to "
"``'__main__'``."
#: library/__main__.rst:100
"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::"
#: library/__main__.rst:105
"if __name__ == '__main__':\n"
"    # Execute when the module is not initialized from an import statement.\n"
#: library/__main__.rst:111
"For a more detailed look at how ``__name__`` is set in all situations, see "
"the tutorial section :ref:`tut-modules`."
#: library/__main__.rst:239
msgid "Idiomatic Usage"
#: library/__main__.rst:118
"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."
#: library/__main__.rst:123
"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."
#: library/__main__.rst:127
"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::"
#: library/__main__.rst:131
"# echo.py\n"
"import shlex\n"
"import sys\n"
"def echo(phrase: str) -> None:\n"
"   \"\"\"A dummy wrapper around print.\"\"\"\n"
"   # for demonstration purposes, you can imagine that there is some\n"
"   # valuable and reusable logic inside this function\n"
"   print(phrase)\n"
"def main() -> int:\n"
"    \"\"\"Echo the input arguments to standard output\"\"\"\n"
"    phrase = shlex.join(sys.argv)\n"
"    echo(phrase)\n"
"    return 0\n"
"if __name__ == '__main__':\n"
"    sys.exit(main())  # next section explains the use of sys.exit"
#: library/__main__.rst:151
"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."
#: library/__main__.rst:158
"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__'``."
#: library/__main__.rst:165
msgid "Packaging Considerations"
#: library/__main__.rst:167
"``main`` functions are often used to create command-line tools by specifying "
"them as entry points for console scripts.  When this is done, `pip <https://"
"pip.pypa.io/>`_ inserts the function call into a template script, where the "
"return value of ``main`` is passed into :func:`sys.exit`. For example::"
#: library/__main__.rst:173
msgid "sys.exit(main())"
#: library/__main__.rst:175
"Since the call to ``main`` is wrapped in :func:`sys.exit`, the expectation "
"is that your function will return some value acceptable as an input to :func:"
"`sys.exit`; typically, an integer or ``None`` (which is implicitly returned "
"if your function does not have a return statement)."
#: library/__main__.rst:180
"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 "
#: library/__main__.rst:185
"In particular, be careful about returning strings from your ``main`` "
"function. :func:`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 :data:`sys.stderr`.  The ``echo."
"py`` example from earlier exemplifies using the ``sys.exit(main())`` "
"convention."
#: library/__main__.rst:193
"`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."
#: library/__main__.rst:199
msgid "``__main__.py`` in Python Packages"
#: library/__main__.rst:201
"If you are not familiar with Python packages, see section :ref:`tut-"
"packages` of the tutorial.  Most commonly, the ``__main__.py`` file is used "
"to provide a command-line interface for a package. Consider the following "
"hypothetical package, \"bandclass\":"
#: library/__main__.rst:206
"bandclass\n"
"  ├── __init__.py\n"
"  ├── __main__.py\n"
"  └── student.py"
#: library/__main__.rst:213
"``__main__.py`` will be executed when the package itself is invoked directly "
"from the command line using the :option:`-m` flag. For example:"
#: library/__main__.rst:216
msgid "$ python -m bandclass"
#: library/__main__.rst:220
"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 hypothetical case, it might make sense to allow the teacher to search "
"for students::"
#: library/__main__.rst:225
"# bandclass/__main__.py\n"
"import sys\n"
"from .student import search_students\n"
"student_name = sys.argv[1] if len(sys.argv) >= 2 else ''\n"
"print(f'Found student: {search_students(student_name)}')"
#: library/__main__.rst:233
"Note that ``from .student import search_students`` is an example of a "
"relative import.  This import style can be used when referencing modules "
"within a package.  For more details, see :ref:`intra-package-references` in "
"the :ref:`tut-modules` section of the tutorial."
#: library/__main__.rst:241
"The content of ``__main__.py`` typically isn't fenced with an ``if __name__ "
"== '__main__'`` block.  Instead, those files are kept short and import "
"functions to execute from other modules.  Those other modules can then be "
"easily unit-tested and are properly reusable."
#: library/__main__.rst:246
"If used, an ``if __name__ == '__main__'`` block will still work as expected "
"for a ``__main__.py`` file within a package, because its ``__name__`` "
"attribute will include the package's path if imported::"
#: library/__main__.rst:250
">>> import asyncio.__main__\n"
">>> asyncio.__main__.__name__\n"
"'asyncio.__main__'"
#: library/__main__.rst:254
"This won't work for ``__main__.py`` files in the root directory of a ``."
"zip`` file though.  Hence, for consistency, a minimal ``__main__.py`` "
"without a ``__name__`` check is preferred."
#: library/__main__.rst:260
"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 ``python -m venv [directory]``."
#: library/__main__.rst:264
"See :mod:`runpy` for more details on the :option:`-m` flag to the "
"interpreter executable."
#: library/__main__.rst:267
"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."
#: library/__main__.rst:274
msgid "``import __main__``"
#: library/__main__.rst:276
"Regardless of which module a Python program was started with, other modules "
"running within that same program can import the top-level environment's "
"scope (:term:`namespace`) by importing the ``__main__`` module.  This "
"doesn't import a ``__main__.py`` file but rather whichever module that "
"received the special name ``'__main__'``."
#: library/__main__.rst:282
msgid "Here is an example module that consumes the ``__main__`` namespace::"
#: library/__main__.rst:284
"# namely.py\n"
"import __main__\n"
"def did_user_define_their_name():\n"
"    return 'my_name' in dir(__main__)\n"
"def print_user_name():\n"
"    if not did_user_define_their_name():\n"
"        raise ValueError('Define the variable `my_name`!')\n"
"    if '__file__' in dir(__main__):\n"
"        print(__main__.my_name, \"found in file\", __main__.__file__)\n"
"    else:\n"
"        print(__main__.my_name)"
#: library/__main__.rst:300
msgid "Example usage of this module could be as follows::"
#: library/__main__.rst:302
"# start.py\n"
"import sys\n"
"from namely import print_user_name\n"
"# my_name = \"Dinsdale\"\n"
"def main():\n"
"    try:\n"
"        print_user_name()\n"
"    except ValueError as ve:\n"
"        return str(ve)\n"
"if __name__ == \"__main__\":\n"
"    sys.exit(main())"
#: library/__main__.rst:319
msgid "Now, if we started our program, the result would look like this:"
#: library/__main__.rst:321
"$ python start.py\n"
"Define the variable `my_name`!"
#: library/__main__.rst:326
"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:"
#: library/__main__.rst:330
"$ python start.py\n"
"Dinsdale found in file /path/to/start.py"
#: library/__main__.rst:335
"Note that importing ``__main__`` doesn't cause any issues with "
"unintentionally running top-level code meant for script use which is put in "
"the ``if __name__ == \"__main__\"`` block of the ``start`` module. Why does "
"this work?"
#: library/__main__.rst:339
"Python inserts an empty ``__main__`` module in :data:`sys.modules` at "
"interpreter startup, and populates it by running top-level code. In our "
"example this is the ``start`` module which runs line by line and imports "
"``namely``. In turn, ``namely`` imports ``__main__`` (which is really "
"``start``). That's an import cycle! Fortunately, since the partially "
"populated ``__main__`` module is present in :data:`sys.modules`, Python "
"passes that to ``namely``. See :ref:`Special considerations for __main__ "
"<import-dunder-main>` in the import system's reference for details on how "
"this works."
#: library/__main__.rst:348
"The Python REPL is another example of a \"top-level environment\", so "
"anything defined in the REPL becomes part of the ``__main__`` scope::"
#: library/__main__.rst:351
">>> import namely\n"
">>> namely.did_user_define_their_name()\n"
">>> namely.print_user_name()\n"
"Traceback (most recent call last):\n"
"ValueError: Define the variable `my_name`!\n"
">>> my_name = 'Jabberwocky'\n"
">>> namely.did_user_define_their_name()\n"
">>> namely.print_user_name()\n"
"Jabberwocky"
#: library/__main__.rst:364
"Note that in this case the ``__main__`` scope doesn't contain a ``__file__`` "
"attribute as it's interactive."
#: library/__main__.rst:367
"The ``__main__`` scope is used in the implementation of :mod:`pdb` and :mod:"
"`rlcompleter`."
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

__main__.po

Latest commit

History

__main__.po

File metadata and controls

main.po

main.po
