Argparse в Python: аргументы командной строки

argparse нужен, чтобы Python-скрипт принимал данные из командной строки: путь к файлу, режим запуска, число попыток, флаг подробного вывода, формат результата. Вместо ручного разбора sys.argv вы описываете аргументы, а argparse сам читает их, проверяет и показывает --help

Это стандартная библиотека Python, устанавливать ничего не нужно

Первый скрипт

Создайте файл app.py

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('name')
parser.add_argument('--upper', action='store_true')

args = parser.parse_args()

message = f'Привет, {args.name}'

if args.upper:
    message = message.upper()

print(message)

Запуск:

python app.py Анна

Результат:

Привет, Анна

Запуск с флагом:

python app.py Анна --upper

Результат:

ПРИВЕТ, АННА

name — позиционный аргумент, его нужно передать обязательно. --upper — флаг, он либо есть, либо нет

Справка через —help

Добавьте описание

parser = argparse.ArgumentParser(
    description='Пример CLI-скрипта на Python'
)

Теперь выполните:

python app.py --help

argparse сам покажет доступные аргументы, описание и формат запуска. Это одна из главных причин использовать его вместо ручного чтения sys.argv

Позиционные аргументы и опции

Позиционный аргумент пишется без --

parser.add_argument('input_file')

Опция пишется с --

parser.add_argument('--output')

Пример:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('input_file')
parser.add_argument('--output', default='result.txt')

args = parser.parse_args()

print(f'Входной файл: {args.input_file}')
print(f'Результат: {args.output}')

Запуск:

python app.py data.csv --output report.txt

Если --output не передать, будет использовано значение result.txt

Типы значений

По умолчанию аргументы приходят строками. Если нужно число, укажите type=int

parser.add_argument('--limit', type=int, default=10)

Полный пример:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--limit', type=int, default=10)

args = parser.parse_args()

print(args.limit * 2)

Запуск:

python app.py --limit 5

Результат:

10

Если передать --limit text, argparse сам покажет ошибку, потому что ждет число

Обязательная опция

Иногда опция должна быть обязательной

parser.add_argument('--file', required=True)

Но не делайте обязательными все подряд. Если значение всегда нужно, часто лучше позиционный аргумент. Если значение дополнительное, лучше опция с default

choices: ограничить варианты

Если режимов несколько, используйте choices

parser.add_argument(
    '--mode',
    choices=['dev', 'prod', 'test'],
    default='dev',
)

Теперь пользователь не сможет передать случайный режим

python app.py --mode prod

Если передать --mode wrong, argparse покажет понятную ошибку

Флаги store_true

Флаг не требует значения. Он просто меняет False на True

parser.add_argument('--verbose', action='store_true')

Пример:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--verbose', action='store_true')

args = parser.parse_args()

if args.verbose:
    print('Подробный режим включен')
else:
    print('Обычный режим')

Запуск:

python app.py --verbose

Список значений

Если нужно принять несколько значений, используйте nargs

parser.add_argument('--tag', action='append', default=[])

Запуск:

python app.py --tag python --tag cli --tag parser

В args.tag будет список:

['python', 'cli', 'parser']

Так удобно передавать несколько меток, файлов, категорий или параметров фильтрации

Мини-пример подкоманд

Для утилит с несколькими действиями можно использовать subparsers

import argparse

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(dest='command', required=True)

run_parser = subparsers.add_parser('run')
run_parser.add_argument('--limit', type=int, default=10)

check_parser = subparsers.add_parser('check')
check_parser.add_argument('file')

args = parser.parse_args()

if args.command == 'run':
    print(f'Запуск с лимитом {args.limit}')
elif args.command == 'check':
    print(f'Проверка файла {args.file}')

Запуск:

python app.py run --limit 5
python app.py check data.csv

Подкоманды полезны, когда один скрипт делает разные действия: run, check, export, import

По этой теме полезно отдельно посмотреть Составьте еженедельное расписание занятий, чтобы расширить контекст и сравнить подходы

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы

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

Забыть type=int и потом сравнивать строку с числом

Сделать слишком много обязательных опций

Писать собственный парсер sys.argv для сложного CLI

Не проверять python app.py --help

Давать аргументам непонятные имена вроде --x и --data2

Прятать всю логику сразу под parse_args(), вместо того чтобы передать args в отдельную функцию

Практические задачи

Сделайте аргумент input_file и опцию --output

Добавьте --limit с типом int и значением по умолчанию 10

Добавьте флаг --verbose

Добавьте --mode с вариантами dev, prod, test

Сделайте две подкоманды: run и check

Проверьте, как выглядит --help после каждого изменения

argparse превращает обычный Python-файл в CLI-утилиту. Вы описываете аргументы, типы, значения по умолчанию, флаги и варианты выбора, а библиотека сама разбирает командную строку и показывает справку

Начните с позиционного аргумента и одного флага. Потом добавьте type, default, choices, required и подкоманды только там, где они действительно делают запуск понятнее