# `optparse` — Analisador sintático para opções de linha de comando

Código-fonte: Lib/optparse.py

Descontinuado desde a versão 3.2: O módulo `optparse` está descontinuado e não será mais desenvolvido; o desenvolvimento continuará com o módulo `argparse`.

`optparse` é uma biblioteca mais conveniente, flexível e poderosa para analisar opções de linha de comando do que o antigo módulo `getopt`. `optparse` usa um estilo mais declarativo de análise de linha de comando: você cria uma instância de `OptionParser`, preenche-a com opções e analisa a linha de comando. `optparse` permite que os usuários especifiquem opções na sintaxe convencional GNU/POSIX e, adicionalmente, gera mensagens de uso e ajuda para você.

Aqui está um exemplo de uso de `optparse` em um script simples:

    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()

Com essas poucas linhas de código, os usuários do seu script agora podem fazer “coisas comuns” na linha de comando, por exemplo:

    <seuscript> --file=outfile -q

Ao analisar a linha de comando, `optparse` define atributos do objeto `options` retornado por `parse_args()` com base nos valores de linha de comando fornecidos pelo usuário. Quando `parse_args()` retorna da análise desta linha de comando, `options.filename` será `"outfile"` e `options.verbose` será `False`. `optparse` provê as opções longas e curtas, permite que opções curtas sejam mescladas e permite que opções sejam associadas a seus argumentos de várias maneiras. Portanto, as seguintes linhas de comando são todas equivalentes ao exemplo acima:

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

Além disso, os usuários podem executar um dos seguintes:

    <seuscript> -h
    <seuscript> --help

e `optparse` vai exibir um breve resumo das opções do seu script:

    Usage: <seuscript> [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

onde o valor de seuscript é determinado em tempo de execução (normalmente de `sys.argv[0]`).

## Contexto

`optparse` foi explicitamente projetado para encorajar a criação de programas com interfaces de linha de comando diretas e convencionais. Para esse fim, ele provê apenas a sintaxe e a semântica de linha de comando mais comuns convencionalmente usadas no Unix. Se você não estiver familiarizado com essas convenções, leia esta seção para se familiarizar com elas.

### Terminologia

argumento

  uma string inserida na linha de comando e passada pelo shell para `execl()` ou `execv()`. Em Python, argumentos são elementos de `sys.argv[1:]` (`sys.argv[0]` é o nome do programa que está sendo executado). Shells Unix também usam o termo “word”.

  Ocasionalmente, é desejável substituir uma lista de argumentos diferente de `sys.argv[1:]`, então você deve ler “argumento” como “um elemento de `sys.argv[1:]`, ou de alguma outra lista fornecida como um substituto para `sys.argv[1:]`”.

opção

  um argumento usado para fornecer informações extras para guiar ou personalizar a execução de um programa. Existem muitas sintaxes diferentes para opções; a sintaxe tradicional do Unix é um hífen (“-”) seguido por uma única letra, por exemplo, `-x` ou `-F`. Além disso, a sintaxe tradicional do Unix permite que várias opções sejam mescladas em um único argumento, por exemplo, `-x -F` é equivalente a `-xF`. O projeto GNU introduziu `--` seguido por uma série de palavras separadas por hífen, por exemplo, `--file` ou `--dry-run`. Essas são as únicas duas sintaxes de opção fornecidas por `optparse`.

  Algumas outras sintaxes de opções que o mundo viu incluem:

  - um hífen seguido por algumas letras, por exemplo `-pf` (isso não é o mesmo que várias opções mescladas em um único argumento)

  - um hífen seguido por uma palavra completa, por exemplo `-file` (isso é tecnicamente equivalente à sintaxe anterior, mas eles geralmente não são vistos no mesmo programa)

  - um sinal de mais seguido por uma única letra, ou algumas letras, ou uma palavra, por exemplo `+f`, `+rgb`

  - uma barra seguida de uma letra, ou algumas letras, ou uma palavra, por exemplo `/f`, `/file`

  Essas sintaxes de opção não são suportadas por `optparse`, e nunca serão. Isso é proposital: as três primeiras não são padrão em nenhum ambiente, e a última só faz sentido se você estiver mirando exclusivamente no Windows ou em certas plataformas legadas (por exemplo, VMS, MS-DOS).

argumento de opção

  um argumento que segue uma opção, está intimamente associado a essa opção e é consumido da lista de argumentos quando essa opção é. Com `optparse`, os argumentos de opção podem estar em um argumento separado de sua opção:

      -f foo
      --file foo

  ou incluídos no mesmo argumento:

      -ffoo
      --file=foo

  Normalmente, uma opção dada ou aceita um argumento ou não. Muitas pessoas querem um recurso de “argumentos opcionais de opção”, o que significa que algumas opções aceitarão um argumento se o virem, e não aceitarão se não o virem. Isso é um tanto controverso, porque torna a análise ambígua: se `-a` aceita um argumento opcional e `-b` é outra opção inteiramente diferente, como interpretamos `-ab`? Por causa dessa ambiguidade, `optparse` não provê esse recurso.

argumento posicional

  algo que sobrou na lista de argumentos depois que as opções foram analisadas, ou seja, depois que as opções e seus argumentos foram analisados e removidos da lista de argumentos.

opção obrigatória

  uma opção que deve ser fornecida na linha de comando; observe que a frase “opção obrigatória” é autocontraditória em inglês. `optparse` não impede que você implemente opções obrigatórias, mas também não ajuda muito nisso.

Por exemplo, considere esta linha de comando hipotética:

    prog -v --report report.txt foo bar

`-v` e `--report` são ambas opções. Supondo que `--report` receba um argumento, `report.txt` é um argumento de opção. `foo` e `bar` são argumentos posicionais.

### Para que servem as opções?

As opções são usadas para fornecer informações extras para ajustar ou personalizar a execução de um programa. Caso não tenha ficado claro, as opções geralmente são opcionais. Um programa deve ser capaz de executar muito bem sem nenhuma opção. (Escolha um programa aleatório dos conjuntos de ferramentas Unix ou GNU. Ele pode ser executado sem nenhuma opção e ainda fazer sentido? As principais exceções são `find`, `tar` e `dd` — todos eles são mutantes excêntricos que foram corretamente criticados por sua sintaxe não padrão e interfaces confusas.)

Muitas pessoas querem que seus programas tenham “opções obrigatórias”. Pense nisso. Se é obrigatório, então não é opcional! Se há uma informação que seu programa absolutamente requer para ser executado com sucesso, é para isso que servem os argumentos posicionais.

Como um exemplo de bom design de interface de linha de comando, considere o humilde utilitário `cp`, para copiar arquivos. Não faz muito sentido tentar copiar arquivos sem fornecer um destino e pelo menos uma fonte. Portanto, `cp` falha se você executá-lo sem argumentos. No entanto, ele tem uma sintaxe flexível e útil que não requer nenhuma opção:

    cp ORIGEM DESTINO
    cp ORIGEM ... DIRETÓRIO

Você pode ir bem longe só com isso. A maioria das implementações de `cp` fornece um monte de opções para ajustar exatamente como os arquivos são copiados: você pode preservar o modo e o tempo de modificação, evitar seguir links simbólicos, perguntar antes de destruir arquivos existentes, etc. Mas nada disso distrai da missão principal de `cp`, que é copiar um arquivo para outro, ou vários arquivos para outro diretório.

### Para que servem os argumentos posicionais?

Argumentos posicionais são para aquelas informações que seu programa absolutamente e positivamente requer para ser executado.

Uma boa interface de usuário deve ter o mínimo de requisitos absolutos possível. Se seu programa requer 17 informações distintas para ser executado com sucesso, não importa muito como você obtém essas informações do usuário — a maioria das pessoas desistirá e irá embora antes de executar o programa com sucesso. Isso se aplica se a interface de usuário for uma linha de comando, um arquivo de configuração ou uma GUI: se você fizer tantas exigências aos seus usuários, a maioria deles simplesmente desistirá.

Em resumo, tente minimizar a quantidade de informações que os usuários são absolutamente obrigados a fornecer — use padrões sensatos sempre que possível. Claro, você também quer tornar seus programas razoavelmente flexíveis. É para isso que servem as opções. Novamente, não importa se são entradas em um arquivo de configuração, widgets no diálogo “Preferências” de uma GUI ou opções de linha de comando — quanto mais opções você implementar, mais flexível será seu programa e mais complicada se tornará sua implementação. Muita flexibilidade também tem desvantagens, é claro; muitas opções podem sobrecarregar os usuários e tornar seu código muito mais difícil de manter.

## Tutorial

Embora `optparse` seja bastante flexível e poderoso, ele também é simples de usar na maioria dos casos. Esta seção abrange os padrões de código que são comuns a qualquer programa baseado em `optparse`.

Primeiro, você precisa importar a classe OptionParser; então, no início do programa principal, crie uma instância de OptionParser:

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

Então você pode começar a definir opções. A sintaxe básica é:

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

Cada opção tem uma ou mais strings de opção, como `-f` ou `--file`, e vários atributos de opção que informam ao `optparse` o que esperar e o que fazer quando encontrar essa opção na linha de comando.

Normalmente, cada opção terá uma sequência de opções curta e uma sequência de opções longa, por exemplo:

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

Você tem a liberdade de definir quantas strings de opções curtas e longas quiser (incluindo zero), desde que haja pelo menos uma string de opção no geral.

As strings de opção passadas para `OptionParser.add_option()` são efetivamente rótulos para a opção definida por essa chamada. Para resumir, frequentemente nos referiremos a encontrar uma opção na linha de comando; na realidade, `optparse` encontra strings de opção e procura opções a partir delas.

Depois que todas as suas opções estiverem definidas, instrua `optparse` para analisar a linha de comando do seu programa:

    (options, args) = parser.parse_args()

(Se desejar, você pode passar uma lista de argumentos personalizada para `parse_args()`, mas isso raramente é necessário: por padrão, ele usa `sys.argv[1:]`.)

`parse_args()` retorna dois valores:

- `options`, um objeto que contém valores para todas as suas opções — por exemplo, se `--file` receber um único argumento de string, então `options.file` será o nome do arquivo fornecido pelo usuário, ou `None` se o usuário não forneceu essa opção

- `args`, a lista de argumentos posicionais restantes após a análise de opções

Esta seção do tutorial abrange apenas os quatro atributos de opção mais importantes: `action`, `type`, `dest` (destino) e `help`. Destes, `action` é o mais fundamental.

### Compreendendo as ações de opções

Ações dizem ao `optparse` o que fazer quando ele encontra uma opção na linha de comando. Há um conjunto fixo de ações codificadas em `optparse`; adicionar novas ações é um tópico avançado abordado na seção Estendendo optparse. A maioria das ações diz ao `optparse` para armazenar um valor em alguma variável — por exemplo, pegue uma string da linha de comando e armazene-a em um atributo de `options`.

Se você não especificar uma ação de opção, `optparse` assumirá como padrão `store`.

### A ação store

A ação de opção mais comum é `store`, que diz ao `optparse` para pegar o próximo argumento (ou o restante do argumento atual), garantir que seja do tipo correto e armazená-lo no destino escolhido.

Por exemplo:

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

Agora vamos criar uma linha de comando falsa e pedir ao `optparse` para analisá-la:

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

Quando `optparse` vê a string de opção `-f`, ele consome o próximo argumento, `foo.txt`, e o armazena em `options.filename`. Então, após essa chamada para `parse_args()`, `options.filename` é `"foo.txt"`.

Alguns outros tipos de opção suportados por `optparse` são `int` e `float`. Aqui está uma opção que espera um argumento inteiro:

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

Note que esta opção não tem uma string de opção longa, o que é perfeitamente aceitável. Além disso, não há nenhuma ação explícita, já que o padrão é `store`.

Vamos analisar outra linha de comando falsa. Desta vez, vamos colocar o argumento de opção bem perto da opção: já que `-n42` (um argumento) equivale a `-n 42` (dois argumentos), o código

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

vai exibir `42`.

Se você não especificar um tipo, `optparse` presume `string`. Combinado com o fato de que a ação padrão é `store`, isso significa que nosso primeiro exemplo pode ser muito mais curto:

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

Se você não fornecer um destino, `optparse` descobre um padrão sensato a partir das strings de opção: se a primeira string de opção longa for `--foo-bar`, então o destino padrão é `foo_bar`. Se não houver strings de opção longas, `optparse` olha para a primeira string de opção curta: o destino padrão para `-f` é `f`.

`optparse` também inclui o tipo `complex` embutido. Adicionar tipos é abordado na seção Estendendo optparse.

### Manipulando opções (sinalizadores) booleanas

Opções de sinalizador — define uma variável como true ou false quando uma opção específica é vista — são bem comuns. `optparse` suporta-as com duas ações separadas, `store_true` e `store_false`. Por exemplo, você pode ter um sinalizador `verbose` que é ativado com `-v` e desativado com `-q`:

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

Aqui temos duas opções diferentes com o mesmo destino, o que é perfeitamente OK. (Isso significa apenas que você tem que ter um pouco de cuidado ao definir valores padrão — veja abaixo.)

Quando `optparse` encontra `-v` na linha de comando, ele define `options.verbose` como `True`; quando encontra `-q`, `options.verbose` é definido como `False`.

### Outras ações

Algumas outras ações suportadas por `optparse` são:

`"store_const"`

  armazena um valor constante, predefinido via `Option.const`

`"append"`

  anexa o argumento desta opção a uma lista

`"count"`

  incrementa um contador em um

`"callback"`

  chama uma função especificada

Elas são abordadas na seção Guia de referência e na seção Funções de retorno de opção.

### Valores padrão

Todos os exemplos acima envolvem a configuração de alguma variável (o “destino”) quando certas opções de linha de comando são vistas. O que acontece se essas opções nunca forem vistas? Como não fornecemos nenhum padrão, todas elas são definidas como `None`. Isso geralmente é bom, mas às vezes você quer mais controle. `optparse` permite que você forneça um valor padrão para cada destino, que é atribuído antes da análise da linha de comando.

Primeiro, considere o exemplo de verbose/quiet. Se quisermos que `optparse` defina `verbose` como `True` a menos que `-q` seja visto, então podemos fazer isso:

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

Como os valores padrão se aplicam ao destino e não a qualquer opção específica, e essas duas opções têm o mesmo destino, isso é exatamente equivalente:

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

Considere isso:

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

Novamente, o valor padrão para `verbose` será `True`: o último valor padrão fornecido para qualquer destino específico é o que conta.

Uma maneira mais clara de especificar valores padrão é o método `set_defaults()` do OptionParser, que você pode chamar a qualquer momento antes de chamar `parse_args()`:

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

Como antes, o último valor especificado para um destino de opção dado é o que conta. Para maior clareza, tente usar um método ou outro de configuração de valores padrão, não ambos.

### Gerando texto de ajuda

A capacidade do `optparse` de gerar texto de ajuda e uso automaticamente é útil para criar interfaces de linha de comando amigáveis ao usuário. Tudo o que você precisa fazer é fornecer um valor `help` para cada opção e, opcionalmente, uma curta mensagem de uso para todo o seu programa. Aqui está um OptionParser preenchido com opções amigáveis (documentadas) ao usuário:

    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]")

Se `optparse` encontrar `-h` ou `--help` na linha de comando, ou se você apenas chamar `parser.print_help()`, ele exibe o seguinte na saída padrão:

    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]

(Se a saída de ajuda for acionada por uma opção de ajuda, `optparse` sai após imprimir o texto de ajuda.)

Há muita coisa acontecendo aqui para ajudar `optparse` a gerar a melhor mensagem de ajuda possível:

- o script define sua própria mensagem de uso:

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

  `optparse` expande `%prog` na string de uso para o nome do programa atual, ou seja, `os.path.basename(sys.argv[0])`. A string expandida é então exibida antes da ajuda detalhada da opção.

  Se você não fornecer uma string de uso, `optparse` usa um padrão simples, mas sensato: `"Usage: %prog [options]"`, o que é bom se seu script não aceita nenhum argumento posicional.

- cada opção define uma string de ajuda e não se preocupa com quebra de linha — `optparse` cuida da quebra de linhas e faz com que a saída de ajuda tenha uma boa aparência.

- opções que assumem um valor indicam esse fato em sua mensagem de ajuda gerada automaticamente, por exemplo, para a opção “mode”:

      -m MODE, --mode=MODE

  Aqui, “MODE” é chamado de metavariável: ele representa o argumento que o usuário deve fornecer para `-m`/`--mode`. Por padrão, `optparse` converte o nome da variável de destino para maiúsculas e usa isso para a metavariável. Às vezes, não é isso que você quer — por exemplo, a opção `--filename` define explicitamente `metavar="FILE"`, resultando nesta descrição de opção gerada automaticamente:

      -f FILE, --filename=FILE

  Isso é importante para mais do que apenas economizar espaço: o texto de ajuda escrito manualmente usa a metavariável `FILE` para dar uma pista ao usuário de que há uma conexão entre a sintaxe semiformal `-f FILE` e a descrição semântica informal como, por exemplo, “write output to FILE”. Essa é uma maneira simples, mas eficaz, de tornar seu texto de ajuda muito mais claro e útil para usuários finais.

- opções que têm um valor padrão podem incluir `%default` na string de ajuda — `optparse` vai substituí-lo por `str()` do valor padrão da opção. Se uma opção não tiver um valor padrão (ou o valor padrão for `None`), `%default` expande para `none`.

#### Agrupando opções

Ao lidar com muitas opções, é conveniente agrupar essas opções para melhor saída de ajuda. Um `OptionParser` pode conter vários grupos de opções, cada um dos quais pode conter várias opções.

Um grupo de opções é obtido usando a classe `OptionGroup`:

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

  onde

  - parser é a instância `OptionParser` na qual o grupo será inserido

  - title é o título do grupo

  - description, opcional, é uma descrição longa do grupo

`OptionGroup` herda de `OptionContainer` (como `OptionParser`) e, portanto, o método `add_option()` pode ser usado para adicionar uma opção ao grupo.

Depois que todas as opções são declaradas, usando o método `OptionParser` `add_option_group()` o grupo é adicionado ao analisador definido anteriormente.

Continuando com o analisador definido na seção anterior, adicionar um `OptionGroup` a um analisador é fácil:

    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)

Isso resultaria na seguinte saída de texto de ajuda:

    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.

Um exemplo um pouco mais completo pode envolver o uso de mais de um grupo: ainda estendendo o exemplo anterior:

    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)

que resulta na seguinte saída:

    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

Outro método interessante, especialmente ao trabalhar programaticamente com grupos de opções, é:

OptionParser.get_option_group(opt_str)

  Retorna o objeto `OptionGroup` ao qual a string de opção curta ou longa opt_str (por exemplo, `'-o'` ou `'--option'`) pertence. Se não houver tal `OptionGroup`, retorna `None`.

### Exibindo uma string de versão

Similar à string breve de uso, `optparse` também pode exibir uma string de versão para seu programa. Você tem que fornecer a string como o argumento `version` para OptionParser:

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

`%prog` é expandido assim como em `usage`. Além disso, `version` pode conter qualquer coisa que você quiser. Quando você o fornece, `optparse` adiciona automaticamente uma opção `--version` ao seu analisador. Se ele encontrar essa opção na linha de comando, ele expande sua string `version` (substituindo `%prog`), exibindo-a no stdout e sai.

Por exemplo, se o seu script for chamado `/usr/bin/foo`:

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

Os dois métodos a seguir podem ser usados para exibir e obter a string `version`:

OptionParser.print_version(file=None)

  Exibe a mensagem de versão para o programa atual (`self.version`) em file (stdout padrão). Assim como em `print_usage()`, qualquer ocorrência de `%prog` em `self.version` é substituída pelo nome do programa atual. Não faz nada se `self.version` estiver vazio ou indefinido.

OptionParser.get_version()

  O mesmo que `print_version()`, mas retorna a string da versão em vez de exibi-la.

### Como `optparse` trata erros

Existem duas classes amplas de erros com os quais `optparse` precisa se preocupar: erros do programador e erros do usuário. Erros do programador geralmente são chamadas errôneas para `OptionParser.add_option()`, por exemplo, strings de opção inválidas, atributos de opção desconhecidos, atributos de opção ausentes, etc. Eles são tratados da maneira usual: levanta uma exceção (seja `optparse.OptionError` ou `TypeError`) e deixe o programa travar.

Lidar com erros do usuário é muito mais importante, pois eles certamente acontecerão não importa quão estável seu código seja. `optparse` pode detectar automaticamente alguns erros do usuário, como argumentos de opção ruins (passando `-n 4x` onde `-n` recebe um argumento inteiro), argumentos ausentes (`-n` no final da linha de comando, onde `-n` recebe um argumento de qualquer tipo). Além disso, você pode chamar `OptionParser.error()` para sinalizar uma condição de erro definida pelo aplicativo:

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

Em ambos os casos, `optparse` lida com o erro da mesma maneira: ele imprime a mensagem de uso do programa e uma mensagem de erro no erro padrão e sai com o status de erro 2.

Considere o primeiro exemplo acima, onde o usuário passa `4x` para uma opção que aceita um inteiro:

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

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

Ou, quando o usuário não passa nenhum valor:

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

    foo: error: -n option requires an argument

As mensagens de erro geradas pelo `optparse` tomam o cuidado de sempre mencionar a opção envolvida no erro; certifique-se de fazer o mesmo ao chamar `OptionParser.error()` do código do sua aplicação.

Se o comportamento padrão de tratamento de erros do `optparse` não atender às suas necessidades, você precisará criar uma subclasse de OptionParser e substituir seus métodos `exit()` e/ou `error()`.

### Juntando tudo

Veja como os scripts baseados no `optparse` geralmente se parecem:

    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()

## Guia de referência

### Criando o analisador sintático

O primeiro passo para usar o `optparse` é criar uma instância de OptionParser.

class optparse.OptionParser(...)

  O construtor do OptionParser não tem argumentos obrigatórios, mas vários argumentos nomeados opcionais. Você deve sempre passá-los como argumentos nomeados, ou seja, não confie na ordem em que os argumentos são declarados.

  `usage` (padrão: `"%prog [options]"`)

    O resumo de uso para exibir quando seu programa é executado incorretamente ou com uma opção de ajuda. Quando `optparse` exibe a string de uso, ele expande `%prog` para `os.path.basename(sys.argv[0])` (ou para `prog` se você passou esse argumento nomeado). Para suprimir uma mensagem de uso, passe o valor especial `optparse.SUPPRESS_USAGE`.

  `option_list` (padrão: `[]`)

    Uma lista de objetos Option para preencher o analisador sintático. As opções em `option_list` são adicionadas após quaisquer opções em `standard_option_list` (um atributo de classe que pode ser definido por subclasses de OptionParser), mas antes de quaisquer opções de versão ou ajuda. Descontinuado; use `add_option()` após criar o analisador sintático.

  `option_class` (padrão: optparse.Option)

    Classe para usar ao adicionar opções ao analisador sintático em `add_option()`.

  `version` (padrão: `None`)

    Uma string de versão para exibir quando o usuário fornece uma opção de versão. Se você fornecer um valor true para `version`, `optparse` adiciona automaticamente uma opção de versão com a string de opção única `--version`. A substring `%prog` é expandida da mesma forma que para `usage`.

  `conflict_handler` (padrão: `"error"`)

    Especifica o que fazer quando opções com strings de opções conflitantes são adicionadas ao analisador sintático; consulte a seção Conflitos entre opções.

  `description` (padrão: `None`)

    Um parágrafo de texto que fornece uma breve visão geral do seu programa. `optparse` reformata este parágrafo para ajustá-lo à largura atual do terminal e o exibe quando o usuário solicita ajuda (depois de `usage`, mas antes da lista de opções).

  `formatter` (padrão: um novo `IndentedHelpFormatter`)

    Uma instância de optparse.HelpFormatter que será usada para exibir um texto de ajuda. `optparse` fornece duas classes concretas para essa finalidade: IndentedHelpFormatter e TitledHelpFormatter.

  `add_help_option` (padrão: `True`)

    Se verdadeiro, `optparse` adicionará uma opção de ajuda (com strings de opção `-h` e `--help`) ao analisador sintático.

  `prog`

    A string a ser usada ao expandir `%prog` em `usage` e `version` em vez de `os.path.basename(sys.argv[0])`.

  `epilog` (padrão: `None`)

    Um parágrafo de texto de ajuda para exibir após a ajuda da opção.

### Preenchendo o analisador sintático

Há várias maneiras de preencher o analisador sintático com opções. A maneira preferida é usando `OptionParser.add_option()`, como mostrado na seção Tutorial. `add_option()` pode ser chamado de uma das duas maneiras:

- passar uma instância de Option (conforme retornado por `make_option()`)

- passar qualquer combinação de argumentos nomeados e posicionais que sejam aceitáveis para `make_option()` (ou seja, para o construtor de Option), e ela criará a instância de Option para você

A outra alternativa é passar uma lista de instâncias de Option pré-construídas para o construtor de OptionParser, como em:

    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()` é uma função de fábrica para criar instâncias de Option; atualmente é um apelido para o construtor de Option. Uma versão futura de `optparse` pode dividir Option em várias classes, e `make_option()` escolherá a classe certa para instanciar. Não instancie Option diretamente.)

### Definindo as opções

Cada instância de Option representa um conjunto de strings de opções de linha de comando sinônimas, por exemplo, `-f` e `--file`. Você pode especificar qualquer número de strings de opções curtas ou longas, mas deve especificar pelo menos uma string de opção geral.

A maneira canônica de criar uma instância de `Option` é com o método `add_option()` de `OptionParser`.

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

  Para definir uma opção com apenas uma sequência de opções curta:

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

  E para definir uma opção com apenas uma longa sequência de opções:

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

  Os argumentos nomeados definem atributos do novo objeto Option. O atributo option mais importante é `action`, e ele determina amplamente quais outros atributos são relevantes ou obrigatórios. Se você passar atributos option irrelevantes, ou deixar de passar os obrigatórios, `optparse` levanta uma exceção `OptionError` explicando seu erro.

  A action de uma opção determina o que `optparse` faz quando encontra essa opção na linha de comando. As ações de opção padrão codificadas no `optparse` são:

  `"store"`

    armazena o argumento desta opção (padrão)

  `"store_const"`

    armazena um valor constante, predefinido via `Option.const`

  `"store_true"`

    armazena `True`

  `"store_false"`

    armazena `False`

  `"append"`

    anexa o argumento desta opção a uma lista

  `"append_const"`

    anexar um valor constante a uma lista, predefinido via `Option.const`

  `"count"`

    incrementa um contador em um

  `"callback"`

    chama uma função especificada

  `"help"`

    exibe uma mensagem de uso incluindo todas as opções e a documentação para elas

  (Se você não fornecer uma ação, o padrão é `"store"`. Para esta ação, você também pode fornecer os atributos de opção `type` e `dest`; consulte Ações de opção padrão.)

Como você pode ver, a maioria das ações envolve armazenar ou atualizar um valor em algum lugar. `optparse` sempre cria um objeto especial para isso, convencionalmente chamado de `options`, que é uma instância de `optparse.Values`.

class optparse.Values

  Um objeto que contém nomes e valores de argumentos analisados como atributos. Normalmente criado chamando ao chamar `OptionParser.parse_args()`, e pode ser substituído por uma subclasse personalizada passada para o argumento values de `OptionParser.parse_args()` (conforme descrito em Análise de argumentos).

Argumentos de opção (e vários outros valores) são armazenados como atributos deste objeto, de acordo com o atributo de opção `dest` (destino).

Por exemplo, quando você chama

    parser.parse_args()

uma das primeiras coisas que `optparse` faz é criar o objeto `options`:

    options = Values()

Se uma das opções neste analisador sintático for definida com

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

e a linha de comando que está sendo analisada inclui qualquer um dos seguintes:

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

então `optparse`, ao ver esta opção, fará o equivalente a

    options.filename = "foo"

Os atributos de opção `type` e `dest` são quase tão importantes quanto `action`, mas `action` é o único que faz sentido para todas as opções.

### Atributos da classe Option

class optparse.Option

  Um único argumento de linha de comando, com vários atributos passados como nomeados para o construtor. Normalmente criado com `OptionParser.add_option()` em vez de diretamente, e pode ser substituído por uma classe personalizada por meio do argumento option_class para `OptionParser`.

Os seguintes atributos de opção podem ser passados como argumentos nomeados para `OptionParser.add_option()`. Se você passar um atributo de opção que não seja relevante para uma opção específica, ou deixar de passar um atributo de opção obrigatório, `optparse` levanta `OptionError`.

Option.action

  (padrão: `"store"`)

  Determina o comportamento de `optparse` quando esta opção é vista na linha de comando; as opções disponíveis estão documentadas aqui.

Option.type

  (padrão: `"string"`)

  O tipo de argumento esperado por esta opção (por exemplo, `"string"` ou `"int"`); os tipos de opções disponíveis estão documentados aqui.

Option.dest

  (padrão: derivado de strings de opção)

  Se a ação da opção implicar escrever ou modificar um valor em algum lugar, isso informa ao `optparse` onde escrevê-lo: `dest` nomeia um atributo do objeto `options` que o `optparse` constrói ao analisar a linha de comando.

Option.default

  O valor para usar para o destino desta opção se a opção não for vista na linha de comando. Veja também `OptionParser.set_defaults()`.

Option.nargs

  (padrão: 1)

  Quantos argumentos do tipo `type` devem ser consumidos quando esta opção for vista. Se > 1, `optparse` armazenará uma tupla de valores em `dest`.

Option.const

  Para ações que armazenam um valor constante, o valor constante a ser armazenado.

Option.choices

  Para opções do tipo `"choice"`, a lista de strings que o usuário pode escolher.

Option.callback

  Para opções com ação `"callback"`, o chamável para chamar quando esta opção for vista. Veja a seção Funções de retorno de opção para detalhes sobre os argumentos passados para o chamável.

Option.callback_args
Option.callback_kwargs

  Argumentos nomeados e posicionais adicionais para passar para `callback` após os quatro argumentos de retorno de chamada padrão.

Option.help

  Texto de ajuda para exibir para esta opção ao listar todas as opções disponíveis após o usuário fornecer uma opção `help` (como `--help`). Se nenhum texto de ajuda for fornecido, a opção será listada sem texto de ajuda. Para ocultar esta opção, use o valor especial `optparse.SUPPRESS_HELP`.

Option.metavar

  (padrão: derivado de strings de opção)

  Substituto para o(s) argumento(s) de opção a ser(em) usado(s) ao exibir texto de ajuda. Veja a seção Tutorial para um exemplo.

### Ações de opção padrão

As várias ações de opção têm requisitos e efeitos ligeiramente diferentes. A maioria das ações tem vários atributos de opção relevantes que você pode especificar para guiar o comportamento de `optparse`; algumas têm atributos obrigatórios, que você deve especificar para qualquer opção que use essa ação.

- `"store"` [relevante: `type`, `dest`, `nargs`, `choices`]

  A opção deve ser seguida por um argumento, que é convertido em um valor de acordo com `type` e armazenado em `dest`. Se `nargs` > 1, vários argumentos serão consumidos da linha de comando; todos serão convertidos de acordo com `type` e armazenados em `dest` como uma tupla. Veja a seção Tipos de opção padrão.

  Se `choices` for fornecido (uma lista ou tupla de strings), o tipo padrão será `"choice"`.

  Se `type` não for fornecido, o padrão será `"string"`.

  Se `dest` não for fornecido, `optparse` deriva um destino da primeira string de opção longa (por exemplo, `--foo-bar` implica `foo_bar`). Se não houver strings de opção longas, `optparse` deriva um destino da primeira string de opção curta (por exemplo, `-f` implica `f`).

  Exemplo:

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

  Como ele analisa a linha de comando

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

  `optparse` vai definir

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

- `"store_const"` [obrigatório: `const`; relevante: `dest`]

  O valor de `const` é armazenado em `dest`.

  Exemplo:

      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")

  Se `--noisy` é encontrado, `optparse` vai definir

      options.verbose = 2

- `"store_true"` [relevante: `dest`]

  Um caso especial de `"store_const"` que armazena `True` em `dest`.

- `"store_false"` [relevante: `dest`]

  Como `"store_true"`, mas armazenad `False`.

  Exemplo:

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

- `"append"` [relevante: `type`, `dest`, `nargs`, `choices`]

  A opção deve ser seguida por um argumento, que é anexado à lista em `dest`. Se nenhum valor padrão para `dest` for fornecido, uma lista vazia será criada automaticamente quando `optparse` encontrar esta opção pela primeira vez na linha de comando. Se `nargs` > 1, vários argumentos serão consumidos e uma tupla de comprimento `nargs` será anexada a `dest`.

  Os padrões para `type` e `dest` são os mesmos da ação `"store"`.

  Exemplo:

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

  Se `-t3` for encontrado na linha de comando, `optparse` faz o equivalente a:

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

  Se, um pouco mais tarde, `--tracks=4` for encontrado, ele faz:

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

  A ação `append` chama o método `append` no valor atual da opção. Isso significa que qualquer valor padrão especificado deve ter um método `append`. Isso também significa que se o valor padrão não for vazio, os elementos padrão estarão presentes no valor analisado para a opção, com quaisquer valores da linha de comando anexados após esses valores padrão:

      >>> 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"` [obrigatório: `const`; relevante: `dest`]

  Como `"store_const"`, mas o valor de `const` é anexado a `dest`; assim como em `"append"`, `dest` assume como padrão `None`, e uma lista vazia é criada automaticamente na primeira vez que a opção é encontrada.

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

  Incrementa o inteiro armazenado em `dest`. Se nenhum valor padrão for fornecido, `dest` é definido como zero antes de ser incrementado pela primeira vez.

  Exemplo:

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

  A primeira vez que `-v` é encontrado na linha de comando, `optparse` faz o equivalente a:

      options.verbosity = 0
      options.verbosity += 1

  Cada ocorrência subsequente de `-v` resulta em

      options.verbosity += 1

- `"callback"` [obrigatório: `callback`; relevante: `type`, `nargs`, `callback_args`, `callback_kwargs`]

  Chama a função especificada por `callback`, que é chamada como

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

  Veja a seção Funções de retorno de opção para mais detalhes.

- `"help"`

  Exibe uma mensagem de ajuda completa para todas as opções no analisador sintático de opções atual. A mensagem de ajuda é construída a partir da string `usage` passada para o construtor do OptionParser e da string `help` passada para cada opção.

  Se nenhuma string de `help` for fornecida para uma opção, ela ainda será listada na mensagem de ajuda. Para omitir uma opção completamente, use o valor especial `optparse.SUPPRESS_HELP`.

  `optparse` adiciona automaticamente uma opção `help` a todos as instâncias de OptionParsers, então normalmente você não precisa criar uma.

  Exemplo:

      from optparse import OptionParser, SUPPRESS_HELP

      # geralmente, uma opção de ajuda é adicionada
      # automaticamente, mas que podem ser suprimida
      # usando o argumento add_help_option
      parser = OptionParser(add_help_option=False)

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

  Se `optparse` encontrar `-h` ou `--help` na linha de comando, ele vai exibir algo como a seguinte mensagem de ajuda no stdout (presumindo que `sys.argv[0]` é `"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

  Após exibir a mensagem de ajuda, `optparse` encerra seu processo com `sys.exit(0)`.

- `"version"`

  Exibe o número da versão fornecido à instância de OptionParser para stdout e sai. O número da versão é realmente formatado e exibido pelo método `print_version()` do OptionParser. Geralmente, é relevante somente se o argumento `version` for fornecido ao construtor de OptionParser. Assim como com as opções de `help`, você raramente criará opções `version`, já que `optparse` as adiciona automaticamente quando necessário.

### Tipos de opção padrão

`optparse` tem cinco tipos de opções embutidos: `"string"`, `"int"`, `"choice"`, `"float"` e `"complex"`. Se você precisar adicionar novos tipos de opções, veja a seção Estendendo optparse.

Os argumentos para opções de string não são verificados ou convertidos de forma alguma: o texto na linha de comando é armazenado no destino (ou passado para a função de retorno) como está.

Argumentos inteiros (tipo `"int"`) são analisados da seguinte forma:

- se o número começar com `0x`, ele será analisado como um número hexadecimal

- se o número começar com `0`, ele será analisado como um número octal

- se o número começar com `0b`, ele será analisado como um número binário

- caso contrário, o número é analisado como um número decimal

A conversão é feita chamando `int()` com a base apropriada (2, 8, 10 ou 16). Se isso falhar, `optparse` também falhará, embora com uma mensagem de erro mais útil.

Os argumentos de opção `"float"` e `"complex"` são convertidos diretamente com `float()` e `complex()`, com tratamento de erros semelhante.

As opções `"choice"` são um subtipo das opções `"string"`. O atributo da opção `choices` (uma sequência de strings) define o conjunto de argumentos de opção permitidos. `optparse.check_choice()` compara os argumentos de opção fornecidos pelo usuário com esta lista mestre e levanta `OptionValueError` se uma string inválida for fornecida.

### Análise de argumentos

O objetivo de criar e preencher uma instância de OptionParser é chamar seu método `parse_args()`.

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

  Analisa as opções de linha de comando encontradas em args.

  Os parâmetros de entrada são

  `args`

    a lista de argumentos para processar (padrão: `sys.argv[1:]`)

  `values`

    um objeto `Values` para armazenar argumentos de opção (padrão: uma nova instância de `Values`) – se você fornecer um objeto existente, os padrões de opção não serão inicializados nele

  e o valor de retorno é um par `(options, args)` sendo

  `options`

    o mesmo objeto que foi passado como values, ou a instância `optparse.Values` criada por `optparse`

  `args`

    os argumentos posicionais restantes depois que todas as opções foram processadas

O uso mais comum é não fornecer nenhum argumento nomeado. Se você fornecer `values`, ele será modificado com chamadas repetidas de `setattr()` (aproximadamente uma para cada argumento de opção armazenado em um destino de opção) e retornado por `parse_args()`.

Se `parse_args()` encontrar algum erro na lista de argumentos, ele chama o método `error()` da instância de OptionParser com uma mensagem de erro apropriada para o usuário final. Isso, em última análise, encerra seu processo com um status de saída 2 (o status de saída tradicional do Unix para erros de linha de comando).

### Consultando e manipulando seu analisador sintático de opções

O comportamento padrão do analisador sintático de opções pode ser ligeiramente personalizado, e você também pode dar uma olhada no seu analisador de opções e ver o que há lá. A classe OptionParser fornece vários métodos para ajudar você:

OptionParser.disable_interspersed_args()

  Define a análise para parar na primeira não opção. Por exemplo, se `-a` e `-b` forem ambas opções simples que não aceitam argumentos, `optparse` normalmente aceita esta sintaxe:

      prog -a arg1 -b arg2

  e trata-a como equivalente a

      prog -a -b arg1 arg2

  Para desabilitar esse recurso, chame `disable_interspersed_args()`. Isso restaura a sintaxe Unix tradicional, onde a análise de opções para com o primeiro argumento não-opcional.

  Use isto se você tiver um processador de comando que executa outro comando que tem opções próprias e você quer ter certeza de que essas opções não fiquem confusas. Por exemplo, cada comando pode ter um conjunto diferente de opções.

OptionParser.enable_interspersed_args()

  Define a análise para não parar na primeira não opção, permitindo intercalar alternadores com argumentos de comando. Esse é o comportamento padrão.

OptionParser.get_option(opt_str)

  Retorna a instância de Option com a string de opção opt_str, ou `None` se nenhuma opção tiver essa string de opção.

OptionParser.has_option(opt_str)

  Retorna `True` se o objeto OptionParser tiver uma opção com string de opção opt_str (por exemplo, `-q` ou `--verbose`).

OptionParser.remove_option(opt_str)

  Se o `OptionParser` tiver uma opção correspondente a opt_str, essa opção será removida. Se essa opção fornecer quaisquer outras strings de opção, todas essas strings de opção se tornarão inválidas. Se opt_str não ocorrer em nenhuma opção pertencente a este `OptionParser`, levanta `ValueError`.

### Conflitos entre opções

Se você não tomar cuidado, é fácil definir opções com strings de opções conflitantes:

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

(Isto é particularmente verdadeiro se você definiu sua própria subclasse de OptionParser com algumas opções padrão.)

Toda vez que você adiciona uma opção, `optparse` verifica se há conflitos com opções existentes. Se encontrar algum, ele invoca o mecanismo de tratamento de conflitos atual. Você pode definir o mecanismo de tratamento de conflitos no construtor:

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

ou com uma chamada separada:

    parser.set_conflict_handler(handler)

Os manipuladores de conflitos disponíveis são:

> `"error"` (padrão)

>   presume que os conflitos de opções são um erro de programação e levanta `OptionConflictError`

> `"resolve"`

>   resolve conflitos de opções de forma inteligente (veja abaixo)

Como exemplo, vamos definir um `OptionParser` que resolve conflitos de forma inteligente e adiciona opções conflitantes a ele:

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

Neste ponto, `optparse` detecta que uma opção adicionada anteriormente já está usando a string de opção `-n`. Como `conflict_handler` é `"resolve"`, ele resolve a situação removendo `-n` da lista de strings de opção da opção anterior. Agora `--dry-run` é a única maneira do usuário ativar essa opção. Se o usuário pedir ajuda, a mensagem de ajuda refletirá isso:

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

É possível reduzir as strings de opção para uma opção adicionada anteriormente até que não haja mais nenhuma, e o usuário não tenha como invocar essa opção da linha de comando. Nesse caso, `optparse` remove essa opção completamente, então ela não aparece no texto de ajuda ou em nenhum outro lugar. Continuando com nosso objeto OptionParser existente:

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

Neste ponto, a opção original `-n`/`--dry-run` não está mais acessível, então `optparse` a remove, deixando este texto de ajuda:

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

### Limpeza

As instâncias de OptionParser têm várias referências cíclicas. Isso não deve ser um problema para o coletor de lixo do Python, mas você pode desejar quebrar as referências cíclicas explicitamente chamando `destroy()` no seu OptionParser quando terminar de usá-lo. Isso é particularmente útil em aplicações de longa execução, onde gráficos de objetos grandes podem ser acessados do seu OptionParser.

### Outros métodos

OptionParser provê vários outros métodos públicos:

OptionParser.set_usage(usage)

  Defina a string de uso de acordo com as regras descritas acima para o argumento nomeado do construtor `usage`. Passar `None` define a string de uso padrão; use `optparse.SUPPRESS_USAGE` para suprimir uma mensagem de uso.

OptionParser.print_usage(file=None)

  Exibe a mensagem de uso para o programa atual (`self.usage`) em file (stdout padrão). Qualquer ocorrência da string `%prog` em `self.usage` é substituída pelo nome do programa atual. Não faz nada se `self.usage` estiver vazio ou não definido.

OptionParser.get_usage()

  O mesmo que `print_usage()`, mas retorna a string de uso em vez de exibi-la.

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

  Define valores padrão para vários destinos de opção de uma vez. Usar `set_defaults()` é a maneira preferida de definir valores padrão para opções, já que várias opções podem compartilhar o mesmo destino. Por exemplo, se várias opções de “modo” definirem o mesmo destino, qualquer uma delas pode definir o padrão, e a última vence:

      parser.add_option("--advanced", action="store_const",
                        dest="mode", const="advanced",
                        default="novice")    # substituída abaixo
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice",
                        default="advanced")  # substitui a configuração acima

  Para evitar essa confusão, use `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")

## Funções de retorno de opção

Quando as ações e tipos embutidos de `optparse` não são o bastante para suas necessidades, você tem duas escolhas: estender `optparse` ou definir uma opção de retorno de chamada. Estender `optparse` é mais geral, mas exagero para muitos casos simples. Muitas vezes, um retorno de chamada simples é tudo o que você precisa.

Há duas etapas para definir uma opção de retorno de chamada:

- definir a opção em si usando a ação `"callback"`

- escrever o função de retorno; esta é uma função (ou método) que recebe pelo menos quatro argumentos, conforme descrito abaixo

### Definindo uma opção de retorno de chamada

Como sempre, a maneira mais fácil de definir uma opção de retorno de chamada é usando o método `OptionParser.add_option()`. Além de `action`, o único atributo de opção que você deve especificar é `callback`, a função a ser chamada:

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

`callback` é uma função (ou outro objeto chamável), então você já deve ter definido `my_callback()` quando criar esta opção de retorno de chamada. Neste caso simples, `optparse` nem sabe se `-c` aceita argumentos, o que geralmente significa que a opção não aceita argumentos — a mera presença de `-c` na linha de comando é tudo o que ela precisa saber. Em algumas circunstâncias, no entanto, você pode querer que seu retorno de chamada consuma um número arbitrário de argumentos de linha de comando. É aqui que escrever retornos de chamada fica complicado; isso é abordado mais adiante nesta seção.

`optparse` sempre passa quatro argumentos particulares para seu retorno de chamada, e ele só passará argumentos adicionais se você especificá-los via `callback_args` e `callback_kwargs`. Assim, a assinatura mínima da função de retorno de chamada é:

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

Os quatro argumentos para um retorno de chamada são descritos abaixo.

Há vários outros atributos de opção que você pode fornecer ao definir uma opção de retorno de chamada:

`type`

  tem seu significado usual: como com as ações `"store"` ou `"append"`, ele instrui `optparse` a consumir um argumento e convertê-lo para `type`. Em vez de armazenar o(s) valor(es) convertido(s) em qualquer lugar, no entanto, `optparse` os passa para sua função de retorno de chamada.

`nargs`

  também tem seu significado usual: se for fornecido e > 1, `optparse` consumirá argumentos `nargs`, cada um dos quais deve ser conversível para `type`. Em seguida, ele passa uma tupla de valores convertidos para seu retorno de chamada.

`callback_args`

  uma tupla de argumentos posicionais extras para passar para a função de retorno

`callback_kwargs`

  um dicionário de argumentos nomeados extras para passar para a função de retorno

### Como os retornos de chamada são chamados

Todos os retornos de chamada são chamados da seguinte forma:

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

onde

`option`

  é a instância de Option que está chamando o retorno de chamada

`opt_str`

  é a string de opção vista na linha de comando que está acionando o retorno de chamada. (Se uma opção longa abreviada foi usada, `opt_str` será a string de opção canônica completa — por exemplo, se o usuário colocar `--foo` na linha de comando como uma abreviação para `--foobar`, então `opt_str` será `"--foobar"`.)

`value`

  é o argumento para esta opção visto na linha de comando. `optparse` só esperará um argumento se `type` estiver definido; o tipo de `value` será o tipo implícito pelo tipo da opção. Se `type` para esta opção for `None` (nenhum argumento esperado), então `value` será `None`. Se `nargs` > 1, `value` será uma tupla de valores do tipo apropriado.

`parser`

  é a instância OptionParser que controla tudo, útil principalmente porque você pode acessar alguns outros dados interessantes por meio de seus atributos de instância:

  `parser.largs`

    a lista atual de argumentos restantes, ou seja, argumentos que foram consumidos, mas não são opções nem argumentos de opção. Sinta-se à vontade para modificar `parser.largs`, por exemplo, adicionando mais argumentos a ele. (Esta lista se tornará `args`, o segundo valor de retorno de `parse_args()`.)

  `parser.rargs`

    a lista atual de argumentos restantes, ou seja, com `opt_str` e `value` (se aplicável) removidos, e apenas os argumentos que os seguem ainda lá. Sinta-se à vontade para modificar `parser.rargs`, por exemplo, consumindo mais argumentos.

  `parser.values`

    o objeto onde os valores de opção são armazenados por padrão (uma instância de optparse.OptionValues). Isso permite que as função de retorno usem o mesmo mecanismo que o resto de `optparse` para armazenar valores de opção; você não precisa mexer com globais ou closures. Você também pode acessar ou modificar o(s) valor(es) de quaisquer opções já encontradas na linha de comando.

`args`

  é uma tupla de argumentos posicionais arbitrários fornecidos por meio do atributo de opção `callback_args`.

`kwargs`

  é um dicionário de argumentos nomeados arbitrários fornecidos via `callback_kwargs`.

### Levantando erros em uma função de retorno

A função de retorno de chamada deve levantar `OptionValueError` se houver algum problema com a opção ou seu(s) argumento(s). `optparse` captura isso e encerra o programa, exibindo a mensagem de erro que você fornece para stderr. Sua mensagem deve ser clara, concisa, precisa e mencionar a opção com defeito. Caso contrário, o usuário terá dificuldade em descobrir o que fez de errado.

### Exemplo de função de retorno 1: retorno de chamada trivial

Aqui está um exemplo de uma opção de retorno de chamada que não aceita argumentos e simplesmente registra que a opção foi vista:

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

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

Claro, você pode fazer isso com a ação `"store_true"`.

### Exemplo de função de retorno 2: verificar a ordem das opções

Aqui está um exemplo um pouco mais interessante: registra o fato de que `-a` é visto, mas explode se ele vier depois de `-b` na linha de comando.

    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")

### Exemplo 3 de função de retorno: verificar a ordem das opções (generalizada)

Se você quiser reutilizar essa função de retorno para várias opções semelhantes (definir um sinalizador, mas explodir se `-b` já tiver sido visto), será preciso um pouco de trabalho: a mensagem de erro e o sinalizador que ele define devem ser generalizados.

    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')

### Exemplo de função de retorno 4: verificar uma condição arbitrária

Claro, você pode colocar qualquer condição ali—você não está limitado a verificar os valores de opções já definidas. Por exemplo, se você tem opções que não devem ser chamadas quando a lua está cheia, tudo o que você tem a fazer é isto:

    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")

(A definição de `is_moon_full()` é deixada como um exercício para o leitor.)

### Exemplo de função de retorno 5: argumentos fixos

As coisas ficam um pouco mais interessantes quando você define opções de retorno de chamada que aceitam um número fixo de argumentos. Especificar que uma opção de retorno de chamada aceita argumentos é semelhante a definir uma opção `"store"` ou `"append"`: se você definir `type`, então a opção aceita um argumento que deve ser conversível para esse tipo; se você definir ainda `nargs`, então a opção aceita argumentos `nargs`.

Aqui está um exemplo que apenas emula a ação padrão `"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 que `optparse` cuida de consumir 3 argumentos e convertê-los em números inteiros para você; tudo o que você precisa fazer é armazená-los. (Ou o que for; obviamente você não precisa de uma função de retorno de chamada para este exemplo.)

### Exemplo de função de retorno 6: argumentos variáveis

As coisas ficam complicadas quando você quer que uma opção receba um número variável de argumentos. Para esse caso, você deve escrever uma função de retorno, pois `optparse` não fornece nenhuma capacidade embutida para ele. E você tem que lidar com certas complexidades da análise sintática de linha de comando Unix convencional que `optparse` normalmente lida para você. Em particular, as funções de retorno devem implementar as regras convencionais para argumentos `--` e `-` simples:

- `--` ou `-` podem ser argumentos de opção

- `--` apenas (se não for o argumento para alguma opção): interrompe o processamento da linha de comando e descarta o `--`

- `-` apenas (se não for o argumento para alguma opção): interrompe o processamento da linha de comando, mas mantém o `-` (anexa-o a `parser.largs`)

Se você quiser uma opção que aceite um número variável de argumentos, há várias questões sutis e complicadas com as quais se preocupar. A implementação exata que você escolher será baseada em quais compensações você está disposto a fazer para sua aplicação (é por isso que `optparse` não oferece suporte a esse tipo de coisa diretamente).

No entanto, aqui vai uma tentativa de função de retorno para uma opção com argumentos variáveis:

    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:
            # para em --foo como opções
            if arg[:2] == "--" and len(arg) > 2:
                break
            # para em -a, mas não em -3 ou -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)

## Estendendo `optparse`

Como os dois principais fatores de controle sobre como `optparse` interpreta as opções de linha de comando são a ação e o tipo de cada opção, a direção mais provável de extensão é adicionar novas ações e novos tipos.

### Adicionando novos tipos

Para adicionar novos tipos, você precisa definir sua própria subclasse da classe `Option` de `optparse`. Esta classe tem alguns atributos que definem os tipos de `optparse`: `TYPES` e `TYPE_CHECKER`.

Option.TYPES

  Uma tupla de nomes de tipos; na sua subclasse, basta definir uma nova tupla `TYPES` que se baseia na tupla padrão.

Option.TYPE_CHECKER

  Um dicionário que mapeia nomes de tipos para funções de verificação de tipos. Uma função de verificação de tipos tem a seguinte assinatura:

      def check_mytype(option, opt, value)

  sendo `option` uma instância `Option`, `opt` é uma string de opção (por exemplo, `-f`), e `value` é a string da linha de comando que deve ser verificada e convertida para o tipo desejado. `check_mytype()` deve retornar um objeto do tipo hipotético `mytype`. O valor retornado por uma função de verificação de tipo acabará na instância OptionValues retornada por `OptionParser.parse_args()`, ou será passado para uma função de retorno como o parâmetro `value`.

  Sua função de verificação de tipo deve levantar `OptionValueError` se encontrar algum problema. `OptionValueError` recebe um único argumento de string, que é passado como está para o método `error()` do `OptionParser`, que por sua vez adiciona o nome do programa e a string `"error:"` e exibe tudo no stderr antes de encerrar o processo.

Aqui está um exemplo bobo que demonstra a adição de um tipo de opção `"complex"` para analisar números complexos no estilo Python na linha de comando. (Isso é ainda mais bobo do que costumava ser, porque `optparse` 1.3 adicionou suporte embutido para números complexos, mas não importa.)

Primeiro, as importações necessárias:

    from copy import copy
    from optparse import Option, OptionValueError

Você precisa definir seu verificador de tipo primeiro, pois ele será referenciado mais tarde (no atributo de classe `TYPE_CHECKER` da sua subclasse de Option):

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

Finalmente, a subclasse de Option:

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

(Se não fizéssemos uma `copy()` de `Option.TYPE_CHECKER`, acabaríamos modificando o atributo `TYPE_CHECKER` da classe Option de `optparse`. Sendo Python, nada impede você de fazer isso, exceto boas maneiras e bom senso.)

Pronto! Agora você pode escrever um script que usa o novo tipo de opção como qualquer outro script baseado em `optparse`, exceto que você tem que instruir seu OptionParser a usar MyOption em vez de Option:

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

Como alternativa, você pode criar sua própria lista de opções e passá-la para o OptionParser; se você não usar `add_option()` da maneira acima, não precisa informar ao OptionParser qual classe de opção usar:

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

### Adicionando novas ações

A adição de novas ações é um pouco mais complicado, porque você precisa entender que `optparse` tem algumas classificações para ações:

Ações “store”

  ações que resultam em `optparse` armazenando um valor em um atributo da instância OptionValues atual; essas opções exigem que um atributo `dest` seja fornecido ao construtor Option.

Ações “typed”

  Ações que pegam um valor da linha de comando e esperam que ele seja de um certo tipo; ou melhor, uma string que pode ser convertida para um certo tipo. Essas opções requerem um atributo `type` para o construtor Option.

Esses são conjuntos sobrepostos: algumas ações “store” padrão são `"store"`, `"store_const"`, `"append"` e `"count"`, enquanto as ações “typed” padrão são `"store"`, `"append"` e `"callback"`.

Ao adicionar uma ação, você precisa categorizá-la listando-a em pelo menos um dos seguintes atributos de classe de Option (todos são listas de strings):

Option.ACTIONS

  Todas as ações devem ser listadas em ACTIONS.

Option.STORE_ACTIONS

  As ações “store” também são listadas aqui.

Option.TYPED_ACTIONS

  As ações “typed” também são listadas aqui.

Option.ALWAYS_TYPED_ACTIONS

  Ações que sempre assumem um tipo (ou seja, cujas opções sempre assumem um valor) são listadas aqui adicionalmente. O único efeito disso é que `optparse` atribui o tipo padrão, `"string"`, a opções sem tipo explícito cuja ação é listada em `ALWAYS_TYPED_ACTIONS`.

Para realmente implementar sua nova ação, você deve substituir o método `take_action()` de Option e adicionar um caso que reconheça sua ação.

Por exemplo, vamos adicionar uma ação `"extend"`. Isso é semelhante à ação padrão `"append"`, mas em vez de pegar um único valor da linha de comando e anexá-lo a uma lista existente, `"extend"` pegará vários valores em uma única string delimitada por vírgulas e estenderá uma lista existente com eles. Ou seja, se `--names` for uma opção `"extend"` do tipo `"string"`, a linha de comando

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

resultaria em uma lista

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

Novamente, nós definimos uma subclasse de 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)

Características de nota:

- `"extend"` espera um valor na linha de comando e armazena esse valor em algum lugar, então ele vai em `STORE_ACTIONS` e `TYPED_ACTIONS`.

- para garantir que `optparse` atribua o tipo padrão de `"string"` às ações `"extend"`, colocamos a ação `"extend"` em `ALWAYS_TYPED_ACTIONS` também.

- `MyOption.take_action()` implementa apenas esta nova ação e passa o controle de volta para `Option.take_action()` para as ações padrão `optparse`.

- `values` é uma instância da classe optparse_parser.Values, que fornece o método muito útil `ensure_value()`. `ensure_value()` é essencialmente `getattr()` com uma válvula de segurança; é chamado como

      values.ensure_value(attr, value)

  Se o atributo `attr` de `values` não existir ou for `None`, então ensure_value() primeiro o define como `value` e então retorna `value`. Isso é muito útil para ações como `"extend"`, `"append"` e `"count"`, todas as quais acumulam dados em uma variável e esperam que essa variável seja de um certo tipo (uma lista para as duas primeiras, um inteiro para a última). Usar `ensure_value()` significa que os scripts que usam sua ação não precisam se preocupar em definir um valor padrão para os destinos de opção em questão; eles podem simplesmente deixar o padrão como `None` e `ensure_value()` cuidará de acertar quando for necessário.

## Exceções

exception optparse.OptionError

  Levantada se uma instância de `Option` for criada com argumentos inválidos ou inconsistentes.

exception optparse.OptionConflictError

  Levantada se opções conflitantes forem adicionadas a um instância de `OptionParser`.

exception optparse.OptionValueError

  Levantada se um valor de opção inválido for encontrado na linha de comando.

exception optparse.BadOptionError

  Levantada se uma opção inválida for passada na linha de comando.

exception optparse.AmbiguousOptionError

  Levantada se uma opção ambígua for passada na linha de comando.