optparse.md

1> **Источник:** https://python-all.ru/3.3/library/optparse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 16.5. [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) – Парсер параметров командной строки89Устарело с версии 3.2: Модуль [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) устарел и не будет развиваться; разработка будет продолжена в модуле [`argparse`](https://python-all.ru/3.3/library/argparse.html#module-argparse).1011**Исходный код:** [Lib/optparse.py](https://python-all.ru/src/3.3/Lib/optparse.py)1213---1415[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) – более удобная, гибкая и мощная библиотека для разбора параметров командной строки, чем старый модуль [`getopt`](https://python-all.ru/3.3/library/getopt.html#module-getopt). [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) использует более декларативный стиль разбора командной строки: создаётся экземпляр [`OptionParser`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser), заполняется параметрами и выполняется разбор командной строки. [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) позволяет пользователям задавать параметры в традиционном синтаксисе GNU/POSIX, а также генерирует сообщения об использовании и справку.1617Вот пример использования [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) устанавливает атрибуты объекта `options`, возвращаемого `parse_args()`, на основе значений, указанных пользователем в командной строке. Когда `parse_args()` завершает разбор этой командной строки, `options.filename` будет равно `"outfile"`, а `options.verbose` будет `False`. [`optparse`](https://python-all.ru/3.3/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.3/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## 16.5.1. Предыстория6869[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) был специально спроектирован для поощрения создания программ с простыми и общепринятыми интерфейсами командной строки. Для этого он поддерживает только наиболее распространённый синтаксис и семантику командной строки, традиционно используемые в Unix. Если вы не знакомы с этими соглашениями, прочитайте этот раздел, чтобы ознакомиться с ними.7071### 16.5.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.3/library/optparse.html#module-optparse).8283Некоторые другие синтаксисы опций, которые встречались в мире, включают:8485- дефис, за которым следует несколько букв, например `-pf` (это *не* то же самое, что объединение нескольких опций в один аргумент)86- дефис, за которым следует целое слово, например `-file` (технически это эквивалентно предыдущему синтаксису, но они обычно не встречаются в одной программе)87- знак плюс, за которым следует одна буква, несколько букв или слово, например `+f`, `+rgb`88- косая черта, за которой следует буква, несколько букв или слово, например `/f`, `/file`8990Эти синтаксисы опций не поддерживаются [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) и никогда не будут. Это сделано намеренно: первые три нестандартны в любом окружении, а последний имеет смысл только если вы ориентируетесь исключительно на VMS, MS-DOS и/или Windows.9192**аргумент опции**9394аргумент, который следует за опцией, тесно связан с этой опцией и извлекается из списка аргументов вместе с ней. В [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) не поддерживает эту функцию.109110**позиционный аргумент**111112то, что осталось в списке аргументов после разбора опций, т.е. после того, как опции и их аргументы были разобраны и удалены из списка аргументов.113114**обязательная опция**115116опция, которая должна быть указана в командной строке; обратите внимание, что фраза «required option» внутренне противоречива в английском языке.117118[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)119120не препятствует реализации обязательных опций, но и не оказывает в этом особой помощи.121122Например, рассмотрим эту гипотетическую командную строку:123124```python125prog -v --report report.txt foo bar126```127128`-v` и `--report` – обе опции. Предполагая, что `--report` принимает один аргумент, `report.txt` является аргументом опции. `foo` и `bar` являются позиционными аргументами.129130### 16.5.1.2. Для чего нужны параметры?131132Опции используются для предоставления дополнительной информации для настройки или кастомизации выполнения программы. На всякий случай, если это не было очевидно: опции обычно *необязательны*. Программа должна нормально работать вообще без опций. (Выберите случайную программу из набора Unix или GNU. Может ли она работать вообще без опций и при этом иметь смысл? Основные исключения – `find`, `tar` и `dd` – все они являются мутантными чудаками, которые справедливо критикуются за нестандартный синтаксис и запутанные интерфейсы.)133134Многие хотят, чтобы в их программах были «обязательные опции». Подумайте об этом. Если это обязательно, значит, это *не необязательно*! Если есть информация, которая absolutely необходима вашей программе для успешного выполнения, для этого существуют позиционные аргументы.135136В качестве примера хорошего дизайна интерфейса командной строки рассмотрим скромную утилиту `cp` для копирования файлов. Не имеет особого смысла пытаться копировать файлы без указания назначения и хотя бы одного источника. Следовательно, `cp` завершается ошибкой, если запустить её без аргументов. Однако у неё гибкий, полезный синтаксис, который вообще не требует никаких опций:137138```python139cp SOURCE DEST140cp SOURCE ... DEST-DIR141```142143С этим можно зайти довольно далеко. Большинство реализаций `cp` предоставляют множество опций для точной настройки копирования: можно сохранять режим и время изменения, избегать следования симлинкам, спрашивать подтверждение перед перезаписью существующих файлов и т.д. Но ничто из этого не отвлекает от основной миссии `cp`, которая состоит в копировании одного файла в другой или нескольких файлов в другой каталог.144145### 16.5.1.3. Для чего нужны позиционные аргументы?146147Позиционные аргументы предназначены для тех частей информации, которые absolutely и однозначно необходимы вашей программе для работы.148149Хороший пользовательский интерфейс должен иметь как можно меньше абсолютных требований. Если вашей программе требуется 17 различных частей информации для успешного запуска, не имеет большого значения *как* вы получаете эту информацию от пользователя – большинство людей сдадутся и уйдут, так и не запустив программу. Это справедливо независимо от того, является ли интерфейс командной строкой, файлом конфигурации или графическим интерфейсом: если вы предъявляете столько требований к пользователям, большинство из них просто сдадутся.150151Короче говоря, старайтесь минимизировать объем информации, которую пользователи absolutely обязаны предоставить – используйте разумные значения по умолчанию, когда это возможно. Конечно, вы также хотите сделать свои программы достаточно гибкими. Для этого и нужны опции. Опять же, неважно, являются ли они записями в файле конфигурации, виджетами в диалоге «Настройки» графического интерфейса или опциями командной строки – чем больше опций вы реализуете, тем гибче становится ваша программа, и тем сложнее становится ее реализация. Слишком большая гибкость тоже имеет недостатки; слишком много опций может перегрузить пользователей и сделать ваш код гораздо сложнее в поддержке.152153## 16.5.2. Учебное пособие154155Хотя [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) довольно гибок и мощен, в большинстве случаев он также прост в использовании. В этом разделе рассматриваются шаблоны кода, общие для любой программы на основе [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse), что ожидать и что делать при встрече этой опции в командной строке.173174Обычно каждая опция имеет одну короткую и одну длинную строку опции, например:175176```python177parser.add_option("-f", "--file", ...)178```179180Вы можете определить любое количество коротких и длинных строк опций (включая ноль), при условии, что в целом есть хотя бы одна строка опции.181182Строки опций, передаваемые в [`OptionParser.add_option()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.add_option), фактически являются метками для опции, определённой этим вызовом. Для краткости мы часто будем ссылаться на *встречу опции* в командной строке; на самом деле [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) встречает *строки опций* и ищет по ним опции.183184После того как все опции определены, укажите [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.Option.action), [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) (назначение) и [`help`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.help). Из них [`action`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.action) является самым основным.198199### 16.5.2.1. Понимание действий параметров200201Действия сообщают [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse), что делать, когда он встречает опцию в командной строке. Существует фиксированный набор действий, встроенных в [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse); добавление новых действий – продвинутая тема, рассмотренная в разделе [*Extending optparse*](https://python-all.ru/3.3/library/optparse.html#optparse-extending-optparse). Большинство действий указывают [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) сохранить значение в некоторую переменную – например, взять строку из командной строки и сохранить её в атрибуте `options`.202203Если не указать действие опции, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) по умолчанию использует `store`.204205### 16.5.2.2. Действие store206207Самое распространённое действие опции – `store`, которое указывает [`optparse`](https://python-all.ru/3.3/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.3/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.3/library/optparse.html#module-optparse) видит строку опции `-f`, он потребляет следующий аргумент, `foo.txt`, и сохраняет его в `options.filename`. Итак, после этого вызова `parse_args()`, `options.filename` равно `"foo.txt"`.224225Некоторые другие типы опций, поддерживаемые [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) предполагает `string`. В сочетании с тем, что действие по умолчанию – `store`, это означает, что наш первый пример может быть гораздо короче:243244```python245parser.add_option("-f", "--file", dest="filename")246```247248Если не указать назначение, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) определяет разумное значение по умолчанию из строк опций: если первая длинная строка опции – `--foo-bar`, то назначение по умолчанию – `foo_bar`. Если длинных строк опций нет, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) смотрит на первую короткую строку опции: назначение по умолчанию для `-f` – `f`.249250[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) также включает встроенный тип `complex`. Добавление типов рассмотрено в разделе [*Extending optparse*](https://python-all.ru/3.3/library/optparse.html#optparse-extending-optparse).251252### 16.5.2.3. Обработка логических параметров (флагов)253254Флаговые опции – устанавливают переменную в true или false при обнаружении определённой опции – довольно распространены. [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) встречает `-v` в командной строке, он устанавливает `options.verbose` в `True`; когда он встречает `-q`, `options.verbose` устанавливается в `False`.264265### 16.5.2.4. Другие действия266267Некоторые другие действия, поддерживаемые [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse):268269**`"store_const"`**270271сохранить константное значение272273**`"append"`**274275добавить аргумент этой опции в список276277**`"count"`**278279увеличить счётчик на единицу280281**`\"колбэк\"`**282283вызвать указанную функцию284285Эти вопросы рассматриваются в разделе [*Справочное руководство*](https://python-all.ru/3.3/library/optparse.html#optparse-reference-guide), Справочное руководство и разделе [*Колбэки опций*](https://python-all.ru/3.3/library/optparse.html#optparse-option-callbacks).286287### 16.5.2.5. Значения по умолчанию288289Во всех приведённых выше примерах устанавливается некоторая переменная («назначение») при обнаружении определённых опций командной строки. Что произойдёт, если эти опции никогда не будут обнаружены? Поскольку мы не указали никаких значений по умолчанию, все они устанавливаются в `None`. Обычно это нормально, но иногда требуется больший контроль. [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) позволяет указать значение по умолчанию для каждого назначения, которое присваивается до разбора командной строки.290291Сначала рассмотрим пример verbose/quiet. Если мы хотим, чтобы [`optparse`](https://python-all.ru/3.3/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### 16.5.2.6. Формирование справки325326Способность [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) автоматически генерировать справочный текст и текст использования полезна для создания удобных интерфейсов командной строки. Всё, что нужно сделать, – указать значение [`help`](https://python-all.ru/3.3/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.3/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.3/library/optparse.html#module-optparse) завершает работу после вывода текста справки.)361362Здесь задействовано много механизмов, чтобы помочь [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) сгенерировать наилучшее возможное сообщение справки:363364- сценарий определяет собственное сообщение об использовании:365366  ```python367  usage = "usage: %prog [options] arg1 arg2"368  ```369370  [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) заменяет `%prog` в строке использования на имя текущей программы, т.е. `os.path.basename(sys.argv[0])`. Затем полученная строка выводится перед подробной справкой по опциям.371372  Если не указать строку использования, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) использует скучное, но разумное значение по умолчанию: `"Usage: %prog [options]"`, что подходит, если скрипт не принимает позиционные аргументы.373- каждая опция определяет строку справки и не беспокоится о переносе строк – [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) заботится о переносе строк и делает вывод справки аккуратным.374- Опции, принимающие значение, указывают на это в автоматически сгенерированном сообщении справки, например, для опции «mode»:375376  ```python377  -m MODE, --mode=MODE378  ```379380  Здесь «MODE» называется мета-переменной: она обозначает аргумент, который пользователь должен указать для `-m`/`--mode`. По умолчанию [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) преобразует имя переменной назначения в верхний регистр и использует его для мета-переменной. Иногда это не то, что нужно – например, опция `--filename` явно задаёт `metavar="FILE"`, в результате чего получается такое автоматически сгенерированное описание опции:381382  ```python383  -f FILE, --filename=FILE384  ```385386  Это важно не только для экономии места: написанный вручную текст справки использует мета-переменную `FILE`, чтобы подсказать пользователю, что существует связь между полуформальным синтаксисом `-f FILE` и неформальным семантическим описанием «write output to FILE». Это простой, но эффективный способ сделать текст справки гораздо понятнее и полезнее для конечных пользователей.387- Параметры, имеющие значение по умолчанию, могут включать `%default` в строку справки – [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) заменит его на [`str()`](https://python-all.ru/3.3/library/stdtypes.html#str) значения параметра по умолчанию. Если параметр не имеет значения по умолчанию (или значение по умолчанию равно `None`), `%default` раскрывается в `none`.388389#### 16.5.2.6.1. Группировка параметров390391При работе с большим количеством параметров удобно группировать их для лучшего вывода справки. [`OptionParser`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser) может содержать несколько групп параметров, каждая из которых может содержать несколько параметров.392393Группа параметров создается с помощью класса [`OptionGroup`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionGroup):394395#### `class optparse.OptionGroup(parser, title, description=None)`396397где398399- parser – это экземпляр [`OptionParser`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser), в который будет вставлена группа.400- title – это заголовок группы401- description (необязательно) – это подробное описание группы402403[`OptionGroup`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionGroup) наследуется от `OptionContainer` (как и [`OptionParser`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser)), поэтому метод `add_option()` можно использовать для добавления параметра в группу.404405После того как все параметры объявлены, группа добавляется в ранее определенный парсер с помощью метода [`OptionParser`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser) – `add_option_group()`.406407Продолжая с парсером, определенным в предыдущем разделе, добавить [`OptionGroup`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.OptionGroup), которому принадлежит строка короткого или длинного параметра *opt\_str* (например, `'-o'` или `'--option'`). Если такой [`OptionGroup`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionGroup) не найден, возвращает `None`.487488### 16.5.2.7. Вывод строки версии489490Подобно краткой строке использования, [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) автоматически добавляет параметр `--version` в ваш парсер. Если он встречает этот параметр в командной строке, он раскрывает строку `version` (заменяя `%prog`), выводит её в stdout и завершает работу.497498Например, если ваш скрипт называется `/usr/bin/foo`:499500```python501$ /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.3/library/optparse.html#optparse.OptionParser.print_usage), любое вхождение `%prog` в `self.version` заменяется на имя текущей программы. Ничего не делает, если `self.version` пусто или не определено.510511#### `OptionParser.get_version()`512513То же, что и [`print_version()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.print_version), но возвращает строку версии вместо её вывода.514515### 16.5.2.8. Как [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) обрабатывает ошибки516517Существует два широких класса ошибок, с которыми приходится иметь дело [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse): ошибки программиста и ошибки пользователя. Ошибки программиста – это обычно неверные вызовы [`OptionParser.add_option()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.add_option), например, недопустимые строки параметров, неизвестные атрибуты параметров, отсутствующие атрибуты и т.д. Они обрабатываются обычным образом: возбуждается исключение (`optparse.OptionError` или [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError)), и программа завершается с ошибкой.518519Обработка ошибок пользователя гораздо важнее, поскольку они гарантированно возникают независимо от стабильности вашего кода. [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) обрабатывает ошибку одинаково: выводит сообщение об использовании программы и сообщение об ошибке в стандартный поток ошибок и завершается с кодом ошибки 2.529530Рассмотрим первый пример выше, где пользователь передает `4x` параметру, который ожидает целое число:531532```python533$ /usr/bin/foo -n 4x534Usage: foo [options]535536foo: error: option -n: invalid integer value: '4x'537```538539Или когда пользователь вообще не передаёт значение:540541```python542$ /usr/bin/foo -n543Usage: foo [options]544545foo: error: -n option requires an argument546```547548Сообщения об ошибках, генерируемые [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse), всегда упоминают параметр, вызвавший ошибку; обязательно делайте то же самое при вызове `OptionParser.error()` из кода вашего приложения.549550Если поведение [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) по умолчанию при обработке ошибок не устраивает, нужно создать подкласс OptionParser и переопределить его методы `exit()` и/или `error()`.551552### 16.5.2.9. Собираем всё вместе553554Вот как обычно выглядят скрипты на основе [`optparse`](https://python-all.ru/3.3/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## 16.5.3. Справочное руководство581582### 16.5.3.1. Создание парсера583584Первый шаг при использовании [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) – создать экземпляр OptionParser.585586#### `class optparse.OptionParser(...)`587588Конструктор OptionParser не требует обязательных аргументов, но принимает ряд необязательных именованных аргументов. Их всегда следует передавать как именованные аргументы, т.е. не полагаться на порядок объявления аргументов.589590**`usage` (по умолчанию: `"%prog [options]"`)**591592Краткое описание использования, выводимое при некорректном запуске программы или при запросе справки. Когда593594[`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.OptionParser.add_option)627628после создания парсера.629630**`option_class` (по умолчанию: optparse.Option)**631632Класс, используемый при добавлении опций в парсер с помощью633634[`add_option()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.add_option)635636.637638**`version` (по умолчанию: `None`)**639640Строка версии, которая выводится, когда пользователь указывает опцию версии. Если передать истинное значение для641642`version`643644,645646[`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse-conflicts-between-options)667668.669670**`description` (по умолчанию: `None`)**671672Абзац текста с кратким обзором программы.673674[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)675676переформатирует этот абзац под текущую ширину терминала и выводит его, когда пользователь запрашивает справку (после677678`usage`679680, но перед списком опций).681682**`formatter` (по умолчанию: новый `IndentedHelpFormatter`)**683684Экземпляр optparse.HelpFormatter, используемый для вывода справки.685686[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)687688предоставляет два конкретных класса для этой цели: IndentedHelpFormatter и TitledHelpFormatter.689690**`add_help_option` (по умолчанию: `True`)**691692Если истинно,693694[`optparse`](https://python-all.ru/3.3/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### 16.5.3.2. Заполнение парсера731732Есть несколько способов наполнить парсер опциями. Предпочтительный – использовать [`OptionParser.add_option()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.add_option), как показано в разделе [*Tutorial*](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) может разделить Option на несколько классов, и `make_option()` будет выбирать подходящий класс для создания экземпляра. Не создавайте экземпляры Option напрямую.)750751### 16.5.3.3. Определение параметров752753Каждый экземпляр Option представляет набор синонимичных строк опций командной строки, например `-f` и `--file`. Можно указать любое количество коротких или длинных строк опций, но необходимо указать хотя бы одну общую строку опции.754755Канонический способ создания экземпляра `Option` – использовать метод `add_option()` класса [`OptionParser`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.Option.action), и он во многом определяет, какие другие атрибуты уместны или обязательны. Если передать неуместные атрибуты опции или не передать обязательные, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) возбуждает исключение `OptionError`, объясняющее ошибку.774775Атрибут *action* опции определяет, что делает [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) при обнаружении этой опции в командной строке. Стандартные действия опций, встроенные в [`optparse`](https://python-all.ru/3.3/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**`\"колбэк\"`**806807вызвать указанную функцию808809**`"help"`**810811вывести сообщение об использовании, включающее все опции и документацию к ним812813(Если не указать действие, по умолчанию используется `"store"`. Для этого действия можно также указать атрибуты опции [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest); см. [*Standard option actions*](https://python-all.ru/3.3/library/optparse.html#optparse-standard-option-actions).)814815Как видно, большинство действий сводится к сохранению или обновлению значения где-либо. [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) всегда создаёт для этого специальный объект, по традиции называемый `options` (он оказывается экземпляром `optparse.Values`). Аргументы опций (и различные другие значения) сохраняются как атрибуты этого объекта в соответствии с атрибутом опции [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) (назначение).816817Например, при вызове818819```python820parser.parse_args()821```822823одна из первых вещей, которую делает [`optparse`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse), увидев эту опцию, сделает эквивалент845846```python847options.filename = "foo"848```849850Атрибуты опции [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) почти так же важны, как [`action`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.action), но [`action`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.action) – единственный, который имеет смысл для *всех* опций.851852### 16.5.3.4. Атрибуты параметров853854Следующие атрибуты опции можно передать как именованные аргументы в [`OptionParser.add_option()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.add_option). Если передать атрибут опции, не имеющий отношения к конкретной опции, или не передать обязательный атрибут опции, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) возбуждает `OptionError`.855856#### `Option.action`857858(по умолчанию: `"store"`)859860Определяет поведение [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) при обнаружении этой опции в командной строке; доступные варианты описаны [*здесь*](https://python-all.ru/3.3/library/optparse.html#optparse-standard-option-actions).861862#### `Option.type`863864(по умолчанию: `"string"`)865866Тип аргумента, ожидаемый этой опцией (например, `"string"` или `"int"`); доступные типы опций описаны [*здесь*](https://python-all.ru/3.3/library/optparse.html#optparse-standard-option-types).867868#### `Option.dest`869870(по умолчанию: выводится из строк опций)871872Если действие опции подразумевает запись или изменение значения где-либо, это сообщает [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse), куда его записать: [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) задаёт атрибут объекта `options`, который [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) создаёт при разборе командной строки.873874#### `Option.default`875876Значение, которое следует использовать для назначения этой опции, если опция не обнаружена в командной строке. См. также [`OptionParser.set_defaults()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.set_defaults).877878#### `Option.nargs`879880(по умолчанию: 1)881882Сколько аргументов типа [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) должно быть потреблено при обнаружении этой опции. Если \> 1, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) сохранит кортеж значений в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest).883884#### `Option.const`885886Для действий, сохраняющих постоянное значение, – само это постоянное значение.887888#### `Option.choices`889890Для опций типа `"choice"` – список строк, из которых пользователь может выбирать.891892#### `Option.callback`893894Для опций с действием `"колбэк"` – вызываемый объект, который будет вызван при обнаружении этой опции. См. раздел [*Option Callbacks*](https://python-all.ru/3.3/library/optparse.html#optparse-option-callbacks) для получения подробностей об аргументах, передаваемых вызываемому объекту.895896#### `Option.callback_args`897898#### `Option.callback_kwargs`899900Дополнительные позиционные и именованные аргументы для передачи в `колбэк` после четырёх стандартных аргументов колбэка.901902#### `Option.help`903904Текст справки для этой опции, выводимый при перечислении всех доступных опций после того, как пользователь укажет опцию [`help`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse-tutorial) for an example.911912### 16.5.3.5. Стандартные действия параметров913914Различные действия опций имеют несколько разные требования и эффекты. У большинства действий есть несколько соответствующих атрибутов опции, которые можно указать, чтобы направлять поведение [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse); у некоторых есть обязательные атрибуты, которые необходимо указать для любой опции, использующей это действие.915916- `"store"` \[соответствующие: [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.choices)\]917918  За опцией должен следовать аргумент, который преобразуется в значение согласно [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) и сохраняется в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest). Если [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs) \> 1, из командной строки будет потреблено несколько аргументов; все они будут преобразованы согласно [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) и сохранены в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) как кортеж. См. раздел [*Стандартные типы опций*](https://python-all.ru/3.3/library/optparse.html#optparse-standard-option-types).919920  Если указан [`choices`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.choices) (список или кортеж строк), по умолчанию тип принимает значение `"choice"`.921922  Если [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) не указан, по умолчанию он принимает значение `"string"`.923924  Если [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) не указан, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) выводит назначение из первой длинной опции (например, `--foo-bar` означает `foo_bar`). Если длинных опций нет, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) выводит назначение из первой короткой опции (например, `-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.3/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.3/library/optparse.html#optparse.Option.const); относящиеся: [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest)\]947948  Значение [`const`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.const) сохраняется в [`dest`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) установит962963  ```python964  options.verbose = 2965  ```966- `"store_true"` \[относящиеся: [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest)\]967968  Частный случай `"store_const"`, который сохраняет истинное значение в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest).969- `"store_false"` \[относящиеся: [`dest`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.Option.type), [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest), [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs), [`choices`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.choices)\]980981  За опцией должен следовать аргумент, который добавляется в список [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest). Если значение по умолчанию для [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) не указано, автоматически создаётся пустой список, когда [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) впервые встречает эту опцию в командной строке. Если [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs) \> 1, потребляется несколько аргументов, и в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) добавляется кортеж длины [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs).982983  Значения по умолчанию для [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type) и [`dest`](https://python-all.ru/3.3/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.3/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.3/library/optparse.html#optparse.Option.const); относящиеся: [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest)\]10131014  Как `"store_const"`, но значение [`const`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.const) добавляется в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest); как и в случае `"append"`, [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest) по умолчанию равен `None`, и пустой список автоматически создаётся при первой встрече опции.1015- `"count"` \[относящиеся: [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest)\]10161017  Увеличивает целое число, хранящееся в [`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest). Если значение по умолчанию не указано, [`dest`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) делает эквивалент следующего:10261027  ```python1028  options.verbosity = 01029  options.verbosity += 11030  ```10311032  Каждое последующее появление `-v` приводит к10331034  ```python1035  options.verbosity += 11036  ```1037- `"колбэк"` \[обязательно: [`колбэк`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback); относящиеся: [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type), [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs), [`callback_args`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_args), [`callback_kwargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_kwargs)\]10381039  Вызывает функцию, указанную колбэком [`колбэк`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback), которая вызывается как10401041  ```python1042  func(option, opt_str, value, parser, *args, **kwargs)1043  ```10441045  Смотрите раздел [*Колбэки опций*](https://python-all.ru/3.3/library/optparse.html#optparse-option-callbacks) для подробностей.1046- `"help"`10471048  Выводит полное справочное сообщение для всех опций текущего анализатора опций. Справочное сообщение строится из строки `usage`, переданной конструктору OptionParser, и строки [`help`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.help), переданной каждой опции.10491050  Если для опции не указана строка [`help`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.help), она всё равно будет включена в справочное сообщение. Чтобы полностью исключить опцию, используйте специальное значение `optparse.SUPPRESS_HELP`.10511052  [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) автоматически добавляет опцию [`help`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.help) во все анализаторы опций, поэтому обычно не нужно создавать её вручную.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.3/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.3/library/optparse.html#module-optparse) завершает процесс с помощью `sys.exit(0)`.1083- `"version"`10841085  Выводит номер версии, переданный OptionParser, в stdout и завершает работу. Номер версии фактически форматируется и выводится методом `print_version()` класса OptionParser. Обычно это актуально только если аргумент `version` передан конструктору OptionParser. Как и в случае с опциями [`help`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.help), вам редко придётся создавать опции `version`, так как [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) добавляет их автоматически при необходимости.10861087### 16.5.3.6. Стандартные типы параметров10881089[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) имеет пять встроенных типов опций: `"string"`, `"int"`, `"choice"`, `"float"` и `"complex"`. Если требуется добавить новые типы опций, обратитесь к разделу [*Расширение optparse*](https://python-all.ru/3.3/library/optparse.html#optparse-extending-optparse).10901091Аргументы строковых опций никак не проверяются и не преобразуются: текст из командной строки сохраняется в целевом атрибуте (или передаётся колбэку) как есть.10921093Целочисленные аргументы (тип `"int"`) разбираются следующим образом:10941095- если число начинается с `0x`, оно разбирается как шестнадцатеричное число1096- если число начинается с `0`, оно разбирается как восьмеричное1097- если число начинается с `0b`, оно разбирается как двоичное число1098- в противном случае число разбирается как десятичное10991100Преобразование выполняется вызовом [`int()`](https://python-all.ru/3.3/library/functions.html#int) с соответствующим основанием (2, 8, 10 или 16). Если это не удаётся, [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) также завершится ошибкой, хотя и с более понятным сообщением.11011102Аргументы опций `"float"` и `"complex"` преобразуются напрямую с помощью [`float()`](https://python-all.ru/3.3/library/functions.html#float) и [`complex()`](https://python-all.ru/3.3/library/functions.html#complex), с аналогичной обработкой ошибок.11031104Опции `"choice"` являются подтипом опций `"string"`. Атрибут [`choices`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.choices) опции (последовательность строк) определяет множество допустимых аргументов опции. `optparse.check_choice()` сравнивает предоставленные пользователем аргументы с этим основным списком и возбуждает `OptionValueError`, если указана недопустимая строка.11051106### 16.5.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.3/library/optparse.html#module-optparse)11471148**`args`**11491150оставшиеся позиционные аргументы после обработки всех опций11511152Наиболее распространённый вариант использования – не указывать ни один из именованных аргументов. Если передать `values`, он будет изменяться повторными вызовами [`setattr()`](https://python-all.ru/3.3/library/functions.html#setattr) (примерно по одному на каждый аргумент опции, сохраняемый в её назначении) и возвращён методом `parse_args()`.11531154Если `parse_args()` встречает какие-либо ошибки в списке аргументов, он вызывает метод `error()` класса OptionParser с соответствующим сообщением об ошибке для конечного пользователя. Это в конечном итоге приводит к завершению процесса с кодом выхода 2 (традиционный код выхода Unix для ошибок командной строки).11551156### 16.5.3.8. Запросы и манипуляции с парсером параметров11571158Поведение парсера опций по умолчанию можно слегка настроить, а также можно заглянуть внутрь парсера и посмотреть, что там есть. OptionParser предоставляет несколько методов, которые в этом помогут:11591160#### `OptionParser.disable_interspersed_args()`11611162Настраивает разбор таким образом, чтобы остановиться на первом не-опционном аргументе. Например, если `-a` и `-b` – простые опции, не принимающие аргументов, [`optparse`](https://python-all.ru/3.3/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.3/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)`11911192If the [`OptionParser`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.OptionParser), raises [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError).11931194### 16.5.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.3/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.3/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.3/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.3/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.3/library/optparse.html#module-optparse) удаляет его, оставляя такой текст справки:12541255```python1256Options:1257  [...]1258  -n, --noisy   be noisy1259  --dry-run     new dry-run option1260```12611262### 16.5.3.10. Очистка12631264Экземпляры OptionParser имеют несколько циклических ссылок. Это не должно быть проблемой для сборщика мусора Python, но вы можете захотеть разорвать циклические ссылки явно, вызвав `destroy()` для вашего OptionParser после завершения работы с ним. Это особенно полезно в долго работающих приложениях, где большие графы объектов достижимы из вашего OptionParser.12651266### 16.5.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.3/library/optparse.html#optparse.OptionParser.print_usage), но возвращает строку использования вместо её вывода.12811282#### `OptionParser.set_defaults(dest=value, ...)`12831284Устанавливает значения по умолчанию для нескольких назначений параметров одновременно. Использование [`set_defaults()`](https://python-all.ru/3.3/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.3/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## 16.5.4. Колбэки опций13061307Когда встроенных действий и типов [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) недостаточно для ваших потребностей, у вас есть два варианта: расширить [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) или определить опцию с колбэком. Расширение [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) более универсально, но избыточно для многих простых случаев. Довольно часто простой колбэк – это всё, что нужно.13081309Определение опции-колбэка состоит из двух шагов:13101311- определите саму опцию, используя действие `"колбэк"`1312- написать колбэк – функцию (или метод), которая принимает как минимум четыре аргумента, как описано ниже13131314### 16.5.4.1. Определение колбэк-опции13151316Как всегда, самый простой способ определить опцию с колбэком – использовать метод [`OptionParser.add_option()`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser.add_option). Кроме [`action`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.action), единственным атрибутом опции, который необходимо указать, является `колбэк` – функция, которую нужно вызвать:13171318```python1319parser.add_option("-c", action="callback", callback=my_callback)1320```13211322`колбэк` – это функция (или другой вызываемый объект), поэтому вы должны уже определить `my_callback()` при создании этой опции с колбэком. В этом простом случае [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) даже не знает, принимает ли `-c` какие-либо аргументы, что обычно означает, что опция не принимает аргументов – одного лишь наличия `-c` в командной строке достаточно. Однако в некоторых обстоятельствах вы можете захотеть, чтобы ваш колбэк потреблял произвольное количество аргументов командной строки. Здесь написание колбэков становится сложным; это рассматривается далее в этом разделе.13231324[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) всегда передаёт четыре определённых аргумента вашему колбэку и будет передавать дополнительные аргументы, только если вы укажете их через [`callback_args`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_args) и [`callback_kwargs`](https://python-all.ru/3.3/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.3/library/optparse.html#optparse.Option.type)**13351336имеет своё обычное значение: как и для действий13371338`"store"`13391340или13411342`"append"`13431344, оно указывает13451346[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)13471348потребить один аргумент и преобразовать его в13491350[`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type)13511352. Однако, вместо сохранения преобразованного значения где-либо,13531354[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)13551356передаёт его вашей функции колбэка.13571358**[`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs)**13591360также имеет своё обычное значение: если он указан и \> 1,13611362[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)13631364будет потреблять13651366[`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs)13671368аргументов, каждый из которых должен быть преобразуемым в13691370[`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type)13711372. Затем он передаёт кортеж преобразованных значений вашему колбэку.13731374**[`callback_args`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_args)**13751376кортеж дополнительных позиционных аргументов, передаваемых колбэку13771378**[`callback_kwargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_kwargs)**13791380словарь дополнительных именованных аргументов, передаваемых колбэку13811382### 16.5.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.3/library/optparse.html#module-optparse)14251426будет ожидать аргумент, только если установлен14271428[`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type)14291430; тип14311432`value`14331434будет типом, подразумеваемым типом опции. Если14351436[`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type)14371438для этой опции равен14391440`None`14411442(аргумент не ожидается), то14431444`value`14451446будет14471448`None`14491450. Если14511452[`nargs`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse)15011502для хранения значений опций; вам не нужно возиться с глобальными переменными или замыканиями. Вы также можете получать доступ или изменять значение(-я) любых опций, уже встреченных в командной строке.15031504**`args`**15051506представляет собой кортеж произвольных позиционных аргументов, предоставленных через атрибут опции15071508[`callback_args`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_args)15091510.15111512**`kwargs`**15131514представляет собой словарь произвольных именованных аргументов, предоставленных через15151516[`callback_kwargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.callback_kwargs)15171518.15191520### 16.5.4.3. Порождение ошибок в колбэке15211522Функция обратного вызова должна вызывать `OptionValueError`, если возникли какие-либо проблемы с опцией или её аргументом(ами). [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) перехватывает это исключение и завершает программу, выводя сообщение об ошибке, которое вы предоставляете, в stderr. Ваше сообщение должно быть ясным, кратким, точным и содержать упоминание опции, вызвавшей ошибку. В противном случае пользователю будет трудно понять, что он сделал неправильно.15231524### 16.5.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### 16.5.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### 16.5.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### 16.5.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### 16.5.4.8. Пример колбэка 5: фиксированные аргументы15841585Ситуация становится чуть более интересной, когда вы определяете опции с обратным вызовом, принимающие фиксированное количество аргументов. Указание, что опция с колбэком принимает аргументы, аналогично определению опции `"store"` или `"append"`: если вы определяете [`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type), то опция принимает один аргумент, который должен быть преобразуем к этому типу; если вы дополнительно определяете [`nargs`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.nargs), то опция принимает [`nargs`](https://python-all.ru/3.3/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.3/library/optparse.html#module-optparse) берёт на себя потребление 3 аргументов и преобразование их в целые числа; всё, что вам нужно сделать, это сохранить их. (Или что-то ещё; очевидно, что для этого примера колбэк не нужен.)15991600### 16.5.4.9. Пример колбэка 6: переменные аргументы16011602Ситуация усложняется, когда вы хотите, чтобы опция принимала переменное количество аргументов. В этом случае вы должны написать колбэк, поскольку [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) не предоставляет встроенных возможностей для этого. И вам придётся разбираться с некоторыми тонкостями традиционного синтаксического анализа командной строки Unix, которые [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) обычно обрабатывает за вас. В частности, колбэки должны реализовывать обычные правила для голых аргументов `--` и `-`:16031604- как `--`, так и `-` могут быть аргументами параметра1605- голый `--` (если не является аргументом какого-либо параметра): остановить обработку командной строки и отбросить `--`1606- голый `-` (если не является аргументом какой-либо опции): остановить обработку командной строки, но сохранить `-` (добавить его в `parser.largs`)16071608Если вы хотите опцию, принимающую переменное количество аргументов, есть несколько тонких и хитрых моментов, о которых стоит побеспокоиться. Точная реализация, которую вы выберете, будет основываться на том, какие компромиссы вы готовы сделать для своего приложения (именно поэтому [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) не поддерживает такие вещи напрямую).16091610Тем не менее, вот пример попытки создать колбэк для параметра с переменным числом аргументов:16111612```python1613 def 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## 16.5.5. Расширение [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)16421643Поскольку двумя основными управляющими факторами того, как [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) интерпретирует параметры командной строки, являются действие и тип каждой опции, наиболее вероятное направление расширения – добавление новых действий и новых типов.16441645### 16.5.5.1. Добавление новых типов16461647Чтобы добавить новые типы, вам нужно определить свой собственный подкласс класса [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)‘s `Option`. Этот класс имеет пару атрибутов, которые определяют типы [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse): [`TYPES`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.TYPES) и [`TYPE_CHECKER`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.TYPE_CHECKER).16481649#### `Option.TYPES`16501651Кортеж имен типов; в вашем подклассе просто определите новый кортеж [`TYPES`](https://python-all.ru/3.3/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` принимает один строковый аргумент, который передаётся как есть методу [`OptionParser`](https://python-all.ru/3.3/library/optparse.html#optparse.OptionParser)‘s `error()`, который, в свою очередь, добавляет имя программы и строку `"error:"` и выводит всё в stderr перед завершением процесса.16641665Вот глупый пример, демонстрирующий добавление типа опции `"complex"` для разбора комплексных чисел в стиле Python из командной строки. (Это стало ещё глупее, чем было, потому что [`optparse`](https://python-all.ru/3.3/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.3/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.3/library/copy.html#module-copy) от [`Option.TYPE_CHECKER`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.TYPE_CHECKER), мы бы в итоге изменили атрибут [`TYPE_CHECKER`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.TYPE_CHECKER) класса [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)‘s Option class. Это же Python, ничто не мешает вам сделать это, кроме хорошего тона и здравого смысла.16951696Вот и всё! Теперь можно написать скрипт, который использует новый тип опции так же, как любой другой скрипт на основе [`optparse`](https://python-all.ru/3.3/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### 16.5.5.2. Добавление новых действий17111712Добавление новых действий немного сложнее, потому что нужно понимать, что [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) имеет несколько классификаций действий:17131714**«store»-действия**17151716действия, в результате которых17171718[`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse)17191720сохраняет значение в атрибут текущего экземпляра OptionValues; такие опции требуют передачи атрибута17211722[`dest`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.dest)17231724конструктору Option.17251726**«typed»-действия**17271728действия, которые берут значение из командной строки и ожидают, что оно будет определённого типа; точнее, строка, которую можно преобразовать в определённый тип. Такие опции требуют атрибута17291730[`type`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.type)17311732в конструкторе Option.17331734Это пересекающиеся множества: некоторые действия «store» по умолчанию – `"store"`, `"store_const"`, `"append"` и `"count"`, в то время как действия «typed» по умолчанию – `"store"`, `"append"` и `"колбэк"`.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.3/library/optparse.html#module-optparse) присваивает тип по умолчанию, `"string"`, опциям без явного типа, чьё действие указано в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).17531754Чтобы реализовать новое действие, необходимо переопределить метод Option `take_action()` и добавить ветвь, распознающую это действие.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.3/library/optparse.html#optparse.Option.STORE_ACTIONS), так и в [`TYPED_ACTIONS`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.TYPED_ACTIONS).1790- чтобы гарантировать, что [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse) присваивает тип по умолчанию `"string"` действиям `"extend"`, мы также помещаем действие `"extend"` в [`ALWAYS_TYPED_ACTIONS`](https://python-all.ru/3.3/library/optparse.html#optparse.Option.ALWAYS_TYPED_ACTIONS).1791- `MyOption.take_action()` реализует только это одно новое действие и возвращает управление `Option.take_action()` для стандартных действий [`optparse`](https://python-all.ru/3.3/library/optparse.html#module-optparse).1792- `values` – экземпляр класса optparse\_parser.Values, предоставляющий очень полезный метод `ensure_value()`. `ensure_value()` по сути [`getattr()`](https://python-all.ru/3.3/library/functions.html#getattr) с предохранительным клапаном; он вызывается как17931794  ```python1795  values.ensure_value(attr, value)1796  ```17971798  Если атрибут `attr` объекта `values` не существует или равен None, то ensure\_value() сначала устанавливает его в `value`, а затем возвращает value. Это очень удобно для таких действий, как `"extend"`, `"append"` и `"count"`, все они накапливают данные в переменной и ожидают, что эта переменная будет определённого типа (список для первых двух, целое число – для последнего). Использование `ensure_value()` означает, что скриптам, использующим ваше действие, не нужно беспокоиться об установке значения по умолчанию для соответствующих целевых опций; они могут просто оставить значение по умолчанию как None, и `ensure_value()` позаботится о правильной установке, когда это понадобится.1799