# `optparse` — Parser for command line options

Вихідний код: Lib/optparse.py

## Choosing an argument parsing library

The standard library includes three argument parsing libraries:

- `getopt`: a module that closely mirrors the procedural C `getopt` API. Included in the standard library since before the initial Python 1.0 release.

- `optparse`: a declarative replacement for `getopt` that provides equivalent functionality without requiring each application to implement its own procedural option parsing logic. Included in the standard library since the Python 2.3 release.

- `argparse`: a more opinionated alternative to `optparse` that provides more functionality by default, at the expense of reduced application flexibility in controlling exactly how arguments are processed. Included in the standard library since the Python 2.7 and Python 3.2 releases.

In the absence of more specific argument parsing design constraints, `argparse` is the recommended choice for implementing command line applications, as it offers the highest level of baseline functionality with the least application level code.

`getopt` is retained almost entirely for backwards compatibility reasons. However, it also serves a niche use case as a tool for prototyping and testing command line argument handling in `getopt`-based C applications.

`optparse` should be considered as an alternative to `argparse` in the following cases:

- an application is already using `optparse` and doesn’t want to risk the subtle behavioural changes that may arise when migrating to `argparse`

- the application requires additional control over the way options and positional parameters are interleaved on the command line (including the ability to disable the interleaving feature completely)

- the application requires additional control over the incremental parsing of command line elements (while `argparse` does support this, the exact way it works in practice is undesirable for some use cases)

- the application requires additional control over the handling of options which accept parameter values that may start with `-` (such as delegated options to be passed to invoked subprocesses)

- the application requires some other command line parameter processing behavior which `argparse` does not support, but which can be implemented in terms of the lower level interface offered by `optparse`

These considerations also mean that `optparse` is likely to provide a better foundation for library authors writing third party command line argument processing libraries.

As a concrete example, consider the following two command line argument parsing configurations, the first using `optparse`, and the second using `argparse`:

    import optparse

    if __name__ == '__main__':
        parser = optparse.OptionParser()
        parser.add_option('-o', '--output')
        parser.add_option('-v', dest='verbose', action='store_true')
        opts, args = parser.parse_args()
        process(args, output=opts.output, verbose=opts.verbose)

    import argparse

    if __name__ == '__main__':
        parser = argparse.ArgumentParser()
        parser.add_argument('-o', '--output')
        parser.add_argument('-v', dest='verbose', action='store_true')
        parser.add_argument('rest', nargs='*')
        args = parser.parse_args()
        process(args.rest, output=args.output, verbose=args.verbose)

The most obvious difference is that in the `optparse` version, the non-option arguments are processed separately by the application after the option processing is complete. In the `argparse` version, positional arguments are declared and processed in the same way as the named options.

However, the `argparse` version will also handle some parameter combination differently from the way the `optparse` version would handle them. For example (amongst other differences):

- supplying `-o -v` gives `output="-v"` and `verbose=False` when using `optparse`, but a usage error with `argparse` (complaining that no value has been supplied for `-o/--output`, since `-v` is interpreted as meaning the verbosity flag)

- similarly, supplying `-o --` gives `output="--"` and `args=()` when using `optparse`, but a usage error with `argparse` (also complaining that no value has been supplied for `-o/--output`, since `--` is interpreted as terminating the option processing and treating all remaining values as positional arguments)

- supplying `-o=foo` gives `output="=foo"` when using `optparse`, but gives `output="foo"` with `argparse` (since `=` is special cased as an alternative separator for option parameter values)

Whether these differing behaviors in the `argparse` version are considered desirable or a problem will depend on the specific command line application use case.

Дивись також

click is a third party argument processing library (originally based on `optparse`), which allows command line applications to be developed as a set of decorated command implementation functions.

Other third party libraries, such as typer or msgspec-click, allow command line interfaces to be specified in ways that more effectively integrate with static checking of Python type annotations.

## Вступ

`optparse` is a more convenient, flexible, and powerful library for parsing command-line options than the minimalist `getopt` module. `optparse` uses a more declarative style of command-line parsing: you create an instance of `OptionParser`, populate it with options, and parse the command line. `optparse` allows users to specify options in the conventional GNU/POSIX syntax, and additionally generates usage and help messages for you.

Here’s an example of using `optparse` in a simple script:

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

    (options, args) = parser.parse_args()

За допомогою цих кількох рядків коду користувачі вашого сценарію тепер можуть виконувати «звичайні дії» в командному рядку, наприклад:

    <yourscript> --file=outfile -q

As it parses the command line, `optparse` sets attributes of the `options` object returned by `parse_args()` based on user-supplied command-line values. When `parse_args()` returns from parsing this command line, `options.filename` will be `"outfile"` and `options.verbose` will be `False`. `optparse` supports both long and short options, allows short options to be merged together, and allows options to be associated with their arguments in a variety of ways. Thus, the following command lines are all equivalent to the above example:

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

Крім того, користувачі можуть запустити одну з таких команд:

    <yourscript> -h
    <yourscript> --help

and `optparse` will print out a brief summary of your script’s options:

    Usage: <yourscript> [options]

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

де значення yourscript визначається під час виконання (зазвичай із `sys.argv[0]`).

## Фон

`optparse` was explicitly designed to encourage the creation of programs with straightforward command-line interfaces that follow the conventions established by the `getopt()` family of functions available to C developers. To that end, it supports only the most common command-line syntax and semantics conventionally used under Unix. If you are unfamiliar with these conventions, reading this section will allow you to acquaint yourself with them.

### Термінологія

аргумент

  рядок, введений у командному рядку та переданий оболонкою до `execl()` або `execv()`. У Python аргументи є елементами `sys.argv[1:]` (`sys.argv[0]` це ім’я програми, що виконується). Оболонки Unix також використовують термін «слово».

  Час від часу бажано замінити список аргументів іншим, ніж `sys.argv[1:]`, тому ви повинні читати «аргумент» як «елемент `sys.argv[1:]` або деяких інший список надається замість `sys.argv[1:]`».

варіант

  an argument used to supply extra information to guide or customize the execution of a program. There are many different syntaxes for options; the traditional Unix syntax is a hyphen («-») followed by a single letter, e.g. `-x` or `-F`. Also, traditional Unix syntax allows multiple options to be merged into a single argument, e.g. `-x -F` is equivalent to `-xF`. The GNU project introduced `--` followed by a series of hyphen-separated words, e.g. `--file` or `--dry-run`. These are the only two option syntaxes provided by `optparse`.

  Деякі інші синтаксиси параметрів, які бачив світ, включають:

  - дефіс, за яким слідує кілька літер, напр. `-pf` (це не те саме, що кілька параметрів, об’єднаних в один аргумент)

  - дефіс, за яким іде ціле слово, напр. `-файл` (технічно це еквівалент попереднього синтаксису, але вони зазвичай не зустрічаються в одній програмі)

  - знак плюс, після якого йде одна літера, або кілька літер, або слово, напр. `+f`, `+rgb`

  - косу риску, за якою йде літера, або кілька літер, або слово, напр. `/f`, `/file`

  These option syntaxes are not supported by `optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, and the last only makes sense if you’re exclusively targeting Windows or certain legacy platforms (e.g. VMS, MS-DOS).

аргумент опції

  an argument that follows an option, is closely associated with that option, and is consumed from the argument list when that option is. With `optparse`, option arguments may either be in a separate argument from their option:

      -f foo
      --file foo

  або включено в той самий аргумент:

      -ffoo
      --file=foo

  Typically, a given option either takes an argument or it doesn’t. Lots of people want an «optional option arguments» feature, meaning that some options will take an argument if they see it, and won’t if they don’t. This is somewhat controversial, because it makes parsing ambiguous: if `-a` takes an optional argument and `-b` is another option entirely, how do we interpret `-ab`? Because of this ambiguity, `optparse` does not support this feature.

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

  щось, що залишилося в списку аргументів після аналізу параметрів, тобто після аналізу параметрів і їхніх аргументів і видалення зі списку аргументів.

необхідна опція

  an option that must be supplied on the command-line; note that the phrase «required option» is self-contradictory in English. `optparse` doesn’t prevent you from implementing required options, but doesn’t give you much help at it either.

Наприклад, розглянемо цей гіпотетичний командний рядок:

    prog -v --report report.txt foo bar

`-v` і `--report` є варіантами. Якщо припустити, що `--report` приймає один аргумент, `report.txt` є аргументом опції. `foo` і `bar` є позиційними аргументами.

### Для чого існують варіанти?

Параметри використовуються для надання додаткової інформації для налаштування або налаштування виконання програми. Якщо це було незрозуміло, параметри зазвичай необов’язкові. Програма повинна нормально працювати без будь-яких опцій. (Виберіть випадкову програму з наборів інструментів Unix або GNU. Чи може вона запускатися взагалі без будь-яких параметрів і мати сенс? Основними винятками є `find`, `tar` і `dd`– - усі вони є диваками-мутантами, яких справедливо критикували за нестандартний синтаксис і заплутані інтерфейси.)

Багато людей хочуть, щоб їхні програми мали «необхідні параметри». Подумай над цим. Якщо це потрібно, то це не обов’язково! Якщо є частина інформації, яка абсолютно необхідна вашій програмі для успішної роботи, це те, для чого потрібні позиційні аргументи.

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

    cp SOURCE DEST
    cp SOURCE ... DEST-DIR

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

### Для чого потрібні позиційні аргументи?

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

Хороший інтерфейс користувача повинен мати якомога менше абсолютних вимог. Якщо ваша програма потребує 17 окремих фрагментів інформації для успішної роботи, не має великого значення як ви отримуєте цю інформацію від користувача — більшість людей здадуться та підуть, перш ніж вони успішно запустять програму. Це стосується незалежно від того, чи є інтерфейс користувача командним рядком, файлом конфігурації чи графічним інтерфейсом користувача: якщо ви поставите стільки вимог до своїх користувачів, більшість із них просто здадуться.

Коротше кажучи, намагайтеся мінімізувати кількість інформації, яку користувачі абсолютно зобов’язані надавати — використовуйте розумні значення за замовчуванням, коли це можливо. Звичайно, ви також хочете зробити свої програми досить гнучкими. Для цього і потрібні варіанти. Знову ж таки, не має значення, чи це записи у конфігураційному файлі, віджети в діалоговому вікні «Параметри» графічного інтерфейсу користувача чи параметри командного рядка — чим більше параметрів ви застосовуєте, тим гнучкішою є ваша програма, і ускладнюється його реалізація. Занадто велика гнучкість також має недоліки, звичайно; занадто багато параметрів може перевантажити користувачів і зробити ваш код набагато складнішим для підтримки.

## Підручник

While `optparse` is quite flexible and powerful, it’s also straightforward to use in most cases. This section covers the code patterns that are common to any `optparse`-based program.

По-перше, вам потрібно імпортувати клас OptionParser; потім на початку основної програми створіть екземпляр OptionParser:

    from optparse import OptionParser
    ...
    parser = OptionParser()

Потім можна приступати до визначення варіантів. Основний синтаксис:

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

Each option has one or more option strings, such as `-f` or `--file`, and several option attributes that tell `optparse` what to expect and what to do when it encounters that option on the command line.

Як правило, кожен параметр матиме один короткий рядок параметра та один довгий рядок параметра, наприклад:

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

Ви можете визначати скільки завгодно коротких рядків параметрів і скільки завгодно довгих рядків параметрів (включаючи нуль), за умови, що є принаймні один рядок параметрів.

The option strings passed to `OptionParser.add_option()` are effectively labels for the option defined by that call. For brevity, we will frequently refer to encountering an option on the command line; in reality, `optparse` encounters option strings and looks up options from them.

Once all of your options are defined, instruct `optparse` to parse your program’s command line:

    (options, args) = parser.parse_args()

(If you like, you can pass a custom argument list to `parse_args()`, but that’s rarely necessary: by default it uses `sys.argv[1:]`.)

`parse_args()` returns two values:

- `options`, об’єкт, що містить значення для всіх ваших параметрів — напр. якщо `--file` приймає один рядковий аргумент, `options.file` буде іменем файлу, наданим користувачем, або `None`, якщо користувач не вказав цей параметр

- `args`, список позиційних аргументів, що залишилися після аналізу параметрів

Цей розділ посібника охоплює лише чотири найважливіші атрибути параметрів: `action`, `type`, `dest` (призначення) і `help`. З них `action` є найбільш фундаментальним.

### Розуміння опціональних дій

Actions tell `optparse` what to do when it encounters an option on the command line. There is a fixed set of actions hard-coded into `optparse`; adding new actions is an advanced topic covered in section Extending optparse. Most actions tell `optparse` to store a value in some variable—for example, take a string from the command line and store it in an attribute of `options`.

If you don’t specify an option action, `optparse` defaults to `store`.

### Акція магазину

The most common option action is `store`, which tells `optparse` to take the next argument (or the remainder of the current argument), ensure that it is of the correct type, and store it to your chosen destination.

Наприклад:

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

Now let’s make up a fake command line and ask `optparse` to parse it:

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

When `optparse` sees the option string `-f`, it consumes the next argument, `foo.txt`, and stores it in `options.filename`. So, after this call to `parse_args()`, `options.filename` is `"foo.txt"`.

Some other option types supported by `optparse` are `int` and `float`. Here’s an option that expects an integer argument:

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

Зауважте, що цей параметр не має довгого рядка параметрів, що цілком прийнятно. Крім того, немає явної дії, оскільки за замовчуванням є `store`.

Давайте розберемо ще один підроблений командний рядок. Цього разу ми зіткнемося з аргументом option прямо проти параметра: оскільки `-n42` (один аргумент) еквівалентний `-n 42` (два аргументи), код

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

надрукує `42`.

If you don’t specify a type, `optparse` assumes `string`. Combined with the fact that the default action is `store`, that means our first example can be a lot shorter:

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

If you don’t supply a destination, `optparse` figures out a sensible default from the option strings: if the first long option string is `--foo-bar`, then the default destination is `foo_bar`. If there are no long option strings, `optparse` looks at the first short option string: the default destination for `-f` is `f`.

`optparse` also includes the built-in `complex` type. Adding types is covered in section Extending optparse.

### Обробка логічних параметрів (прапорів).

Flag options—set a variable to true or false when a particular option is seen—are quite common. `optparse` supports them with two separate actions, `store_true` and `store_false`. For example, you might have a `verbose` flag that is turned on with `-v` and off with `-q`:

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

Тут у нас є два різні варіанти з тим самим пунктом призначення, що цілком нормально. (Це лише означає, що ви повинні бути трохи обережними, встановлюючи значення за замовчуванням — див. нижче.)

When `optparse` encounters `-v` on the command line, it sets `options.verbose` to `True`; when it encounters `-q`, `options.verbose` is set to `False`.

### Інші дії

Some other actions supported by `optparse` are:

`"store_const"`

  store a constant value, pre-set via `Option.const`

`"додати"`

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

`"рахувати"`

  збільшити лічильник на одиницю

`"зворотний виклик"`

  викликати вказану функцію

Вони описані в розділі Довідковий посібник і розділі Опція зворотних викликів.

### Значення за замовчуванням

All of the above examples involve setting some variable (the «destination») when certain command-line options are seen. What happens if those options are never seen? Since we didn’t supply any defaults, they are all set to `None`. This is usually fine, but sometimes you want more control. `optparse` lets you supply a default value for each destination, which is assigned before the command line is parsed.

First, consider the verbose/quiet example. If we want `optparse` to set `verbose` to `True` unless `-q` is seen, then we can do this:

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

Оскільки значення за замовчуванням застосовуються до призначення, а не до будь-якого конкретного параметра, і ці два параметри мають одне призначення, це точно еквівалентно:

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

Розглянемо це:

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

Знову ж таки, значенням за замовчуванням для `verbose` буде `True`: останнє значення за замовчуванням, надане для будь-якого конкретного призначення, є тим, яке враховується.

A clearer way to specify default values is the `set_defaults()` method of OptionParser, which you can call at any time before calling `parse_args()`:

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

Як і раніше, зараховується останнє значення, указане для даного призначення опції. Для ясності спробуйте використовувати один або інший метод встановлення значень за замовчуванням, а не обидва.

### Створення довідки

`optparse`’s ability to generate help and usage text automatically is useful for creating user-friendly command-line interfaces. All you have to do is supply a `help` value for each option, and optionally a short usage message for your whole program. Here’s an OptionParser populated with user-friendly (documented) options:

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

If `optparse` encounters either `-h` or `--help` on the command-line, or if you just call `parser.print_help()`, it prints the following to standard output:

    Usage: <yourscript> [options] arg1 arg2

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

(If the help output is triggered by a help option, `optparse` exits after printing the help text.)

There’s a lot going on here to help `optparse` generate the best possible help message:

- сценарій визначає власне повідомлення про використання:

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

  `optparse` expands `%prog` in the usage string to the name of the current program, i.e. `os.path.basename(sys.argv[0])`. The expanded string is then printed before the detailed option help.

  If you don’t supply a usage string, `optparse` uses a bland but sensible default: `"Usage: %prog [options]"`, which is fine if your script doesn’t take any positional arguments.

- every option defines a help string, and doesn’t worry about line-wrapping—`optparse` takes care of wrapping lines and making the help output look good.

- options that take a value indicate this fact in their automatically generated help message, e.g. for the «mode» option:

      -m MODE, --mode=MODE

  Here, «MODE» is called the meta-variable: it stands for the argument that the user is expected to supply to `-m`/`--mode`. By default, `optparse` converts the destination variable name to uppercase and uses that for the meta-variable. Sometimes, that’s not what you want—for example, the `--filename` option explicitly sets `metavar="FILE"`, resulting in this automatically generated option description:

      -f FILE, --filename=FILE

  Однак це важливо не тільки для економії місця: написаний вручну текст довідки використовує мета-змінну `FILE`, щоб зрозуміти користувачеві, що існує зв’язок між напівформальним синтаксисом `-f FILE` і неформальний семантичний опис «записати вихід у ФАЙЛ». Це простий, але ефективний спосіб зробити ваш текст довідки набагато зрозумілішим і кориснішим для кінцевих користувачів.

- options that have a default value can include `%default` in the help string—`optparse` will replace it with `str()` of the option’s default value. If an option has no default value (or the default value is `None`), `%default` expands to `none`.

#### Параметри групування

Коли ви маєте справу з багатьма параметрами, зручно згрупувати ці параметри для кращого виведення довідки. `OptionParser` може містити кілька груп опцій, кожна з яких може містити кілька опцій.

Група опцій отримується за допомогою класу `OptionGroup`:

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

  де

  - parser — це екземпляр `OptionParser`, до якого буде вставлено групу

  - title — назва групи

  - description, необов’язковий, це довгий опис групи

`OptionGroup` успадковує `OptionContainer` (наприклад, `OptionParser`), тому метод `add_option()` можна використовувати для додавання опції до групи.

Після оголошення всіх опцій за допомогою методу `OptionParser` `add_option_group()` група додається до попередньо визначеного аналізатора.

Продовжуючи роботу з аналізатором, визначеним у попередньому розділі, додати `OptionGroup` до аналізатора легко:

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

Це призведе до наступного результату довідки:

    Usage: <yourscript> [options] arg1 arg2

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

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

        -g                  Group option.

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

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

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

що призводить до наступного результату:

    Usage: <yourscript> [options] arg1 arg2

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

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

        -g                  Group option.

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

Ще один цікавий метод, зокрема під час програмної роботи з групами параметрів:

OptionParser.get_option_group(opt_str)

  Повертає `OptionGroup`, до якої належить короткий або довгий рядок параметрів opt_str (наприклад, `'-o'` або `'--option'`). Якщо такої `OptionGroup` немає, поверніть `None`.

### Друк рядка версії

Similar to the brief usage string, `optparse` can also print a version string for your program. You have to supply the string as the `version` argument to OptionParser:

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

`%prog` is expanded just like it is in `usage`. Apart from that, `version` can contain anything you like. When you supply it, `optparse` automatically adds a `--version` option to your parser. If it encounters this option on the command line, it expands your `version` string (by replacing `%prog`), prints it to stdout, and exits.

Наприклад, якщо ваш скрипт називається `/usr/bin/foo`:

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

Наступні два методи можна використати для друку та отримання рядка `version`:

OptionParser.print_version(file=None)

  Вивести повідомлення про версію для поточної програми (`self.version`) у файл (стандартний вивід за замовчуванням). Як і у випадку з `print_usage()`, будь-яке входження `%prog` у `self.version` замінюється назвою поточної програми. Нічого не робить, якщо `self.version` порожній або невизначений.

OptionParser.get_version()

  Те саме, що `print_version()`, але повертає рядок версії замість її друку.

### How `optparse` handles errors

There are two broad classes of errors that `optparse` has to worry about: programmer errors and user errors. Programmer errors are usually erroneous calls to `OptionParser.add_option()`, e.g. invalid option strings, unknown option attributes, missing option attributes, etc. These are dealt with in the usual way: raise an exception (either `optparse.OptionError` or `TypeError`) and let the program crash.

Handling user errors is much more important, since they are guaranteed to happen no matter how stable your code is. `optparse` can automatically detect some user errors, such as bad option arguments (passing `-n 4x` where `-n` takes an integer argument), missing arguments (`-n` at the end of the command line, where `-n` takes an argument of any type). Also, you can call `OptionParser.error()` to signal an application-defined error condition:

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

In either case, `optparse` handles the error the same way: it prints the program’s usage message and an error message to standard error and exits with error status 2.

Розглянемо перший приклад вище, де користувач передає `4x` опції, яка приймає ціле число:

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

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

Або, коли користувач взагалі не може передати значення:

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

    foo: error: -n option requires an argument

`optparse`-generated error messages take care always to mention the option involved in the error; be sure to do the same when calling `OptionParser.error()` from your application code.

If `optparse`’s default error-handling behaviour does not suit your needs, you’ll need to subclass OptionParser and override its `exit()` and/or `error()` methods.

### Зібравши все разом

Here’s what `optparse`-based scripts usually look like:

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

    if __name__ == "__main__":
        main()

## Довідковий посібник

### Створення аналізатора

The first step in using `optparse` is to create an OptionParser instance.

class optparse.OptionParser(...)

  Конструктор OptionParser не має обов’язкових аргументів, але має декілька необов’язкових ключових аргументів. Ви завжди повинні передавати їх як аргументи ключового слова, тобто не покладайтеся на порядок, у якому оголошено аргументи.

  `використання` (за замовчуванням: `"%prog [параметри]"`)

    The usage summary to print when your program is run incorrectly or with a help option. When `optparse` prints the usage string, it expands `%prog` to `os.path.basename(sys.argv[0])` (or to `prog` if you passed that keyword argument). To suppress a usage message, pass the special value `optparse.SUPPRESS_USAGE`.

  `option_list` (за замовчуванням: `[]`)

    Список об’єктів Option для заповнення аналізатора. Опції в `option_list` додаються після будь-яких опцій в `standard_option_list` (атрибут класу, який може бути встановлений підкласами OptionParser), але перед будь-якою версією або опціями довідки. Застаріле; замість цього використовуйте `add_option()` після створення аналізатора.

  `option_class` (за замовчуванням: optparse.Option)

    Клас для використання під час додавання параметрів до аналізатора в `add_option()`.

  `version` (за замовчуванням: `None`)

    A version string to print when the user supplies a version option. If you supply a true value for `version`, `optparse` automatically adds a version option with the single option string `--version`. The substring `%prog` is expanded the same as for `usage`.

  `conflict_handler` (за замовчуванням: `"помилка"`)

    Вказує, що робити, коли параметри з конфліктуючими рядками параметрів додаються до аналізатора; див. розділ Конфлікти між варіантами.

  `опис` (за замовчуванням: `None`)

    A paragraph of text giving a brief overview of your program. `optparse` reformats this paragraph to fit the current terminal width and prints it when the user requests help (after `usage`, but before the list of options).

  `formatter` (за замовчуванням: новий `IndentedHelpFormatter`)

    An instance of optparse.HelpFormatter that will be used for printing help text. `optparse` provides two concrete classes for this purpose: IndentedHelpFormatter and TitledHelpFormatter.

  `add_help_option` (за замовчуванням: `True`)

    If true, `optparse` will add a help option (with option strings `-h` and `--help`) to the parser.

  `програма`

    Рядок для використання під час розширення `%prog` у `usage` і `version` замість `os.path.basename(sys.argv[0])`.

  `епілог` (за замовчуванням: `None`)

    Абзац тексту довідки для друку після довідки параметра.

### Заповнення аналізатора

Є кілька способів заповнити аналізатор параметрами. Кращим способом є використання `OptionParser.add_option()`, як показано в розділі Підручник. `add_option()` можна викликати одним із двох способів:

- передати йому екземпляр Option (як повертає `make_option()`)

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

Іншою альтернативою є передача списку попередньо сконструйованих екземплярів Option конструктору OptionParser, як у:

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

(`make_option()` is a factory function for creating Option instances; currently it is an alias for the Option constructor. A future version of `optparse` may split Option into several classes, and `make_option()` will pick the right class to instantiate. Do not instantiate Option directly.)

### Визначення варіантів

Кожен екземпляр Option представляє набір синонімічних рядків параметрів командного рядка, напр. `-f` і `--file`. Ви можете вказати будь-яку кількість коротких або довгих рядків параметрів, але ви повинні вказати принаймні один загальний рядок параметрів.

Канонічним способом створення екземпляра `Option` є метод `add_option()` `OptionParser`.

OptionParser.add_option(option)
OptionParser.add_option(*opt_str, attr=value, ...)

  Щоб визначити опцію лише за допомогою короткого рядка опції:

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

  І щоб визначити опцію лише з довгим рядком опції:

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

  The keyword arguments define attributes of the new Option object. The most important option attribute is `action`, and it largely determines which other attributes are relevant or required. If you pass irrelevant option attributes, or fail to pass required ones, `optparse` raises an `OptionError` exception explaining your mistake.

  An option’s action determines what `optparse` does when it encounters this option on the command-line. The standard option actions hard-coded into `optparse` are:

  `"магазин"`

    зберегти аргумент цього параметра (за замовчуванням)

  `"store_const"`

    store a constant value, pre-set via `Option.const`

  `"store_true"`

    зберігати `Правда`

  `"store_false"`

    зберігати `False`

  `"додати"`

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

  `"append_const"`

    append a constant value to a list, pre-set via `Option.const`

  `"рахувати"`

    збільшити лічильник на одиницю

  `"зворотний виклик"`

    викликати вказану функцію

  `"допомога"`

    роздрукувати повідомлення про використання, включно з усіма параметрами та документацією до них

  (Якщо ви не вказали дію, за замовчуванням буде `"store"`. Для цієї дії ви також можете вказати атрибути параметрів `type` і `dest` див. Стандартні опційні дії.)

As you can see, most actions involve storing or updating a value somewhere. `optparse` always creates a special object for this, conventionally called `options`, which is an instance of `optparse.Values`.

class optparse.Values

  An object holding parsed argument names and values as attributes. Normally created by calling when calling `OptionParser.parse_args()`, and can be overridden by a custom subclass passed to the values argument of `OptionParser.parse_args()` (as described in Розбір аргументів).

Option arguments (and various other values) are stored as attributes of this object, according to the `dest` (destination) option attribute.

Наприклад, коли ви дзвоните

    parser.parse_args()

one of the first things `optparse` does is create the `options` object:

    options = Values()

Якщо один із параметрів цього синтаксичного аналізатора визначено за допомогою

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

а командний рядок, що аналізується, містить будь-яке з наступного:

    -ffoo
    -f foo
    --file=foo
    --file foo

then `optparse`, on seeing this option, will do the equivalent of

    options.filename = "foo"

Атрибути `type` і `dest` майже такі ж важливі, як і `action`, але `action` є єдиним такий, який має сенс для всіх варіантів.

### Атрибути варіантів

class optparse.Option

  A single command line argument, with various attributes passed by keyword to the constructor. Normally created with `OptionParser.add_option()` rather than directly, and can be overridden by a custom class via the option_class argument to `OptionParser`.

The following option attributes may be passed as keyword arguments to `OptionParser.add_option()`. If you pass an option attribute that is not relevant to a particular option, or fail to pass a required option attribute, `optparse` raises `OptionError`.

Option.action

  (за замовчуванням: `"магазин"`)

  Determines `optparse`’s behaviour when this option is seen on the command line; the available options are documented here.

Option.type

  (за замовчуванням: `"рядок"`)

  Тип аргументу, очікуваний цією опцією (наприклад, `"string"` або `"int"`); доступні типи опцій задокументовані тут.

Option.dest

  (за замовчуванням: отримано з рядків параметрів)

  If the option’s action implies writing or modifying a value somewhere, this tells `optparse` where to write it: `dest` names an attribute of the `options` object that `optparse` builds as it parses the command line.

Option.default

  Значення для призначення цього параметра, якщо параметр не відображається в командному рядку. Дивіться також `OptionParser.set_defaults()`.

Option.nargs

  (за замовчуванням: 1)

  How many arguments of type `type` should be consumed when this option is seen. If > 1, `optparse` will store a tuple of values to `dest`.

Option.const

  Для дій, які зберігають постійне значення, постійне значення для збереження.

Option.choices

  Для параметрів типу `"вибір"`, список рядків, з яких користувач може вибрати.

Option.callback

  Для параметрів із дією `"callback"`, виклик якого потрібно викликати, коли цей параметр видно. Дивіться розділ Опція зворотних викликів для детальної інформації про аргументи, які передаються викликаному.

Option.callback_args
Option.callback_kwargs

  Додаткові позиційні та ключові аргументи для передачі в `callback` після чотирьох стандартних аргументів зворотного виклику.

Option.help

  Help text to print for this option when listing all available options after the user supplies a `help` option (such as `--help`). If no help text is supplied, the option will be listed without help text. To hide this option, use the special value `optparse.SUPPRESS_HELP`.

Option.metavar

  (за замовчуванням: отримано з рядків параметрів)

  Заміна аргументу(ів) опції для використання під час друку довідкового тексту. Перегляньте розділ Підручник для прикладу.

### Стандартні опційні дії

The various option actions all have slightly different requirements and effects. Most actions have several relevant option attributes which you may specify to guide `optparse`’s behaviour; a few have required attributes, which you must specify for any option using that action.

- `"магазин"` [релевантний: `type`, `dest`, `nargs`, `choices`]

  За параметром має слідувати аргумент, який перетворюється на значення відповідно до `type` і зберігається в `dest`. Якщо `nargs` > 1, з командного рядка буде використано кілька аргументів; усе буде перетворено відповідно до `type` і збережено в `dest` як кортеж. Перегляньте розділ Типи стандартних варіантів.

  Якщо надано `choices` (список або кортеж рядків), типом за замовчуванням є `"choice"`.

  Якщо `type` не вказано, за замовчуванням буде `"string"`.

  If `dest` is not supplied, `optparse` derives a destination from the first long option string (e.g., `--foo-bar` implies `foo_bar`). If there are no long option strings, `optparse` derives a destination from the first short option string (e.g., `-f` implies `f`).

  Приклад:

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

  Під час аналізу командного рядка

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

  `optparse` will set

      options.f = "foo.txt"
      options.point = (1.0, -3.5, 4.0)
      options.f = "bar.txt"

- `"store_const"` [потрібно: `const`; релевантний: `dest`]

  Значення `const` зберігається в `dest`.

  Приклад:

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

  If `--noisy` is seen, `optparse` will set

      options.verbose = 2

- `"store_true"` [релевантний: `dest`]

  Особливий випадок `"store_const"`, який зберігає `True` у `dest`.

- `"store_false"` [релевантний: `dest`]

  Подібно до `"store_true"`, але зберігає `False`.

  Приклад:

      parser.add_option("--clobber", action="store_true", dest="clobber")
      parser.add_option("--no-clobber", action="store_false", dest="clobber")

- `"append"` [релевантні: `type`, `dest`, `nargs`, `choices`]

  The option must be followed by an argument, which is appended to the list in `dest`. If no default value for `dest` is supplied, an empty list is automatically created when `optparse` first encounters this option on the command-line. If `nargs` > 1, multiple arguments are consumed, and a tuple of length `nargs` is appended to `dest`.

  Значення за замовчуванням для `type` і `dest` такі самі, як і для дії `"store"`.

  Приклад:

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

  If `-t3` is seen on the command-line, `optparse` does the equivalent of:

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

  Якщо трохи пізніше з’явиться `--tracks=4`, це так:

      options.tracks.append(int("4"))

  Дія `append` викликає метод `append` для поточного значення опції. Це означає, що будь-яке вказане значення за замовчуванням повинно мати метод `додавання`. Це також означає, що якщо значення за замовчуванням не є порожнім, елементи за замовчуванням будуть присутні в розібраному значенні для параметра, а будь-які значення з командного рядка будуть додані після цих значень за замовчуванням:

      >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
      >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
      >>> opts.files
      ['~/.mypkg/defaults', 'overrides.mypkg']

- `"append_const"` [потрібно: `const`; релевантний: `dest`]

  Як `"store_const"`, але значення `const` додається до `dest`; як і у випадку з `"append"`, `dest` за замовчуванням має значення `None`, і порожній список автоматично створюється, коли вперше зустрічається опція.

- `"count"` [relevant: `dest`]

  Збільшити ціле число, що зберігається в `dest`. Якщо значення за замовчуванням не вказано, `dest` встановлюється на нуль перед першим збільшенням.

  Приклад:

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

  The first time `-v` is seen on the command line, `optparse` does the equivalent of:

      options.verbosity = 0
      options.verbosity += 1

  Кожне наступне повторення `-v` призводить до:

      options.verbosity += 1

- `"callback"` [потрібно: `callback`; релевантні: `type`, `nargs`, `callback_args`, `callback_kwargs`]

  Виклик функції, визначеної `callback`, яка викликається як

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

  Дивіться розділ Опція зворотних викликів для більш детальної інформації.

- `"допомога"`

  Друкує повне довідкове повідомлення для всіх параметрів у поточному аналізаторі параметрів. Повідомлення довідки складається з рядка `usage`, переданого конструктору OptionParser, і рядка `help`, переданого кожному параметру.

  If no `help` string is supplied for an option, it will still be listed in the help message. To omit an option entirely, use the special value `optparse.SUPPRESS_HELP`.

  `optparse` automatically adds a `help` option to all OptionParsers, so you do not normally need to create one.

  Приклад:

      from optparse import OptionParser, SUPPRESS_HELP

      # usually, a help option is added automatically, but that can
      # be suppressed using the add_help_option argument
      parser = OptionParser(add_help_option=False)

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

  If `optparse` sees either `-h` or `--help` on the command line, it will print something like the following help message to stdout (assuming `sys.argv[0]` is `"foo.py"`):

      Usage: foo.py [options]

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

  After printing the help message, `optparse` terminates your process with `sys.exit(0)`.

- `"версія"`

  Prints the version number supplied to the OptionParser to stdout and exits. The version number is actually formatted and printed by the `print_version()` method of OptionParser. Generally only relevant if the `version` argument is supplied to the OptionParser constructor. As with `help` options, you will rarely create `version` options, since `optparse` automatically adds them when needed.

### Типи стандартних варіантів

`optparse` has five built-in option types: `"string"`, `"int"`, `"choice"`, `"float"` and `"complex"`. If you need to add new option types, see section Extending optparse.

Аргументи параметрів рядка не перевіряються та не перетворюються жодним чином: текст у командному рядку зберігається в місці призначення (або передається зворотному виклику) як є.

Цілі аргументи (тип `"int"`) аналізуються таким чином:

- якщо число починається з `0x`, воно аналізується як шістнадцяткове число

- якщо число починається з `0`, воно аналізується як вісімкове число

- якщо число починається з `0b`, воно аналізується як двійкове число

- інакше число аналізується як десяткове число

The conversion is done by calling `int()` with the appropriate base (2, 8, 10, or 16). If this fails, so will `optparse`, although with a more useful error message.

Аргументи параметрів `"float"` і `"complex"` перетворюються безпосередньо за допомогою `float()` і `complex()`, з подібною обробкою помилок.

Опції `"choice"` є підтипом опцій `"string"`. Атрибут опції `choices` (послідовність рядків) визначає набір дозволених аргументів опції. `optparse.check_choice()` порівнює аргументи параметрів, надані користувачем, із цим головним списком і викликає `OptionValueError`, якщо вказано недійсний рядок.

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

The whole point of creating and populating an OptionParser is to call its `parse_args()` method.

OptionParser.parse_args(args=None, values=None)

  Parse the command-line options found in args.

  The input parameters are

  `args`

    список аргументів для обробки (за замовчуванням: `sys.argv[1:]`)

  `значення`

    a `Values` object to store option arguments in (default: a new instance of `Values`) – if you give an existing object, the option defaults will not be initialized on it

  and the return value is a pair `(options, args)` where

  `параметри`

    the same object that was passed in as values, or the `optparse.Values` instance created by `optparse`

  `args`

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

The most common usage is to supply neither keyword argument. If you supply `values`, it will be modified with repeated `setattr()` calls (roughly one for every option argument stored to an option destination) and returned by `parse_args()`.

If `parse_args()` encounters any errors in the argument list, it calls the OptionParser’s `error()` method with an appropriate end-user error message. This ultimately terminates your process with an exit status of 2 (the traditional Unix exit status for command-line errors).

### Запити та маніпулювання вашим аналізатором параметрів

Поведінку аналізатора параметрів за замовчуванням можна дещо налаштувати, і ви також можете пошукати свій аналізатор параметрів і подивитися, що там є. OptionParser пропонує кілька методів, які допоможуть вам:

OptionParser.disable_interspersed_args()

  Set parsing to stop on the first non-option. For example, if `-a` and `-b` are both simple options that take no arguments, `optparse` normally accepts this syntax:

      prog -a arg1 -b arg2

  і розглядає його як еквівалент

      prog -a -b arg1 arg2

  Щоб вимкнути цю функцію, викличте `disable_interspersed_args()`. Це відновлює традиційний синтаксис Unix, де розбір параметрів припиняється з першим аргументом, що не є параметром.

  Використовуйте це, якщо у вас є командний процесор, який виконує іншу команду, яка має власні параметри, і ви хочете переконатися, що ці параметри не плутаються. Наприклад, кожна команда може мати різний набір параметрів.

OptionParser.enable_interspersed_args()

  Налаштуйте розбір так, щоб він не зупинявся на першому не-параметрі, дозволяючи вставляти перемикачі в аргументи команди. Це типова поведінка.

OptionParser.get_option(opt_str)

  Повертає екземпляр Option із рядком параметра opt_str або `None`, якщо параметри не мають такого рядка параметра.

OptionParser.has_option(opt_str)

  Повертає `True`, якщо OptionParser має параметр із рядком параметра opt_str (наприклад, `-q` або `--verbose`).

OptionParser.remove_option(opt_str)

  Якщо `OptionParser` має параметр, що відповідає opt_str, цей параметр буде видалено. Якщо цей параметр містить будь-які інші рядки параметрів, усі ці рядки параметрів стають недійсними. Якщо opt_str не зустрічається в жодному параметрі, що належить цьому `OptionParser`, викликає `ValueError`.

### Конфлікти між варіантами

Якщо ви не будете обережні, можна легко визначити параметри з конфліктуючими рядками параметрів:

    parser.add_option("-n", "--dry-run", ...)
    ...
    parser.add_option("-n", "--noisy", ...)

(Це особливо вірно, якщо ви визначили свій власний підклас OptionParser з деякими стандартними параметрами.)

Every time you add an option, `optparse` checks for conflicts with existing options. If it finds any, it invokes the current conflict-handling mechanism. You can set the conflict-handling mechanism either in the constructor:

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

або окремим дзвінком:

    parser.set_conflict_handler(handler)

Доступні засоби обробки конфліктів:

> `"помилка"` (за замовчуванням)

>   припустити, що конфлікти параметрів є помилкою програмування, і викликати `OptionConflictError`

> `"розв'язати"`

>   розумно вирішувати конфлікти варіантів (див. нижче)

Як приклад, давайте визначимо `OptionParser`, який розумно вирішує конфлікти, і додамо до нього конфліктуючі параметри:

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

At this point, `optparse` detects that a previously added option is already using the `-n` option string. Since `conflict_handler` is `"resolve"`, it resolves the situation by removing `-n` from the earlier option’s list of option strings. Now `--dry-run` is the only way for the user to activate that option. If the user asks for help, the help message will reflect that:

    Options:
      --dry-run     do no harm
      ...
      -n, --noisy   be noisy

It’s possible to whittle away the option strings for a previously added option until there are none left, and the user has no way of invoking that option from the command-line. In that case, `optparse` removes that option completely, so it doesn’t show up in help text or anywhere else. Carrying on with our existing OptionParser:

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

At this point, the original `-n`/`--dry-run` option is no longer accessible, so `optparse` removes it, leaving this help text:

    Options:
      ...
      -n, --noisy   be noisy
      --dry-run     new dry-run option

### Прибирати

Екземпляри OptionParser мають кілька циклічних посилань. Це не повинно бути проблемою для збирача сміття Python, але ви можете розірвати циклічні посилання явно, викликавши `destroy()` на вашому OptionParser, коли ви закінчите з цим. Це особливо корисно в довготривалих програмах, де великі об’єктні графіки доступні з вашого OptionParser.

### Інші методи

OptionParser підтримує кілька інших публічних методів:

OptionParser.set_usage(usage)

  Set the usage string according to the rules described above for the `usage` constructor keyword argument. Passing `None` sets the default usage string; use `optparse.SUPPRESS_USAGE` to suppress a usage message.

OptionParser.print_usage(file=None)

  Надрукувати повідомлення про використання для поточної програми (`self.usage`) у файл (стандартний вихід за замовчуванням). Будь-яке входження рядка `%prog` у `self.usage` замінюється назвою поточної програми. Нічого не робить, якщо `self.usage` порожній або не визначений.

OptionParser.get_usage()

  Те саме, що `print_usage()`, але повертає рядок використання замість його друку.

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

  Встановіть значення за замовчуванням для кількох пунктів призначення одночасно. Використання `set_defaults()` є кращим способом встановлення значень за замовчуванням для параметрів, оскільки кілька параметрів можуть мати одне призначення. Наприклад, якщо кілька параметрів «режиму» встановлюють одне й те саме призначення, будь-який із них може встановити значення за замовчуванням, і виграє останній:

      parser.add_option("--advanced", action="store_const",
                        dest="mode", const="advanced",
                        default="novice")    # overridden below
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice",
                        default="advanced")  # overrides above setting

  Щоб уникнути цієї плутанини, використовуйте `set_defaults()`:

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

## Опція зворотних викликів

When `optparse`’s built-in actions and types aren’t quite enough for your needs, you have two choices: extend `optparse` or define a callback option. Extending `optparse` is more general, but overkill for a lot of simple cases. Quite often a simple callback is all you need.

Існує два кроки, щоб визначити опцію зворотного виклику:

- визначте саму опцію за допомогою дії `"callback"`

- написати зворотний дзвінок; це функція (або метод), яка приймає щонайменше чотири аргументи, як описано нижче

### Визначення опції зворотного виклику

Як завжди, найпростішим способом визначення опції зворотного виклику є використання методу `OptionParser.add_option()`. Окрім `action`, єдиним атрибутом параметра, який ви повинні вказати, є `callback`, функція для виклику:

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

`callback` is a function (or other callable object), so you must have already defined `my_callback()` when you create this callback option. In this simple case, `optparse` doesn’t even know if `-c` takes any arguments, which usually means that the option takes no arguments—the mere presence of `-c` on the command-line is all it needs to know. In some circumstances, though, you might want your callback to consume an arbitrary number of command-line arguments. This is where writing callbacks gets tricky; it’s covered later in this section.

`optparse` always passes four particular arguments to your callback, and it will only pass additional arguments if you specify them via `callback_args` and `callback_kwargs`. Thus, the minimal callback function signature is:

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

Чотири аргументи зворотного виклику описані нижче.

Є кілька інших атрибутів опції, які ви можете надати, коли визначаєте опцію зворотного виклику:

`type`

  has its usual meaning: as with the `"store"` or `"append"` actions, it instructs `optparse` to consume one argument and convert it to `type`. Rather than storing the converted value(s) anywhere, though, `optparse` passes it to your callback function.

`nargs`

  also has its usual meaning: if it is supplied and > 1, `optparse` will consume `nargs` arguments, each of which must be convertible to `type`. It then passes a tuple of converted values to your callback.

`callback_args`

  кортеж додаткових позиційних аргументів для передачі зворотному виклику

`callback_kwargs`

  словник додаткових ключових аргументів для передачі зворотному виклику

### Як називаються зворотні виклики

Усі зворотні виклики викликаються наступним чином:

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

де

`опція`

  це екземпляр Option, який викликає зворотний виклик

`opt_str`

  це рядок параметрів, який можна побачити в командному рядку, який запускає зворотний виклик. (Якщо використовувався скорочений довгий параметр, `opt_str` буде повним, канонічним рядком параметра — наприклад, якщо користувач розміщує `--foo` у командному рядку як скорочення для `-- foobar`, тоді `opt_str` буде `"--foobar"`.)

`значення`

  is the argument to this option seen on the command-line. `optparse` will only expect an argument if `type` is set; the type of `value` will be the type implied by the option’s type. If `type` for this option is `None` (no argument expected), then `value` will be `None`. If `nargs` > 1, `value` will be a tuple of values of the appropriate type.

`парсер`

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

  `parser.largs`

    the current list of leftover arguments, ie. arguments that have been consumed but are neither options nor option arguments. Feel free to modify `parser.largs`, e.g. by adding more arguments to it. (This list will become `args`, the second return value of `parse_args()`.)

  `parser.rargs`

    поточний список аргументів, що залишилися, тобто. з вилученими параметрами `opt_str` і `value` (якщо застосовно), і залишаються лише наступні за ними аргументи. Не соромтеся змінити `parser.rargs`, напр. споживаючи більше аргументів.

  `parser.values`

    the object where option values are by default stored (an instance of optparse.OptionValues). This lets callbacks use the same mechanism as the rest of `optparse` for storing option values; you don’t need to mess around with globals or closures. You can also access or modify the value(s) of any options already encountered on the command-line.

`args`

  це кортеж довільних позиційних аргументів, що надаються через атрибут опції `callback_args`.

`кварги`

  це словник довільних аргументів ключових слів, які надаються через `callback_kwargs`.

### Викликання помилок у зворотному виклику

The callback function should raise `OptionValueError` if there are any problems with the option or its argument(s). `optparse` catches this and terminates the program, printing the error message you supply to stderr. Your message should be clear, concise, accurate, and mention the option at fault. Otherwise, the user will have a hard time figuring out what they did wrong.

### Приклад зворотного виклику 1: тривіальний зворотний виклик

Ось приклад опції зворотного виклику, яка не приймає аргументів і просто записує, що опцію було розглянуто:

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

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

Звичайно, ви можете зробити це за допомогою дії `"store_true"`.

### Приклад зворотного виклику 2: перевірте порядок варіантів

Ось трохи цікавіший приклад: зафіксуйте факт відображення `-a`, але роздуйте, якщо він стоїть після `-b` у командному рядку.

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

### Приклад зворотного виклику 3: перевірка порядку опцій (узагальнено)

If you want to reuse this callback for several similar options (set a flag, but blow up if `-b` has already been seen), it needs a bit of work: the error message and the flag that it sets must be generalized.

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

### Приклад зворотного виклику 4: перевірка довільної умови

Звичайно, ви можете поставити туди будь-яку умову — ви не обмежені перевіркою значень уже визначених параметрів. Наприклад, якщо у вас є опції, які не слід викликати в повний місяць, все, що вам потрібно зробити, це:

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

(Визначення `is_moon_full()` залишено як вправа для читача.)

### Приклад зворотного виклику 5: фіксовані аргументи

Справи стають трохи цікавішими, коли ви визначаєте параметри зворотного виклику, які приймають фіксовану кількість аргументів. Вказівка того, що опція зворотного виклику приймає аргументи, подібна до визначення опції `"store"` або `"append"`: якщо ви визначаєте `type`, тоді опція приймає один аргумент, який повинен бути конвертованим у цей тип; якщо ви далі визначаєте `nargs`, тоді параметр приймає аргументи `nargs`.

Ось приклад, який просто емулює стандартну дію `"store"`:

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

Note that `optparse` takes care of consuming 3 arguments and converting them to integers for you; all you have to do is store them. (Or whatever; obviously you don’t need a callback for this example.)

### Приклад зворотного виклику 6: змінні аргументи

Things get hairy when you want an option to take a variable number of arguments. For this case, you must write a callback, as `optparse` doesn’t provide any built-in capabilities for it. And you have to deal with certain intricacies of conventional Unix command-line parsing that `optparse` normally handles for you. In particular, callbacks should implement the conventional rules for bare `--` and `-` arguments:

- `--` або `-` можуть бути аргументами опції

- голий `--` (якщо не аргумент для якогось параметра): зупинити обробку командного рядка та відкинути `--`

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

If you want an option that takes a variable number of arguments, there are several subtle, tricky issues to worry about. The exact implementation you choose will be based on which trade-offs you’re willing to make for your application (which is why `optparse` doesn’t support this sort of thing directly).

Тим не менш, ось спроба зворотного виклику для опції зі змінними аргументами:

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

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

        for arg in parser.rargs:
            # stop on --foo like options
            if arg[:2] == "--" and len(arg) > 2:
                break
            # stop on -a, but not on -3 or -3.0
            if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
                break
            value.append(arg)

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

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

## Extending `optparse`

Since the two major controlling factors in how `optparse` interprets command-line options are the action and type of each option, the most likely direction of extension is to add new actions and new types.

### Додавання нових типів

To add new types, you need to define your own subclass of `optparse`’s `Option` class. This class has a couple of attributes that define `optparse`’s types: `TYPES` and `TYPE_CHECKER`.

Option.TYPES

  Кортеж імен типів; у своєму підкласі просто визначте новий кортеж `TYPES`, який базується на стандартному.

Option.TYPE_CHECKER

  Словник, що зіставляє назви типів із функціями перевірки типу. Функція перевірки типу має такий підпис:

      def check_mytype(option, opt, value)

  де `option` - це екземпляр `Option`, `opt` - це рядок параметра (наприклад, `-f`), а `value` - це рядок із командного рядка, який необхідно перевірити та перетворити на потрібний тип. `check_mytype()` має повертати об’єкт гіпотетичного типу `mytype`. Значення, повернуте функцією перевірки типу, з’явиться в екземплярі OptionValues, поверненому `OptionParser.parse_args()`, або буде передано зворотному виклику як параметр `value`.

  Ваша функція перевірки типу має викликати `OptionValueError`, якщо вона стикається з будь-якими проблемами. `OptionValueError` приймає один рядковий аргумент, який передається як є до методу `error()` `OptionParser`, який, у свою чергу, додає назву програми та рядок `"помилка: "` і друкує все в stderr перед завершенням процесу.

Here’s a silly example that demonstrates adding a `"complex"` option type to parse Python-style complex numbers on the command line. (This is even sillier than it used to be, because `optparse` 1.3 added built-in support for complex numbers, but never mind.)

По-перше, необхідний імпорт:

    from copy import copy
    from optparse import Option, OptionValueError

Спершу вам потрібно визначити свій засіб перевірки типів, оскільки на нього посилатимуться пізніше (в атрибуті класу `TYPE_CHECKER` вашого підкласу Option):

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

Нарешті, підклас Option:

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

(If we didn’t make a `copy()` of `Option.TYPE_CHECKER`, we would end up modifying the `TYPE_CHECKER` attribute of `optparse`’s Option class. This being Python, nothing stops you from doing that except good manners and common sense.)

That’s it! Now you can write a script that uses the new option type just like any other `optparse`-based script, except you have to instruct your OptionParser to use MyOption instead of Option:

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

Крім того, ви можете створити власний список параметрів і передати його в OptionParser; якщо ви не використовуєте `add_option()` вищезгаданим способом, вам не потрібно вказувати OptionParser, який клас параметрів використовувати:

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

### Додавання нових дій

Adding new actions is a bit trickier, because you have to understand that `optparse` has a couple of classifications for actions:

дії «магазину».

  actions that result in `optparse` storing a value to an attribute of the current OptionValues instance; these options require a `dest` attribute to be supplied to the Option constructor.

«набрані» дії

  дії, які беруть значення з командного рядка та очікують, що воно буде певного типу; точніше, рядок, який можна перетворити на певний тип. Для цих параметрів потрібен атрибут `type` конструктору Option.

Це набори, що перекриваються: деякі дії «зберігання» за замовчуванням - це `"store"`, `"store_const"`, `"append"` і `"count"`, а за замовчуванням «typed» « діями є `"зберігати"`, `"додавати"` і `"зворотний виклик"`.

Коли ви додаєте дію, вам потрібно класифікувати її, перерахувавши принаймні в одному з наступних атрибутів класу Option (усі є списками рядків):

Option.ACTIONS

  Усі дії мають бути вказані в ACTIONS.

Option.STORE_ACTIONS

  тут додатково перераховані дії «магазину».

Option.TYPED_ACTIONS

  «введені» дії додатково перераховані тут.

Option.ALWAYS_TYPED_ACTIONS

  Actions that always take a type (i.e. whose options always take a value) are additionally listed here. The only effect of this is that `optparse` assigns the default type, `"string"`, to options with no explicit type whose action is listed in `ALWAYS_TYPED_ACTIONS`.

Щоб фактично реалізувати вашу нову дію, ви повинні перевизначити метод `take_action()` Option і додати регістр, який розпізнає вашу дію.

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

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

призведе до списку

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

Знову ми визначаємо підклас Option:

    class MyOption(Option):

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

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

Примітка.

- `"extend"` очікує значення в командному рядку та десь зберігає це значення, тому воно входить і в `STORE_ACTIONS`, і в `TYPED_ACTIONS`.

- to ensure that `optparse` assigns the default type of `"string"` to `"extend"` actions, we put the `"extend"` action in `ALWAYS_TYPED_ACTIONS` as well.

- `MyOption.take_action()` implements just this one new action, and passes control back to `Option.take_action()` for the standard `optparse` actions.

- `values` є екземпляром класу optparse_parser.Values, який надає дуже корисний метод `ensure_value()`. `ensure_value()` це по суті `getattr()` із запобіжним клапаном; це називається як

      values.ensure_value(attr, value)

  If the `attr` attribute of `values` doesn’t exist or is `None`, then ensure_value() first sets it to `value`, and then returns `value`. This is very handy for actions like `"extend"`, `"append"`, and `"count"`, all of which accumulate data in a variable and expect that variable to be of a certain type (a list for the first two, an integer for the latter). Using `ensure_value()` means that scripts using your action don’t have to worry about setting a default value for the option destinations in question; they can just leave the default as `None` and `ensure_value()` will take care of getting it right when it’s needed.

## Винятки

exception optparse.OptionError

  Raised if an `Option` instance is created with invalid or inconsistent arguments.

exception optparse.OptionConflictError

  Raised if conflicting options are added to an `OptionParser`.

exception optparse.OptionValueError

  Raised if an invalid option value is encountered on the command line.

exception optparse.BadOptionError

  Raised if an invalid option is passed on the command line.

exception optparse.AmbiguousOptionError

  Raised if an ambiguous option is passed on the command line.