"optparse" --- Analisador sintático para opções de linha de comando
*******************************************************************

**Código-fonte:** Lib/optparse.py

======================================================================


Escolhendo uma biblioteca de análise de linha de comando
========================================================

A biblioteca padrão inclui três bibliotecas de análise de argumentos:

* "getopt": um módulo que espelha de perto a API procedural C
  "getopt". Incluído na biblioteca padrão desde antes do lançamento
  inicial do Python 1.0.

* "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": uma alternativa mais opinativa a "optparse" que fornece
  mais funcionalidade por padrão, às custas de flexibilidade reduzida
  da aplicação em controlar exatamente como os argumentos são
  processados. Incluído na biblioteca padrão desde as versões Python
  2.7 e Python 3.2.

Na ausência de restrições de design de análise de argumentos mais
específicas, "argparse" é a escolha recomendada para implementar
aplicações de linha de comando, pois oferece o mais alto nível de
funcionalidade básica com o mínimo de código em nível de aplicação.

"getopt" é mantido quase inteiramente por razões de
retrocompatibilidade. No entanto, ele também serve como um caso de uso
de nicho como uma ferramenta para prototipagem e teste de manipulação
de argumentos de linha de comando em aplicações C baseadas em
"getopt".

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

* a aplicação requer controle adicional sobre a maneira como as opções
  e os parâmetros posicionais são intercalados na linha de comando
  (incluindo a capacidade de desabilitar completamente o recurso de
  intercalação)

* a aplicação requer controle adicional sobre a análise incremental de
  elementos de linha de comando (embora "argparse" suporte isso, a
  maneira exata como ele funciona na prática é indesejável para alguns
  casos de uso)

* a aplicação requer controle adicional sobre o tratamento de opções
  que aceitam valores de parâmetros que podem começar com "-" (como
  opções delegadas a serem passadas para subprocessos invocados)

* a aplicação requer algum outro comportamento de processamento de
  parâmetros de linha de comando que "argparse" não suporta, mas que
  pode ser implementado em termos da interface de nível inferior
  oferecida por "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.

Como exemplo concreto, considere as duas configurações de análise de
argumentos de linha de comando a seguir, a primeira usando "optparse"
e a segunda usando "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)

A diferença mais óbvia é que na versão "optparse", os argumentos não
opcionais são processados separadamente pelo aplicativo após o
processamento da opção ser concluído. Na versão "argparse", os
argumentos posicionais são declarados e processados da mesma forma que
as opções nomeadas.

No entanto, a versão "argparse" também manipulará algumas combinações
de parâmetros de forma diferente da forma como a versão "optparse" as
manipularia. Por exemplo (entre outras diferenças):

* fornecer "-o -v" retorna "output="-v"" e "verbose=False" ao usar
  "optparse", mas um erro de uso com "argparse" (reclamando que nenhum
  valor foi fornecido para "-o/--output", já que "-v" é interpretado
  como significando o sinalizador de verbosidade)

* da mesma forma, fornecer "-o --" retorna "output="--"" e "args=()"
  ao usar "optparse", mas um erro de uso com "argparse" (também
  reclamando que nenhum valor foi fornecido para "-o/--output", já que
  "--" é interpretado como o término do processamento da opção e o
  tratamento de todos os valores restantes como argumentos
  posicionais)

* fornecer "-o=foo" retorna "output="=foo"" ao usar "optparse", mas
  retorna "output="foo"" com "argparse" (já que "=" é um caso especial
  como um separador alternativo para valores de parâmetros de opção)

Se esses comportamentos diferentes na versão "argparse" são
considerados desejáveis ou um problema dependerá do caso de uso
específico da aplicação de linha de comando.

Ver também:

  click é uma biblioteca de processamento de argumentos de terceiros
  (originalmente baseada em "optparse"), que permite que aplicações de
  linha de comando sejam desenvolvidas como um conjunto de funções de
  implementação de comando decoradas.

  Outras bibliotecas de terceiros, como typer ou msgspec-click,
  permitem que interfaces de linha de comando sejam especificadas de
  maneiras que se integrem de forma mais eficaz com a verificação
  estática de anotações de tipo Python.


Introdução
==========

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

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

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:

   <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

and "optparse" will print out a brief summary of your script's
options:

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


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

   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"

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

argumento de opção
   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

   ou incluídos no mesmo argumento:

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

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

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
========

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.

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, ...)

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.

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.

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

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

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


A ação 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.

Por exemplo:

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

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

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.


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

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

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

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


Outras ações
------------

Some other actions supported by "optparse" are:

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

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

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

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

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

     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.

* 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

  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

  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.

* 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".


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

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.


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.

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

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


Juntando tudo
-------------

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


Guia de referência
==================


Criando o analisador sintático
------------------------------

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

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]"")
      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" (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")
      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" (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")
      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" (padrão: um novo "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" (padrão: "True")
      If true, "optparse" will add a help option (with option strings
      "-h" and "--help") to the parser.

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


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, ...)

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

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

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

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

   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

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

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

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

   (padrão: ""store"")

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

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)

   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

   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)

   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

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

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.

* ""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"".

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

  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" will set

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

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

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

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

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

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

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

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

     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" automatically adds a "help" option to all OptionParsers,
  so you do not normally need to create one.

  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)

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

* ""version""

  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.


Tipos de opção padrão
---------------------

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

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

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.

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"
      the same object that was passed in as *values*, or the
      "optparse.Values" instance created by "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()

   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

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

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)

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

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


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
===========================

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.

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

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

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

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.


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


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

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:

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

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

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)


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.


Adicionando novos tipos
-----------------------

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

   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.

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

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

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

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

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

Ações "store"
   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.

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

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

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

* 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" é 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.
