optparse.md

1> **Источник:** https://python-all.ru/3.5/library/optparse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 36.1. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) – Парсер параметров командной строки89**Исходный код:** [Lib/optparse.py](https://python-all.ru/src/3.5/Lib/optparse.py)1011Устарело с версии 3.2: Модуль [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) устарел и не будет развиваться дальше; разработка будет продолжена с модулем [`argparse`](https://python-all.ru/3.5/library/argparse.html#module-argparse).1213---1415[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) – это более удобная, гибкая и мощная библиотека для разбора параметров командной строки, чем старый модуль [`getopt`](https://python-all.ru/3.5/library/getopt.html#module-getopt). [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) использует более декларативный стиль разбора командной строки: вы создаёте экземпляр [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser), заполняете его параметрами и разбираете командную строку. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) позволяет пользователям указывать параметры в стандартном синтаксисе GNU/POSIX, а также автоматически генерирует для вас сообщения об использовании и справку.1617Вот пример использования [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) в простом скрипте:1819```python20from optparse import OptionParser21...22parser = OptionParser()23parser.add_option("-f", "--file", dest="filename",24                  help="write report to FILE", metavar="FILE")25parser.add_option("-q", "--quiet",26                  action="store_false", dest="verbose", default=True,27                  help="don't print status messages to stdout")2829(options, args) = parser.parse_args()30```3132С помощью этих нескольких строк кода пользователи вашего скрипта теперь могут делать «обычные вещи» в командной строке, например:3334```python35<yourscript> --file=outfile -q36```3738По мере разбора командной строки [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) устанавливает атрибуты объекта `options`, возвращаемого `parse_args()`, на основе предоставленных пользователем значений командной строки. Когда `parse_args()` завершает разбор этой командной строки, `options.filename` будет `"outfile"`, а `options.verbose` будет `False`. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) поддерживает как длинные, так и короткие параметры, позволяет объединять короткие параметры, а также позволяет связывать параметры с их аргументами различными способами. Таким образом, следующие командные строки эквивалентны приведённому выше примеру:3940```python41<yourscript> -f outfile --quiet42<yourscript> --quiet --file outfile43<yourscript> -q -foutfile44<yourscript> -qfoutfile45```4647Кроме того, можно запустить один из4849```python50<yourscript> -h51<yourscript> --help52```5354и [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) выведет краткую сводку параметров вашего скрипта:5556```text57Usage: <yourscript> [options]5859Options:60  -h, --help            show this help message and exit61  -f FILE, --file=FILE  write report to FILE62  -q, --quiet           don't print status messages to stdout63```6465где значение *yourscript* определяется во время выполнения (обычно из `sys.argv[0]`).6667## 36.1.1. Предыстория6869[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) был явно спроектирован для поощрения создания программ с простыми и стандартными интерфейсами командной строки. Для этого он поддерживает только самые распространённые синтаксис и семантику командной строки, традиционно используемые в Unix. Если вы не знакомы с этими соглашениями, прочитайте этот раздел, чтобы ознакомиться с ними.7071### 36.1.1.1. Терминология7273**аргумент**7475строка, введенная в командной строке и переданная оболочкой в `execl()` или `execv()`. В Python аргументами являются элементы `sys.argv[1:]` (`sys.argv[0]` – это имя выполняемой программы). Оболочки Unix также используют термин «слово».7677Иногда желательно подставить список аргументов, отличный от `sys.argv[1:]`, поэтому под «аргументом» следует понимать «элемент `sys.argv[1:]` или любого другого списка, предоставленного взамен `sys.argv[1:]`».7879**опция**8081аргумент, используемый для предоставления дополнительной информации для управления или настройки выполнения программы. Существует много разных синтаксисов для опций; традиционный синтаксис Unix – это дефис («-») с последующей одной буквой, например `-x` или `-F`. Также традиционный синтаксис Unix позволяет объединять несколько опций в один аргумент, например `-x -F` эквивалентно `-xF`. Проект GNU ввел `--` с последующей последовательностью слов, разделенных дефисом, например `--file` или `--dry-run`. Это единственные два синтаксиса опций, предоставляемые [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse).8283Некоторые другие синтаксисы опций, которые встречались в мире, включают:8485- дефис с последующими несколькими буквами, например `-pf` (это *не* то же самое, что несколько опций, объединенных в один аргумент)86- дефис с последующим целым словом, например `-file` (технически это эквивалентно предыдущему синтаксису, но они обычно не встречаются в одной программе)87- знак плюс с последующей одной буквой, или несколькими буквами, или словом, например `+f`, `+rgb`88- косая черта с последующей буквой, или несколькими буквами, или словом, например `/f`, `/file`8990Эти синтаксисы опций не поддерживаются [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) и никогда не будут. Это сделано намеренно: первые три нестандартны в любом окружении, а последний имеет смысл только если вы ориентируетесь исключительно на VMS, MS-DOS и/или Windows.9192**аргумент опции**9394аргумент, который следует за опцией, тесно связан с этой опцией и извлекается из списка аргументов вместе с ней. В [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) аргументы опций могут находиться как в отдельном аргументе от своей опции:9596```text97-f foo98--file foo99```100101или включены в тот же аргумент:102103```text104-ffoo105--file=foo106```107108Обычно конкретная опция либо принимает аргумент, либо нет. Многие хотят функцию «необязательных аргументов опций», то есть некоторые опции будут принимать аргумент, если он есть, и не будут, если его нет. Это несколько спорно, поскольку делает разбор неоднозначным: если `-a` принимает необязательный аргумент, а `-b` – это совершенно другая опция, как интерпретировать `-ab`? Из-за этой неоднозначности [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) не поддерживает такую функцию.109110**позиционный аргумент**111112то, что осталось в списке аргументов после разбора опций, т.е. после того, как опции и их аргументы были разобраны и удалены из списка аргументов.113114**обязательная опция**115116опция, которая должна быть указана в командной строке; обратите внимание, что фраза «обязательная опция» противоречива по своей сути.117118[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)119120не препятствует реализации обязательных опций, но и не оказывает большой помощи в этом.121122Например, рассмотрим эту гипотетическую командную строку:123124```python125prog -v --report report.txt foo bar126```127128`-v` и `--report` являются опциями. Предполагая, что `--report` принимает один аргумент, `report.txt` является аргументом опции. `foo` и `bar` являются позиционными аргументами.129130### 36.1.1.2. Для чего нужны опции?131132Опции используются для предоставления дополнительной информации для настройки или кастомизации выполнения программы. Если это не было очевидно, опции обычно *необязательны*. Программа должна нормально работать вообще без опций. (Возьмите случайную программу из инструментария Unix или GNU. Может ли она работать без каких-либо опций и при этом иметь смысл? Главные исключения – `find`, `tar` и `dd` – все они мутанты-чудаки, которые по праву критикуются за нестандартный синтаксис и запутанные интерфейсы.)133134Многие хотят, чтобы в их программах были «обязательные опции». Подумайте об этом. Если это обязательно, значит, это *не необязательно*! Если есть информация, которая absolutely необходима вашей программе для успешного выполнения, для этого существуют позиционные аргументы.135136В качестве примера хорошего дизайна интерфейса командной строки рассмотрим скромную утилиту `cp` для копирования файлов. Копировать файлы без указания назначения и хотя бы одного источника не имеет особого смысла. Поэтому `cp` завершается с ошибкой, если запустить ее без аргументов. Однако у нее гибкий, полезный синтаксис, который вообще не требует опций:137138```python139cp SOURCE DEST140cp SOURCE ... DEST-DIR141```142143На этом можно многого добиться. Большинство реализаций `cp` предоставляют множество опций для точной настройки копирования: можно сохранять права и время модификации, не следовать симлинкам, спрашивать перед перезаписью существующих файлов и т.д. Но ничто из этого не отвлекает от основной задачи `cp` – скопировать один файл в другой или несколько файлов в другой каталог.144145### 36.1.1.3. Для чего нужны позиционные аргументы?146147Позиционные аргументы предназначены для тех частей информации, которые absolutely и однозначно необходимы вашей программе для работы.148149Хороший пользовательский интерфейс должен иметь как можно меньше абсолютных требований. Если вашей программе требуется 17 различных частей информации для успешного запуска, не имеет большого значения *как* вы получаете эту информацию от пользователя – большинство людей сдадутся и уйдут, так и не запустив программу. Это справедливо независимо от того, является ли интерфейс командной строкой, файлом конфигурации или графическим интерфейсом: если вы предъявляете столько требований к пользователям, большинство из них просто сдадутся.150151Короче говоря, старайтесь минимизировать объем информации, которую пользователи absolutely обязаны предоставить – используйте разумные значения по умолчанию, когда это возможно. Конечно, вы также хотите сделать свои программы достаточно гибкими. Для этого и нужны опции. Опять же, неважно, являются ли они записями в файле конфигурации, виджетами в диалоге «Настройки» графического интерфейса или опциями командной строки – чем больше опций вы реализуете, тем гибче становится ваша программа, и тем сложнее становится ее реализация. Слишком большая гибкость тоже имеет недостатки; слишком много опций может перегрузить пользователей и сделать ваш код гораздо сложнее в поддержке.152153## 36.1.2. Учебник154155Хотя [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) довольно гибкий и мощный, он также прост в использовании в большинстве случаев. В этом разделе рассматриваются шаблоны кода, общие для любой программы на основе [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse).156157Сначала необходимо импортировать класс OptionParser; затем, в начале основной программы, создать экземпляр OptionParser:158159```python160from optparse import OptionParser161...162parser = OptionParser()163```164165Затем можно приступить к определению опций. Базовый синтаксис:166167```python168parser.add_option(opt_str, ...,169                  attr=value, ...)170```171172Каждая опция имеет одну или несколько строк опций, например `-f` или `--file`, и несколько атрибутов, которые сообщают [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), что ожидать и что делать, когда он встречает эту опцию в командной строке.173174Обычно каждая опция имеет одну короткую и одну длинную строку опции, например:175176```python177parser.add_option("-f", "--file", ...)178```179180Вы можете определить любое количество коротких и длинных строк опций (включая ноль), при условии, что в целом есть хотя бы одна строка опции.181182Строки опций, передаваемые в [`OptionParser.add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option), по сути являются метками для опции, определяемой этим вызовом. Для краткости мы часто будем ссылаться на *встречу опции* в командной строке; на самом деле [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) встречает *строки опций* и ищет опции по ним.183184Когда все опции определены, укажите [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) разобрать командную строку вашей программы:185186```python187(options, args) = parser.parse_args()188```189190(При желании можно передать собственный список аргументов в `parse_args()`, но это редко необходимо: по умолчанию он использует `sys.argv[1:]`.)191192`parse_args()` возвращает два значения:193194- `options` – объект, содержащий значения для всех опций. Например, если `--file` принимает один строковый аргумент, то `options.file` будет именем файла, указанным пользователем, или `None`, если пользователь не указал эту опцию.195- `args` – список позиционных аргументов, оставшихся после разбора опций196197В этом учебном разделе рассматриваются только четыре наиболее важных атрибута опций: [`action`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.action), [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) (destination) и [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help). Из них [`action`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.action) является самым основным.198199### 36.1.2.1. Понимание действий опций200201Действия сообщают [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), что делать, когда он встречает опцию в командной строке. Существует фиксированный набор действий, встроенных в [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse); добавление новых действий – продвинутая тема, рассматриваемая в разделе [Расширение optparse](https://python-all.ru/3.5/library/optparse.html#optparse-extending-optparse). Большинство действий говорят [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) сохранить значение в некоторую переменную – например, взять строку из командной строки и сохранить её в атрибуте `options`.202203Если не указано действие опции, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) по умолчанию использует `store`.204205### 36.1.2.2. Действие store206207Наиболее распространенное действие опции – `store`, которое говорит [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) взять следующий аргумент (или остаток текущего аргумента), убедиться, что он имеет правильный тип, и сохранить его в выбранное место назначения.208209Например:210211```python212parser.add_option("-f", "--file",213                  action="store", type="string", dest="filename")214```215216Теперь давайте создадим фиктивную командную строку и попросим [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) разобрать её:217218```python219args = ["-f", "foo.txt"]220(options, args) = parser.parse_args(args)221```222223Когда [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) видит строку опции `-f`, он потребляет следующий аргумент, `foo.txt`, и сохраняет его в `options.filename`. Итак, после этого вызова `parse_args()`, `options.filename` равно `"foo.txt"`.224225Некоторые другие типы опций, поддерживаемые [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse): `int` и `float`. Вот опция, которая ожидает целочисленный аргумент:226227```python228parser.add_option("-n", type="int", dest="num")229```230231Обратите внимание, что эта опция не имеет длинной строки опции, что вполне допустимо. Кроме того, отсутствует явное действие, поскольку по умолчанию используется `store`.232233Давайте разберём другую фиктивную командную строку. На этот раз мы поместим аргумент опции непосредственно рядом с опцией: поскольку `-n42` (один аргумент) эквивалентно `-n 42` (два аргумента), код234235```python236(options, args) = parser.parse_args(["-n42"])237print(options.num)238```239240выведет `42`.241242Если тип не указан, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) предполагает `string`. В сочетании с тем, что действие по умолчанию – `store`, это означает, что наш первый пример можно сделать гораздо короче:243244```python245parser.add_option("-f", "--file", dest="filename")246```247248Если место назначения не указано, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) определяет разумное значение по умолчанию из строк опций: если первая длинная строка опции – `--foo-bar`, то по умолчанию местом назначения будет `foo_bar`. Если длинных строк опций нет, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) смотрит на первую короткую строку опции: местом назначения по умолчанию для `-f` будет `f`.249250[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) также включает встроенный тип `complex`. Добавление типов рассматривается в разделе [Расширение optparse](https://python-all.ru/3.5/library/optparse.html#optparse-extending-optparse).251252### 36.1.2.3. Обработка логических (флаговых) опций253254Флаговые опции – устанавливают переменную в true или false при обнаружении определённой опции – довольно распространены. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) поддерживает их с помощью двух отдельных действий: `store_true` и `store_false`. Например, у вас может быть флаг `verbose`, который включается с помощью `-v` и выключается с помощью `-q`:255256```python257parser.add_option("-v", action="store_true", dest="verbose")258parser.add_option("-q", action="store_false", dest="verbose")259```260261Здесь у нас две разные опции с одним и тем же назначением, что совершенно нормально. (Это просто означает, что нужно быть немного внимательнее при установке значений по умолчанию – см. ниже.)262263Когда [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) встречает `-v` в командной строке, он устанавливает `options.verbose` в `True`; когда он встречает `-q`, `options.verbose` устанавливается в `False`.264265### 36.1.2.4. Другие действия266267Некоторые другие действия, поддерживаемые [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse):268269**`"store_const"`**270271сохранить константное значение272273**`"append"`**274275добавить аргумент этой опции в список276277**`"count"`**278279увеличить счётчик на единицу280281**`"callback"`**282283вызвать указанную функцию284285Эти вопросы рассматриваются в разделе [Справочное руководство](https://python-all.ru/3.5/library/optparse.html#optparse-reference-guide), Справочное руководство и разделе [Колбэки опций](https://python-all.ru/3.5/library/optparse.html#optparse-option-callbacks).286287### 36.1.2.5. Значения по умолчанию288289Все приведённые выше примеры предполагают установку некоторой переменной («назначения») при обнаружении определённых параметров командной строки. Что произойдёт, если эти параметры никогда не встретятся? Поскольку мы не указали значения по умолчанию, все они будут установлены в `None`. Обычно это нормально, но иногда требуется больший контроль. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) позволяет указать значение по умолчанию для каждого назначения, которое присваивается до разбора командной строки.290291Сначала рассмотрим пример с подробным/тихим режимом. Если мы хотим, чтобы [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) устанавливал `verbose` в `True`, если не встречен `-q`, то можно сделать так:292293```python294parser.add_option("-v", action="store_true", dest="verbose", default=True)295parser.add_option("-q", action="store_false", dest="verbose")296```297298Поскольку значения по умолчанию применяются к *назначению*, а не к какому-либо конкретному параметру, и эти два параметра имеют одно и то же назначение, это полностью эквивалентно:299300```python301parser.add_option("-v", action="store_true", dest="verbose")302parser.add_option("-q", action="store_false", dest="verbose", default=True)303```304305Рассмотрим это:306307```python308parser.add_option("-v", action="store_true", dest="verbose", default=False)309parser.add_option("-q", action="store_false", dest="verbose", default=True)310```311312Опять же, значение по умолчанию для `verbose` будет `True`: последнее указанное значение по умолчанию для любого конкретного назначения и будет использоваться.313314Более понятный способ задать значения по умолчанию – это метод `set_defaults()` объекта OptionParser, который можно вызывать в любое время до вызова `parse_args()`:315316```python317parser.set_defaults(verbose=True)318parser.add_option(...)319(options, args) = parser.parse_args()320```321322Как и прежде, последнее указанное значение для данного назначения параметра и будет использоваться. Для ясности старайтесь использовать какой-то один способ задания значений по умолчанию, а не оба сразу.323324### 36.1.2.6. Генерация справки325326Возможность [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) автоматически генерировать текст справки и использования полезна для создания удобных интерфейсов командной строки. Всё, что нужно сделать – указать значение [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help) для каждого параметра и, опционально, краткое сообщение об использовании для всей программы. Вот OptionParser, заполненный удобными (документированными) параметрами:327328```python329usage = "usage: %prog [options] arg1 arg2"330parser = OptionParser(usage=usage)331parser.add_option("-v", "--verbose",332                  action="store_true", dest="verbose", default=True,333                  help="make lots of noise [default]")334parser.add_option("-q", "--quiet",335                  action="store_false", dest="verbose",336                  help="be vewwy quiet (I'm hunting wabbits)")337parser.add_option("-f", "--filename",338                  metavar="FILE", help="write output to FILE")339parser.add_option("-m", "--mode",340                  default="intermediate",341                  help="interaction mode: novice, intermediate, "342                       "or expert [default: %default]")343```344345Если [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) встречает в командной строке `-h` или `--help`, или если просто вызвать `parser.print_help()`, он выводит следующее в стандартный вывод:346347```text348Usage: <yourscript> [options] arg1 arg2349350Options:351  -h, --help            show this help message and exit352  -v, --verbose         make lots of noise [default]353  -q, --quiet           be vewwy quiet (I'm hunting wabbits)354  -f FILE, --filename=FILE355                        write output to FILE356  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or357                        expert [default: intermediate]358```359360(Если вывод справки вызван опцией помощи, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) завершает работу после печати текста справки.)361362Здесь много деталей, помогающих [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) сгенерировать наилучшее сообщение справки:363364- сценарий определяет собственное сообщение об использовании:365366  ```python367  usage = "usage: %prog [options] arg1 arg2"368  ```369370  [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) заменяет `%prog` в строке использования на имя текущей программы, т.е. `os.path.basename(sys.argv[0])`. Затем расширенная строка выводится перед подробной справкой по параметрам.371372  Если не указать строку использования, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) использует простое, но разумное значение по умолчанию: `"Usage: %prog [options]"`, что подходит, если сценарий не принимает позиционные аргументы.373- каждая опция определяет строку справки, и не нужно беспокоиться о переносе строк – [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) заботится о переносе строк и делает вывод справки красивым.374- Опции, принимающие значение, указывают на это в автоматически сгенерированном сообщении справки, например, для опции «mode»:375376  ```python377  -m MODE, --mode=MODE378  ```379380  Здесь «MODE» называется метапеременной: она обозначает аргумент, который пользователь должен передать в `-m`/`--mode`. По умолчанию [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) преобразует имя переменной назначения в верхний регистр и использует его для метапеременной. Иногда это не то, что нужно – например, опция `--filename` явно задаёт `metavar="FILE"`, что приводит к такому автоматически сгенерированному описанию опции:381382  ```python383  -f FILE, --filename=FILE384  ```385386  Это важно не только для экономии места: вручную написанный текст справки использует мета-переменную `FILE`, чтобы подсказать пользователю, что существует связь между полуформальным синтаксисом `-f FILE` и неформальным семантическим описанием «записать вывод в FILE». Это простой, но эффективный способ сделать текст справки гораздо понятнее и полезнее для конечных пользователей.387- Параметры, имеющие значение по умолчанию, могут включать `%default` в строку справки – [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) заменит его на [`str()`](https://python-all.ru/3.5/library/stdtypes.html#str) значения по умолчанию этого параметра. Если параметр не имеет значения по умолчанию (или значение по умолчанию равно `None`), `%default` раскрывается в `none`.388389#### 36.1.2.6.1. Группировка опций390391При работе с большим количеством параметров удобно группировать их для улучшения вывода справки. [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser) может содержать несколько групп параметров, каждая из которых может содержать несколько параметров.392393Группа параметров создаётся с помощью класса [`OptionGroup`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionGroup):394395#### `class optparse.OptionGroup(parser, title, description=None)`396397где398399- parser – это экземпляр [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser), в который будет вставлена группа400- title – это заголовок группы401- description (необязательно) – это подробное описание группы402403[`OptionGroup`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionGroup) наследуется от `OptionContainer` (как [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser)), поэтому метод `add_option()` можно использовать для добавления опции в группу.404405После объявления всех опций с помощью метода [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser) `add_option_group()` группа добавляется в ранее определённый парсер.406407Продолжая с парсером, определённым в предыдущем разделе, добавить [`OptionGroup`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionGroup) в парсер несложно:408409```python410group = OptionGroup(parser, "Dangerous Options",411                    "Caution: use these options at your own risk.  "412                    "It is believed that some of them bite.")413group.add_option("-g", action="store_true", help="Group option.")414parser.add_option_group(group)415```416417Это приведёт к следующему выводу справки:418419```text420Usage: <yourscript> [options] arg1 arg2421422Options:423  -h, --help            show this help message and exit424  -v, --verbose         make lots of noise [default]425  -q, --quiet           be vewwy quiet (I'm hunting wabbits)426  -f FILE, --filename=FILE427                        write output to FILE428  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or429                        expert [default: intermediate]430431  Dangerous Options:432    Caution: use these options at your own risk.  It is believed that some433    of them bite.434435    -g                  Group option.436```437438Несколько более полный пример может включать использование более одной группы: всё так же расширяя предыдущий пример:439440```python441group = OptionGroup(parser, "Dangerous Options",442                    "Caution: use these options at your own risk.  "443                    "It is believed that some of them bite.")444group.add_option("-g", action="store_true", help="Group option.")445parser.add_option_group(group)446447group = OptionGroup(parser, "Debug Options")448group.add_option("-d", "--debug", action="store_true",449                 help="Print debug information")450group.add_option("-s", "--sql", action="store_true",451                 help="Print all SQL statements executed")452group.add_option("-e", action="store_true", help="Print every action done")453parser.add_option_group(group)454```455456что приводит к следующему выводу:457458```text459Usage: <yourscript> [options] arg1 arg2460461Options:462  -h, --help            show this help message and exit463  -v, --verbose         make lots of noise [default]464  -q, --quiet           be vewwy quiet (I'm hunting wabbits)465  -f FILE, --filename=FILE466                        write output to FILE467  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or expert468                        [default: intermediate]469470  Dangerous Options:471    Caution: use these options at your own risk.  It is believed that some472    of them bite.473474    -g                  Group option.475476  Debug Options:477    -d, --debug         Print debug information478    -s, --sql           Print all SQL statements executed479    -e                  Print every action done480```481482Ещё один интересный метод, особенно при программной работе с группами опций:483484#### `OptionParser.get_option_group(opt_str)`485486Возвращает [`OptionGroup`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionGroup), которому принадлежит короткая или длинная строка опции *opt\_str* (например, `'-o'` или `'--option'`). Если такого [`OptionGroup`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionGroup) нет, возвращает `None`.487488### 36.1.2.7. Вывод строки версии489490Подобно краткой строке использования, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) также может выводить строку версии для программы. Строку нужно передать в качестве аргумента `version` конструктору OptionParser:491492```python493parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")494```495496`%prog` раскрывается так же, как в `usage`. Кроме того, `version` может содержать что угодно. При передаче строки [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) автоматически добавляет опцию `--version` в парсер. Если эта опция встречается в командной строке, строка `version` раскрывается (заменой `%prog`), выводится в stdout, и программа завершается.497498Например, если скрипт называется `/usr/bin/foo`:499500```console501$ /usr/bin/foo --version502foo 1.0503```504505Следующие два метода можно использовать для вывода и получения строки `version`:506507#### `OptionParser.print_version(file=None)`508509Выводит сообщение о версии текущей программы (`self.version`) в *file* (по умолчанию stdout). Как и в [`print_usage()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.print_usage), любое вхождение `%prog` в `self.version` заменяется на имя текущей программы. Ничего не делает, если `self.version` пусто или не определено.510511#### `OptionParser.get_version()`512513То же, что и [`print_version()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.print_version), но возвращает строку версии вместо её вывода.514515### 36.1.2.8. Как [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) обрабатывает ошибки516517Существует два широких класса ошибок, с которыми приходится иметь дело [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse): ошибки программиста и ошибки пользователя. Ошибки программиста – это обычно неверные вызовы [`OptionParser.add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option), например, некорректные строки опций, неизвестные атрибуты опций, отсутствующие атрибуты опций и т.д. Они обрабатываются обычным способом: возбуждается исключение (`optparse.OptionError` или [`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError)), и программа завершается аварийно.518519Обработка ошибок пользователя гораздо важнее, поскольку они гарантированно возникают независимо от стабильности кода. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) может автоматически обнаруживать некоторые ошибки пользователя, такие как неверные аргументы опций (передача `-n 4x`, когда `-n` принимает целочисленный аргумент), отсутствие аргументов (`-n` в конце командной строки, когда `-n` принимает аргумент любого типа). Кроме того, можно вызвать `OptionParser.error()` для сигнализации об ошибке, определённой приложением:520521```python522(options, args) = parser.parse_args()523...524if options.a and options.b:525    parser.error("options -a and -b are mutually exclusive")526```527528В любом случае [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) обрабатывает ошибку одинаково: выводит сообщение об использовании программы и сообщение об ошибке в стандартный поток ошибок и завершается с кодом ошибки 2.529530Рассмотрим первый пример выше, где пользователь передаёт `4x` опции, которая принимает целое число:531532```console533$ /usr/bin/foo -n 4x534Usage: foo [options]535536foo: error: option -n: invalid integer value: '4x'537```538539Или когда пользователь вообще не передаёт значение:540541```console542$ /usr/bin/foo -n543Usage: foo [options]544545foo: error: -n option requires an argument546```547548Сообщения об ошибках, сгенерированные [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), всегда содержат упоминание опции, вызвавшей ошибку; обязательно делайте то же самое при вызове `OptionParser.error()` из кода приложения.549550Если поведение обработки ошибок по умолчанию в [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) не соответствует требованиям, нужно создать подкласс OptionParser и переопределить его методы `exit()` и/или `error()`.551552### 36.1.2.9. Собираем всё вместе553554Вот как обычно выглядят скрипты на основе [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse):555556```python557from optparse import OptionParser558...559def main():560    usage = "usage: %prog [options] arg"561    parser = OptionParser(usage)562    parser.add_option("-f", "--file", dest="filename",563                      help="read data from FILENAME")564    parser.add_option("-v", "--verbose",565                      action="store_true", dest="verbose")566    parser.add_option("-q", "--quiet",567                      action="store_false", dest="verbose")568    ...569    (options, args) = parser.parse_args()570    if len(args) != 1:571        parser.error("incorrect number of arguments")572    if options.verbose:573        print("reading %s..." % options.filename)574    ...575576if __name__ == "__main__":577    main()578```579580## 36.1.3. Справочное руководство581582### 36.1.3.1. Создание парсера583584Первым шагом при использовании [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) является создание экземпляра OptionParser.585586#### `class optparse.OptionParser(...)`587588Конструктор OptionParser не требует обязательных аргументов, но принимает ряд необязательных именованных аргументов. Их всегда следует передавать как именованные аргументы, т.е. не полагаться на порядок объявления аргументов.589590**`usage` (по умолчанию: `"%prog [options]"`)**591592Краткая справка по использованию, выводимая при неправильном запуске программы или по запросу справки. Когда593594[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)595596выводит строку использования, он заменяет597598`%prog`599600на601602`os.path.basename(sys.argv[0])`603604(или на605606`prog`607608, если был передан соответствующий именованный аргумент). Чтобы отключить сообщение об использовании, передайте специальное значение609610`optparse.SUPPRESS_USAGE`611612.613614**`option_list` (по умолчанию: `[]`)**615616Список объектов Option для заполнения парсера. Опции из617618`option_list`619620добавляются после любых опций из621622`standard_option_list`623624(атрибута класса, который может быть установлен подклассами OptionParser), но перед опциями версии и справки. Устарело; вместо этого используйте625626[`add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option)627628после создания парсера.629630**`option_class` (по умолчанию: optparse.Option)**631632Класс, используемый при добавлении опций в парсер в633634[`add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option)635636.637638**`version` (по умолчанию: `None`)**639640Строка версии, выводимая по запросу опции версии. Если задать истинное значение для641642`version`643644,645646[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)647648автоматически добавляет опцию версии с единственной строкой опции649650`--version`651652. Подстрока653654`%prog`655656заменяется так же, как для657658`usage`659660.661662**`conflict_handler` (по умолчанию: `"error"`)**663664Определяет, что делать, когда в парсер добавляются опции с конфликтующими строками опций; см. раздел665666[Конфликты между опциями](https://python-all.ru/3.5/library/optparse.html#optparse-conflicts-between-options)667668.669670**`description` (по умолчанию: `None`)**671672Абзац текста с кратким обзором программы.673674[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)675676переформатирует этот абзац под текущую ширину терминала и выводит его по запросу справки (после677678`usage`679680, но перед списком опций).681682**`formatter` (по умолчанию: новый `IndentedHelpFormatter`)**683684Экземпляр optparse.HelpFormatter, используемый для вывода текста справки.685686[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)687688предоставляет два конкретных класса для этой цели: IndentedHelpFormatter и TitledHelpFormatter.689690**`add_help_option` (по умолчанию: `True`)**691692Если истина,693694[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)695696добавит в парсер опцию справки (со строками опций697698`-h`699700и701702`--help`703704).705706**`prog`**707708Строка, используемая при замене709710`%prog`711712в713714`usage`715716и717718`version`719720вместо721722`os.path.basename(sys.argv[0])`723724.725726**`epilog` (по умолчанию: `None`)**727728Абзац текста справки, выводимый после справки по опциям.729730### 36.1.3.2. Заполнение парсера731732Есть несколько способов заполнить парсер опциями. Предпочтительный способ – использовать [`OptionParser.add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option), как показано в разделе [Учебное пособие](https://python-all.ru/3.5/library/optparse.html#optparse-tutorial). `add_option()` можно вызывать одним из двух способов:733734- передать ему экземпляр Option (как возвращается `make_option()`)735- передать ему любую комбинацию позиционных и именованных аргументов, приемлемую для `make_option()` (т.е. для конструктора Option), и он создаст экземпляр Option автоматически736737Другой способ – передать список предварительно созданных экземпляров Option конструктору OptionParser, например:738739```python740option_list = [741    make_option("-f", "--filename",742                action="store", type="string", dest="filename"),743    make_option("-q", "--quiet",744                action="store_false", dest="verbose"),745    ]746parser = OptionParser(option_list=option_list)747```748749(`make_option()` – фабричная функция для создания экземпляров Option; в настоящее время это псевдоним конструктора Option. Будущая версия [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) может разделить Option на несколько классов, и `make_option()` будет выбирать нужный класс для создания экземпляра. Не создавайте экземпляры Option напрямую.)750751### 36.1.3.3. Определение опций752753Каждый экземпляр Option представляет набор синонимичных строк опций командной строки, например `-f` и `--file`. Можно указать любое количество коротких или длинных строк опций, но необходимо указать хотя бы одну общую строку опции.754755Канонический способ создания экземпляра `Option` – это метод `add_option()` объекта [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser).756757#### `OptionParser.add_option(option)`758759#### `OptionParser.add_option(*opt_str, attr=value, ...)`760761Для определения опции только с короткой строкой опции:762763```python764parser.add_option("-f", attr=value, ...)765```766767А для определения опции только с длинной строкой опции:768769```python770parser.add_option("--foo", attr=value, ...)771```772773Именованные аргументы определяют атрибуты нового объекта Option. Самый важный атрибут опции – [`action`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.action), и он в значительной степени определяет, какие другие атрибуты являются релевантными или обязательными. Если передать нерелевантные атрибуты опции или не указать обязательные, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) вызовет исключение `OptionError`, поясняющее ошибку.774775Атрибут *action* опции определяет, что делает [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), когда встречает эту опцию в командной строке. Стандартные действия опций, встроенные в [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse):776777**`"store"`**778779сохранить аргумент опции (по умолчанию)780781**`"store_const"`**782783сохранить константное значение784785**`"store_true"`**786787сохраняет истинное значение788789**`"store_false"`**790791сохраняет ложное значение792793**`"append"`**794795добавить аргумент этой опции в список796797**`"append_const"`**798799добавить константное значение в список800801**`"count"`**802803увеличить счётчик на единицу804805**`"callback"`**806807вызвать указанную функцию808809**`"help"`**810811вывести сообщение об использовании, включающее все опции и документацию к ним812813(Если не указать действие, по умолчанию используется `"store"`. Для этого действия можно также указать атрибуты опций [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest); см. [Стандартные действия опций](https://python-all.ru/3.5/library/optparse.html#optparse-standard-option-actions).)814815Как видите, большинство действий подразумевают сохранение или обновление значения где-либо. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) всегда создаёт для этого специальный объект, обычно называемый `options` (который является экземпляром `optparse.Values`). Аргументы опций (и различные другие значения) сохраняются как атрибуты этого объекта, согласно атрибуту опции [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) (назначение).816817Например, при вызове818819```python820parser.parse_args()821```822823одно из первых действий [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) – создание объекта `options`:824825```python826options = Values()827```828829Если одна из опций в этом анализаторе определена с помощью830831```python832parser.add_option("-f", "--file", action="store", type="string", dest="filename")833```834835и разбираемая командная строка включает любую из следующих:836837```python838-ffoo839-f foo840--file=foo841--file foo842```843844тогда [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), увидев эту опцию, сделает эквивалент845846```python847options.filename = "foo"848```849850Атрибуты опций [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) почти так же важны, как [`action`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.action), но [`action`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.action) – единственный, который имеет смысл для *всех* опций.851852### 36.1.3.4. Атрибуты опций853854Следующие атрибуты опций могут быть переданы как именованные аргументы в [`OptionParser.add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option). Если передать атрибут опции, который не является релевантным для конкретной опции, или не указать обязательный атрибут опции, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) вызовет `OptionError`.855856#### `Option.action`857858(по умолчанию: `"store"`)859860Determines [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)’s behaviour when this option is seen on the command line; the available options are documented [here](https://python-all.ru/3.5/library/optparse.html#optparse-standard-option-actions).861862#### `Option.type`863864(по умолчанию: `"string"`)865866The argument type expected by this option (e.g., `"string"` or `"int"`); the available option types are documented [here](https://python-all.ru/3.5/library/optparse.html#optparse-standard-option-types).867868#### `Option.dest`869870(по умолчанию: выводится из строк опций)871872Если действие опции подразумевает запись или изменение какого-либо значения, этот параметр указывает [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), куда его записать: [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) задаёт имя атрибута объекта `options`, который [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) создаёт по мере разбора командной строки.873874#### `Option.default`875876Значение, используемое для целевого атрибута этой опции, если опция не встречена в командной строке. См. также [`OptionParser.set_defaults()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.set_defaults).877878#### `Option.nargs`879880(по умолчанию: 1)881882Сколько аргументов типа [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) должно быть потреблено, когда эта опция встречена. Если \> 1, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) сохранит кортеж значений в [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest).883884#### `Option.const`885886Для действий, сохраняющих постоянное значение, – само это постоянное значение.887888#### `Option.choices`889890Для опций типа `"choice"` – список строк, из которых пользователь может выбирать.891892#### `Option.callback`893894For options with action `"callback"`, the callable to call when this option is seen. See section [Option Callbacks](https://python-all.ru/3.5/library/optparse.html#optparse-option-callbacks) for detail on the arguments passed to the callable.895896#### `Option.callback_args`897898#### `Option.callback_kwargs`899900Дополнительные позиционные и именованные аргументы, передаваемые в `callback` после четырёх стандартных аргументов колбэка.901902#### `Option.help`903904Текст справки для этой опции, выводимый при перечислении всех доступных опций после того, как пользователь укажет опцию [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help) (например, `--help`). Если текст справки не указан, опция будет выведена без него. Чтобы скрыть опцию, используйте специальное значение `optparse.SUPPRESS_HELP`.905906#### `Option.metavar`907908(по умолчанию: выводится из строк опций)909910Stand-in for the option argument(s) to use when printing help text. See section [Tutorial](https://python-all.ru/3.5/library/optparse.html#optparse-tutorial) for an example.911912### 36.1.3.5. Стандартные действия опций913914Различные действия опций имеют слегка разные требования и эффекты. У большинства действий есть несколько соответствующих атрибутов опции, которые вы можете указать, чтобы управлять поведением [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse); некоторые имеют обязательные атрибуты, которые необходимо указывать для любой опции, использующей это действие.915916- `"store"` \[относится: [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.choices)\]917918  The option must be followed by an argument, which is converted to a value according to [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) and stored in [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest). If [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs) \> 1, multiple arguments will be consumed from the command line; all will be converted according to [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) and stored to [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) as a tuple. See the [Standard option types](https://python-all.ru/3.5/library/optparse.html#optparse-standard-option-types) section.919920  Если указан [`choices`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.choices) (список или кортеж строк), тип по умолчанию `"choice"`.921922  Если [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) не указан, по умолчанию используется `"string"`.923924  Если [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) не указан, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) выводит destination из первой длинной строки опции (например, `--foo-bar` подразумевает `foo_bar`). Если длинных строк опций нет, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) выводит destination из первой короткой строки опции (например, `-f` подразумевает `f`).925926  Пример:927928  ```python929  parser.add_option("-f")930  parser.add_option("-p", type="float", nargs=3, dest="point")931  ```932933  В процессе разбора командной строки934935  ```python936  -f foo.txt -p 1 -3.5 4 -fbar.txt937  ```938939  [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) установит940941  ```python942  options.f = "foo.txt"943  options.point = (1.0, -3.5, 4.0)944  options.f = "bar.txt"945  ```946- `"store_const"` \[обязательно: [`const`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.const); относится: [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest)\]947948  Значение [`const`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.const) сохраняется в [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest).949950  Пример:951952  ```python953  parser.add_option("-q", "--quiet",954                    action="store_const", const=0, dest="verbose")955  parser.add_option("-v", "--verbose",956                    action="store_const", const=1, dest="verbose")957  parser.add_option("--noisy",958                    action="store_const", const=2, dest="verbose")959  ```960961  Если встречается `--noisy`, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) установит962963  ```python964  options.verbose = 2965  ```966- `"store_true"` \[относится: [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest)\]967968  Особый случай `"store_const"`, который сохраняет истинное значение в [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest).969- `"store_false"` \[относится: [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest)\]970971  Как и `"store_true"`, но сохраняет ложное значение.972973  Пример:974975  ```python976  parser.add_option("--clobber", action="store_true", dest="clobber")977  parser.add_option("--no-clobber", action="store_false", dest="clobber")978  ```979- `"append"` \[относится: [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.choices)\]980981  За опцией должен следовать аргумент, который добавляется в список [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest). Если значение по умолчанию для [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) не указано, пустой список автоматически создаётся, когда [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) впервые встречает эту опцию в командной строке. Если [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs) \> 1, потребляется несколько аргументов, и кортеж длины [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs) добавляется в [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest).982983  Значения по умолчанию для [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) такие же, как для действия `"store"`.984985  Пример:986987  ```python988  parser.add_option("-t", "--tracks", action="append", type="int")989  ```990991  Если в командной строке встречается `-t3`, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) делает то же самое, что:992993  ```python994  options.tracks = []995  options.tracks.append(int("3"))996  ```997998  Если чуть позже встречается `--tracks=4`, выполняется:9991000  ```python1001  options.tracks.append(int("4"))1002  ```10031004  Действие `append` вызывает метод `append` для текущего значения опции. Это означает, что любое указанное значение по умолчанию должно иметь метод `append`. Это также означает, что если значение по умолчанию непустое, элементы по умолчанию будут присутствовать в разобранном значении для опции, а любые значения из командной строки будут добавлены после этих значений по умолчанию:10051006  ```python1007  >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])1008  >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])1009  >>> opts.files1010  ['~/.mypkg/defaults', 'overrides.mypkg']1011  ```1012- `"append_const"` \[обязательно: [`const`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.const); относится: [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest)\]10131014  Как `"store_const"`, но значение [`const`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.const) добавляется в [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest); как и в `"append"`, [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) по умолчанию равен `None`, и пустой список автоматически создаётся при первом обнаружении опции.1015- `"count"` \[относится: [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest)\]10161017  Увеличивает целое число, хранящееся в [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest). Если значение по умолчанию не указано, [`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest) устанавливается в ноль перед первым увеличением.10181019  Пример:10201021  ```python1022  parser.add_option("-v", action="count", dest="verbosity")1023  ```10241025  При первом появлении `-v` в командной строке [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) делает то же самое, что:10261027  ```python1028  options.verbosity = 01029  options.verbosity += 11030  ```10311032  Каждое последующее появление `-v` приводит к10331034  ```python1035  options.verbosity += 11036  ```1037- `"callback"` \[обязательно: [`callback`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback); относится: [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type), [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs), [`callback_args`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_args), [`callback_kwargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_kwargs)\]10381039  Вызывает функцию, указанную в [`callback`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback), которая вызывается как10401041  ```python1042  func(option, opt_str, value, parser, *args, **kwargs)1043  ```10441045  Смотрите раздел [Колбэки опций](https://python-all.ru/3.5/library/optparse.html#optparse-option-callbacks) для подробностей.1046- `"help"`10471048  Выводит полное справочное сообщение для всех опций текущего парсера опций. Справочное сообщение формируется из строки `usage`, переданной конструктору OptionParser, и строки [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help), переданной каждой опции.10491050  Если для опции не указана строка [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help), она всё равно будет перечислена в справочном сообщении. Чтобы полностью исключить опцию, используйте специальное значение `optparse.SUPPRESS_HELP`.10511052  [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) автоматически добавляет опцию [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help) для всех объектов OptionParser, поэтому обычно не требуется создавать его отдельно.10531054  Пример:10551056  ```python1057  from optparse import OptionParser, SUPPRESS_HELP10581059  # обычно опция справки добавляется автоматически, но её можно1060  # подавить, используя аргумент add_help_option1061  parser = OptionParser(add_help_option=False)10621063  parser.add_option("-h", "--help", action="help")1064  parser.add_option("-v", action="store_true", dest="verbose",1065                    help="Be moderately verbose")1066  parser.add_option("--file", dest="filename",1067                    help="Input file to read data from")1068  parser.add_option("--secret", help=SUPPRESS_HELP)1069  ```10701071  Если [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) обнаруживает в командной строке `-h` или `--help`, он выводит примерно такое справочное сообщение в stdout (при условии, что `sys.argv[0]` равно `"foo.py"`):10721073  ```text1074  Usage: foo.py [options]10751076  Options:1077    -h, --help        Show this help message and exit1078    -v                Be moderately verbose1079    --file=FILENAME   Input file to read data from1080  ```10811082  После вывода справочного сообщения [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) завершает процесс с кодом `sys.exit(0)`.1083- `"version"`10841085  Выводит номер версии, переданный OptionParser, в stdout и завершает работу. Номер версии форматируется и выводится методом `print_version()` объекта OptionParser. Обычно актуально только если аргумент `version` передан конструктору OptionParser. Как и для опций [`help`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.help), `version` редко создаются вручную, так как [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) добавляет их автоматически при необходимости.10861087### 36.1.3.6. Стандартные типы опций10881089[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) содержит пять встроенных типов опций: `"string"`, `"int"`, `"choice"`, `"float"` и `"complex"`. Если требуется добавить новые типы опций, см. раздел [Расширение optparse](https://python-all.ru/3.5/library/optparse.html#optparse-extending-optparse).10901091Аргументы строковых опций никак не проверяются и не преобразуются: текст из командной строки сохраняется в целевом атрибуте (или передаётся колбэку) как есть.10921093Целочисленные аргументы (тип `"int"`) разбираются следующим образом:10941095- если число начинается с `0x`, оно разбирается как шестнадцатеричное1096- если число начинается с `0`, оно разбирается как восьмеричное1097- если число начинается с `0b`, оно разбирается как двоичное1098- в противном случае число разбирается как десятичное10991100Преобразование выполняется вызовом [`int()`](https://python-all.ru/3.5/library/functions.html#int) с соответствующим основанием (2, 8, 10 или 16). В случае неудачи так же поступит и [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), хотя и с более полезным сообщением об ошибке.11011102Аргументы опций `"float"` и `"complex"` преобразуются напрямую с помощью [`float()`](https://python-all.ru/3.5/library/functions.html#float) и [`complex()`](https://python-all.ru/3.5/library/functions.html#complex), с аналогичной обработкой ошибок.11031104Опции `"choice"` являются подтипом опций `"string"`. Атрибут опции [`choices`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.choices) (последовательность строк) определяет набор допустимых аргументов опции. `optparse.check_choice()` сравнивает предоставленные пользователем аргументы опции с этим основным списком и возбуждает `OptionValueError`, если указана недопустимая строка.11051106### 36.1.3.7. Разбор аргументов11071108Весь смысл создания и заполнения OptionParser заключается в вызове его метода `parse_args()`:11091110```python1111(options, args) = parser.parse_args(args=None, values=None)1112```11131114где входные параметры:11151116**`args`**11171118список аргументов для обработки (по умолчанию:11191120`sys.argv[1:]`11211122)11231124**`values`**11251126объект11271128`optparse.Values`11291130для хранения аргументов параметров (по умолчанию: новый экземпляр11311132`Values`11331134) – если передать существующий объект, значения параметров по умолчанию не будут в нем инициализированы11351136а возвращаемые значения –11371138**`options`**11391140тот же объект, который был передан как11411142`values`11431144, или экземпляр optparse.Values, созданный11451146[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)11471148**`args`**11491150оставшиеся позиционные аргументы после обработки всех опций11511152Наиболее распространённый способ использования – не указывать ни один из именованных аргументов. Если передать `values`, он будет изменён многократными вызовами [`setattr()`](https://python-all.ru/3.5/library/functions.html#setattr) (примерно по одному на каждый аргумент опции, сохраняемый в целевой атрибут) и возвращён `parse_args()`.11531154Если `parse_args()` обнаруживает ошибки в списке аргументов, он вызывает метод `error()` объекта OptionParser с подходящим сообщением об ошибке для конечного пользователя. В итоге процесс завершается с кодом возврата 2 (традиционный код выхода Unix для ошибок командной строки).11551156### 36.1.3.8. Запросы и управление анализатором опций11571158Поведение парсера опций по умолчанию можно слегка настроить, а также можно заглянуть внутрь парсера и посмотреть, что там есть. OptionParser предоставляет несколько методов, которые в этом помогут:11591160#### `OptionParser.disable_interspersed_args()`11611162Настраивает разбор на остановку при первом не-опции. Например, если `-a` и `-b` – простые опции, не принимающие аргументов, [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) обычно принимает такой синтаксис:11631164```python1165prog -a arg1 -b arg21166```11671168и обрабатывает его как эквивалент11691170```python1171prog -a -b arg1 arg21172```11731174Чтобы отключить эту возможность, вызовите [`disable_interspersed_args()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.disable_interspersed_args). Это восстанавливает традиционный синтаксис Unix, где разбор опций останавливается на первом аргументе, не являющемся опцией.11751176Используйте это, если у вас есть обработчик команд, который запускает другую команду с собственными опциями, и нужно гарантировать, что эти опции не будут перепутаны. Например, каждая команда может иметь свой набор опций.11771178#### `OptionParser.enable_interspersed_args()`11791180Настраивает разбор на то, чтобы не останавливаться на первом не-опции, позволяя перемешивать ключи с аргументами команды. Это поведение по умолчанию.11811182#### `OptionParser.get_option(opt_str)`11831184Возвращает экземпляр Option с строкой опции *opt\_str* или `None`, если ни одна опция не имеет такой строки.11851186#### `OptionParser.has_option(opt_str)`11871188Возвращает True, если OptionParser имеет опцию со строкой опции *opt\_str* (например, `-q` или `--verbose`).11891190#### `OptionParser.remove_option(opt_str)`11911192Если [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser) имеет опцию, соответствующую *opt\_str*, эта опция удаляется. Если эта опция предоставляла какие-либо другие строки опций, все эти строки опций становятся недействительными. Если *opt\_str* не встречается ни в одной опции, принадлежащей этому [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser), возбуждается [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError).11931194### 36.1.3.9. Конфликты между опциями11951196Если быть невнимательным, легко определить опции с конфликтующими строками опций:11971198```python1199parser.add_option("-n", "--dry-run", ...)1200...1201parser.add_option("-n", "--noisy", ...)1202```12031204(Это особенно актуально, если определён собственный подкласс OptionParser с некоторыми стандартными опциями.)12051206При каждом добавлении опции [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) проверяет наличие конфликтов с существующими опциями. Если они обнаружены, вызывается текущий механизм обработки конфликтов. Механизм обработки конфликтов можно задать либо в конструкторе:12071208```python1209parser = OptionParser(..., conflict_handler=handler)1210```12111212или отдельным вызовом:12131214```python1215parser.set_conflict_handler(handler)1216```12171218Доступные обработчики конфликтов:12191220> **`"error"` (по умолчанию)**1221>1222> считать конфликты опций программной ошибкой и возбуждать1223>1224> `OptionConflictError`1225>1226> **`"resolve"`**1227>1228> разрешать конфликты опций интеллектуально (см. ниже)12291230В качестве примера определим [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser), который разрешает конфликты интеллектуально, и добавим к нему конфликтующие опции:12311232```python1233parser = OptionParser(conflict_handler="resolve")1234parser.add_option("-n", "--dry-run", ..., help="do no harm")1235parser.add_option("-n", "--noisy", ..., help="be noisy")1236```12371238На этом этапе [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) обнаруживает, что ранее добавленная опция уже использует строку опции `-n`. Поскольку `conflict_handler` является `"resolve"`, он разрешает ситуацию, удаляя `-n` из списка строк опций более ранней опции. Теперь `--dry-run` – единственный способ для пользователя активировать эту опцию. Если пользователь запросит справку, сообщение справки отразит это:12391240```python1241Options:1242  --dry-run     do no harm1243  ...1244  -n, --noisy   be noisy1245```12461247Можно сокращать строки опций для ранее добавленной опции до тех пор, пока их не останется, и у пользователя не будет способа вызвать эту опцию из командной строки. В этом случае [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) полностью удаляет эту опцию, так что она не появляется в тексте справки или где-либо ещё. Продолжая с нашим существующим OptionParser:12481249```python1250parser.add_option("--dry-run", ..., help="new dry-run option")1251```12521253На этом этапе исходная опция `-n`/`--dry-run` больше не доступна, поэтому [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) удаляет её, оставляя такой текст справки:12541255```python1256Options:1257  ...1258  -n, --noisy   be noisy1259  --dry-run     new dry-run option1260```12611262### 36.1.3.10. Очистка12631264Экземпляры OptionParser содержат несколько циклических ссылок. Это не должно быть проблемой для сборщика мусора Python, но можно явно разорвать циклические ссылки, вызвав `destroy()` для вашего OptionParser после завершения работы с ним. Это особенно полезно в долго работающих приложениях, где из OptionParser достижимы большие графы объектов.12651266### 36.1.3.11. Другие методы12671268OptionParser поддерживает несколько других открытых методов:12691270#### `OptionParser.set_usage(usage)`12711272Устанавливает строку использования в соответствии с правилами, описанными выше для аргумента конструктора `usage`. Передача `None` устанавливает строку использования по умолчанию; используйте `optparse.SUPPRESS_USAGE`, чтобы подавить сообщение об использовании.12731274#### `OptionParser.print_usage(file=None)`12751276Выводит сообщение об использовании для текущей программы (`self.usage`) в *file* (по умолчанию stdout). Любое вхождение строки `%prog` в `self.usage` заменяется именем текущей программы. Ничего не делает, если `self.usage` пусто или не определено.12771278#### `OptionParser.get_usage()`12791280То же, что и [`print_usage()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.print_usage), но возвращает строку использования вместо её вывода.12811282#### `OptionParser.set_defaults(dest=value, ...)`12831284Устанавливает значения по умолчанию для нескольких целевых параметров опций одновременно. Использование [`set_defaults()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.set_defaults) является предпочтительным способом установки значений по умолчанию для опций, поскольку несколько опций могут совместно использовать один и тот же целевой параметр. Например, если несколько опций «режим» устанавливают один и тот же целевой параметр, любая из них может задать значение по умолчанию, и последняя имеет преимущество:12851286```python1287parser.add_option("--advanced", action="store_const",1288                  dest="mode", const="advanced",1289                  default="novice")    # переопределено ниже1290parser.add_option("--novice", action="store_const",1291                  dest="mode", const="novice",1292                  default="advanced")  # переопределяет вышеуказанную настройку1293```12941295Чтобы избежать этой путаницы, используйте [`set_defaults()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.set_defaults):12961297```python1298parser.set_defaults(mode="advanced")1299parser.add_option("--advanced", action="store_const",1300                  dest="mode", const="advanced")1301parser.add_option("--novice", action="store_const",1302                  dest="mode", const="novice")1303```13041305## 36.1.4. Колбэки опций13061307Когда встроенных действий и типов [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) недостаточно, есть два варианта: расширить [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) или определить опцию-колбэк. Расширение [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) более универсально, но для многих простых случаев избыточно. Зачастую простого колбэка вполне достаточно.13081309Определение опции-колбэка состоит из двух шагов:13101311- определить саму опцию с помощью действия `"callback"`1312- написать колбэк – функцию (или метод), которая принимает как минимум четыре аргумента, как описано ниже13131314### 36.1.4.1. Определение опции с колбэком13151316Как всегда, проще всего определить опцию-колбэк с помощью метода [`OptionParser.add_option()`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser.add_option). Кроме [`action`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.action), единственный атрибут опции, который необходимо указать, – это `callback`, вызываемая функция:13171318```python1319parser.add_option("-c", action="callback", callback=my_callback)1320```13211322`callback` – это функция (или другой вызываемый объект), поэтому к моменту создания опции-колбэка `my_callback()` должна быть уже определена. В этом простом случае [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) даже не знает, принимает ли `-c` какие-либо аргументы, что обычно означает, что опция не принимает аргументов – достаточно одного присутствия `-c` в командной строке. Однако в некоторых ситуациях может потребоваться, чтобы колбэк обрабатывал произвольное количество аргументов командной строки. Здесь написание колбэков становится сложнее; об этом рассказывается далее в этом разделе.13231324[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) всегда передаёт колбэку четыре определённых аргумента и передаёт дополнительные, только если они указаны через [`callback_args`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_args) и [`callback_kwargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_kwargs). Таким образом, минимальная сигнатура функции колбэка выглядит так:13251326```python1327def my_callback(option, opt, value, parser):1328```13291330Четыре аргумента колбэка описаны ниже.13311332Есть ещё несколько атрибутов опции, которые можно указать при определении опции-колбэка:13331334**[`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type)**13351336имеет обычный смысл: как и действия13371338`"store"`13391340или13411342`"append"`13431344, он указывает13451346[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)13471348потребить один аргумент и преобразовать его в13491350[`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type)13511352. Однако вместо сохранения преобразованного значения где-либо,13531354[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)13551356передаёт его функции колбэка.13571358**[`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs)**13591360также имеет обычный смысл: если он указан и больше 1,13611362[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)13631364потребит13651366[`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs)13671368аргументов, каждый из которых должен быть преобразуем в13691370[`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type)13711372. Затем он передаёт колбэку кортеж преобразованных значений.13731374**[`callback_args`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_args)**13751376кортеж дополнительных позиционных аргументов, передаваемых колбэку13771378**[`callback_kwargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_kwargs)**13791380словарь дополнительных именованных аргументов, передаваемых колбэку13811382### 36.1.4.2. Как вызываются колбэки13831384Все колбэки вызываются следующим образом:13851386```python1387func(option, opt_str, value, parser, *args, **kwargs)1388```13891390где13911392**`option`**13931394это экземпляр Option, который вызывает колбэк13951396**`opt_str`**13971398это строка опции, указанная в командной строке, которая запускает колбэк. (Если использовалась сокращённая длинная опция,13991400`opt_str`14011402будет полной канонической строкой опции – например, если пользователь ввёл14031404`--foo`14051406в командной строке как сокращение для14071408`--foobar`14091410, то14111412`opt_str`14131414будет14151416`"--foobar"`14171418.)14191420**`value`**14211422это аргумент данной опции, указанный в командной строке.14231424[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)14251426будет ожидать аргумент, только если установлен14271428[`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type)14291430; тип14311432`value`14331434будет типом, подразумеваемым типом опции. Если14351436[`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type)14371438для этой опции равно14391440`None`14411442(аргумент не ожидается), то14431444`value`14451446будет14471448`None`14491450. Если14511452[`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs)14531454\> 1,14551456`value`14571458будет кортежем значений соответствующего типа.14591460**`parser`**14611462это экземпляр OptionParser, управляющий всем процессом; он полезен тем, что через его атрибуты можно получить доступ к некоторым другим интересным данным:14631464**`parser.largs`**14651466текущий список оставшихся аргументов, то есть аргументов, которые были потреблены, но не являются ни опциями, ни аргументами опций.14671468`parser.largs`14691470можно изменять, например, добавляя в него новые аргументы. (Этот список станет14711472`args`14731474, вторым возвращаемым значением14751476`parse_args()`14771478.)14791480**`parser.rargs`**14811482текущий список оставшихся аргументов, то есть после удаления14831484`opt_str`14851486и14871488`value`14891490(если применимо), в котором остались только следующие за ними аргументы.14911492`parser.rargs`14931494можно изменять, например, потребляя дополнительные аргументы.14951496**`parser.values`**14971498объект, в котором по умолчанию хранятся значения опций (экземпляр optparse.OptionValues). Это позволяет колбэкам использовать тот же механизм хранения значений опций, что и остальная часть14991500[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)15011502; не нужно возиться с глобальными переменными или замыканиями. Также можно получать или изменять значения любых опций, уже встреченных в командной строке.15031504**`args`**15051506это кортеж произвольных позиционных аргументов, переданных через атрибут опции15071508[`callback_args`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_args)15091510.15111512**`kwargs`**15131514это словарь произвольных именованных аргументов, переданных через15151516[`callback_kwargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.callback_kwargs)15171518.15191520### 36.1.4.3. Возбуждение ошибок в колбэке15211522Функция колбэка должна возбуждать `OptionValueError` при любых проблемах с опцией или её аргументами. [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) перехватывает это исключение и завершает программу, выводя сообщение об ошибке, которое вы передаёте, в stderr. Сообщение должно быть ясным, кратким, точным и содержать указание на вызвавшую проблему опцию. В противном случае пользователю будет сложно понять, что он сделал неправильно.15231524### 36.1.4.4. Пример колбэка 1: простейший колбэк15251526Вот пример опции-колбэка, которая не принимает аргументов и просто записывает факт своего появления:15271528```python1529def record_foo_seen(option, opt_str, value, parser):1530    parser.values.saw_foo = True15311532parser.add_option("--foo", action="callback", callback=record_foo_seen)1533```15341535Конечно, это можно было бы сделать с помощью действия `"store_true"`.15361537### 36.1.4.5. Пример колбэка 2: проверка порядка опций15381539Вот чуть более интересный пример: запоминать, что `-a` был замечен, но завершаться с ошибкой, если он встречается после `-b` в командной строке.15401541```python1542def check_order(option, opt_str, value, parser):1543    if parser.values.b:1544        raise OptionValueError("can't use -a after -b")1545    parser.values.a = 11546...1547parser.add_option("-a", action="callback", callback=check_order)1548parser.add_option("-b", action="store_true", dest="b")1549```15501551### 36.1.4.6. Пример колбэка 3: проверка порядка опций (обобщённая)15521553Если требуется повторно использовать этот колбэк для нескольких похожих опций (устанавливать флаг, но выдавать ошибку, если `-b` уже был обработан), потребуется доработка: сообщение об ошибке и устанавливаемый флаг должны быть обобщены.15541555```python1556def check_order(option, opt_str, value, parser):1557    if parser.values.b:1558        raise OptionValueError("can't use %s after -b" % opt_str)1559    setattr(parser.values, option.dest, 1)1560...1561parser.add_option("-a", action="callback", callback=check_order, dest='a')1562parser.add_option("-b", action="store_true", dest="b")1563parser.add_option("-c", action="callback", callback=check_order, dest='c')1564```15651566### 36.1.4.7. Пример колбэка 4: проверка произвольного условия15671568Конечно, можно задать любое условие – вы не ограничены проверкой значений уже определённых параметров. Например, если есть параметры, которые не должны вызываться в полнолуние, достаточно сделать так:15691570```python1571def check_moon(option, opt_str, value, parser):1572    if is_moon_full():1573        raise OptionValueError("%s option invalid when moon is full"1574                               % opt_str)1575    setattr(parser.values, option.dest, 1)1576...1577parser.add_option("--foo",1578                  action="callback", callback=check_moon, dest="foo")1579```15801581(Определение `is_moon_full()` оставляется читателю в качестве упражнения.)15821583### 36.1.4.8. Пример колбэка 5: фиксированные аргументы15841585Ситуация становится немного интереснее, когда определяется параметр-колбэк с фиксированным числом аргументов. Указание, что параметр-колбэк принимает аргументы, аналогично определению параметра `"store"` или `"append"`: если задано [`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type), то параметр принимает один аргумент, который должен быть преобразуем к этому типу; если дополнительно задано [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs), то параметр принимает [`nargs`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.nargs) аргументов.15861587Вот пример, который просто эмулирует стандартное действие `"store"`:15881589```python1590def store_value(option, opt_str, value, parser):1591    setattr(parser.values, option.dest, value)1592...1593parser.add_option("--foo",1594                  action="callback", callback=store_value,1595                  type="int", nargs=3, dest="foo")1596```15971598Обратите внимание, что [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) сам заботится о потреблении 3 аргументов и преобразовании их в целые числа; остаётся только сохранить их. (Или что угодно; очевидно, для этого примера колбэк не нужен.)15991600### 36.1.4.9. Пример колбэка 6: переменные аргументы16011602Всё становится сложнее, когда требуется, чтобы параметр принимал переменное число аргументов. В этом случае нужно писать колбэк, так как [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) не предоставляет встроенных средств для этого. И придётся разбираться с определёнными тонкостями традиционного разбора командной строки Unix, которые [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) обычно обрабатывает автоматически. В частности, колбэки должны реализовывать обычные правила для голых аргументов `--` и `-`:16031604- как `--`, так и `-` могут быть аргументами параметра1605- голый `--` (если не является аргументом какого-либо параметра): остановить обработку командной строки и отбросить `--`1606- голый `-` (если не является аргументом какого-либо параметра): остановить обработку командной строки, но сохранить `-` (добавить его к `parser.largs`)16071608Если нужен параметр, принимающий переменное число аргументов, возникает несколько тонких и сложных моментов. Конкретная реализация будет зависеть от того, на какие компромиссы вы готовы пойти для своего приложения (именно поэтому [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) не поддерживает такое напрямую).16091610Тем не менее, вот пример попытки создать колбэк для параметра с переменным числом аргументов:16111612```python1613def vararg_callback(option, opt_str, value, parser):1614    assert value is None1615    value = []16161617    def floatable(str):1618        try:1619            float(str)1620            return True1621        except ValueError:1622            return False16231624    for arg in parser.rargs:1625        # останавливаться на опциях вида --foo1626        if arg[:2] == "--" and len(arg) > 2:1627            break1628        # останавливаться на -a, но не на -3 или -3.01629        if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):1630            break1631        value.append(arg)16321633    del parser.rargs[:len(value)]1634    setattr(parser.values, option.dest, value)16351636...1637parser.add_option("-c", "--callback", dest="vararg_attr",1638                  action="callback", callback=vararg_callback)1639```16401641## 36.1.5. Расширение [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)16421643Поскольку двумя основными управляющими факторами того, как [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) интерпретирует параметры командной строки, являются действие и тип каждого параметра, наиболее вероятное направление расширения – добавление новых действий и новых типов.16441645### 36.1.5.1. Добавление новых типов16461647Чтобы добавить новые типы, нужно определить собственный подкласс класса `Option` из [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse). У этого класса есть пара атрибутов, определяющих типы [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse): [`TYPES`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPES) и [`TYPE_CHECKER`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPE_CHECKER).16481649#### `Option.TYPES`16501651Кортеж имён типов; в своём подклассе просто определите новый кортеж [`TYPES`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPES), основанный на стандартном.16521653#### `Option.TYPE_CHECKER`16541655Словарь, отображающий имена типов в функции проверки типа. Функция проверки типа имеет следующую сигнатуру:16561657```python1658def check_mytype(option, opt, value)1659```16601661где `option` – это экземпляр `Option`, `opt` – строка параметра (например, `-f`), а `value` – строка из командной строки, которую нужно проверить и преобразовать в желаемый тип. `check_mytype()` должна возвращать объект гипотетического типа `mytype`. Значение, возвращаемое функцией проверки типа, окажется в экземпляре OptionValues, возвращаемом `OptionParser.parse_args()`, или будет передано колбэку как параметр `value`.16621663Функция проверки типа должна возбуждать `OptionValueError` при возникновении проблем. `OptionValueError` принимает единственный строковый аргумент, который передаётся как есть методу `error()` объекта [`OptionParser`](https://python-all.ru/3.5/library/optparse.html#optparse.OptionParser), который, в свою очередь, добавляет имя программы и строку `"error:"` и печатает всё в stderr перед завершением процесса.16641665Вот глуповатый пример, демонстрирующий добавление типа параметра `"complex"` для разбора комплексных чисел в стиле Python в командной строке. (Этот пример стал ещё глупее, чем был, потому что в [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) 1.3 добавлена встроенная поддержка комплексных чисел, но не будем обращать внимания.)16661667Сначала необходимые импорты:16681669```python1670from copy import copy1671from optparse import Option, OptionValueError1672```16731674Сначала нужно определить проверщик типов, так как на него будет ссылка позже (в атрибуте класса [`TYPE_CHECKER`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPE_CHECKER) вашего подкласса Option):16751676```python1677def check_complex(option, opt, value):1678    try:1679        return complex(value)1680    except ValueError:1681        raise OptionValueError(1682            "option %s: invalid complex value: %r" % (opt, value))1683```16841685Наконец, подкласс Option:16861687```python1688class MyOption (Option):1689    TYPES = Option.TYPES + ("complex",)1690    TYPE_CHECKER = copy(Option.TYPE_CHECKER)1691    TYPE_CHECKER["complex"] = check_complex1692```16931694(Если бы мы не создали [`copy()`](https://python-all.ru/3.5/library/copy.html#module-copy) для [`Option.TYPE_CHECKER`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPE_CHECKER), мы бы в итоге изменили атрибут [`TYPE_CHECKER`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPE_CHECKER) класса Option из [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse). Поскольку это Python, ничто не мешает это сделать, кроме хороших манер и здравого смысла.)16951696Вот и всё! Теперь можно написать скрипт, использующий новый тип опции, точно так же, как и любой другой скрипт на основе [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse), за исключением того, что нужно указать своему OptionParser использовать MyOption вместо Option:16971698```python1699parser = OptionParser(option_class=MyOption)1700parser.add_option("-c", type="complex")1701```17021703Либо можно собрать собственный список опций и передать его в OptionParser; если не использовать `add_option()` описанным выше способом, не требуется сообщать OptionParser, какой класс опции использовать:17041705```python1706option_list = [MyOption("-c", action="store", type="complex", dest="c")]1707parser = OptionParser(option_list=option_list)1708```17091710### 36.1.5.2. Добавление новых действий17111712Добавление новых действий немного сложнее, потому что нужно понимать, что [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) разделяет действия на несколько категорий:17131714**«store»-действия**17151716действия, в результате которых17171718[`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse)17191720сохраняет значение в атрибут текущего экземпляра OptionValues; для таких опций в конструктор Option требуется передать атрибут17211722[`dest`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.dest)17231724.17251726**«typed»-действия**17271728действия, которые берут значение из командной строки и ожидают, что оно будет определённого типа; точнее, ожидают строку, которую можно преобразовать в заданный тип. Для таких опций в конструктор Option требуется передать атрибут17291730[`type`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.type)17311732.17331734Это пересекающиеся множества: к стандартным «store»-действиям относятся `"store"`, `"store_const"`, `"append"` и `"count"`, а к стандартным «typed»-действиям – `"store"`, `"append"` и `"callback"`.17351736При добавлении действия его нужно отнести к категории, включив как минимум в один из следующих атрибутов класса Option (все они являются списками строк):17371738#### `Option.ACTIONS`17391740Все действия должны быть перечислены в ACTIONS.17411742#### `Option.STORE_ACTIONS`17431744«store»-действия дополнительно перечисляются здесь.17451746#### `Option.TYPED_ACTIONS`17471748«typed»-действия дополнительно перечисляются здесь.17491750#### `Option.ALWAYS_TYPED_ACTIONS`17511752Действия, которые всегда принимают тип (то есть их опции всегда получают значение), дополнительно перечисляются здесь. Единственный эффект этого состоит в том, что [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) назначает тип по умолчанию `"string"` опциям без явно указанного типа, чьё действие перечислено в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).17531754Чтобы реализовать новое действие, нужно переопределить метод `take_action()` класса Option и добавить ветвь, распознающую это действие.17551756Например, добавим действие `"extend"`. Оно похоже на стандартное `"append"`, но вместо того, чтобы взять из командной строки одно значение и добавить его в конец существующего списка, `"extend"` принимает несколько значений в одной строке с разделителями-запятыми и расширяет ими существующий список. То есть, если `--names` является опцией `"extend"` с типом `"string"`, то командная строка17571758```python1759--names=foo,bar --names blah --names ding,dong1760```17611762приведёт к списку17631764```python1765["foo", "bar", "blah", "ding", "dong"]1766```17671768Снова определим подкласс Option:17691770```python1771class MyOption(Option):17721773    ACTIONS = Option.ACTIONS + ("extend",)1774    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)1775    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)1776    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)17771778    def take_action(self, action, dest, opt, value, values, parser):1779        if action == "extend":1780            lvalue = value.split(",")1781            values.ensure_value(dest, []).extend(lvalue)1782        else:1783            Option.take_action(1784                self, action, dest, opt, value, values, parser)1785```17861787Что следует отметить:17881789- `"extend"` одновременно ожидает значение в командной строке и сохраняет его, поэтому попадает как в [`STORE_ACTIONS`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.STORE_ACTIONS), так и в [`TYPED_ACTIONS`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.TYPED_ACTIONS).1790- чтобы [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse) назначал тип по умолчанию `"string"` действиям `"extend"`, мы помещаем действие `"extend"` также в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.5/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).1791- `MyOption.take_action()` реализует только это одно новое действие и передаёт управление обратно `Option.take_action()` для стандартных действий [`optparse`](https://python-all.ru/3.5/library/optparse.html#module-optparse).1792- `values` – это экземпляр класса optparse\_parser.Values, предоставляющий очень полезный метод `ensure_value()`. `ensure_value()` – это по сути [`getattr()`](https://python-all.ru/3.5/library/functions.html#getattr) с предохранительным клапаном; он вызывается как17931794  ```python1795  values.ensure_value(attr, value)1796  ```17971798  Если атрибут `attr` объекта `values` не существует или равен `None`, то ensure\_value() сначала устанавливает его в `value`, а затем возвращает значение. Это очень удобно для действий вроде `"extend"`, `"append"` и `"count"`, все из которых накапливают данные в переменной и ожидают, что переменная будет определённого типа (список для первых двух, целое число для последнего). Использование `ensure_value()` означает, что сценарии, использующие ваше действие, могут не беспокоиться об установке значения по умолчанию для соответствующих мест назначения опций; они могут просто оставить значение по умолчанию равным `None`, и `ensure_value()` позаботится о том, чтобы всё было правильно, когда это потребуется.1799