optparse.md

1> **Источник:** https://python-all.ru/3.13/library/optparse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `optparse` – Парсер параметров командной строки89**Исходный код:** [Lib/optparse.py](https://python-all.ru/src/3.13/Lib/optparse.py)1011---1213## Выбор библиотеки для разбора аргументов1415Стандартная библиотека включает три библиотеки для разбора аргументов:1617- [`getopt`](https://python-all.ru/3.13/library/getopt.html#module-getopt): модуль, который тесно повторяет процедурный API `getopt` на C. Включён в стандартную библиотеку ещё до выхода Python 1.0.18- `optparse`: декларативная замена для `getopt`, которая предоставляет эквивалентную функциональность, не требуя от каждого приложения реализовывать собственную процедурную логику разбора параметров. Включён в стандартную библиотеку начиная с Python 2.3.19- [`argparse`](https://python-all.ru/3.13/library/argparse.html#module-argparse): более жёсткая альтернатива `optparse`, которая предоставляет больше функциональности по умолчанию в ущерб гибкости приложения в точном управлении обработкой аргументов. Включён в стандартную библиотеку начиная с Python 2.7 и Python 3.2.2021При отсутствии более конкретных ограничений на разбор аргументов, [`argparse`](https://python-all.ru/3.13/library/argparse.html#module-argparse) является рекомендуемым выбором для реализации приложений командной строки, поскольку он предлагает наивысший уровень базовой функциональности при минимальном объёме кода приложения.2223[`getopt`](https://python-all.ru/3.13/library/getopt.html#module-getopt) сохранён почти полностью по соображениям обратной совместимости. Однако он также служит нишевым вариантом использования как инструмент для прототипирования и тестирования обработки аргументов командной строки в C-приложениях на основе `getopt`.2425`optparse` следует рассматривать как альтернативу [`argparse`](https://python-all.ru/3.13/library/argparse.html#module-argparse) в следующих случаях:2627- приложение уже использует `optparse` и не хочет рисковать тонкими изменениями поведения, которые могут возникнуть при миграции на [`argparse`](https://python-all.ru/3.13/library/argparse.html#module-argparse)28- приложению требуется дополнительный контроль над тем, как параметры и позиционные аргументы чередуются в командной строке (включая возможность полностью отключить эту функцию чередования)29- приложению требуется дополнительный контроль над инкрементальным разбором элементов командной строки (хотя `argparse` поддерживает это, точный порядок работы на практике нежелателен для некоторых случаев использования)30- приложению требуется дополнительный контроль над обработкой параметров, которые принимают значения, начинающиеся с `-` (например, делегированные параметры, передаваемые вызываемым подпроцессам)31- приложению требуется какое-либо другое поведение обработки параметров командной строки, которое `argparse` не поддерживает, но которое может быть реализовано с помощью низкоуровневого интерфейса, предоставляемого `optparse`3233Эти соображения также означают, что `optparse`, вероятно, обеспечивает лучшую основу для авторов библиотек, пишущих сторонние библиотеки обработки аргументов командной строки.3435В качестве конкретного примера рассмотрим следующие две конфигурации разбора аргументов командной строки: первая использует `optparse`, а вторая использует `argparse`:3637```python38import optparse3940if __name__ == '__main__':41    parser = optparse.OptionParser()42    parser.add_option('-o', '--output')43    parser.add_option('-v', dest='verbose', action='store_true')44    opts, args = parser.parse_args()45    process(args, output=opts.output, verbose=opts.verbose)46```4748```python49import argparse5051if __name__ == '__main__':52    parser = argparse.ArgumentParser()53    parser.add_argument('-o', '--output')54    parser.add_argument('-v', dest='verbose', action='store_true')55    parser.add_argument('rest', nargs='*')56    args = parser.parse_args()57    process(args.rest, output=args.output, verbose=args.verbose)58```5960Наиболее очевидное различие в том, что в версии `optparse` неопционные аргументы обрабатываются приложением отдельно после завершения обработки параметров. В версии `argparse` позиционные аргументы объявляются и обрабатываются так же, как именованные параметры.6162Однако версия `argparse` также будет обрабатывать некоторые комбинации параметров иначе, чем версия `optparse`. Например (среди прочих различий):6364- передача `-o -v` даёт `output="-v"` и `verbose=False` при использовании `optparse`, но ошибку использования с `argparse` (с жалобой, что не указано значение для `-o/--output`, поскольку `-v` интерпретируется как флаг подробного вывода)65- аналогично, передача `-o --` даёт `output="--"` и `args=()` при использовании `optparse`, но ошибку использования с `argparse` (также с жалобой, что не указано значение для `-o/--output`, поскольку `--` интерпретируется как завершение обработки параметров и все оставшиеся значения считаются позиционными аргументами)66- передача `-o=foo` даёт `output="=foo"` при использовании `optparse`, но даёт `output="foo"` с `argparse` (поскольку `=` обрабатывается особым образом как альтернативный разделитель значений параметров)6768Будут ли эти различия в поведении в версии `argparse` считаться желательными или проблемными, зависит от конкретного случая использования приложения командной строки.6970> **См. также**71>72> [click](https://python-all.ru/3.13/library/optparse.html) – это сторонняя библиотека обработки аргументов (изначально основанная на `optparse`), которая позволяет разрабатывать приложения командной строки как набор декорированных функций реализации команд.73>74> Другие сторонние библиотеки, такие как [typer](https://python-all.ru/3.13/library/optparse.html) или [msgspec-click](https://python-all.ru/3.13/library/optparse.html), позволяют задавать интерфейсы командной строки способами, которые более эффективно интегрируются со статической проверкой аннотаций типов Python.7576## Введение7778`optparse` – более удобная, гибкая и мощная библиотека для разбора параметров командной строки, чем минималистичный модуль [`getopt`](https://python-all.ru/3.13/library/getopt.html#module-getopt). `optparse` использует более декларативный стиль разбора командной строки: создаётся экземпляр [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser), заполняется параметрами, и выполняется разбор командной строки. `optparse` позволяет пользователям указывать параметры в общепринятом синтаксисе GNU/POSIX, а также генерирует сообщения об использовании и справку.7980Вот пример использования `optparse` в простом скрипте:8182```python83from optparse import OptionParser84...85parser = OptionParser()86parser.add_option("-f", "--file", dest="filename",87                  help="write report to FILE", metavar="FILE")88parser.add_option("-q", "--quiet",89                  action="store_false", dest="verbose", default=True,90                  help="don't print status messages to stdout")9192(options, args) = parser.parse_args()93```9495С помощью этих нескольких строк кода пользователи вашего скрипта теперь могут делать «обычные вещи» в командной строке, например:9697```python98<yourscript> --file=outfile -q99```100101По мере разбора командной строки `optparse` устанавливает атрибуты объекта `options`, возвращаемого [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args), на основе предоставленных пользователем значений командной строки. Когда `parse_args()` завершает разбор этой командной строки, `options.filename` будет `"outfile"`, а `options.verbose` будет `False`. `optparse` поддерживает как длинные, так и короткие параметры, позволяет объединять короткие параметры, а также позволяет связывать параметры с их аргументами различными способами. Таким образом, следующие командные строки эквивалентны приведённому выше примеру:102103```python104<yourscript> -f outfile --quiet105<yourscript> --quiet --file outfile106<yourscript> -q -foutfile107<yourscript> -qfoutfile108```109110Кроме того, пользователи могут выполнить одну из следующих команд:111112```python113<yourscript> -h114<yourscript> --help115```116117и `optparse` выведет краткую сводку параметров вашего скрипта:118119```text120Usage: <yourscript> [options]121122Options:123  -h, --help            show this help message and exit124  -f FILE, --file=FILE  write report to FILE125  -q, --quiet           don't print status messages to stdout126```127128где значение *yourscript* определяется во время выполнения (обычно из `sys.argv[0]`).129130## Предыстория131132`optparse` был явно спроектирован для поощрения создания программ с простыми интерфейсами командной строки, следующими соглашениям, установленным семейством функций `getopt()`, доступных разработчикам на C. С этой целью он поддерживает только наиболее распространенный синтаксис и семантику командной строки, традиционно используемые в Unix. Если вы не знакомы с этими соглашениями, прочтение этого раздела позволит вам с ними ознакомиться.133134### Терминология135136**аргумент**137138строка, введенная в командной строке и переданная оболочкой в `execl()` или `execv()`. В Python аргументами являются элементы `sys.argv[1:]` (`sys.argv[0]` – это имя выполняемой программы). Оболочки Unix также используют термин «слово».139140Иногда желательно подставить список аргументов, отличный от `sys.argv[1:]`, поэтому под «аргументом» следует понимать «элемент `sys.argv[1:]` или любого другого списка, предоставленного взамен `sys.argv[1:]`».141142**опция**143144аргумент, используемый для предоставления дополнительной информации для управления или настройки выполнения программы. Существует много разных синтаксисов для опций; традиционный синтаксис Unix – это дефис («-») с последующей одной буквой, например `-x` или `-F`. Также традиционный синтаксис Unix позволяет объединять несколько опций в один аргумент, например `-x -F` эквивалентно `-xF`. Проект GNU ввел `--` с последующей последовательностью слов, разделенных дефисом, например `--file` или `--dry-run`. Это единственные два синтаксиса опций, предоставляемые `optparse`.145146Некоторые другие синтаксисы опций, которые встречались в мире, включают:147148- дефис с последующими несколькими буквами, например `-pf` (это *не* то же самое, что несколько опций, объединенных в один аргумент)149- дефис с последующим целым словом, например `-file` (технически это эквивалентно предыдущему синтаксису, но они обычно не встречаются в одной программе)150- знак плюс с последующей одной буквой, или несколькими буквами, или словом, например `+f`, `+rgb`151- косая черта с последующей буквой, или несколькими буквами, или словом, например `/f`, `/file`152153Эти синтаксисы опций не поддерживаются `optparse` и никогда не будут поддерживаться. Это сделано намеренно: первые три являются нестандартными в любом окружении, а последний имеет смысл только если вы ориентируетесь исключительно на Windows или определенные устаревшие платформы (например, VMS, MS-DOS).154155**аргумент опции**156157аргумент, который следует за опцией, тесно связан с этой опцией и извлекается из списка аргументов вместе с ней. В `optparse` аргументы опций могут находиться как в отдельном аргументе от своей опции:158159```text160-f foo161--file foo162```163164или включены в тот же аргумент:165166```text167-ffoo168--file=foo169```170171Обычно конкретная опция либо принимает аргумент, либо нет. Многие хотят функцию «необязательных аргументов опций», то есть некоторые опции будут принимать аргумент, если он есть, и не будут, если его нет. Это несколько спорно, поскольку делает разбор неоднозначным: если `-a` принимает необязательный аргумент, а `-b` – это совершенно другая опция, как интерпретировать `-ab`? Из-за этой неоднозначности `optparse` не поддерживает такую функцию.172173**позиционный аргумент**174175то, что осталось в списке аргументов после разбора опций, т.е. после того, как опции и их аргументы были разобраны и удалены из списка аргументов.176177**обязательная опция**178179опция, которая должна быть указана в командной строке; обратите внимание, что фраза «обязательная опция» противоречива по своей сути. `optparse` не препятствует реализации обязательных опций, но и не оказывает большой помощи в этом.180181Например, рассмотрим эту гипотетическую командную строку:182183```python184prog -v --report report.txt foo bar185```186187`-v` и `--report` являются опциями. Предполагая, что `--report` принимает один аргумент, `report.txt` является аргументом опции. `foo` и `bar` являются позиционными аргументами.188189### Для чего нужны опции?190191Опции используются для предоставления дополнительной информации для настройки или кастомизации выполнения программы. Если это не было очевидно, опции обычно *необязательны*. Программа должна нормально работать вообще без опций. (Возьмите случайную программу из инструментария Unix или GNU. Может ли она работать без каких-либо опций и при этом иметь смысл? Главные исключения – `find`, `tar` и `dd` – все они мутанты-чудаки, которые по праву критикуются за нестандартный синтаксис и запутанные интерфейсы.)192193Многие хотят, чтобы в их программах были «обязательные опции». Подумайте об этом. Если это обязательно, значит, это *не необязательно*! Если есть информация, которая absolutely необходима вашей программе для успешного выполнения, для этого существуют позиционные аргументы.194195В качестве примера хорошего дизайна интерфейса командной строки рассмотрим скромную утилиту `cp` для копирования файлов. Копировать файлы без указания назначения и хотя бы одного источника не имеет особого смысла. Поэтому `cp` завершается с ошибкой, если запустить ее без аргументов. Однако у нее гибкий, полезный синтаксис, который вообще не требует опций:196197```python198cp SOURCE DEST199cp SOURCE ... DEST-DIR200```201202На этом можно многого добиться. Большинство реализаций `cp` предоставляют множество опций для точной настройки копирования: можно сохранять права и время модификации, не следовать симлинкам, спрашивать перед перезаписью существующих файлов и т.д. Но ничто из этого не отвлекает от основной задачи `cp` – скопировать один файл в другой или несколько файлов в другой каталог.203204### Для чего нужны позиционные аргументы?205206Позиционные аргументы предназначены для тех частей информации, которые absolutely и однозначно необходимы вашей программе для работы.207208Хороший пользовательский интерфейс должен иметь как можно меньше абсолютных требований. Если вашей программе требуется 17 различных частей информации для успешного запуска, не имеет большого значения *как* вы получаете эту информацию от пользователя – большинство людей сдадутся и уйдут, так и не запустив программу. Это справедливо независимо от того, является ли интерфейс командной строкой, файлом конфигурации или графическим интерфейсом: если вы предъявляете столько требований к пользователям, большинство из них просто сдадутся.209210Короче говоря, старайтесь минимизировать объем информации, которую пользователи absolutely обязаны предоставить – используйте разумные значения по умолчанию, когда это возможно. Конечно, вы также хотите сделать свои программы достаточно гибкими. Для этого и нужны опции. Опять же, неважно, являются ли они записями в файле конфигурации, виджетами в диалоге «Настройки» графического интерфейса или опциями командной строки – чем больше опций вы реализуете, тем гибче становится ваша программа, и тем сложнее становится ее реализация. Слишком большая гибкость тоже имеет недостатки; слишком много опций может перегрузить пользователей и сделать ваш код гораздо сложнее в поддержке.211212## Учебное руководство213214Хотя `optparse` довольно гибкий и мощный, он также прост в использовании в большинстве случаев. В этом разделе рассматриваются шаблоны кода, общие для любой программы на основе `optparse`.215216Сначала необходимо импортировать класс OptionParser; затем, в начале основной программы, создать экземпляр OptionParser:217218```python219from optparse import OptionParser220...221parser = OptionParser()222```223224Затем можно приступить к определению опций. Базовый синтаксис:225226```python227parser.add_option(opt_str, ...,228                  attr=value, ...)229```230231Каждая опция имеет одну или несколько строк опций, например `-f` или `--file`, и несколько атрибутов, которые сообщают `optparse`, что ожидать и что делать, когда он встречает эту опцию в командной строке.232233Обычно каждая опция имеет одну короткую и одну длинную строку опции, например:234235```python236parser.add_option("-f", "--file", ...)237```238239Вы можете определить любое количество коротких и длинных строк опций (включая ноль), при условии, что в целом есть хотя бы одна строка опции.240241Строки опций, передаваемые в [`OptionParser.add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option), по сути являются метками для опции, определяемой этим вызовом. Для краткости мы часто будем ссылаться на *встречу опции* в командной строке; на самом деле `optparse` встречает *строки опций* и ищет опции по ним.242243Когда все опции определены, укажите `optparse` разобрать командную строку вашей программы:244245```python246(options, args) = parser.parse_args()247```248249(При желании можно передать собственный список аргументов в [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args), но это редко необходимо: по умолчанию он использует `sys.argv[1:]`.)250251[`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args) возвращает два значения:252253- `options` – объект, содержащий значения для всех опций. Например, если `--file` принимает один строковый аргумент, то `options.file` будет именем файла, указанным пользователем, или `None`, если пользователь не указал эту опцию.254- `args` – список позиционных аргументов, оставшихся после разбора опций255256В этом учебном разделе рассматриваются только четыре наиболее важных атрибута опций: [`action`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.action), [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest) (destination) и [`help`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.help). Из них `action` является самым основным.257258### Понимание действий опций259260Действия сообщают `optparse`, что делать, когда он встречает опцию в командной строке. Существует фиксированный набор действий, встроенных в `optparse`; добавление новых действий – продвинутая тема, рассматриваемая в разделе [Расширение optparse](https://python-all.ru/3.13/library/optparse.html#optparse-extending-optparse). Большинство действий говорят `optparse` сохранить значение в некоторую переменную – например, взять строку из командной строки и сохранить её в атрибуте `options`.261262Если не указано действие опции, `optparse` по умолчанию использует `store`.263264### Действие store265266Наиболее распространенное действие опции – `store`, которое говорит `optparse` взять следующий аргумент (или остаток текущего аргумента), убедиться, что он имеет правильный тип, и сохранить его в выбранное место назначения.267268Например:269270```python271parser.add_option("-f", "--file",272                  action="store", type="string", dest="filename")273```274275Теперь давайте создадим фиктивную командную строку и попросим `optparse` разобрать её:276277```python278args = ["-f", "foo.txt"]279(options, args) = parser.parse_args(args)280```281282Когда `optparse` видит строку опции `-f`, он потребляет следующий аргумент, `foo.txt`, и сохраняет его в `options.filename`. Итак, после этого вызова [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args), `options.filename` равно `"foo.txt"`.283284Некоторые другие типы опций, поддерживаемые `optparse`: `int` и `float`. Вот опция, которая ожидает целочисленный аргумент:285286```python287parser.add_option("-n", type="int", dest="num")288```289290Обратите внимание, что эта опция не имеет длинной строки опции, что вполне допустимо. Кроме того, отсутствует явное действие, поскольку по умолчанию используется `store`.291292Давайте разберём другую фиктивную командную строку. На этот раз мы поместим аргумент опции непосредственно рядом с опцией: поскольку `-n42` (один аргумент) эквивалентно `-n 42` (два аргумента), код293294```python295(options, args) = parser.parse_args(["-n42"])296print(options.num)297```298299выведет `42`.300301Если тип не указан, `optparse` предполагает `string`. В сочетании с тем, что действие по умолчанию – `store`, это означает, что наш первый пример можно сделать гораздо короче:302303```python304parser.add_option("-f", "--file", dest="filename")305```306307Если место назначения не указано, `optparse` определяет разумное значение по умолчанию из строк опций: если первая длинная строка опции – `--foo-bar`, то по умолчанию местом назначения будет `foo_bar`. Если длинных строк опций нет, `optparse` смотрит на первую короткую строку опции: местом назначения по умолчанию для `-f` будет `f`.308309`optparse` также включает встроенный тип `complex`. Добавление типов рассматривается в разделе [Расширение optparse](https://python-all.ru/3.13/library/optparse.html#optparse-extending-optparse).310311### Обработка булевых (флаговых) опций312313Флаговые опции – установка переменной в true или false при обнаружении определённой опции – довольно распространены. `optparse` поддерживает их с помощью двух отдельных действий: `store_true` и `store_false`. Например, у вас может быть флаг `verbose`, который включается опцией `-v` и выключается опцией `-q`:314315```python316parser.add_option("-v", action="store_true", dest="verbose")317parser.add_option("-q", action="store_false", dest="verbose")318```319320Здесь у нас две разные опции с одним и тем же местом назначения, что совершенно нормально. (Это просто означает, что нужно быть немного осторожнее при установке значений по умолчанию – см. ниже.)321322Когда `optparse` встречает `-v` в командной строке, он устанавливает `options.verbose` в `True`; когда он встречает `-q`, `options.verbose` устанавливается в `False`.323324### Другие действия325326Некоторые другие действия, поддерживаемые `optparse`:327328**`"store_const"`**329330сохранить постоянное значение, предварительно заданное через [`Option.const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const)331332**`"append"`**333334добавить аргумент этой опции в список335336**`"count"`**337338увеличить счётчик на единицу339340**`"callback"`**341342вызвать указанную функцию343344Они описаны в разделе [Справочное руководство](https://python-all.ru/3.13/library/optparse.html#optparse-reference-guide), и в разделе [Колбэки параметров](https://python-all.ru/3.13/library/optparse.html#optparse-option-callbacks).345346### Значения по умолчанию347348Все приведённые выше примеры предполагают установку некоторой переменной («назначения») при обнаружении определённых параметров командной строки. Что произойдёт, если эти параметры никогда не встретятся? Поскольку мы не указали значения по умолчанию, все они будут установлены в `None`. Обычно это нормально, но иногда требуется больший контроль. `optparse` позволяет указать значение по умолчанию для каждого назначения, которое присваивается до разбора командной строки.349350Сначала рассмотрим пример с подробным/тихим режимом. Если мы хотим, чтобы `optparse` устанавливал `verbose` в `True`, если не встречен `-q`, то можно сделать так:351352```python353parser.add_option("-v", action="store_true", dest="verbose", default=True)354parser.add_option("-q", action="store_false", dest="verbose")355```356357Поскольку значения по умолчанию применяются к *назначению*, а не к какому-либо конкретному параметру, и эти два параметра имеют одно и то же назначение, это полностью эквивалентно:358359```python360parser.add_option("-v", action="store_true", dest="verbose")361parser.add_option("-q", action="store_false", dest="verbose", default=True)362```363364Рассмотрим это:365366```python367parser.add_option("-v", action="store_true", dest="verbose", default=False)368parser.add_option("-q", action="store_false", dest="verbose", default=True)369```370371Опять же, значение по умолчанию для `verbose` будет `True`: последнее указанное значение по умолчанию для любого конкретного назначения и будет использоваться.372373Более понятный способ указать значения по умолчанию – метод `set_defaults()` объекта OptionParser, который можно вызвать в любое время до вызова [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args):374375```python376parser.set_defaults(verbose=True)377parser.add_option(...)378(options, args) = parser.parse_args()379```380381Как и прежде, последнее указанное значение для данного назначения параметра и будет использоваться. Для ясности старайтесь использовать какой-то один способ задания значений по умолчанию, а не оба сразу.382383### Генерация справки384385Возможность `optparse` автоматически генерировать текст справки и использования полезна для создания удобных интерфейсов командной строки. Всё, что нужно сделать – указать значение [`help`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.help) для каждого параметра и, опционально, краткое сообщение об использовании для всей программы. Вот OptionParser, заполненный удобными (документированными) параметрами:386387```python388usage = "usage: %prog [options] arg1 arg2"389parser = OptionParser(usage=usage)390parser.add_option("-v", "--verbose",391                  action="store_true", dest="verbose", default=True,392                  help="make lots of noise [default]")393parser.add_option("-q", "--quiet",394                  action="store_false", dest="verbose",395                  help="be vewwy quiet (I'm hunting wabbits)")396parser.add_option("-f", "--filename",397                  metavar="FILE", help="write output to FILE")398parser.add_option("-m", "--mode",399                  default="intermediate",400                  help="interaction mode: novice, intermediate, "401                       "or expert [default: %default]")402```403404Если `optparse` встречает в командной строке `-h` или `--help`, или если просто вызвать `parser.print_help()`, он выводит следующее в стандартный вывод:405406```text407Usage: <yourscript> [options] arg1 arg2408409Options:410  -h, --help            show this help message and exit411  -v, --verbose         make lots of noise [default]412  -q, --quiet           be vewwy quiet (I'm hunting wabbits)413  -f FILE, --filename=FILE414                        write output to FILE415  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or416                        expert [default: intermediate]417```418419(Если вывод справки вызван опцией помощи, `optparse` завершает работу после печати текста справки.)420421Здесь много деталей, помогающих `optparse` сгенерировать наилучшее сообщение справки:422423- сценарий определяет собственное сообщение об использовании:424425  ```python426  usage = "usage: %prog [options] arg1 arg2"427  ```428429  `optparse` заменяет `%prog` в строке использования на имя текущей программы, т.е. `os.path.basename(sys.argv[0])`. Затем расширенная строка выводится перед подробной справкой по параметрам.430431  Если не указать строку использования, `optparse` использует простое, но разумное значение по умолчанию: `"Usage: %prog [options]"`, что подходит, если сценарий не принимает позиционные аргументы.432- каждый параметр определяет строку справки и не заботится о переносе строк – `optparse` заботится о переносе и о том, чтобы вывод справки выглядел хорошо.433- параметры, принимающие значение, указывают на это в автоматически сгенерированном сообщении справки, например, для параметра «mode»:434435  ```python436  -m MODE, --mode=MODE437  ```438439  Здесь «MODE» называется мета-переменной: она представляет аргумент, который пользователь должен передать `-m`/`--mode`. По умолчанию `optparse` преобразует имя переменной назначения в верхний регистр и использует его для мета-переменной. Иногда это не то, что нужно – например, параметр `--filename` явно устанавливает `metavar="FILE"`, что приводит к такому автоматически сгенерированному описанию параметра:440441  ```python442  -f FILE, --filename=FILE443  ```444445  Это важно не только для экономии места: вручную написанный текст справки использует мета-переменную `FILE`, чтобы подсказать пользователю, что существует связь между полуформальным синтаксисом `-f FILE` и неформальным семантическим описанием «записать вывод в FILE». Это простой, но эффективный способ сделать текст справки гораздо понятнее и полезнее для конечных пользователей.446- Параметры, имеющие значение по умолчанию, могут включать `%default` в строку справки – `optparse` заменит его на [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) значения по умолчанию этого параметра. Если параметр не имеет значения по умолчанию (или значение по умолчанию равно `None`), `%default` раскрывается в `none`.447448#### Группировка параметров449450При работе с большим количеством параметров удобно группировать их для улучшения вывода справки. [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser) может содержать несколько групп параметров, каждая из которых может содержать несколько параметров.451452Группа параметров создаётся с помощью класса [`OptionGroup`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionGroup):453454#### `class optparse.OptionGroup(parser, title, description=None)`455456где457458- parser – это экземпляр [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser), в который будет вставлена группа459- title – это заголовок группы460- description (необязательно) – это подробное описание группы461462[`OptionGroup`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionGroup) наследуется от `OptionContainer` (как [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser)), поэтому метод `add_option()` можно использовать для добавления опции в группу.463464После объявления всех опций с помощью метода [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser) `add_option_group()` группа добавляется в ранее определённый парсер.465466Продолжая с парсером, определённым в предыдущем разделе, добавить [`OptionGroup`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionGroup) в парсер несложно:467468```python469group = OptionGroup(parser, "Dangerous Options",470                    "Caution: use these options at your own risk.  "471                    "It is believed that some of them bite.")472group.add_option("-g", action="store_true", help="Group option.")473parser.add_option_group(group)474```475476Это приведёт к следующему выводу справки:477478```text479Usage: <yourscript> [options] arg1 arg2480481Options:482  -h, --help            show this help message and exit483  -v, --verbose         make lots of noise [default]484  -q, --quiet           be vewwy quiet (I'm hunting wabbits)485  -f FILE, --filename=FILE486                        write output to FILE487  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or488                        expert [default: intermediate]489490  Dangerous Options:491    Caution: use these options at your own risk.  It is believed that some492    of them bite.493494    -g                  Group option.495```496497Несколько более полный пример может включать использование более одной группы: всё так же расширяя предыдущий пример:498499```python500group = OptionGroup(parser, "Dangerous Options",501                    "Caution: use these options at your own risk.  "502                    "It is believed that some of them bite.")503group.add_option("-g", action="store_true", help="Group option.")504parser.add_option_group(group)505506group = OptionGroup(parser, "Debug Options")507group.add_option("-d", "--debug", action="store_true",508                 help="Print debug information")509group.add_option("-s", "--sql", action="store_true",510                 help="Print all SQL statements executed")511group.add_option("-e", action="store_true", help="Print every action done")512parser.add_option_group(group)513```514515что приводит к следующему выводу:516517```text518Usage: <yourscript> [options] arg1 arg2519520Options:521  -h, --help            show this help message and exit522  -v, --verbose         make lots of noise [default]523  -q, --quiet           be vewwy quiet (I'm hunting wabbits)524  -f FILE, --filename=FILE525                        write output to FILE526  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or expert527                        [default: intermediate]528529  Dangerous Options:530    Caution: use these options at your own risk.  It is believed that some531    of them bite.532533    -g                  Group option.534535  Debug Options:536    -d, --debug         Print debug information537    -s, --sql           Print all SQL statements executed538    -e                  Print every action done539```540541Ещё один интересный метод, особенно при программной работе с группами опций:542543#### `OptionParser.get_option_group(opt_str)`544545Возвращает [`OptionGroup`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionGroup), которому принадлежит короткая или длинная строка опции *opt\_str* (например, `'-o'` или `'--option'`). Если такого `OptionGroup` нет, возвращает `None`.546547### Печать строки версии548549Подобно краткой строке использования, `optparse` также может выводить строку версии для программы. Строку нужно передать в качестве аргумента `version` конструктору OptionParser:550551```python552parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")553```554555`%prog` раскрывается так же, как в `usage`. Кроме того, `version` может содержать что угодно. При передаче строки `optparse` автоматически добавляет опцию `--version` в парсер. Если эта опция встречается в командной строке, строка `version` раскрывается (заменой `%prog`), выводится в stdout, и программа завершается.556557Например, если скрипт называется `/usr/bin/foo`:558559```console560$ /usr/bin/foo --version561foo 1.0562```563564Следующие два метода можно использовать для вывода и получения строки `version`:565566#### `OptionParser.print_version(file=None)`567568Выводит сообщение о версии текущей программы (`self.version`) в *file* (по умолчанию stdout). Как и в [`print_usage()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.print_usage), любое вхождение `%prog` в `self.version` заменяется на имя текущей программы. Ничего не делает, если `self.version` пусто или не определено.569570#### `OptionParser.get_version()`571572То же, что и [`print_version()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.print_version), но возвращает строку версии вместо её вывода.573574### Как `optparse` обрабатывает ошибки575576Существует два широких класса ошибок, с которыми приходится иметь дело `optparse`: ошибки программиста и ошибки пользователя. Ошибки программиста – это обычно неверные вызовы [`OptionParser.add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option), например, некорректные строки опций, неизвестные атрибуты опций, отсутствующие атрибуты опций и т.д. Они обрабатываются обычным способом: возбуждается исключение ([`optparse.OptionError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionError) или [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError)), и программа завершается аварийно.577578Обработка ошибок пользователя гораздо важнее, поскольку они гарантированно возникают независимо от стабильности кода. `optparse` может автоматически обнаруживать некоторые ошибки пользователя, такие как неверные аргументы опций (передача `-n 4x`, когда `-n` принимает целочисленный аргумент), отсутствие аргументов (`-n` в конце командной строки, когда `-n` принимает аргумент любого типа). Кроме того, можно вызвать `OptionParser.error()` для сигнализации об ошибке, определённой приложением:579580```python581(options, args) = parser.parse_args()582...583if options.a and options.b:584    parser.error("options -a and -b are mutually exclusive")585```586587В любом случае `optparse` обрабатывает ошибку одинаково: выводит сообщение об использовании программы и сообщение об ошибке в стандартный поток ошибок и завершается с кодом ошибки 2.588589Рассмотрим первый пример выше, где пользователь передаёт `4x` опции, которая принимает целое число:590591```console592$ /usr/bin/foo -n 4x593Usage: foo [options]594595foo: error: option -n: invalid integer value: '4x'596```597598Или когда пользователь вообще не передаёт значение:599600```console601$ /usr/bin/foo -n602Usage: foo [options]603604foo: error: -n option requires an argument605```606607Сообщения об ошибках, сгенерированные `optparse`, всегда содержат упоминание опции, вызвавшей ошибку; обязательно делайте то же самое при вызове `OptionParser.error()` из кода приложения.608609Если поведение обработки ошибок по умолчанию в `optparse` не соответствует требованиям, нужно создать подкласс OptionParser и переопределить его методы `exit()` и/или `error()`.610611### Собираем всё вместе612613Вот как обычно выглядят скрипты на основе `optparse`:614615```python616from optparse import OptionParser617...618def main():619    usage = "usage: %prog [options] arg"620    parser = OptionParser(usage)621    parser.add_option("-f", "--file", dest="filename",622                      help="read data from FILENAME")623    parser.add_option("-v", "--verbose",624                      action="store_true", dest="verbose")625    parser.add_option("-q", "--quiet",626                      action="store_false", dest="verbose")627    ...628    (options, args) = parser.parse_args()629    if len(args) != 1:630        parser.error("incorrect number of arguments")631    if options.verbose:632        print("reading %s..." % options.filename)633    ...634635if __name__ == "__main__":636    main()637```638639## Справочное руководство640641### Создание парсера642643Первым шагом при использовании `optparse` является создание экземпляра OptionParser.644645#### `class optparse.OptionParser(...)`646647Конструктор OptionParser не требует обязательных аргументов, но принимает ряд необязательных именованных аргументов. Их всегда следует передавать как именованные аргументы, т.е. не полагаться на порядок объявления аргументов.648649**`usage` (по умолчанию: `"%prog [options]"`)**650651Краткая справка по использованию, выводимая при неправильном запуске программы или по запросу справки. Когда `optparse` выводит строку использования, он заменяет `%prog` на `os.path.basename(sys.argv[0])` (или на `prog`, если был передан соответствующий именованный аргумент). Чтобы отключить сообщение об использовании, передайте специальное значение `optparse.SUPPRESS_USAGE`.652653**`option_list` (по умолчанию: `[]`)**654655Список объектов Option для заполнения парсера. Опции из `option_list` добавляются после любых опций из `standard_option_list` (атрибута класса, который может быть установлен подклассами OptionParser), но перед опциями версии и справки. Устарело; вместо этого используйте [`add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option) после создания парсера.656657**`option_class` (по умолчанию: optparse.Option)**658659Класс, используемый при добавлении опций в парсер в [`add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option).660661**`version` (по умолчанию: `None`)**662663Строка версии, выводимая по запросу опции версии. Если задать истинное значение для `version`, `optparse` автоматически добавляет опцию версии с единственной строкой опции `--version`. Подстрока `%prog` заменяется так же, как для `usage`.664665**`conflict_handler` (по умолчанию: `"error"`)**666667Определяет, что делать, когда в парсер добавляются опции с конфликтующими строками опций; см. раздел [Конфликты между опциями](https://python-all.ru/3.13/library/optparse.html#optparse-conflicts-between-options).668669**`description` (по умолчанию: `None`)**670671Абзац текста с кратким обзором программы. `optparse` переформатирует этот абзац под текущую ширину терминала и выводит его по запросу справки (после `usage`, но перед списком опций).672673**`formatter` (по умолчанию: новый `IndentedHelpFormatter`)**674675Экземпляр optparse.HelpFormatter, используемый для вывода текста справки. `optparse` предоставляет два конкретных класса для этой цели: IndentedHelpFormatter и TitledHelpFormatter.676677**`add_help_option` (по умолчанию: `True`)**678679Если истина, `optparse` добавит в парсер опцию справки (со строками опций `-h` и `--help`).680681**`prog`**682683Строка, используемая при замене `%prog` в `usage` и `version` вместо `os.path.basename(sys.argv[0])`.684685**`epilog` (по умолчанию: `None`)**686687Абзац текста справки, выводимый после справки по опциям.688689### Заполнение парсера690691Есть несколько способов заполнить парсер опциями. Предпочтительный способ – использовать [`OptionParser.add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option), как показано в разделе [Учебное пособие](https://python-all.ru/3.13/library/optparse.html#optparse-tutorial). `add_option()` можно вызывать одним из двух способов:692693- передать ему экземпляр Option (как возвращается `make_option()`)694- передать ему любую комбинацию позиционных и именованных аргументов, приемлемую для `make_option()` (т.е. для конструктора Option), и он создаст экземпляр Option автоматически695696Другой способ – передать список предварительно созданных экземпляров Option конструктору OptionParser, например:697698```python699option_list = [700    make_option("-f", "--filename",701                action="store", type="string", dest="filename"),702    make_option("-q", "--quiet",703                action="store_false", dest="verbose"),704    ]705parser = OptionParser(option_list=option_list)706```707708(`make_option()` – фабричная функция для создания экземпляров Option; в настоящее время это псевдоним конструктора Option. Будущая версия `optparse` может разделить Option на несколько классов, и `make_option()` будет выбирать нужный класс для создания экземпляра. Не создавайте экземпляры Option напрямую.)709710### Определение опций711712Каждый экземпляр Option представляет набор синонимичных строк опций командной строки, например `-f` и `--file`. Можно указать любое количество коротких или длинных строк опций, но необходимо указать хотя бы одну общую строку опции.713714Канонический способ создания экземпляра [`Option`](https://python-all.ru/3.13/library/optparse.html#optparse.Option) – это метод `add_option()` объекта [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser).715716#### `OptionParser.add_option(option)`717718#### `OptionParser.add_option(*opt_str, attr=value, ...)`719720Для определения опции только с короткой строкой опции:721722```python723parser.add_option("-f", attr=value, ...)724```725726А для определения опции только с длинной строкой опции:727728```python729parser.add_option("--foo", attr=value, ...)730```731732Именованные аргументы определяют атрибуты нового объекта Option. Самый важный атрибут опции – [`action`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.action), и он в значительной степени определяет, какие другие атрибуты являются релевантными или обязательными. Если передать нерелевантные атрибуты опции или не указать обязательные, `optparse` вызовет исключение [`OptionError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionError), поясняющее ошибку.733734Атрибут *action* опции определяет, что делает `optparse`, когда встречает эту опцию в командной строке. Стандартные действия опций, встроенные в `optparse`:735736**`"store"`**737738сохранить аргумент опции (по умолчанию)739740**`"store_const"`**741742сохранить постоянное значение, предварительно заданное через [`Option.const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const)743744**`"store_true"`**745746сохранить `True`747748**`"store_false"`**749750сохранить `False`751752**`"append"`**753754добавить аргумент этой опции в список755756**`"append_const"`**757758добавить постоянное значение в список, предварительно заданное через [`Option.const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const)759760**`"count"`**761762увеличить счётчик на единицу763764**`"callback"`**765766вызвать указанную функцию767768**`"help"`**769770вывести сообщение об использовании, включающее все опции и документацию к ним771772(Если не указать действие, по умолчанию используется `"store"`. Для этого действия можно также указать атрибуты опций [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest); см. [Стандартные действия опций](https://python-all.ru/3.13/library/optparse.html#optparse-standard-option-actions).)773774Как видно, большинство действий связано с сохранением или обновлением значения где-либо. `optparse` всегда создаёт для этого специальный объект, традиционно называемый `options`, который является экземпляром [`optparse.Values`](https://python-all.ru/3.13/library/optparse.html#optparse.Values).775776#### `class optparse.Values`777778Объект, содержащий имена и значения разобранных аргументов в виде атрибутов. Обычно создаётся при вызове [`OptionParser.parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args), и может быть заменён пользовательским подклассом, переданным в аргумент *values* функции `OptionParser.parse_args()` (как описано в [Разбор аргументов](https://python-all.ru/3.13/library/optparse.html#optparse-parsing-arguments)).779780Аргументы опции (и различные другие значения) сохраняются как атрибуты этого объекта в соответствии с атрибутом опции [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest) (назначение).781782Например, при вызове783784```python785parser.parse_args()786```787788одно из первых действий `optparse` – создание объекта `options`:789790```python791options = Values()792```793794Если одна из опций в этом анализаторе определена с помощью795796```python797parser.add_option("-f", "--file", action="store", type="string", dest="filename")798```799800и разбираемая командная строка включает любую из следующих:801802```python803-ffoo804-f foo805--file=foo806--file foo807```808809тогда `optparse`, увидев эту опцию, сделает эквивалент810811```python812options.filename = "foo"813```814815Атрибуты опций [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest) почти так же важны, как [`action`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.action), но `action` – единственный, который имеет смысл для *всех* опций.816817### Атрибуты опций818819#### `class optparse.Option`820821Один аргумент командной строки, с различными атрибутами, передаваемыми по ключу конструктору. Обычно создаётся с помощью [`OptionParser.add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option), а не напрямую, и может быть заменён пользовательским классом через аргумент *option\_class* функции [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser).822823Следующие атрибуты опций могут быть переданы как именованные аргументы в [`OptionParser.add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option). Если передать атрибут опции, который не является релевантным для конкретной опции, или не указать обязательный атрибут опции, `optparse` вызовет [`OptionError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionError).824825#### `Option.action`826827(по умолчанию: `"store"`)828829Determines `optparse`’s behaviour when this option is seen on the command line; the available options are documented [here](https://python-all.ru/3.13/library/optparse.html#optparse-standard-option-actions).830831#### `Option.type`832833(по умолчанию: `"string"`)834835The argument type expected by this option (e.g., `"string"` or `"int"`); the available option types are documented [here](https://python-all.ru/3.13/library/optparse.html#optparse-standard-option-types).836837#### `Option.dest`838839(по умолчанию: выводится из строк опций)840841Если действие опции подразумевает запись или изменение какого-либо значения, этот параметр указывает `optparse`, куда его записать: `dest` задаёт имя атрибута объекта `options`, который `optparse` создаёт по мере разбора командной строки.842843#### `Option.default`844845Значение, используемое для целевого атрибута этой опции, если опция не встречена в командной строке. См. также [`OptionParser.set_defaults()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.set_defaults).846847#### `Option.nargs`848849(по умолчанию: 1)850851Сколько аргументов типа [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type) должно быть потреблено, когда эта опция встречена. Если \> 1, `optparse` сохранит кортеж значений в [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest).852853#### `Option.const`854855Для действий, сохраняющих постоянное значение, – само это постоянное значение.856857#### `Option.choices`858859Для опций типа `"choice"` – список строк, из которых пользователь может выбирать.860861#### `Option.callback`862863For options with action `"callback"`, the callable to call when this option is seen. See section [Option Callbacks](https://python-all.ru/3.13/library/optparse.html#optparse-option-callbacks) for detail on the arguments passed to the callable.864865#### `Option.callback_args`866867#### `Option.callback_kwargs`868869Дополнительные позиционные и именованные аргументы, передаваемые в `callback` после четырёх стандартных аргументов колбэка.870871#### `Option.help`872873Текст справки для этой опции, выводимый при перечислении всех доступных опций после того, как пользователь укажет опцию `help` (например, `--help`). Если текст справки не указан, опция будет выведена без него. Чтобы скрыть опцию, используйте специальное значение `optparse.SUPPRESS_HELP`.874875#### `Option.metavar`876877(по умолчанию: выводится из строк опций)878879Stand-in for the option argument(s) to use when printing help text. See section [Tutorial](https://python-all.ru/3.13/library/optparse.html#optparse-tutorial) for an example.880881### Стандартные действия опций882883Различные действия опций имеют слегка разные требования и эффекты. У большинства действий есть несколько соответствующих атрибутов опции, которые вы можете указать, чтобы управлять поведением `optparse`; некоторые имеют обязательные атрибуты, которые необходимо указывать для любой опции, использующей это действие.884885- `"store"` \[относится: [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.choices)\]886887  The option must be followed by an argument, which is converted to a value according to [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type) and stored in [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest). If [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs) \> 1, multiple arguments will be consumed from the command line; all will be converted according to `type` and stored to `dest` as a tuple. See the [Standard option types](https://python-all.ru/3.13/library/optparse.html#optparse-standard-option-types) section.888889  Если указан [`choices`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.choices) (список или кортеж строк), тип по умолчанию `"choice"`.890891  Если [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type) не указан, по умолчанию используется `"string"`.892893  Если [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest) не указан, `optparse` выводит destination из первой длинной строки опции (например, `--foo-bar` подразумевает `foo_bar`). Если длинных строк опций нет, `optparse` выводит destination из первой короткой строки опции (например, `-f` подразумевает `f`).894895  Пример:896897  ```python898  parser.add_option("-f")899  parser.add_option("-p", type="float", nargs=3, dest="point")900  ```901902  В процессе разбора командной строки903904  ```python905  -f foo.txt -p 1 -3.5 4 -fbar.txt906  ```907908  `optparse` установит909910  ```python911  options.f = "foo.txt"912  options.point = (1.0, -3.5, 4.0)913  options.f = "bar.txt"914  ```915- `"store_const"` \[обязательно: [`const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const); относится: [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest)\]916917  Значение [`const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const) сохраняется в [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest).918919  Пример:920921  ```python922  parser.add_option("-q", "--quiet",923                    action="store_const", const=0, dest="verbose")924  parser.add_option("-v", "--verbose",925                    action="store_const", const=1, dest="verbose")926  parser.add_option("--noisy",927                    action="store_const", const=2, dest="verbose")928  ```929930  Если встречается `--noisy`, `optparse` установит931932  ```python933  options.verbose = 2934  ```935- `"store_true"` \[относится: [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest)\]936937  Частный случай `"store_const"`, который сохраняет `True` в [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest).938- `"store_false"` \[относится: [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest)\]939940  Как `"store_true"`, но сохраняет `False`.941942  Пример:943944  ```python945  parser.add_option("--clobber", action="store_true", dest="clobber")946  parser.add_option("--no-clobber", action="store_false", dest="clobber")947  ```948- `"append"` \[относится: [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.choices)\]949950  За опцией должен следовать аргумент, который добавляется в список [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest). Если значение по умолчанию для `dest` не указано, пустой список автоматически создаётся, когда `optparse` впервые встречает эту опцию в командной строке. Если [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs) \> 1, потребляется несколько аргументов, и кортеж длины `nargs` добавляется в `dest`.951952  Значения по умолчанию для [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest) такие же, как для действия `"store"`.953954  Пример:955956  ```python957  parser.add_option("-t", "--tracks", action="append", type="int")958  ```959960  Если в командной строке встречается `-t3`, `optparse` делает то же самое, что:961962  ```python963  options.tracks = []964  options.tracks.append(int("3"))965  ```966967  Если чуть позже встречается `--tracks=4`, выполняется:968969  ```python970  options.tracks.append(int("4"))971  ```972973  Действие `append` вызывает метод `append` для текущего значения опции. Это означает, что любое указанное значение по умолчанию должно иметь метод `append`. Это также означает, что если значение по умолчанию непустое, элементы по умолчанию будут присутствовать в разобранном значении для опции, а любые значения из командной строки будут добавлены после этих значений по умолчанию:974975  ```python976  >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])977  >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])978  >>> opts.files979  ['~/.mypkg/defaults', 'overrides.mypkg']980  ```981- `"append_const"` \[обязательно: [`const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const); относится: [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest)\]982983  Как `"store_const"`, но значение [`const`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.const) добавляется в [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest); как и в `"append"`, `dest` по умолчанию равен `None`, и пустой список автоматически создаётся при первом обнаружении опции.984- `"count"` \[относится: [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest)\]985986  Увеличивает целое число, хранящееся в [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest). Если значение по умолчанию не указано, `dest` устанавливается в ноль перед первым увеличением.987988  Пример:989990  ```python991  parser.add_option("-v", action="count", dest="verbosity")992  ```993994  При первом появлении `-v` в командной строке `optparse` делает то же самое, что:995996  ```python997  options.verbosity = 0998  options.verbosity += 1999  ```10001001  Каждое последующее появление `-v` приводит к10021003  ```python1004  options.verbosity += 11005  ```1006- `"callback"` \[обязательно: [`callback`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback); относится: [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type), [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs), [`callback_args`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_args), [`callback_kwargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_kwargs)\]10071008  Вызывает функцию, указанную в [`callback`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback), которая вызывается как10091010  ```python1011  func(option, opt_str, value, parser, *args, **kwargs)1012  ```10131014  Смотрите раздел [Колбэки опций](https://python-all.ru/3.13/library/optparse.html#optparse-option-callbacks) для подробностей.1015- `"help"`10161017  Выводит полное справочное сообщение для всех опций текущего парсера опций. Справочное сообщение формируется из строки `usage`, переданной конструктору OptionParser, и строки [`help`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.help), переданной каждой опции.10181019  Если для опции не указана строка [`help`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.help), она всё равно будет перечислена в справочном сообщении. Чтобы полностью исключить опцию, используйте специальное значение `optparse.SUPPRESS_HELP`.10201021  `optparse` автоматически добавляет опцию [`help`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.help) для всех объектов OptionParser, поэтому обычно не требуется создавать его отдельно.10221023  Пример:10241025  ```python1026  from optparse import OptionParser, SUPPRESS_HELP10271028  # обычно опция справки добавляется автоматически, но её можно1029  # подавить, используя аргумент add_help_option1030  parser = OptionParser(add_help_option=False)10311032  parser.add_option("-h", "--help", action="help")1033  parser.add_option("-v", action="store_true", dest="verbose",1034                    help="Be moderately verbose")1035  parser.add_option("--file", dest="filename",1036                    help="Input file to read data from")1037  parser.add_option("--secret", help=SUPPRESS_HELP)1038  ```10391040  Если `optparse` обнаруживает в командной строке `-h` или `--help`, он выводит примерно такое справочное сообщение в stdout (при условии, что `sys.argv[0]` равно `"foo.py"`):10411042  ```text1043  Usage: foo.py [options]10441045  Options:1046    -h, --help        Show this help message and exit1047    -v                Be moderately verbose1048    --file=FILENAME   Input file to read data from1049  ```10501051  После вывода справочного сообщения `optparse` завершает процесс с кодом `sys.exit(0)`.1052- `"version"`10531054  Выводит номер версии, переданный OptionParser, в stdout и завершает работу. Номер версии форматируется и выводится методом `print_version()` объекта OptionParser. Обычно актуально только если аргумент `version` передан конструктору OptionParser. Как и для опций [`help`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.help), `version` редко создаются вручную, так как `optparse` добавляет их автоматически при необходимости.10551056### Стандартные типы опций10571058`optparse` содержит пять встроенных типов опций: `"string"`, `"int"`, `"choice"`, `"float"` и `"complex"`. Если требуется добавить новые типы опций, см. раздел [Расширение optparse](https://python-all.ru/3.13/library/optparse.html#optparse-extending-optparse).10591060Аргументы строковых опций никак не проверяются и не преобразуются: текст из командной строки сохраняется в целевом атрибуте (или передаётся колбэку) как есть.10611062Целочисленные аргументы (тип `"int"`) разбираются следующим образом:10631064- если число начинается с `0x`, оно разбирается как шестнадцатеричное1065- если число начинается с `0`, оно разбирается как восьмеричное1066- если число начинается с `0b`, оно разбирается как двоичное1067- в противном случае число разбирается как десятичное10681069Преобразование выполняется вызовом [`int()`](https://python-all.ru/3.13/library/functions.html#int) с соответствующим основанием (2, 8, 10 или 16). В случае неудачи так же поступит и `optparse`, хотя и с более полезным сообщением об ошибке.10701071Аргументы опций `"float"` и `"complex"` преобразуются напрямую с помощью [`float()`](https://python-all.ru/3.13/library/functions.html#float) и [`complex()`](https://python-all.ru/3.13/library/functions.html#complex), с аналогичной обработкой ошибок.10721073Опции `"choice"` являются подтипом опций `"string"`. Атрибут опции [`choices`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.choices) (последовательность строк) определяет набор допустимых аргументов опции. `optparse.check_choice()` сравнивает предоставленные пользователем аргументы опции с этим основным списком и возбуждает [`OptionValueError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionValueError), если указана недопустимая строка.10741075### Разбор аргументов10761077Весь смысл создания и заполнения OptionParser заключается в вызове его метода [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args).10781079#### `OptionParser.parse_args(args=None, values=None)`10801081Разбирает параметры командной строки, переданные в *args*.10821083Входные параметры:10841085**`args`**10861087список аргументов для обработки (по умолчанию: `sys.argv[1:]`)10881089**`values`**10901091объект [`Values`](https://python-all.ru/3.13/library/optparse.html#optparse.Values) для сохранения аргументов опций (по умолчанию – новый экземпляр `Values`); если передать существующий объект, значения опций по умолчанию не будут в него инициализированы10921093а возвращаемое значение – это пара `(options, args)`, где10941095**`options`**10961097тот же объект, который был передан как *values*, или экземпляр `optparse.Values`, созданный с помощью `optparse`10981099**`args`**11001101оставшиеся позиционные аргументы после обработки всех опций11021103Наиболее распространённый способ использования – не указывать ни один из именованных аргументов. Если передать `values`, он будет изменён многократными вызовами [`setattr()`](https://python-all.ru/3.13/library/functions.html#setattr) (примерно по одному на каждый аргумент опции, сохраняемый в целевой атрибут) и возвращён [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args).11041105Если [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args) обнаруживает ошибки в списке аргументов, он вызывает метод `error()` объекта OptionParser с подходящим сообщением об ошибке для конечного пользователя. В итоге процесс завершается с кодом возврата 2 (традиционный код выхода Unix для ошибок командной строки).11061107### Запросы и изменение вашего парсера опций11081109Поведение парсера опций по умолчанию можно слегка настроить, а также можно заглянуть внутрь парсера и посмотреть, что там есть. OptionParser предоставляет несколько методов, которые в этом помогут:11101111#### `OptionParser.disable_interspersed_args()`11121113Настраивает разбор на остановку при первом не-опции. Например, если `-a` и `-b` – простые опции, не принимающие аргументов, `optparse` обычно принимает такой синтаксис:11141115```python1116prog -a arg1 -b arg21117```11181119и обрабатывает его как эквивалент11201121```python1122prog -a -b arg1 arg21123```11241125Чтобы отключить эту возможность, вызовите `disable_interspersed_args()`. Это восстанавливает традиционный синтаксис Unix, где разбор опций останавливается на первом аргументе, не являющемся опцией.11261127Используйте это, если у вас есть обработчик команд, который запускает другую команду с собственными опциями, и нужно гарантировать, что эти опции не будут перепутаны. Например, каждая команда может иметь свой набор опций.11281129#### `OptionParser.enable_interspersed_args()`11301131Настраивает разбор на то, чтобы не останавливаться на первом не-опции, позволяя перемешивать ключи с аргументами команды. Это поведение по умолчанию.11321133#### `OptionParser.get_option(opt_str)`11341135Возвращает экземпляр Option с строкой опции *opt\_str* или `None`, если ни одна опция не имеет такой строки.11361137#### `OptionParser.has_option(opt_str)`11381139Возвращает `True`, если OptionParser имеет опцию с строкой опции *opt\_str* (например, `-q` или `--verbose`).11401141#### `OptionParser.remove_option(opt_str)`11421143Если [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser) имеет опцию, соответствующую *opt\_str*, эта опция удаляется. Если эта опция предоставляла какие-либо другие строки опций, все эти строки опций становятся недействительными. Если *opt\_str* не встречается ни в одной опции, принадлежащей этому `OptionParser`, возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).11441145### Конфликты между опциями11461147Если быть невнимательным, легко определить опции с конфликтующими строками опций:11481149```python1150parser.add_option("-n", "--dry-run", ...)1151...1152parser.add_option("-n", "--noisy", ...)1153```11541155(Это особенно актуально, если определён собственный подкласс OptionParser с некоторыми стандартными опциями.)11561157При каждом добавлении опции `optparse` проверяет наличие конфликтов с существующими опциями. Если они обнаружены, вызывается текущий механизм обработки конфликтов. Механизм обработки конфликтов можно задать либо в конструкторе:11581159```python1160parser = OptionParser(..., conflict_handler=handler)1161```11621163или отдельным вызовом:11641165```python1166parser.set_conflict_handler(handler)1167```11681169Доступные обработчики конфликтов:11701171> **`"error"` (по умолчанию)**1172>1173> считать конфликты опций программной ошибкой и возбуждать [`OptionConflictError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionConflictError)1174>1175> **`"resolve"`**1176>1177> разрешать конфликты опций интеллектуально (см. ниже)11781179В качестве примера определим [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser), который разрешает конфликты интеллектуально, и добавим к нему конфликтующие опции:11801181```python1182parser = OptionParser(conflict_handler="resolve")1183parser.add_option("-n", "--dry-run", ..., help="do no harm")1184parser.add_option("-n", "--noisy", ..., help="be noisy")1185```11861187На этом этапе `optparse` обнаруживает, что ранее добавленная опция уже использует строку опции `-n`. Поскольку `conflict_handler` имеет значение `"resolve"`, ситуация разрешается удалением `-n` из списка строк опций предыдущей опции. Теперь `--dry-run` – единственный способ для пользователя активировать эту опцию. Если пользователь запросит справку, сообщение справки будет отражать это:11881189```python1190Options:1191  --dry-run     do no harm1192  ...1193  -n, --noisy   be noisy1194```11951196Можно постепенно удалять строки опций ранее добавленной опции, пока их не останется, и у пользователя не будет возможности вызвать эту опцию из командной строки. В этом случае `optparse` полностью удаляет эту опцию, так что она не появляется в тексте справки и где-либо ещё. Продолжая работу с существующим OptionParser:11971198```python1199parser.add_option("--dry-run", ..., help="new dry-run option")1200```12011202На этом этапе исходная опция `-n`/`--dry-run` больше не доступна, поэтому `optparse` удаляет её, оставляя такой текст справки:12031204```python1205Options:1206  ...1207  -n, --noisy   be noisy1208  --dry-run     new dry-run option1209```12101211### Очистка12121213Экземпляры OptionParser содержат несколько циклических ссылок. Это не должно быть проблемой для сборщика мусора Python, но можно явно разорвать циклические ссылки, вызвав `destroy()` для вашего OptionParser после завершения работы с ним. Это особенно полезно в долго работающих приложениях, где из OptionParser достижимы большие графы объектов.12141215### Другие методы12161217OptionParser поддерживает несколько других открытых методов:12181219#### `OptionParser.set_usage(usage)`12201221Устанавливает строку использования в соответствии с правилами, описанными выше для аргумента конструктора `usage`. Передача `None` устанавливает строку использования по умолчанию; используйте `optparse.SUPPRESS_USAGE`, чтобы подавить сообщение об использовании.12221223#### `OptionParser.print_usage(file=None)`12241225Выводит сообщение об использовании для текущей программы (`self.usage`) в *file* (по умолчанию stdout). Любое вхождение строки `%prog` в `self.usage` заменяется именем текущей программы. Ничего не делает, если `self.usage` пусто или не определено.12261227#### `OptionParser.get_usage()`12281229То же, что и [`print_usage()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.print_usage), но возвращает строку использования вместо её вывода.12301231#### `OptionParser.set_defaults(dest=value, ...)`12321233Устанавливает значения по умолчанию для нескольких целевых параметров опций одновременно. Использование `set_defaults()` является предпочтительным способом установки значений по умолчанию для опций, поскольку несколько опций могут совместно использовать один и тот же целевой параметр. Например, если несколько опций «режим» устанавливают один и тот же целевой параметр, любая из них может задать значение по умолчанию, и последняя имеет преимущество:12341235```python1236parser.add_option("--advanced", action="store_const",1237                  dest="mode", const="advanced",1238                  default="novice")    # переопределено ниже1239parser.add_option("--novice", action="store_const",1240                  dest="mode", const="novice",1241                  default="advanced")  # переопределяет вышеуказанную настройку1242```12431244Чтобы избежать этой путаницы, используйте `set_defaults()`:12451246```python1247parser.set_defaults(mode="advanced")1248parser.add_option("--advanced", action="store_const",1249                  dest="mode", const="advanced")1250parser.add_option("--novice", action="store_const",1251                  dest="mode", const="novice")1252```12531254## Колбэки опций12551256Когда встроенных действий и типов `optparse` недостаточно, есть два варианта: расширить `optparse` или определить опцию-колбэк. Расширение `optparse` более универсально, но для многих простых случаев избыточно. Зачастую простого колбэка вполне достаточно.12571258Определение опции-колбэка состоит из двух шагов:12591260- определить саму опцию с помощью действия `"callback"`1261- написать колбэк – функцию (или метод), которая принимает как минимум четыре аргумента, как описано ниже12621263### Определение опции-колбэка12641265Как всегда, проще всего определить опцию-колбэк с помощью метода [`OptionParser.add_option()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.add_option). Кроме [`action`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.action), единственный атрибут опции, который необходимо указать, – это `callback`, вызываемая функция:12661267```python1268parser.add_option("-c", action="callback", callback=my_callback)1269```12701271`callback` – это функция (или другой вызываемый объект), поэтому к моменту создания опции-колбэка `my_callback()` должна быть уже определена. В этом простом случае `optparse` даже не знает, принимает ли `-c` какие-либо аргументы, что обычно означает, что опция не принимает аргументов – достаточно одного присутствия `-c` в командной строке. Однако в некоторых ситуациях может потребоваться, чтобы колбэк обрабатывал произвольное количество аргументов командной строки. Здесь написание колбэков становится сложнее; об этом рассказывается далее в этом разделе.12721273`optparse` всегда передаёт колбэку четыре определённых аргумента и передаёт дополнительные, только если они указаны через [`callback_args`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_args) и [`callback_kwargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_kwargs). Таким образом, минимальная сигнатура функции колбэка выглядит так:12741275```python1276def my_callback(option, opt, value, parser):1277```12781279Четыре аргумента колбэка описаны ниже.12801281Есть ещё несколько атрибутов опции, которые можно указать при определении опции-колбэка:12821283**[`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type)**12841285имеет обычный смысл: как и действия `"store"` или `"append"`, он указывает `optparse` потребить один аргумент и преобразовать его в [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type). Однако вместо сохранения преобразованного значения где-либо, `optparse` передаёт его функции колбэка.12861287**[`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs)**12881289также имеет обычный смысл: если он указан и больше 1, `optparse` потребит [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs) аргументов, каждый из которых должен быть преобразуем в [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type). Затем он передаёт колбэку кортеж преобразованных значений.12901291**[`callback_args`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_args)**12921293кортеж дополнительных позиционных аргументов, передаваемых колбэку12941295**[`callback_kwargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_kwargs)**12961297словарь дополнительных именованных аргументов, передаваемых колбэку12981299### Как вызываются колбэки13001301Все колбэки вызываются следующим образом:13021303```python1304func(option, opt_str, value, parser, *args, **kwargs)1305```13061307где13081309**`option`**13101311это экземпляр Option, который вызывает колбэк13121313**`opt_str`**13141315это строка опции, указанная в командной строке, которая запускает колбэк. (Если использовалась сокращённая длинная опция, `opt_str` будет полной канонической строкой опции – например, если пользователь ввёл `--foo` в командной строке как сокращение для `--foobar`, то `opt_str` будет `"--foobar"`.)13161317**`value`**13181319это аргумент данной опции, указанный в командной строке. `optparse` будет ожидать аргумент, только если установлен [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type); тип `value` будет типом, подразумеваемым типом опции. Если `type` для этой опции равно `None` (аргумент не ожидается), то `value` будет `None`. Если [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs) \> 1, `value` будет кортежем значений соответствующего типа.13201321**`parser`**13221323это экземпляр OptionParser, управляющий всем процессом; он полезен тем, что через его атрибуты можно получить доступ к некоторым другим интересным данным:13241325**`parser.largs`**13261327текущий список оставшихся аргументов, то есть аргументов, которые были потреблены, но не являются ни опциями, ни аргументами опций. `parser.largs` можно изменять, например, добавляя в него новые аргументы. (Этот список станет `args`, вторым возвращаемым значением [`parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args).)13281329**`parser.rargs`**13301331текущий список оставшихся аргументов, то есть после удаления `opt_str` и `value` (если применимо), в котором остались только следующие за ними аргументы. `parser.rargs` можно изменять, например, потребляя дополнительные аргументы.13321333**`parser.values`**13341335объект, в котором по умолчанию хранятся значения опций (экземпляр optparse.OptionValues). Это позволяет колбэкам использовать тот же механизм хранения значений опций, что и остальная часть `optparse`; не нужно возиться с глобальными переменными или замыканиями. Также можно получать или изменять значения любых опций, уже встреченных в командной строке.13361337**`args`**13381339это кортеж произвольных позиционных аргументов, переданных через атрибут опции [`callback_args`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_args).13401341**`kwargs`**13421343это словарь произвольных именованных аргументов, переданных через [`callback_kwargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.callback_kwargs).13441345### Возбуждение ошибок в колбэке13461347Функция колбэка должна возбуждать [`OptionValueError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionValueError) при любых проблемах с опцией или её аргументами. `optparse` перехватывает это исключение и завершает программу, выводя сообщение об ошибке, указанное вами, в stderr. Сообщение должно быть ясным, кратким, точным и содержать указание на опцию, вызвавшую ошибку. В противном случае пользователю будет сложно понять, что он сделал не так.13481349### Пример колбэка 1: тривиальный колбэк13501351Вот пример опции-колбэка, которая не принимает аргументов и просто записывает факт своего появления:13521353```python1354def record_foo_seen(option, opt_str, value, parser):1355    parser.values.saw_foo = True13561357parser.add_option("--foo", action="callback", callback=record_foo_seen)1358```13591360Конечно, это можно было бы сделать с помощью действия `"store_true"`.13611362### Пример колбэка 2: проверка порядка опций13631364Вот чуть более интересный пример: запоминать, что `-a` был замечен, но завершаться с ошибкой, если он встречается после `-b` в командной строке.13651366```python1367def check_order(option, opt_str, value, parser):1368    if parser.values.b:1369        raise OptionValueError("can't use -a after -b")1370    parser.values.a = 11371...1372parser.add_option("-a", action="callback", callback=check_order)1373parser.add_option("-b", action="store_true", dest="b")1374```13751376### Пример колбэка 3: проверка порядка параметров (обобщённый)13771378Если нужно переиспользовать этот колбэк для нескольких похожих параметров (устанавливать флаг, но завершаться с ошибкой, если `-b` уже был замечен), потребуется доработка: сообщение об ошибке и устанавливаемый флаг должны быть обобщены.13791380```python1381def check_order(option, opt_str, value, parser):1382    if parser.values.b:1383        raise OptionValueError("can't use %s after -b" % opt_str)1384    setattr(parser.values, option.dest, 1)1385...1386parser.add_option("-a", action="callback", callback=check_order, dest='a')1387parser.add_option("-b", action="store_true", dest="b")1388parser.add_option("-c", action="callback", callback=check_order, dest='c')1389```13901391### Пример колбэка 4: проверка произвольного условия13921393Конечно, можно задать любое условие – вы не ограничены проверкой значений уже определённых параметров. Например, если есть параметры, которые не должны вызываться в полнолуние, достаточно сделать так:13941395```python1396def check_moon(option, opt_str, value, parser):1397    if is_moon_full():1398        raise OptionValueError("%s option invalid when moon is full"1399                               % opt_str)1400    setattr(parser.values, option.dest, 1)1401...1402parser.add_option("--foo",1403                  action="callback", callback=check_moon, dest="foo")1404```14051406(Определение `is_moon_full()` оставляется читателю в качестве упражнения.)14071408### Пример колбэка 5: фиксированное число аргументов14091410Ситуация становится немного интереснее, когда определяется параметр-колбэк с фиксированным числом аргументов. Указание, что параметр-колбэк принимает аргументы, аналогично определению параметра `"store"` или `"append"`: если задано [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type), то параметр принимает один аргумент, который должен быть преобразуем к этому типу; если дополнительно задано [`nargs`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.nargs), то параметр принимает `nargs` аргументов.14111412Вот пример, который просто эмулирует стандартное действие `"store"`:14131414```python1415def store_value(option, opt_str, value, parser):1416    setattr(parser.values, option.dest, value)1417...1418parser.add_option("--foo",1419                  action="callback", callback=store_value,1420                  type="int", nargs=3, dest="foo")1421```14221423Обратите внимание, что `optparse` сам заботится о потреблении 3 аргументов и преобразовании их в целые числа; остаётся только сохранить их. (Или что угодно; очевидно, для этого примера колбэк не нужен.)14241425### Пример колбэка 6: переменное число аргументов14261427Всё становится сложнее, когда требуется, чтобы параметр принимал переменное число аргументов. В этом случае нужно писать колбэк, так как `optparse` не предоставляет встроенных средств для этого. И придётся разбираться с определёнными тонкостями традиционного разбора командной строки Unix, которые `optparse` обычно обрабатывает автоматически. В частности, колбэки должны реализовывать обычные правила для голых аргументов `--` и `-`:14281429- как `--`, так и `-` могут быть аргументами параметра1430- голый `--` (если не является аргументом какого-либо параметра): остановить обработку командной строки и отбросить `--`1431- голый `-` (если не является аргументом какого-либо параметра): остановить обработку командной строки, но сохранить `-` (добавить его к `parser.largs`)14321433Если нужен параметр, принимающий переменное число аргументов, возникает несколько тонких и сложных моментов. Конкретная реализация будет зависеть от того, на какие компромиссы вы готовы пойти для своего приложения (именно поэтому `optparse` не поддерживает такое напрямую).14341435Тем не менее, вот пример попытки создать колбэк для параметра с переменным числом аргументов:14361437```python1438def vararg_callback(option, opt_str, value, parser):1439    assert value is None1440    value = []14411442    def floatable(str):1443        try:1444            float(str)1445            return True1446        except ValueError:1447            return False14481449    for arg in parser.rargs:1450        # останавливаться на опциях вида --foo1451        if arg[:2] == "--" and len(arg) > 2:1452            break1453        # останавливаться на -a, но не на -3 или -3.01454        if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):1455            break1456        value.append(arg)14571458    del parser.rargs[:len(value)]1459    setattr(parser.values, option.dest, value)14601461...1462parser.add_option("-c", "--callback", dest="vararg_attr",1463                  action="callback", callback=vararg_callback)1464```14651466## Расширение `optparse`14671468Поскольку двумя основными управляющими факторами того, как `optparse` интерпретирует параметры командной строки, являются действие и тип каждого параметра, наиболее вероятное направление расширения – добавление новых действий и новых типов.14691470### Добавление новых типов14711472Чтобы добавить новые типы, нужно определить собственный подкласс класса [`Option`](https://python-all.ru/3.13/library/optparse.html#optparse.Option) из `optparse`. У этого класса есть пара атрибутов, определяющих типы `optparse`: [`TYPES`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.TYPES) и [`TYPE_CHECKER`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.TYPE_CHECKER).14731474#### `Option.TYPES`14751476Кортеж имён типов; в своём подклассе просто определите новый кортеж [`TYPES`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.TYPES), основанный на стандартном.14771478#### `Option.TYPE_CHECKER`14791480Словарь, отображающий имена типов в функции проверки типа. Функция проверки типа имеет следующую сигнатуру:14811482```python1483def check_mytype(option, opt, value)1484```14851486где `option` – это экземпляр [`Option`](https://python-all.ru/3.13/library/optparse.html#optparse.Option), `opt` – строка параметра (например, `-f`), а `value` – строка из командной строки, которую нужно проверить и преобразовать в желаемый тип. `check_mytype()` должна возвращать объект гипотетического типа `mytype`. Значение, возвращаемое функцией проверки типа, окажется в экземпляре OptionValues, возвращаемом [`OptionParser.parse_args()`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser.parse_args), или будет передано колбэку как параметр `value`.14871488Функция проверки типа должна возбуждать [`OptionValueError`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionValueError) при возникновении проблем. `OptionValueError` принимает единственный строковый аргумент, который передаётся как есть методу `error()` объекта [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser), который, в свою очередь, добавляет имя программы и строку `"error:"` и печатает всё в stderr перед завершением процесса.14891490Вот глуповатый пример, демонстрирующий добавление типа параметра `"complex"` для разбора комплексных чисел в стиле Python в командной строке. (Этот пример стал ещё глупее, чем был, потому что в `optparse` 1.3 добавлена встроенная поддержка комплексных чисел, но не будем обращать внимания.)14911492Сначала необходимые импорты:14931494```python1495from copy import copy1496from optparse import Option, OptionValueError1497```14981499Сначала нужно определить проверщик типов, так как на него будет ссылка позже (в атрибуте класса [`TYPE_CHECKER`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.TYPE_CHECKER) вашего подкласса Option):15001501```python1502def check_complex(option, opt, value):1503    try:1504        return complex(value)1505    except ValueError:1506        raise OptionValueError(1507            "option %s: invalid complex value: %r" % (opt, value))1508```15091510Наконец, подкласс Option:15111512```python1513class MyOption (Option):1514    TYPES = Option.TYPES + ("complex",)1515    TYPE_CHECKER = copy(Option.TYPE_CHECKER)1516    TYPE_CHECKER["complex"] = check_complex1517```15181519(Если бы мы не создали [`copy()`](https://python-all.ru/3.13/library/copy.html#module-copy) для [`Option.TYPE_CHECKER`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.TYPE_CHECKER), мы бы в итоге изменили атрибут `TYPE_CHECKER` класса Option из `optparse`. Поскольку это Python, ничто не мешает это сделать, кроме хороших манер и здравого смысла.)15201521Вот и всё! Теперь можно написать скрипт, использующий новый тип опции, точно так же, как и любой другой скрипт на основе `optparse`, за исключением того, что нужно указать своему OptionParser использовать MyOption вместо Option:15221523```python1524parser = OptionParser(option_class=MyOption)1525parser.add_option("-c", type="complex")1526```15271528Либо можно собрать собственный список опций и передать его в OptionParser; если не использовать `add_option()` описанным выше способом, не требуется сообщать OptionParser, какой класс опции использовать:15291530```python1531option_list = [MyOption("-c", action="store", type="complex", dest="c")]1532parser = OptionParser(option_list=option_list)1533```15341535### Добавление новых действий15361537Добавление новых действий немного сложнее, потому что нужно понимать, что `optparse` разделяет действия на несколько категорий:15381539**«store»-действия**15401541действия, в результате которых `optparse` сохраняет значение в атрибут текущего экземпляра OptionValues; для таких опций в конструктор Option требуется передать атрибут [`dest`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.dest).15421543**«typed»-действия**15441545действия, которые берут значение из командной строки и ожидают, что оно будет определённого типа; точнее, ожидают строку, которую можно преобразовать в заданный тип. Для таких опций в конструктор Option требуется передать атрибут [`type`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.type).15461547Это пересекающиеся множества: к стандартным «store»-действиям относятся `"store"`, `"store_const"`, `"append"` и `"count"`, а к стандартным «typed»-действиям – `"store"`, `"append"` и `"callback"`.15481549При добавлении действия его нужно отнести к категории, включив как минимум в один из следующих атрибутов класса Option (все они являются списками строк):15501551#### `Option.ACTIONS`15521553Все действия должны быть перечислены в ACTIONS.15541555#### `Option.STORE_ACTIONS`15561557«store»-действия дополнительно перечисляются здесь.15581559#### `Option.TYPED_ACTIONS`15601561«typed»-действия дополнительно перечисляются здесь.15621563#### `Option.ALWAYS_TYPED_ACTIONS`15641565Действия, которые всегда принимают тип (то есть их опции всегда получают значение), дополнительно перечисляются здесь. Единственный эффект этого состоит в том, что `optparse` назначает тип по умолчанию `"string"` опциям без явно указанного типа, чьё действие перечислено в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).15661567Чтобы реализовать новое действие, нужно переопределить метод `take_action()` класса Option и добавить ветвь, распознающую это действие.15681569Например, добавим действие `"extend"`. Оно похоже на стандартное `"append"`, но вместо того, чтобы взять из командной строки одно значение и добавить его в конец существующего списка, `"extend"` принимает несколько значений в одной строке с разделителями-запятыми и расширяет ими существующий список. То есть, если `--names` является опцией `"extend"` с типом `"string"`, то командная строка15701571```python1572--names=foo,bar --names blah --names ding,dong1573```15741575приведёт к списку15761577```python1578["foo", "bar", "blah", "ding", "dong"]1579```15801581Снова определим подкласс Option:15821583```python1584class MyOption(Option):15851586    ACTIONS = Option.ACTIONS + ("extend",)1587    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)1588    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)1589    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)15901591    def take_action(self, action, dest, opt, value, values, parser):1592        if action == "extend":1593            lvalue = value.split(",")1594            values.ensure_value(dest, []).extend(lvalue)1595        else:1596            Option.take_action(1597                self, action, dest, opt, value, values, parser)1598```15991600Что следует отметить:16011602- `"extend"` одновременно ожидает значение в командной строке и сохраняет его, поэтому попадает как в [`STORE_ACTIONS`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.STORE_ACTIONS), так и в [`TYPED_ACTIONS`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.TYPED_ACTIONS).1603- чтобы `optparse` назначал тип по умолчанию `"string"` действиям `"extend"`, мы помещаем действие `"extend"` также в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.13/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).1604- `MyOption.take_action()` реализует только это одно новое действие и передаёт управление обратно `Option.take_action()` для стандартных действий `optparse`.1605- `values` – это экземпляр класса optparse\_parser.Values, предоставляющий очень полезный метод `ensure_value()`. `ensure_value()` – это по сути [`getattr()`](https://python-all.ru/3.13/library/functions.html#getattr) с предохранительным клапаном; он вызывается как16061607  ```python1608  values.ensure_value(attr, value)1609  ```16101611  Если атрибут `attr` у `values` не существует или равен `None`, то ensure\_value() сначала устанавливает его в `value`, а затем возвращает `value`. Это очень удобно для таких действий, как `"extend"`, `"append"` и `"count"`, которые накапливают данные в переменной и ожидают, что эта переменная будет определённого типа (список для первых двух, целое число для последнего). Использование `ensure_value()` означает, что скриптам, использующим ваше действие, не нужно беспокоиться о задании значения по умолчанию для соответствующих назначений опций; они могут просто оставить значение по умолчанию равным `None`, и `ensure_value()` позаботится о том, чтобы при необходимости установить его правильно.16121613## Исключения16141615#### `exception optparse.OptionError`16161617Возбуждается, если экземпляр [`Option`](https://python-all.ru/3.13/library/optparse.html#optparse.Option) создан с недопустимыми или противоречивыми аргументами.16181619#### `exception optparse.OptionConflictError`16201621Возбуждается, если в [`OptionParser`](https://python-all.ru/3.13/library/optparse.html#optparse.OptionParser) добавляются конфликтующие опции.16221623#### `exception optparse.OptionValueError`16241625Возбуждается, если в командной строке указано недопустимое значение параметра.16261627#### `exception optparse.BadOptionError`16281629Возбуждается, если в командной строке передан недопустимый параметр.16301631#### `exception optparse.AmbiguousOptionError`16321633Возбуждается, если в командной строке передан неоднозначный параметр.1634