> **Источник:** https://python-all.ru/3.1/library/optparse.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 15.4. `optparse` – более мощный парсер опций командной строки

`optparse` – это более удобная, гибкая и мощная библиотека для разбора опций командной строки, чем старый модуль [`getopt`](https://python-all.ru/3.1/library/getopt.html#module-getopt). `optparse` использует более декларативный стиль разбора командной строки: создаётся экземпляр [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser), заполняется опциями, и разбирается командная строка. `optparse` позволяет пользователям задавать опции в общепринятом синтаксисе GNU/POSIX, а также автоматически генерирует сообщения об использовании и справку.

Вот пример использования `optparse` в простом скрипте:

```python
from optparse import OptionParser
[...]
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=True,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()
```

С помощью этих нескольких строк кода пользователи вашего скрипта теперь могут делать «обычные вещи» в командной строке, например:

```python
<yourscript> --file=outfile -q
```

При разборе командной строки `optparse` устанавливает атрибуты объекта `options`, возвращаемого функцией `parse_args()`, на основе введённых пользователем значений командной строки. Когда `parse_args()` завершает разбор этой командной строки, `options.filename` будет равен `"outfile"`, а `options.verbose` – `False`. `optparse` поддерживает как длинные, так и короткие опции, позволяет объединять короткие опции и связывать опции с их аргументами различными способами. Таким образом, все следующие командные строки эквивалентны приведённому выше примеру:

```python
<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile
```

Кроме того, можно запустить один из

```python
<yourscript> -h
<yourscript> --help
```

и `optparse` выведет краткую сводку опций вашего скрипта:

```text
Usage: <yourscript> [options]

Options:
  -h, --help            show this help message and exit
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout
```

где значение *yourscript* определяется во время выполнения (обычно из `sys.argv[0]`).

## 15.4.1. Предыстория

`optparse` был разработан специально для поощрения создания программ с простыми и общепринятыми интерфейсами командной строки. Для этого он поддерживает только наиболее распространённый синтаксис и семантику командной строки, традиционно используемые в Unix. Если вы не знакомы с этими соглашениями, прочтите этот раздел, чтобы ознакомиться с ними.

### 15.4.1.1. Терминология

**аргумент**

строка, введённая в командной строке и переданная оболочкой в `execl()` или `execv()`. В Python аргументы являются элементами `sys.argv[1:]` (`sys.argv[0]` – это имя выполняемой программы). В оболочках Unix также используется термин «слово».

Иногда требуется подставить список аргументов, отличный от `sys.argv[1:]`, поэтому следует понимать «аргумент» как «элемент `sys.argv[1:]` или какого-либо другого списка, предоставленного вместо `sys.argv[1:]`».

**опция**

аргумент, используемый для предоставления дополнительной информации, направляющей или настраивающей выполнение программы. Существует много разных синтаксисов для опций; традиционный синтаксис Unix – дефис («-»), за которым следует одна буква, например `-x` или `-F`. Кроме того, традиционный синтаксис Unix позволяет объединять несколько опций в один аргумент, например `-x -F` эквивалентно `-xF`. Проект GNU ввёл `--`, за которым следует серия слов, разделённых дефисами, например `--file` или `--dry-run`. Это единственные два синтаксиса опций, поддерживаемые `optparse`.

Некоторые другие синтаксисы опций, которые встречались в мире, включают:

- дефис, за которым следует несколько букв, например `-pf` (это *не* то же самое, что объединение нескольких опций в один аргумент)
- дефис, за которым следует целое слово, например `-file` (технически это эквивалентно предыдущему синтаксису, но они обычно не встречаются в одной программе)
- знак плюс, за которым следует одна буква, несколько букв или слово, например `+f`, `+rgb`
- косая черта, за которой следует буква, несколько букв или слово, например `/f`, `/file`

Эти синтаксисы опций не поддерживаются `optparse` и никогда не будут. Это сделано намеренно: первые три нестандартны в любом окружении, а последний имеет смысл только при ориентации исключительно на VMS, MS-DOS и/или Windows.

**аргумент опции**

аргумент, который следует за опцией, тесно связан с ней и извлекается из списка аргументов вместе с этой опцией. В `optparse` аргументы опций могут находиться либо в отдельном аргументе от своей опции:

```text
-f foo
--file foo
```

или включены в тот же аргумент:

```text
-ffoo
--file=foo
```

Обычно конкретная опция либо принимает аргумент, либо нет. Многие хотят функцию «необязательных аргументов опции», означающую, что некоторые опции будут принимать аргумент, если его увидят, и не будут, если не увидят. Это довольно спорно, потому что делает разбор неоднозначным: если `-a` принимает необязательный аргумент, а `-b` – совершенно другая опция, как интерпретировать `-ab`? Из-за этой неоднозначности `optparse` не поддерживает такую возможность.

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

то, что осталось в списке аргументов после разбора опций, т.е. после того, как опции и их аргументы были разобраны и удалены из списка аргументов.

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

опция, которая обязательно должна быть указана в командной строке; обратите внимание, что фраза «обязательная опция» внутренне противоречива в английском языке.

`optparse`

не запрещает реализовывать обязательные опции, но и особо не помогает в этом.

Например, рассмотрим эту гипотетическую командную строку:

```python
prog -v --report /tmp/report.txt foo bar
```

`-v` и `--report` – оба опции. Если допустить, что `--report` принимает один аргумент, то `/tmp/report.txt` – это аргумент опции. `foo` и `bar` – позиционные аргументы.

### 15.4.1.2. Для чего нужны опции?

Опции используются для предоставления дополнительной информации для настройки или кастомизации выполнения программы. На всякий случай, если это не было очевидно: опции обычно *необязательны*. Программа должна нормально работать вообще без опций. (Выберите случайную программу из набора Unix или GNU. Может ли она работать вообще без опций и при этом иметь смысл? Основные исключения – `find`, `tar` и `dd` – все они являются мутантными чудаками, которые справедливо критикуются за нестандартный синтаксис и запутанные интерфейсы.)

Многие хотят, чтобы в их программах были «обязательные опции». Подумайте об этом. Если это обязательно, значит, это *не необязательно*! Если есть информация, которая absolutely необходима вашей программе для успешного выполнения, для этого существуют позиционные аргументы.

В качестве примера хорошего дизайна интерфейса командной строки рассмотрим скромную утилиту `cp` для копирования файлов. Не имеет особого смысла пытаться копировать файлы без указания назначения и хотя бы одного источника. Следовательно, `cp` завершается ошибкой, если запустить её без аргументов. Однако у неё гибкий, полезный синтаксис, который вообще не требует никаких опций:

```python
cp SOURCE DEST
cp SOURCE ... DEST-DIR
```

С этим можно зайти довольно далеко. Большинство реализаций `cp` предоставляют множество опций для точной настройки копирования: можно сохранять режим и время изменения, избегать следования симлинкам, спрашивать подтверждение перед перезаписью существующих файлов и т.д. Но ничто из этого не отвлекает от основной миссии `cp`, которая состоит в копировании одного файла в другой или нескольких файлов в другой каталог.

### 15.4.1.3. Для чего нужны позиционные аргументы?

Позиционные аргументы предназначены для тех частей информации, которые absolutely и однозначно необходимы вашей программе для работы.

Хороший пользовательский интерфейс должен иметь как можно меньше абсолютных требований. Если вашей программе требуется 17 различных частей информации для успешного запуска, не имеет большого значения *как* вы получаете эту информацию от пользователя – большинство людей сдадутся и уйдут, так и не запустив программу. Это справедливо независимо от того, является ли интерфейс командной строкой, файлом конфигурации или графическим интерфейсом: если вы предъявляете столько требований к пользователям, большинство из них просто сдадутся.

Короче говоря, старайтесь минимизировать объем информации, которую пользователи absolutely обязаны предоставить – используйте разумные значения по умолчанию, когда это возможно. Конечно, вы также хотите сделать свои программы достаточно гибкими. Для этого и нужны опции. Опять же, неважно, являются ли они записями в файле конфигурации, виджетами в диалоге «Настройки» графического интерфейса или опциями командной строки – чем больше опций вы реализуете, тем гибче становится ваша программа, и тем сложнее становится ее реализация. Слишком большая гибкость тоже имеет недостатки; слишком много опций может перегрузить пользователей и сделать ваш код гораздо сложнее в поддержке.

## 15.4.2. Руководство

Хотя `optparse` довольно гибок и мощен, в большинстве случаев он достаточно прост в использовании. В этом разделе рассматриваются шаблоны кода, общие для любой программы на основе `optparse`.

Сначала необходимо импортировать класс OptionParser; затем, в начале основной программы, создать экземпляр OptionParser:

```python
from optparse import OptionParser
[...]
parser = OptionParser()
```

Затем можно приступить к определению опций. Базовый синтаксис:

```python
parser.add_option(opt_str, ...,
                  attr=value, ...)
```

Каждая опция имеет одну или несколько строк опций, таких как `-f` или `--file`, и несколько атрибутов опции, которые сообщают `optparse`, что ожидать и что делать при обнаружении этой опции в командной строке.

Обычно каждая опция имеет одну короткую и одну длинную строку опции, например:

```python
parser.add_option("-f", "--file", ...)
```

Вы можете определить любое количество коротких и длинных строк опций (включая ноль), при условии, что в целом есть хотя бы одна строка опции.

Строки опций, передаваемые в `add_option()`, по сути являются метками для опции, определённой этим вызовом. Для краткости мы часто будем говорить о *встрече опции* в командной строке; на самом деле `optparse` встречает *строки опций* и ищет по ним опции.

Когда все опции определены, укажите `optparse` разобрать командную строку вашей программы:

```python
(options, args) = parser.parse_args()
```

(При желании можно передать собственный список аргументов в `parse_args()`, но это редко бывает необходимо: по умолчанию используется `sys.argv[1:]`.)

`parse_args()` возвращает два значения:

- `options` – объект, содержащий значения всех опций; например, если `--file` принимает один строковый аргумент, то `options.file` будет именем файла, указанным пользователем, или `None`, если пользователь не указал эту опцию.
- `args` – список позиционных аргументов, оставшихся после разбора опций.

В этом разделе руководства рассматриваются только четыре наиболее важных атрибута опций: [`action`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.action), [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) (назначение) и [`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help). Из них [`action`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.action) является самым основным.

### 15.4.2.1. Понимание действий опций

Действия сообщают `optparse`, что делать при обнаружении опции в командной строке. Существует фиксированный набор действий, встроенных в `optparse`; добавление новых действий – продвинутая тема, рассматриваемая в разделе [*Расширение optparse*](https://python-all.ru/3.1/library/optparse.html#optparse-extending-optparse). Большинство действий указывают `optparse` сохранить значение в некоторой переменной – например, взять строку из командной строки и сохранить её в атрибуте `options`.

Если не указать действие опции, `optparse` по умолчанию использует `store`.

### 15.4.2.2. Действие store

Наиболее распространённое действие опции – `store`, которое указывает `optparse` взять следующий аргумент (или остаток текущего аргумента), убедиться, что он имеет правильный тип, и сохранить его в выбранное вами назначение.

Например:

```python
parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")
```

Теперь создадим фиктивную командную строку и попросим `optparse` разобрать её:

```python
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
```

Когда `optparse` видит строку опции `-f`, он потребляет следующий аргумент, `foo.txt`, и сохраняет его в `options.filename`. Таким образом, после этого вызова `parse_args()`, `options.filename` равен `"foo.txt"`.

Некоторые другие типы опций, поддерживаемые `optparse`: `int` и `float`. Вот опция, ожидающая целочисленный аргумент:

```python
parser.add_option("-n", type="int", dest="num")
```

Обратите внимание, что эта опция не имеет длинной строки опции, что вполне допустимо. Кроме того, нет явного действия, поскольку по умолчанию используется `store`.

Разберём ещё одну фиктивную командную строку. На этот раз мы поместим аргумент опции непосредственно рядом с опцией: поскольку `-n42` (один аргумент) эквивалентно `-n 42` (два аргумента), код

```python
(options, args) = parser.parse_args(["-n42"])
print(options.num)
```

выведет `42`.

Если не указать тип, `optparse` предполагает `string`. В сочетании с тем, что действие по умолчанию – `store`, это означает, что наш первый пример можно значительно сократить:

```python
parser.add_option("-f", "--file", dest="filename")
```

Если не указать назначение, `optparse` самостоятельно определяет разумное значение по умолчанию из строк параметров: если первая длинная строка параметра – `--foo-bar`, то назначение по умолчанию – `foo_bar`. Если длинных строк параметров нет, `optparse` берёт первую короткую строку параметра: назначение по умолчанию для `-f` – `f`.

`optparse` также включает встроенный тип `complex`. Добавление типов описано в разделе [*Extending optparse*](https://python-all.ru/3.1/library/optparse.html#optparse-extending-optparse).

### 15.4.2.3. Обработка булевых (флаговых) параметров

Флаговые параметры – установка переменной в true или false при встрече определённого параметра – довольно распространены. `optparse` поддерживает их с помощью двух отдельных действий: `store_true` и `store_false`. Например, у вас может быть флаг `verbose`, который включается с помощью `-v` и выключается с помощью `-q`:

```python
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
```

Здесь у нас две разные опции с одним и тем же назначением, что совершенно нормально. (Это просто означает, что нужно быть немного внимательнее при установке значений по умолчанию – см. ниже.)

Когда `optparse` встречает в командной строке `-v`, он устанавливает `options.verbose` в `True`; когда он встречает `-q`, `options.verbose` устанавливается в `False`.

### 15.4.2.4. Другие действия

Некоторые другие действия, поддерживаемые `optparse`:

**`"store_const"`**

сохранить константное значение

**`"append"`**

добавить аргумент этой опции в список

**`"count"`**

увеличить счётчик на единицу

**`\"колбэк\"`**

вызвать указанную функцию

Эти вопросы рассматриваются в разделе [*Справочное руководство*](https://python-all.ru/3.1/library/optparse.html#optparse-reference-guide), Справочное руководство и разделе [*Колбэки опций*](https://python-all.ru/3.1/library/optparse.html#optparse-option-callbacks).

### 15.4.2.5. Значения по умолчанию

Все приведённые выше примеры подразумевают установку некоторой переменной (так называемого «назначения») при встрече определённых параметров командной строки. Что произойдёт, если эти параметры ни разу не встретятся? Поскольку мы не указали значения по умолчанию, все они будут установлены в `None`. Обычно это нормально, но иногда хочется большего контроля. `optparse` позволяет указать значение по умолчанию для каждого назначения; оно присваивается до разбора командной строки.

Сначала рассмотрим пример с verbose/quiet. Если мы хотим, чтобы `optparse` устанавливал `verbose` в `True`, если только не встречен `-q`, то можно сделать так:

```python
parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")
```

Поскольку значения по умолчанию применяются к *назначению*, а не к какому-либо конкретному параметру, и эти два параметра имеют одно и то же назначение, это полностью эквивалентно:

```python
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)
```

Рассмотрим это:

```python
parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)
```

Опять же, значение по умолчанию для `verbose` будет `True`: последнее значение по умолчанию, указанное для любого конкретного назначения, считается окончательным.

Более понятный способ указать значения по умолчанию – метод `set_defaults()` класса OptionParser, который можно вызвать в любое время до вызова `parse_args()`:

```python
parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()
```

Как и прежде, последнее указанное значение для данного назначения параметра и будет использоваться. Для ясности старайтесь использовать какой-то один способ задания значений по умолчанию, а не оба сразу.

### 15.4.2.6. Генерация справки

Возможность `optparse` автоматически генерировать текст справки и использования полезна для создания удобных интерфейсов командной строки. Всё, что нужно сделать, – указать значение [`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help) для каждого параметра и, возможно, короткое сообщение об использовании для всей программы. Вот OptionParser, заполненный удобными (документированными) параметрами:

```python
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=True,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose",
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
                  metavar="FILE", help="write output to FILE")
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: novice, intermediate, "
                       "or expert [default: %default]")
```

Если `optparse` встречает в командной строке `-h` или `--help`, или же просто вызвать `parser.print_help()`, он выводит следующее в стандартный вывод:

```text
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]
```

(Если вывод справки вызван параметром помощи, `optparse` завершает работу после печати текста справки.)

Здесь задействовано много всего, чтобы помочь `optparse` сгенерировать наилучшее сообщение справки:

- сценарий определяет собственное сообщение об использовании:

  ```python
  usage = "usage: %prog [options] arg1 arg2"
  ```

  `optparse` заменяет `%prog` в строке использования на имя текущей программы, т.е. `os.path.basename(sys.argv[0])`. Затем развёрнутая строка выводится перед подробной справкой по параметрам.

  Если не указать строку использования, `optparse` использует простое, но разумное значение по умолчанию: `"Usage: %prog [options]"`, что нормально, если ваш сценарий не принимает позиционных аргументов.
- каждый параметр определяет строку справки, и не нужно беспокоиться о переносе строк – `optparse` заботится о переносе строк и о том, чтобы вывод справки выглядел хорошо.
- Опции, принимающие значение, указывают на это в автоматически сгенерированном сообщении справки, например, для опции «mode»:

  ```python
  -m MODE, --mode=MODE
  ```

  Здесь «MODE» называется мета-переменной: она обозначает аргумент, который пользователь должен указать для `-m`/`--mode`. По умолчанию `optparse` преобразует имя переменной назначения в верхний регистр и использует его в качестве мета-переменной. Иногда это не то, что нужно – например, параметр `--filename` явно задаёт `metavar="FILE"`, что приводит к такому автоматически сгенерированному описанию параметра:

  ```python
  -f FILE, --filename=FILE
  ```

  Это важно не только для экономии места: написанный вручную текст справки использует мета-переменную `FILE`, чтобы подсказать пользователю, что существует связь между полуформальным синтаксисом `-f FILE` и неформальным семантическим описанием «write output to FILE». Это простой, но эффективный способ сделать текст справки гораздо понятнее и полезнее для конечных пользователей.
- параметры, имеющие значение по умолчанию, могут включать `%default` в строку справки – `optparse` заменит его на [`str()`](https://python-all.ru/3.1/library/functions.html#str) от значения по умолчанию параметра. Если у параметра нет значения по умолчанию (или значение по умолчанию – `None`), `%default` разворачивается в `none`.

#### 15.4.2.6.1. Группировка параметров

При работе с большим количеством параметров удобно группировать их для лучшего вывода справки. [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser) может содержать несколько групп параметров, каждая из которых может содержать несколько параметров.

Группа параметров создается с помощью класса [`OptionGroup`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionGroup):

#### `class optparse.OptionGroup(parser, title, description=None)`

где

- parser – это экземпляр [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser), в который будет вставлена группа.
- title – это заголовок группы
- description (необязательно) – это подробное описание группы

[`OptionGroup`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionGroup) наследуется от `OptionContainer` (как и [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser)), поэтому метод `add_option()` можно использовать для добавления параметра в группу.

После того как все параметры объявлены, группа добавляется в ранее определенный парсер с помощью метода [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser) – `add_option_group()`.

Продолжая с парсером, определенным в предыдущем разделе, добавить [`OptionGroup`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionGroup) к парсеру легко:

```python
group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk.  "
                    "It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
```

Это приведёт к следующему выводу справки:

```text
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]

  Dangerous Options:
    Caution: use these options at your own risk.  It is believed that some
    of them bite.

    -g                  Group option.
```

Более полный пример может включать использование нескольких групп: продолжая предыдущий пример:

```python
group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk.  "
                    "It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)

group = OptionGroup(parser, "Debug Options")
group.add_option("-d", "--debug", action="store_true",
                 help="Print debug information")
group.add_option("-s", "--sql", action="store_true",
                 help="Print all SQL statements executed")
group.add_option("-e", action="store_true", help="Print every action done")
parser.add_option_group(group)
```

что приводит к следующему выводу:

```text
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or expert
                        [default: intermediate]

  Dangerous Options:
    Caution: use these options at your own risk.  It is believed that some
    of them bite.

    -g                  Group option.

  Debug Options:
    -d, --debug         Print debug information
    -s, --sql           Print all SQL statements executed
    -e                  Print every action done
```

Ещё один интересный метод, особенно при программной работе с группами опций:

#### `OptionParser.get_option_group(opt_str)`

Возвращает, если определена,

[`OptionGroup`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionGroup)

, заголовок или длинное описание которой равно

*opt\_str*

.

### 15.4.2.7. Вывод строки версии

Подобно краткой строке использования, `optparse` также может выводить строку версии для вашей программы. Нужно указать эту строку в качестве аргумента `version` для OptionParser:

```python
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
```

`%prog` разворачивается так же, как и в `usage`. Помимо этого, `version` может содержать что угодно. Когда вы его указываете, `optparse` автоматически добавляет параметр `--version` в ваш анализатор. Если он встречает этот параметр в командной строке, он разворачивает строку `version` (заменяя `%prog`), выводит её в stdout и завершает работу.

Например, если ваш скрипт называется `/usr/bin/foo`:

```python
$ /usr/bin/foo --version
foo 1.0
```

Следующие два метода можно использовать для вывода и получения строки `version`:

#### `OptionParser.print_version(file=None)`

Выводит сообщение о версии текущей программы (

`self.version`

) в

*file*

(по умолчанию stdout). Как и в

[`print_usage()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.print_usage)

, любое вхождение

`%prog`

в

`self.version`

заменяется на имя текущей программы. Ничего не делает, если

`self.version`

пусто или не определено.

#### `OptionParser.get_version()`

То же, что и

[`print_version()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.print_version)

, но возвращает строку версии вместо её вывода.

### 15.4.2.8. Как `optparse` обрабатывает ошибки

Есть два основных класса ошибок, с которыми приходится иметь дело `optparse`: ошибки программиста и ошибки пользователя. Ошибки программиста – это обычно неверные вызовы [`OptionParser.add_option()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.add_option), например, недопустимые строки опций, неизвестные атрибуты опций, отсутствующие атрибуты опций и т.д. Они обрабатываются обычным способом: вызывается исключение (либо `optparse.OptionError`, либо [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)) и программа завершается с ошибкой.

Обработка ошибок пользователя гораздо важнее, поскольку они неизбежно возникают независимо от того, насколько стабилен ваш код. `optparse` может автоматически обнаруживать некоторые ошибки пользователя, такие как неверные аргументы опций (передача `-n 4x`, где `-n` принимает целочисленный аргумент), отсутствие аргументов (`-n` в конце командной строки, где `-n` принимает аргумент любого типа). Также можно вызвать `OptionParser.error()` для сигнализации об ошибке, определённой приложением:

```python
(options, args) = parser.parse_args()
[...]
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")
```

В любом случае `optparse` обрабатывает ошибку одинаково: выводит справку по использованию программы и сообщение об ошибке в стандартный поток ошибок и завершается с кодом ошибки 2.

Рассмотрим первый пример выше, где пользователь передает `4x` параметру, который ожидает целое число:

```python
$ /usr/bin/foo -n 4x
Usage: foo [options]

foo: error: option -n: invalid integer value: '4x'
```

Или когда пользователь вообще не передаёт значение:

```python
$ /usr/bin/foo -n
Usage: foo [options]

foo: error: -n option requires an argument
```

Сообщения об ошибках, генерируемые `optparse`, всегда упоминают опцию, связанную с ошибкой; обязательно делайте то же самое при вызове `OptionParser.error()` из кода вашего приложения.

Если поведение обработки ошибок по умолчанию `optparse` не подходит для ваших нужд, необходимо создать подкласс OptionParser и переопределить его методы `exit()` и/или `error()`.

### 15.4.2.9. Собираем всё вместе

Вот как обычно выглядят сценарии на основе `optparse`:

```python
from optparse import OptionParser
[...]
def main():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", dest="filename",
                      help="read data from FILENAME")
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose")
    [...]
    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")
    if options.verbose:
        print("reading %s..." % options.filename)
    [...]

if __name__ == "__main__":
    main()
```

## 15.4.3. Справочное руководство

### 15.4.3.1. Создание парсера

Первый шаг при использовании `optparse` – создание экземпляра OptionParser.

#### `class optparse.OptionParser(...)`

Конструктор OptionParser не требует обязательных аргументов, но принимает ряд необязательных именованных аргументов. Их всегда следует передавать как именованные аргументы, т.е. не полагаться на порядок объявления аргументов.

**`usage` (по умолчанию: `"%prog [options]"`)**

Краткая справка по использованию, выводимая при неправильном запуске программы или с опцией помощи. Когда

`optparse`

выводит строку использования, он заменяет

`%prog`

на

`os.path.basename(sys.argv[0])`

(или на

`prog`

, если был передан соответствующий именованный аргумент). Чтобы подавить сообщение об использовании, передайте специальное значение

`optparse.SUPPRESS_USAGE`

.

**`option_list` (по умолчанию: `[]`)**

Список объектов Option для заполнения парсера. Параметры из

`option_list`

добавляются после всех параметров из

`standard_option_list`

(атрибут класса, который может быть установлен подклассами OptionParser), но перед любыми параметрами версии или справки. Устарело; вместо этого используйте

[`add_option()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.add_option)

после создания парсера.

**`option_class` (по умолчанию: optparse.Option)**

Класс, используемый при добавлении опций в парсер с помощью

[`add_option()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.add_option)

.

**`version` (по умолчанию: `None`)**

Строка версии, выводимая, когда пользователь указывает опцию версии. Если передать истинное значение для

`version`

,

`optparse`

автоматически добавляет опцию версии с единственной строкой опции

`--version`

. Подстрока

`%prog`

раскрывается так же, как и для

`usage`

.

**`conflict_handler` (по умолчанию: `"error"`)**

Определяет, что делать, когда в парсер добавляются опции с конфликтующими строками опций; см. раздел

[*Конфликты между опциями*](https://python-all.ru/3.1/library/optparse.html#optparse-conflicts-between-options)

.

**`description` (по умолчанию: `None`)**

Абзац текста с кратким обзором программы.

`optparse`

переформатирует этот абзац под текущую ширину терминала и выводит его при запросе помощи (после

`usage`

, но до списка опций).

**`formatter` (по умолчанию: новый `IndentedHelpFormatter`)**

Экземпляр optparse.HelpFormatter, который будет использоваться для вывода справки.

`optparse`

предоставляет два конкретных класса для этой цели: IndentedHelpFormatter и TitledHelpFormatter.

**`add_help_option` (по умолчанию: `True`)**

Если истина,

`optparse`

добавит опцию помощи (со строками опции

`-h`

и

`--help`

) в парсер.

**`prog`**

Строка, используемая при раскрытии

`%prog`

в

`usage`

и

`version`

вместо

`os.path.basename(sys.argv[0])`

.

**`epilog` (по умолчанию: `None`)**

Абзац текста справки, выводимый после справки по опциям.

### 15.4.3.2. Наполнение парсера

Есть несколько способов наполнить парсер опциями. Предпочтительный – использовать [`OptionParser.add_option()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.add_option), как показано в разделе [*Tutorial*](https://python-all.ru/3.1/library/optparse.html#optparse-tutorial). `add_option()` можно вызывать одним из двух способов:

- передать ему экземпляр Option (возвращаемый функцией `make_option()`)
- передать ему любую комбинацию позиционных и именованных аргументов, допустимых для `make_option()` (т.е. для конструктора Option), и он создаст экземпляр Option.

Другой способ – передать список предварительно созданных экземпляров Option конструктору OptionParser, например:

```python
option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)
```

(`make_option()` – это фабричная функция для создания экземпляров Option; в настоящее время это псевдоним конструктора Option. Будущая версия `optparse` может разделить Option на несколько классов, и `make_option()` будет выбирать правильный класс для создания. Не создавайте экземпляры Option напрямую.)

### 15.4.3.3. Определение опций

Каждый экземпляр Option представляет набор синонимичных строк опций командной строки, например `-f` и `--file`. Можно указать любое количество коротких или длинных строк опций, но необходимо указать хотя бы одну общую строку опции.

Канонический способ создания экземпляра `Option` – использовать метод `add_option()` класса [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser).

#### `OptionParser.add_option(opt_str[, ...], attr=value, ...)`

Для определения опции только с короткой строкой опции:

```python
parser.add_option("-f", attr=value, ...)
```

А для определения опции только с длинной строкой опции:

```python
parser.add_option("--foo", attr=value, ...)
```

Именованные аргументы определяют атрибуты нового объекта Option. Наиболее важный атрибут опции – [`action`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.action), и он в значительной степени определяет, какие другие атрибуты имеют значение или обязательны. Если передать нерелевантные атрибуты опции или не передать обязательные, `optparse` вызывает исключение `OptionError` с объяснением ошибки.

Атрибут *action* опции определяет, что `optparse` делает при встрече этой опции в командной строке. Стандартные действия опций, жёстко закодированные в `optparse`:

**`"store"`**

сохранить аргумент опции (по умолчанию)

**`"store_const"`**

сохранить константное значение

**`"store_true"`**

сохраняет истинное значение

**`"store_false"`**

сохраняет ложное значение

**`"append"`**

добавить аргумент этой опции в список

**`"append_const"`**

добавить константное значение в список

**`"count"`**

увеличить счётчик на единицу

**`\"колбэк\"`**

вызвать указанную функцию

**`"help"`**

вывести сообщение об использовании, включающее все опции и документацию к ним

(Если не указать действие, по умолчанию используется `"store"`. Для этого действия можно также указать атрибуты опции [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest); см. [*Standard option actions*](https://python-all.ru/3.1/library/optparse.html#optparse-standard-option-actions).)

Как видите, большинство действий сводятся к сохранению или обновлению значения где-либо. `optparse` всегда создаёт для этого специальный объект, традиционно называемый `options` (на самом деле это экземпляр `optparse.Values`). Аргументы опций (и различные другие значения) хранятся как атрибуты этого объекта в соответствии с атрибутом опции [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) (назначение).

Например, при вызове

```python
parser.parse_args()
```

одно из первых действий `optparse` – создать объект `options`:

```python
options = Values()
```

Если одна из опций в этом анализаторе определена с помощью

```python
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
```

и разбираемая командная строка включает любую из следующих:

```python
-ffoo
-f foo
--file=foo
--file foo
```

затем `optparse`, увидев эту опцию, выполнит эквивалент

```python
options.filename = "foo"
```

Атрибуты опции [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) почти так же важны, как [`action`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.action), но [`action`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.action) – единственный, который имеет смысл для *всех* опций.

### 15.4.3.4. Атрибуты опций

Следующие атрибуты опций могут быть переданы в качестве именованных аргументов в [`OptionParser.add_option()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.add_option). Если передать атрибут, не относящийся к данной опции, или не передать обязательный атрибут, `optparse` возбуждает `OptionError`.

#### `Option.action`

(по умолчанию: `"store"`)

Определяет поведение `optparse` при обнаружении этой опции в командной строке; доступные варианты описаны [*здесь*](https://python-all.ru/3.1/library/optparse.html#optparse-standard-option-actions).

#### `Option.type`

(по умолчанию: `"string"`)

Тип аргумента, ожидаемый этой опцией (например, `"string"` или `"int"`); доступные типы опций описаны [*здесь*](https://python-all.ru/3.1/library/optparse.html#optparse-standard-option-types).

#### `Option.dest`

(по умолчанию: выводится из строк опций)

Если действие опции подразумевает запись или изменение значения где-либо, это указывает `optparse`, куда его записывать: [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) задаёт атрибут объекта `options`, который `optparse` создаёт при разборе командной строки.

#### `Option.default`

Значение, которое следует использовать для назначения этой опции, если опция не обнаружена в командной строке. См. также

[`OptionParser.set_defaults()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.set_defaults)

.

#### `Option.nargs`

(по умолчанию: 1)

Сколько аргументов типа [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) должно быть обработано при обнаружении этой опции. Если \> 1, `optparse` сохранит кортеж значений в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest).

#### `Option.const`

Для действий, сохраняющих постоянное значение, – само это постоянное значение.

#### `Option.choices`

Для опций типа

`"choice"`

– список строк, из которых пользователь может выбирать.

#### `Option.callback`

Для опций с действием

`"колбэк"`

– вызываемый объект, который будет вызван при обнаружении этой опции. См. раздел

[*Option Callbacks*](https://python-all.ru/3.1/library/optparse.html#optparse-option-callbacks)

для получения подробностей об аргументах, передаваемых вызываемому объекту.

#### `Option.callback_args`

#### `Option.callback_kwargs`

Дополнительные позиционные и именованные аргументы для передачи в

`колбэк`

после четырёх стандартных аргументов колбэка.

#### `Option.help`

Текст справки для этой опции, выводимый при перечислении всех доступных опций после того, как пользователь укажет опцию

[`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help)

(например,

`--help`

). Если текст справки не указан, опция будет перечислена без текста справки. Чтобы скрыть эту опцию, используйте специальное значение

`optparse.SUPPRESS_HELP`

.

#### `Option.metavar`

(по умолчанию: выводится из строк опций)

Stand-in for the option argument(s) to use when printing help text. See section [*Tutorial*](https://python-all.ru/3.1/library/optparse.html#optparse-tutorial) for an example.

### 15.4.3.5. Стандартные действия опций

Различные действия опций имеют несколько разные требования и эффекты. Большинство действий имеют несколько соответствующих атрибутов, которые можно указать, чтобы направить поведение `optparse`; некоторые имеют обязательные атрибуты, которые необходимо указать для любой опции, использующей это действие.

- `"store"` \[соответствующие: [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.choices)\]

  За опцией должен следовать аргумент, который преобразуется в значение согласно [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) и сохраняется в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest). Если [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs) \> 1, из командной строки будет потреблено несколько аргументов; все они будут преобразованы согласно [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) и сохранены в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) как кортеж. См. раздел [*Стандартные типы опций*](https://python-all.ru/3.1/library/optparse.html#optparse-standard-option-types).

  Если указан [`choices`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.choices) (список или кортеж строк), по умолчанию тип принимает значение `"choice"`.

  Если [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) не указан, по умолчанию он принимает значение `"string"`.

  Если [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) не указан, `optparse` выводит назначение из первой длинной строки опции (например, `--foo-bar` подразумевает `foo_bar`). Если длинных строк опций нет, `optparse` выводит назначение из первой короткой строки опции (например, `-f` подразумевает `f`).

  Пример:

  ```python
  parser.add_option("-f")
  parser.add_option("-p", type="float", nargs=3, dest="point")
  ```

  В процессе разбора командной строки

  ```python
  -f foo.txt -p 1 -3.5 4 -fbar.txt
  ```

  `optparse` установит

  ```python
  options.f = "foo.txt"
  options.point = (1.0, -3.5, 4.0)
  options.f = "bar.txt"
  ```
- `"store_const"` \[обязательно: [`const`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.const); относящиеся: [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest)\]

  Значение [`const`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.const) сохраняется в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest).

  Пример:

  ```python
  parser.add_option("-q", "--quiet",
                    action="store_const", const=0, dest="verbose")
  parser.add_option("-v", "--verbose",
                    action="store_const", const=1, dest="verbose")
  parser.add_option("--noisy",
                    action="store_const", const=2, dest="verbose")
  ```

  Если обнаружено `--noisy`, `optparse` установит

  ```python
  options.verbose = 2
  ```
- `"store_true"` \[относящиеся: [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest)\]

  Частный случай `"store_const"`, который сохраняет истинное значение в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest).
- `"store_false"` \[относящиеся: [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest)\]

  Как `"store_true"`, но сохраняет ложное значение.

  Пример:

  ```python
  parser.add_option("--clobber", action="store_true", dest="clobber")
  parser.add_option("--no-clobber", action="store_false", dest="clobber")
  ```
- `"append"` \[относящиеся: [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.choices)\]

  За опцией должен следовать аргумент, который добавляется в список в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest). Если значение по умолчанию для [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) не задано, пустой список автоматически создаётся при первом обнаружении этой опции в командной строке `optparse`. Если [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs) \> 1, потребляется несколько аргументов, и кортеж длиной [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs) добавляется к [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest).

  Значения по умолчанию для [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) такие же, как для действия `"store"`.

  Пример:

  ```python
  parser.add_option("-t", "--tracks", action="append", type="int")
  ```

  Если в командной строке обнаружено `-t3`, `optparse` выполняет эквивалент:

  ```python
  options.tracks = []
  options.tracks.append(int("3"))
  ```

  Если чуть позже встречается `--tracks=4`, он делает:

  ```python
  options.tracks.append(int("4"))
  ```
- `"append_const"` \[обязательно: [`const`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.const); относящиеся: [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest)\]

  Как `"store_const"`, но значение [`const`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.const) добавляется в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest); как и в случае `"append"`, [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) по умолчанию равен `None`, и пустой список автоматически создаётся при первой встрече опции.
- `"count"` \[относящиеся: [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest)\]

  Увеличивает целое число, хранящееся в [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest). Если значение по умолчанию не указано, [`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest) устанавливается в ноль перед первым увеличением.

  Пример:

  ```python
  parser.add_option("-v", action="count", dest="verbosity")
  ```

  Когда `-v` встречается в командной строке в первый раз, `optparse` выполняет эквивалент:

  ```python
  options.verbosity = 0
  options.verbosity += 1
  ```

  Каждое последующее появление `-v` приводит к

  ```python
  options.verbosity += 1
  ```
- `"колбэк"` \[обязательно: [`колбэк`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback); относящиеся: [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type), [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs), [`callback_args`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_args), [`callback_kwargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_kwargs)\]

  Вызывает функцию, указанную колбэком [`колбэк`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback), которая вызывается как

  ```python
  func(option, opt_str, value, parser, *args, **kwargs)
  ```

  Смотрите раздел [*Колбэки опций*](https://python-all.ru/3.1/library/optparse.html#optparse-option-callbacks) для подробностей.
- `"help"`

  Выводит полное справочное сообщение для всех опций текущего анализатора опций. Справочное сообщение строится из строки `usage`, переданной конструктору OptionParser, и строки [`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help), переданной каждой опции.

  Если для опции не указана строка [`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help), она всё равно будет включена в справочное сообщение. Чтобы полностью исключить опцию, используйте специальное значение `optparse.SUPPRESS_HELP`.

  `optparse` автоматически добавляет опцию [`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help) во все OptionParsers, поэтому обычно не нужно создавать её отдельно.

  Пример:

  ```python
  from optparse import OptionParser, SUPPRESS_HELP

  # обычно опция справки добавляется автоматически, но её можно
  # подавить, используя аргумент add_help_option
  parser = OptionParser(add_help_option=False)

  parser.add_option("-h", "--help", action="help")
  parser.add_option("-v", action="store_true", dest="verbose",
                    help="Be moderately verbose")
  parser.add_option("--file", dest="filename",
                    help="Input file to read data from")
  parser.add_option("--secret", help=SUPPRESS_HELP)
  ```

  Если `optparse` обнаруживает в командной строке `-h` или `--help`, он выводит в stdout что-то вроде следующего сообщения справки (при условии, что `sys.argv[0]` равно `"foo.py"`):

  ```text
  Usage: foo.py [options]

  Options:
    -h, --help        Show this help message and exit
    -v                Be moderately verbose
    --file=FILENAME   Input file to read data from
  ```

  После вывода сообщения справки `optparse` завершает процесс с помощью `sys.exit(0)`.
- `"version"`

  Выводит номер версии, переданный OptionParser, в stdout и завершает работу. Номер версии фактически форматируется и выводится методом `print_version()` класса OptionParser. Обычно это актуально, только если аргумент `version` передан конструктору OptionParser. Как и в случае с опциями [`help`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.help), редко приходится создавать опции `version`, поскольку `optparse` автоматически добавляет их при необходимости.

### 15.4.3.6. Стандартные типы опций

`optparse` имеет пять встроенных типов опций: `"string"`, `"int"`, `"choice"`, `"float"` и `"complex"`. Если нужно добавить новые типы опций, смотрите раздел [*Расширение optparse*](https://python-all.ru/3.1/library/optparse.html#optparse-extending-optparse).

Аргументы строковых опций никак не проверяются и не преобразуются: текст из командной строки сохраняется в целевом атрибуте (или передаётся колбэку) как есть.

Целочисленные аргументы (тип `"int"`) разбираются следующим образом:

- если число начинается с `0x`, оно разбирается как шестнадцатеричное число
- если число начинается с `0`, оно разбирается как восьмеричное
- если число начинается с `0b`, оно разбирается как двоичное число
- в противном случае число разбирается как десятичное

Преобразование выполняется вызовом [`int()`](https://python-all.ru/3.1/library/functions.html#int) с соответствующим основанием (2, 8, 10 или 16). Если это не удаётся, то `optparse` тоже завершится ошибкой, хотя и с более полезным сообщением.

Аргументы опций `"float"` и `"complex"` преобразуются напрямую с помощью [`float()`](https://python-all.ru/3.1/library/functions.html#float) и [`complex()`](https://python-all.ru/3.1/library/functions.html#complex), с аналогичной обработкой ошибок.

Опции `"choice"` являются подтипом опций `"string"`. Атрибут [`choices`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.choices) опции (последовательность строк) определяет множество допустимых аргументов опции. `optparse.check_choice()` сравнивает предоставленные пользователем аргументы с этим основным списком и возбуждает `OptionValueError`, если указана недопустимая строка.

### 15.4.3.7. Разбор аргументов

Весь смысл создания и настройки OptionParser – вызвать его метод `parse_args()`:

```python
(options, args) = parser.parse_args(args=None, values=None)
```

где входные параметры:

**`args`**

список аргументов для обработки (по умолчанию:

`sys.argv[1:]`

)

**`values`**

объект

`optparse.Values`

для сохранения аргументов параметров (по умолчанию: новый экземпляр

`Values`

) – если передать существующий объект, значения параметров по умолчанию не будут в нём инициализированы

а возвращаемые значения –

**`options`**

тот же объект, который был передан как

`values`

, или экземпляр optparse.Values, созданный

`optparse`

**`args`**

оставшиеся позиционные аргументы после обработки всех опций

Наиболее распространённый вариант использования – не указывать ни один из именованных аргументов. Если передать `values`, он будет изменяться повторными вызовами [`setattr()`](https://python-all.ru/3.1/library/functions.html#setattr) (примерно по одному на каждый аргумент опции, сохраняемый в её назначении) и возвращён методом `parse_args()`.

Если `parse_args()` встречает какие-либо ошибки в списке аргументов, он вызывает метод `error()` класса OptionParser с соответствующим сообщением об ошибке для конечного пользователя. Это в конечном итоге приводит к завершению процесса с кодом выхода 2 (традиционный код выхода Unix для ошибок командной строки).

### 15.4.3.8. Запросы и управление анализатором опций

Поведение парсера опций по умолчанию можно слегка настроить, а также можно заглянуть внутрь парсера и посмотреть, что там есть. OptionParser предоставляет несколько методов, которые в этом помогут:

#### `OptionParser.disable_interspersed_args()`

Устанавливает, что разбор останавливается на первой не-опции. Например, если `-a` и `-b` – это простые опции без аргументов, `optparse` обычно принимает такой синтаксис:

```python
prog -a arg1 -b arg2
```

и обрабатывает его как эквивалент

```python
prog -a -b arg1 arg2
```

Чтобы отключить эту возможность, вызовите [`disable_interspersed_args()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.disable_interspersed_args). Это восстанавливает традиционный синтаксис Unix, при котором разбор опций останавливается на первом не-опционном аргументе.

Используйте это, если у вас есть обработчик команд, который запускает другую команду с собственными опциями, и нужно гарантировать, что эти опции не будут перепутаны. Например, каждая команда может иметь свой набор опций.

#### `OptionParser.enable_interspersed_args()`

Настраивает разбор на то, чтобы не останавливаться на первом не-опции, позволяя перемешивать ключи с аргументами команды. Это поведение по умолчанию.

#### `OptionParser.get_option(opt_str)`

Возвращает экземпляр Option с опционной строкой

*opt\_str*

или

`None`

, если ни одна опция не имеет такой строки.

#### `OptionParser.has_option(opt_str)`

Возвращает true, если OptionParser содержит опцию с опционной строкой

*opt\_str*

(например,

`-q`

или

`--verbose`

).

#### `OptionParser.remove_option(opt_str)`

If the

[`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser)

has an option corresponding to

*opt\_str*

, that option is removed. If that option provided any other option strings, all of those option strings become invalid. If

*opt\_str*

does not occur in any option belonging to this

[`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser)

, raises

[`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError)

.

### 15.4.3.9. Конфликты между опциями

Если быть невнимательным, легко определить опции с конфликтующими строками опций:

```python
parser.add_option("-n", "--dry-run", ...)
[...]
parser.add_option("-n", "--noisy", ...)
```

(Это особенно актуально, если определён собственный подкласс OptionParser с некоторыми стандартными опциями.)

Каждый раз при добавлении опции `optparse` проверяет конфликты с существующими опциями. Если они находятся, вызывается текущий механизм разрешения конфликтов. Можно задать механизм разрешения конфликтов либо в конструкторе:

```python
parser = OptionParser(..., conflict_handler=handler)
```

или отдельным вызовом:

```python
parser.set_conflict_handler(handler)
```

Доступные обработчики конфликтов:

> **`"error"` (по умолчанию)**
>
> считать конфликты опций программной ошибкой и возбуждать
>
> `OptionConflictError`
>
> **`\"resolve\"`**
>
> разрешать конфликты опций интеллектуально (см. ниже)

В качестве примера определим [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser), который разрешает конфликты интеллектуально, и добавим к нему конфликтующие параметры:

```python
parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
```

На этом этапе `optparse` обнаруживает, что ранее добавленная опция уже использует строку опции `-n`. Поскольку `conflict_handler` равен `"resolve"`, он разрешает ситуацию, удаляя `-n` из списка строк опции более ранней опции. Теперь `--dry-run` – единственный способ для пользователя активировать эту опцию. Если пользователь запросит справку, сообщение справки отразит это:

```python
Options:
  --dry-run     do no harm
  [...]
  -n, --noisy   be noisy
```

Можно сокращать строки опций для ранее добавленной опции, пока их не останется, и у пользователя не будет возможности вызвать эту опцию из командной строки. В этом случае `optparse` полностью удаляет эту опцию, так что она не появляется в тексте справки или где-либо ещё. Продолжая с нашим существующим OptionParser:

```python
parser.add_option("--dry-run", ..., help="new dry-run option")
```

На этом этапе исходная опция `-n`/`--dry-run` больше не доступна, поэтому `optparse` удаляет её, оставляя такой текст справки:

```python
Options:
  [...]
  -n, --noisy   be noisy
  --dry-run     new dry-run option
```

### 15.4.3.10. Очистка

Экземпляры OptionParser имеют несколько циклических ссылок. Это не должно быть проблемой для сборщика мусора Python, но вы можете захотеть разорвать циклические ссылки явно, вызвав `destroy()` для вашего OptionParser после завершения работы с ним. Это особенно полезно в долго работающих приложениях, где большие графы объектов достижимы из вашего OptionParser.

### 15.4.3.11. Другие методы

OptionParser поддерживает несколько других открытых методов:

#### `OptionParser.set_usage(usage)`

Устанавливает строку использования в соответствии с правилами, описанными выше для

`usage`

аргумента-ключевого слова конструктора. Передача

`None`

устанавливает строку использования по умолчанию; используйте

`optparse.SUPPRESS_USAGE`

для подавления сообщения об использовании.

#### `OptionParser.print_usage(file=None)`

Выводит сообщение об использовании для текущей программы (

`self.usage`

) в

*file*

(по умолчанию stdout). Любое вхождение строки

`%prog`

в

`self.usage`

заменяется на имя текущей программы. Ничего не делает, если

`self.usage`

пуст или не определён.

#### `OptionParser.get_usage()`

То же, что и

[`print_usage()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.print_usage)

, но возвращает строку использования вместо её вывода.

#### `OptionParser.set_defaults(dest=value, ...)`

Устанавливает значения по умолчанию для нескольких назначений параметров одновременно. Использование [`set_defaults()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.set_defaults) – предпочтительный способ установки значений по умолчанию для параметров, поскольку несколько параметров могут совместно использовать одно назначение. Например, если несколько параметров «режим» устанавливают одно и то же назначение, любой из них может установить значение по умолчанию, и последний выигрывает:

```python
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced",
                  default="novice")    # переопределено ниже
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice",
                  default="advanced")  # переопределяет вышеуказанную настройку
```

Чтобы избежать этой путаницы, используйте [`set_defaults()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.set_defaults):

```python
parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice")
```

## 15.4.4. Опциональные колбэки

Когда встроенных действий и типов `optparse` недостаточно для ваших нужд, у вас есть два варианта: расширить `optparse` или определить опцию с колбэком. Расширение `optparse` более универсально, но избыточно для многих простых случаев. Часто достаточно простого колбэка.

Определение опции-колбэка состоит из двух шагов:

- определите саму опцию, используя действие `"колбэк"`
- написать колбэк – функцию (или метод), которая принимает как минимум четыре аргумента, как описано ниже

### 15.4.4.1. Определение опции с колбэком

Как всегда, самый простой способ определить опцию с колбэком – использовать метод [`OptionParser.add_option()`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser.add_option). Кроме [`action`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.action), единственным атрибутом опции, который необходимо указать, является `колбэк` – функция, которую нужно вызвать:

```python
parser.add_option("-c", action="callback", callback=my_callback)
```

`колбэк` – это функция (или другой вызываемый объект), поэтому вы должны уже определить `my_callback()` до создания этой опции с колбэком. В этом простом случае `optparse` даже не знает, принимает ли `-c` какие-то аргументы, что обычно означает, что опция не принимает аргументов – достаточно лишь присутствия `-c` в командной строке. Однако в некоторых обстоятельствах колбэк может потреблять произвольное число аргументов командной строки. Вот здесь написание колбэков становится сложным; это рассматривается далее в этом разделе.

`optparse` всегда передаёт вашему колбэку четыре определённых аргумента, и он передаст дополнительные аргументы только если вы укажете их через [`callback_args`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_args) и [`callback_kwargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_kwargs). Таким образом, минимальная сигнатура функции колбэка:

```python
def my_callback(option, opt, value, parser):
```

Четыре аргумента колбэка описаны ниже.

Есть ещё несколько атрибутов опции, которые можно указать при определении опции-колбэка:

**[`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type)**

имеет своё обычное значение: как и в случае действий

`"store"`

или

`"append"`

, он предписывает

`optparse`

потребить один аргумент и преобразовать его в

[`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type)

. Однако вместо сохранения преобразованного значения,

`optparse`

передаёт его в функцию обратного вызова.

**[`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs)**

также имеет своё обычное значение: если он указан и больше 1,

`optparse`

потребит

[`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs)

аргументов, каждый из которых должен быть преобразуем в

[`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type)

. Затем он передаёт кортеж преобразованных значений в функцию обратного вызова.

**[`callback_args`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_args)**

кортеж дополнительных позиционных аргументов, передаваемых колбэку

**[`callback_kwargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_kwargs)**

словарь дополнительных именованных аргументов, передаваемых колбэку

### 15.4.4.2. Как вызываются колбэки

Все колбэки вызываются следующим образом:

```python
func(option, opt_str, value, parser, *args, **kwargs)
```

где

**`option`**

это экземпляр Option, который вызывает колбэк

**`opt_str`**

– это строка параметра, видимая в командной строке, которая запускает колбэк. (Если была использована сокращённая длинная опция,

`opt_str`

будет полной, канонической строкой параметра – например, если пользователь поместил

`--foo`

в командную строку как сокращение для

`--foobar`

, то

`opt_str`

будет

`"--foobar"`

.)

**`value`**

это аргумент данной опции, указанный в командной строке.

`optparse`

ожидает аргумент только если установлен

[`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type)

; тип

`value`

будет соответствовать типу, подразумеваемому типом опции. Если

[`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type)

для этой опции равен

`None`

(аргумент не ожидается), то

`value`

будет

`None`

. Если

[`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs)

\> 1,

`value`

будет кортежем значений подходящего типа.

**`parser`**

это экземпляр OptionParser, управляющий всем процессом; он полезен тем, что через его атрибуты можно получить доступ к некоторым другим интересным данным:

**`parser.largs`**

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

`parser.largs`

, например, добавляя в него дополнительные аргументы. (Этот список станет

`args`

, вторым возвращаемым значением

`parse_args()`

.)

**`parser.rargs`**

текущий список оставшихся аргументов, т.е. с удалёнными

`opt_str`

и

`value`

(если применимо), и только следующие за ними аргументы всё ещё присутствуют. Можно свободно изменять

`parser.rargs`

, например, потребляя больше аргументов.

**`parser.values`**

объект, в котором по умолчанию хранятся значения опций (экземпляр optparse.OptionValues). Это позволяет колбэкам использовать тот же механизм, что и остальная часть

`optparse`

, для хранения значений опций; не нужно возиться с глобальными переменными или замыканиями. Также можно получить доступ или изменить значения любых опций, уже встреченных в командной строке.

**`args`**

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

[`callback_args`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_args)

.

**`kwargs`**

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

[`callback_kwargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.callback_kwargs)

.

### 15.4.4.3. Возбуждение ошибок в колбэке

Функция обратного вызова должна возбуждать `OptionValueError`, если возникли проблемы с опцией или её аргументом(ами). `optparse` перехватывает это и завершает программу, выводя в stderr указанное сообщение об ошибке. Сообщение должно быть ясным, кратким, точным и указывать на виновную опцию. В противном случае пользователю будет трудно понять, что было сделано не так.

### 15.4.4.4. Пример колбэка 1: простейший колбэк

Вот пример опции-колбэка, которая не принимает аргументов и просто записывает факт своего появления:

```python
def record_foo_seen(option, opt_str, value, parser):
    parser.values.saw_foo = True

parser.add_option("--foo", action="callback", callback=record_foo_seen)
```

Конечно, вы можете сделать это с помощью действия `"store_true"`.

### 15.4.4.5. Пример колбэка 2: проверка порядка опций

Вот чуть более интересный пример: записать факт, что `-a` встречен, но аварийно завершиться, если он появляется после `-b` в командной строке.

```python
def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use -a after -b")
    parser.values.a = 1
[...]
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
```

### 15.4.4.6. Пример колбэка 3: проверка порядка опций (обобщённый вариант)

Если вы хотите повторно использовать этот колбэк для нескольких похожих опций (установить флаг, но аварийно завершиться, если `-b` уже был встречен), потребуется немного доработки: сообщение об ошибке и устанавливаемый флаг должны быть обобщены.

```python
def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt_str)
    setattr(parser.values, option.dest, 1)
[...]
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')
```

### 15.4.4.7. Пример колбэка 4: проверка произвольного условия

Конечно, можно задать любое условие – вы не ограничены проверкой значений уже определённых параметров. Например, если есть параметры, которые не должны вызываться в полнолуние, достаточно сделать так:

```python
def check_moon(option, opt_str, value, parser):
    if is_moon_full():
        raise OptionValueError("%s option invalid when moon is full"
                               % opt_str)
    setattr(parser.values, option.dest, 1)
[...]
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")
```

(Определение `is_moon_full()` оставляется читателю в качестве упражнения.)

### 15.4.4.8. Пример колбэка 5: фиксированные аргументы

Ситуация становится чуть более интересной, когда вы определяете опции с обратным вызовом, принимающие фиксированное количество аргументов. Указание, что опция с колбэком принимает аргументы, аналогично определению опции `"store"` или `"append"`: если вы определяете [`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type), то опция принимает один аргумент, который должен быть преобразуем к этому типу; если вы дополнительно определяете [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs), то опция принимает [`nargs`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.nargs) аргументов.

Вот пример, который просто эмулирует стандартное действие `"store"`:

```python
def store_value(option, opt_str, value, parser):
    setattr(parser.values, option.dest, value)
[...]
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")
```

Обратите внимание, что `optparse` самостоятельно заботится о потреблении 3 аргументов и преобразовании их в целые числа; всё, что нужно сделать – сохранить их. (Или что-то ещё; очевидно, для этого примера колбэк не нужен.)

### 15.4.4.9. Пример колбэка 6: переменное число аргументов

Дело усложняется, когда требуется, чтобы опция принимала переменное число аргументов. В этом случае необходимо написать колбэк, поскольку `optparse` не предоставляет для этого встроенных возможностей. И придётся разобраться с некоторыми тонкостями традиционного разбора командной строки Unix, которые `optparse` обычно обрабатывает автоматически. В частности, колбэки должны реализовывать стандартные правила для аргументов `--` и `-`:

- как `--`, так и `-` могут быть аргументами параметра
- голый `--` (если не является аргументом какого-либо параметра): остановить обработку командной строки и отбросить `--`
- голый `-` (если не является аргументом какой-либо опции): остановить обработку командной строки, но сохранить `-` (добавить его в `parser.largs`)

Если требуется опция, принимающая переменное число аргументов, нужно учитывать несколько тонких и коварных моментов. Конкретная реализация будет зависеть от того, на какие компромиссы вы готовы пойти ради своего приложения (именно поэтому `optparse` не поддерживает такие вещи напрямую).

Тем не менее, вот пример попытки создать колбэк для параметра с переменным числом аргументов:

```python
 def vararg_callback(option, opt_str, value, parser):
     assert value is None
     value = []

     def floatable(str):
         try:
             float(str)
             return True
         except ValueError:
             return False

     for arg in parser.rargs:
         # останавливаться на опциях вида --foo
         if arg[:2] == "--" and len(arg) > 2:
             break
         # останавливаться на -a, но не на -3 или -3.0
         if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
             break
         value.append(arg)

     del parser.rargs[:len(value)]
     setattr(parser.values, option.dest, value)

[...]
parser.add_option("-c", "--callback", dest="vararg_attr",
                  action="callback", callback=vararg_callback)
```

## 15.4.5. Расширение `optparse`

Поскольку двумя основными управляющими факторами, определяющими, как `optparse` интерпретирует опции командной строки, являются действие и тип каждой опции, наиболее вероятное направление расширения – добавление новых действий и новых типов.

### 15.4.5.1. Добавление новых типов

Чтобы добавить новые типы, нужно определить собственный подкласс класса `optparse` `Option`. Этот класс имеет несколько атрибутов, определяющих типы `optparse`: [`TYPES`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPES) и [`TYPE_CHECKER`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPE_CHECKER).

#### `Option.TYPES`

Кортеж имен типов; в вашем подклассе просто определите новый кортеж

[`TYPES`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPES)

, который расширяет стандартный.

#### `Option.TYPE_CHECKER`

Словарь, отображающий имена типов в функции проверки типа. Функция проверки типа имеет следующую сигнатуру:

```python
def check_mytype(option, opt, value)
```

где `option` – это экземпляр `Option`, `opt` – строка опции (например, `-f`), а `value` – строка из командной строки, которая должна быть проверена и преобразована в нужный тип. `check_mytype()` должна вернуть объект гипотетического типа `mytype`. Значение, возвращаемое функцией проверки типа, в конечном итоге окажется в экземпляре OptionValues, возвращаемом `OptionParser.parse_args()`, или будет передано колбэку как параметр `value`.

Ваша функция проверки типа должна вызывать `OptionValueError`, если она сталкивается с какими-либо проблемами. `OptionValueError` принимает один строковый аргумент, который передаётся как есть методу [`OptionParser`](https://python-all.ru/3.1/library/optparse.html#optparse.OptionParser)‘s `error()`, который, в свою очередь, добавляет имя программы и строку `"error:"` и выводит всё в stderr перед завершением процесса.

Вот глупый пример, демонстрирующий добавление типа опции `"complex"` для разбора комплексных чисел в стиле Python из командной строки. (Теперь это ещё глупее, чем раньше, потому что в `optparse` 1.3 уже есть встроенная поддержка комплексных чисел, но неважно.)

Сначала необходимые импорты:

```python
from copy import copy
from optparse import Option, OptionValueError
```

Сначала нужно определить вашу функцию проверки типа, так как на неё ссылаются позже (в атрибуте класса [`TYPE_CHECKER`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPE_CHECKER) вашего подкласса Option):

```python
def check_complex(option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))
```

Наконец, подкласс Option:

```python
class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex
```

(Если бы мы не сделали `copy()` от [`Option.TYPE_CHECKER`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPE_CHECKER), то в итоге изменили бы атрибут [`TYPE_CHECKER`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPE_CHECKER) класса `optparse` Option. В Python нет ничего, что помешало бы это сделать, кроме хороших манер и здравого смысла.)

Вот и всё! Теперь можно написать скрипт, использующий новый тип опций так же, как и любой другой скрипт на основе `optparse`, за исключением того, что нужно указать OptionParser использовать MyOption вместо Option:

```python
parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")
```

В качестве альтернативы можно составить собственный список опций и передать его OptionParser; если не использовать `add_option()` указанным выше способом, не нужно сообщать OptionParser, какой класс опций использовать:

```python
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
```

### 15.4.5.2. Добавление новых действий

Добавление новых действий немного сложнее, потому что нужно понимать, что у `optparse` есть несколько классификаций действий:

**«store»-действия**

действия, в результате которых

`optparse`

сохраняет значение в атрибуте текущего экземпляра OptionValues; для таких опций требуется указать атрибут

[`dest`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.dest)

в конструкторе Option.

**«typed»-действия**

действия, которые берут значение из командной строки и ожидают, что оно будет определённого типа; точнее, строка, которую можно преобразовать в определённый тип. Такие опции требуют атрибута

[`type`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.type)

в конструкторе Option.

Это пересекающиеся множества: некоторые действия «store» по умолчанию – `"store"`, `"store_const"`, `"append"` и `"count"`, в то время как действия «typed» по умолчанию – `"store"`, `"append"` и `"колбэк"`.

При добавлении действия его нужно отнести к категории, включив как минимум в один из следующих атрибутов класса Option (все они являются списками строк):

#### `Option.ACTIONS`

Все действия должны быть перечислены в ACTIONS.

#### `Option.STORE_ACTIONS`

«store»-действия дополнительно перечисляются здесь.

#### `Option.TYPED_ACTIONS`

«typed»-действия дополнительно перечисляются здесь.

#### `Option.ALWAYS_TYPED_ACTIONS`

Действия, которые всегда требуют тип (т.е. опции которых всегда принимают значение), дополнительно перечислены здесь. Единственный эффект этого заключается в том, что

`optparse`

назначает тип по умолчанию,

`"string"`

, опциям без явного типа, чьё действие перечислено в

[`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS)

.

Чтобы реализовать новое действие, необходимо переопределить метод Option `take_action()` и добавить ветвь, распознающую это действие.

Например, добавим действие `"extend"`. Оно похоже на стандартное действие `"append"`, но вместо того, чтобы брать одно значение из командной строки и добавлять его в конец существующего списка, `"extend"` принимает несколько значений в одной строке с разделителями-запятыми и расширяет существующий список этими значениями. То есть, если `--names` – опция `"extend"` типа `"string"`, то командная строка

```python
--names=foo,bar --names blah --names ding,dong
```

приведёт к списку

```python
["foo", "bar", "blah", "ding", "dong"]
```

Снова определим подкласс Option:

```python
class MyOption(Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)

    def take_action(self, action, dest, opt, value, values, parser):
        if action == "extend":
            lvalue = value.split(",")
            values.ensure_value(dest, []).extend(lvalue)
        else:
            Option.take_action(
                self, action, dest, opt, value, values, parser)
```

Что следует отметить:

- `"extend"` одновременно ожидает значение в командной строке и сохраняет его, поэтому оно входит как в [`STORE_ACTIONS`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.STORE_ACTIONS), так и в [`TYPED_ACTIONS`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.TYPED_ACTIONS).
- чтобы `optparse` назначал тип по умолчанию `"string"` для действий `"extend"`, мы также помещаем действие `"extend"` в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.1/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).
- `MyOption.take_action()` реализует только это одно новое действие и передаёт управление обратно `Option.take_action()` для стандартных действий `optparse`.
- `values` – экземпляр класса optparse\_parser.Values, предоставляющий очень полезный метод `ensure_value()`. `ensure_value()` по сути [`getattr()`](https://python-all.ru/3.1/library/functions.html#getattr) с предохранительным клапаном; он вызывается как

  ```python
  values.ensure_value(attr, value)
  ```

  Если атрибут `attr` объекта `values` не существует или равен None, то ensure\_value() сначала устанавливает его в `value`, а затем возвращает value. Это очень удобно для таких действий, как `"extend"`, `"append"` и `"count"`, все они накапливают данные в переменной и ожидают, что эта переменная будет определённого типа (список для первых двух, целое число – для последнего). Использование `ensure_value()` означает, что скриптам, использующим ваше действие, не нужно беспокоиться об установке значения по умолчанию для соответствующих целевых опций; они могут просто оставить значение по умолчанию как None, и `ensure_value()` позаботится о правильной установке, когда это понадобится.