Организация стартовой функции main в Python проекте

Раздел: Структура проекта -> точка входа в программу

Основной подход: защита кода при импорте

Как сделать, чтобы код выполнялся только при запуске файла как главной программы?

В Python каждому модулю присваивается встроенная переменная __name__. Когда файл запускается непосредственно, эта переменная равна строке '__main__'. При импорте модуля она становится равной имени модуля. Конструкция if __name__ == '__main__' позволяет определить, является ли текущий файл точкой входа.


# main_example.py
def main():
    print("Это главная функция программы.")

if __name__ == '__main__':
    main()

Main python (главная функция main в python)

При запуске python main_example.py будет выведено сообщение. При импорте import main_example функция main не вызовется, что позволяет использовать код как библиотеку.

Типичные ошибки:

  • Забыть проверить __name__: тогда весь код уровня модуля выполняется при импорте, что может привести к нежелательным побочным эффектам (вывод в консоль, запуск сервера и т.д.).
  • Помещать вызов main без блока if: если модуль импортируется, main запустится сразу.
  • Использовать глобальные переменные, которые изменяются при импорте, что нарушает предсказуемость.
  • Ошибка в написании '__main__' (два подчеркивания с обеих сторон).

Как передать аргументы командной строки в main с помощью sys.argv?

Модуль sys предоставляет список sys.argv, содержащий имя скрипта и переданные аргументы. Их можно передать в main в качестве параметров.


# args_example.py
import sys

def main(args):
    if len(args) != 3:
        print("Использование: python args_example.py <имя> <возраст>")
        return
    name, age = args[1], int(args[2])
    print(f"Привет, {name}. Тебе {age} лет.")

if __name__ == '__main__':
    main(sys.argv)
  
$ python args_example.py Иван 25
Привет, Иван. Тебе 25 лет.

Возможные проблемы:

  • Индексация: sys.argv[0] – имя скрипта, аргументы начинаются с 1.
  • Неправильное количество аргументов может вызвать IndexError.
  • Преобразование типов (int(args[2])) может выбросить ValueError при некорректном вводе.
  • Отсутствие проверки аргументов приводит к неинформативным ошибкам.

Как создать профессиональный интерфейс командной строки с помощью argparse?

Модуль argparse упрощает разбор аргументов, формирование справки и обработку ошибок. Рекомендуется для сложных скриптов.


# argparse_example.py
import argparse

def main():
    parser = argparse.ArgumentParser(description="Приветствие пользователя.")
    parser.add_argument('name', help='Имя пользователя')
    parser.add_argument('--age', type=int, default=0, help='Возраст (опционально)')
    parser.add_argument('--greeting', '-g', default='Привет', help='Текст приветствия')
    args = parser.parse_args()
    
    greeting_msg = f"{args.greeting}, {args.name}!"
    if args.age:
        greeting_msg += f" Тебе {args.age} лет."
    print(greeting_msg)

if __name__ == '__main__':
    main()
  
$ python argparse_example.py Мария --age 30
Привет, Мария! Тебе 30 лет.

Распространенные ошибки:

  • Забыть вызвать parse_args() – аргументы не будут разобраны.
  • Неправильно указать тип (type) – argparse не сможет преобразовать.
  • Путаница с обязательными и опциональными аргументами: обязательные без дефиса, опциональные с -- или -.
  • Отсутствие справки (--help) при некорректном вводе – argparse предоставляет её автоматически.

Как организовать точку входа в пакете с помощью __main__.py?

Если проект представляет собой пакет (директорию с __init__.py), можно создать файл __main__.py внутри пакета. Запуск python -m имя_пакета выполнит этот файл.


# структура:
# mypackage/
#   __init__.py
#   __main__.py
#   module.py

# __main__.py
from mypackage import module

def main():
    print("Запущен пакет mypackage.")
    module.run()

if __name__ == '__main__':
    main()
  
$ python -m mypackage
Запущен пакет mypackage.
(вывод из module.run)

Проблемы при использовании:

  • Отсутствие __main__.py приводит к ошибке "No module named ...".
  • Импорты внутри __main__.py должны быть абсолютными или правильными относительными (с учетом точки).
  • Не следует путать __main__.py с точкой входа в исполняемый файл setup.py.
  • При разработке и тестировании может потребоваться изменить PYTHONPATH.

Как реализовать асинхронную main с asyncio?

Для асинхронных скриптов основная функция может быть объявлена как async def main(). Запуск выполняется с помощью asyncio.run(main()).


# async_main.py
import asyncio

async def main():
    print("Начало асинхронной программы")
    await asyncio.sleep(1)
    print("Конец через 1 секунду")

if __name__ == '__main__':
    asyncio.run(main())
  
$ python async_main.py
Начало асинхронной программы
(пауза 1 сек)
Конец через 1 секунду

Частые ошибки:

  • Использование устаревшего loop.run_until_complete() вместо asyncio.run() (последний появился в Python 3.7 и управляет циклом событий корректно).
  • Забыть await внутри main – корутина не выполнится или выполнится неправильно.
  • Попытка запустить asyncio.run() в среде, где уже запущен цикл событий (например, в Jupyter), вызывает RuntimeError. В таких случаях используют await main() в самой консоли.
  • Передача нескольких аргументов корутине – нужно использовать asyncio.gather() или соответствующие конструкции.

Расширенные примеры организации main в Python

Пример 1: main с логированием и обработкой исключений

Пример 

import sys
import logging

def setup_logging():
    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

def main():
    setup_logging()
    logging.info("Запуск программы")
    try:
        # основной код
        input_data = input("Введите число: ")
        number = float(input_data)
        result = number * 2
        logging.info(f"Результат: {result}")
    except ValueError as e:
        logging.error(f"Ошибка преобразования: {e}")
        sys.exit(1)
    except KeyboardInterrupt:
        logging.info("Программа прервана пользователем")
        sys.exit(0)

if __name__ == '__main__':
    main()

$ python logging_main.py
2025-03-27 10:00:00,000 - INFO - Запуск программы
Введите число: 42
2025-03-27 10:00:05,000 - INFO - Результат: 84.0

Пример 2: main для веб-сервера на Flask

Пример 

# app.py
from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello, World!"

def main():
    # можно добавить конфигурацию, инициализацию БД и т.д.
    app.run(debug=True, host='0.0.0.0', port=5000)

if __name__ == '__main__':
    main()

$ python app.py
 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://0.0.0.0:5000 (Press CTRL+C to quit)

Пример 3: тестирование функции main с помощью unittest.mock

Пример 

# main_test.py
import unittest
from unittest.mock import patch
import sys
# предположим, что у нас есть файл mymain.py с функцией main, использующей sys.argv
# mymain.py:
# import sys
# def main():
#     name = sys.argv[1]
#     print(f"Hello {name}")
# if __name__ == '__main__':
#     main()

from mymain import main

class TestMain(unittest.TestCase):
    @patch('sys.argv', ['script.py', 'Alice'])
    @patch('builtins.print')
    def test_main_with_name(self, mock_print, mock_argv):
        main()
        mock_print.assert_called_once_with("Hello Alice")

if __name__ == '__main__':
    unittest.main()

$ python -m unittest main_test.py
.
----------------------------------------------------------------------
Ran 1 test in 0.001s

OK

главная функция main в Python - comments

En
Main python (python)