`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.

optparse — Parser for command line options¶