"argparse" --- Parser para opções de linha de comando, argumentos e subcomandos
*******************************************************************************

Novo na versão 3.2.

**Código Fonte:** Lib/argparse.py

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


Tutorial
^^^^^^^^

Esta página contém informações da API de Referência. Para uma
introdução mais prática para o parser de linha de comando Python,
acesse argparse tutorial.

O módulo "argparse" torna fácil a escrita de interfaces de linha de
comando amigáveis. O programa define quais argumentos são necessários
e "argparse" descobrirá como analisá-lo e interpretá-los a partir do
"sys.argv".  O módulo "argparse" também gera automaticamente o texto
ajuda, mensagens de uso e error emitidos quando o usuário prover
argumentos inválidos para o programa.


Exemplo
=======

O código a seguir é um programa Python que recebe uma lista de
inteiros e apresenta a soma ou o máximo:

   import argparse

   parser = argparse.ArgumentParser(description='Process some integers.')
   parser.add_argument('integers', metavar='N', type=int, nargs='+',
                       help='an integer for the accumulator')
   parser.add_argument('--sum', dest='accumulate', action='store_const',
                       const=sum, default=max,
                       help='sum the integers (default: find the max)')

   args = parser.parse_args()
   print(args.accumulate(args.integers))

Assumindo que o código Python acima está salvo em um arquivo chamado
"prog.py", pode-se executá-lo pela linha de comando e obter mensagens
de ajuda úteis:

   $ python prog.py -h
   usage: prog.py [-h] [--sum] N [N ...]

   Process some integers.

   positional arguments:
    N           an integer for the accumulator

   optional arguments:
    -h, --help  show this help message and exit
    --sum       sum the integers (default: find the max)

Quando executado com argumentos apropriados, a soma ou o maior número
dos números digitados na linha de comando:

   $ python prog.py 1 2 3 4
   4

   $ python prog.py 1 2 3 4 --sum
   10

Se argumentos inválidos são passados, um erro será emitido:

   $ python prog.py a b c
   usage: prog.py [-h] [--sum] N [N ...]
   prog.py: error: argument N: invalid int value: 'a'

As próximas seções apresentarão detalhes deste exemplo.


Criando um parser
-----------------

O primeiro passo ao utilizar o "argparse" é criar um objeto
"ArgumentParser":

   >>> parser = argparse.ArgumentParser(description='Process some integers.')

O objeto "ArgumentParser" contém toda informação necerrária para
análise e interpretação da linha de comando em tipos de dados Python.


Adicionando argumentos
----------------------

O preenchimento de "ArgumentParser" com informações sobre os
argumentos do programa é feito por chamadas ao método
"add_argument()". Geralmente, estas chamadas informam ao
"ArgumentParser" como traduzir strings da linha de comando e torná-los
em objetos. Esta informação é armazenada e utilizada quando o método
"parse_args()" é invocado. Por exemplo:

   >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
   ...                     help='an integer for the accumulator')
   >>> parser.add_argument('--sum', dest='accumulate', action='store_const',
   ...                     const=sum, default=max,
   ...                     help='sum the integers (default: find the max)')

Em seguida, a chamada ao método "parse_args()" irá retornar um objeto
com dois atributos, "integers" e "accumulate". O atributo "integers"
será uma lista com um ou mais números inteiros, e o atributo
"accumulate" será ou a função "sum()", se "--sum" for especificado na
linha de comando, ou a função "max()", caso contrário.


Análise de argumentos
---------------------

"ArgumentParser" analisa os argumentos através do método
"parse_args()". Isso inspecionará a linha de comando, converterá cada
argumento no tipo apropriado e, em seguida, chamará a ação apropriada.
Na maioria dos casos, isso significa que um objeto "Namespace" simples
será construído a partir de atributos analisados a partir da linha de
comando:

   >>> parser.parse_args(['--sum', '7', '-1', '42'])
   Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

Em um script, "parse_args()" será tipicamente chamado sem argumentos,
e "ArgumentParser" irá determinar automaticamente os argumentos de
linha de comando de "sys.argv".


Objetos ArgumentParser
======================

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)

   Cria um novo objeto "ArgumentParser". Todos os parâmetros devem ser
   passados como argumentos nomeados. Cada parâmetro tem sua própria
   descrição mais detalhada abaixo, mas em resumo eles são:

   * prog - O nome do programa (padrão: "sys.argv[0]")

   * usage - A string que descreve o uso do programa (padrão: gerado a
     partir de argumentos adicionados ao analisador sintático)

   * description - Texto para exibir antes da ajuda dos argumentos
     (padrão: nenhuma)

   * epilog - Texto para exibir após da ajuda dos argumentos (padrão:
     nenhum)

   * parents - Uma lista de objetos "ArgumentParser" cujos argumentos
     também devem ser incluídos

   * formatter_class - Uma classe para personalizar a saída de ajuda

   * prefix_chars - O conjunto de caracteres que prefixam argumentos
     opcionais (padrão: "-")

   * fromfile_prefix_chars - O conjunto de caracteres que prefixam os
     arquivos dos quais os argumentos adicionais devem ser lidos
     (padrão: "None")

   * argument_default - O valor padrão global para argumentos (padrão:
     "None")

   * conflict_handler - A estratégia para resolver opcionais
     conflitantes (geralmente desnecessário)

   * add_help - Adiciona uma opção "-h/--help" para o analisador
     sintático (padrão: "True")

   * allow_abbrev - Permite que opções longas sejam abreviadas se a
     abreviação não for ambígua. (padrão: "True")

   Alterado na versão 3.5: O parâmetro *allow_abbrev* foi adicionado.

As seções a seguir descrevem como cada um deles é usado.


prog
----

Por padrão, os objetos "ArgumentParser" usam "sys.argv[0]" para
determinar como exibir o nome do programa nas mensagens de ajuda. Esse
padrão é quase sempre desejável porque fará com que as mensagens de
ajuda correspondam à forma como o programa foi chamado na linha de
comando. Por exemplo, considere um arquivo denominado "myprogram.py"
com o seguinte código:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--foo', help='foo help')
   args = parser.parse_args()

A ajuda para este programa exibirá "myprogram.py" como o nome do
programa (independentemente de onde o programa foi chamado):

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help
   $ cd ..
   $ python subdir/myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help

Para alterar este comportamento padrão, outro valor pode ser fornecido
usando o argumento "prog=" para "ArgumentParser":

   >>> parser = argparse.ArgumentParser(prog='myprogram')
   >>> parser.print_help()
   usage: myprogram [-h]

   optional arguments:
    -h, --help  show this help message and exit

Observe que o nome do programa, seja determinado a partir de
"sys.argv[0]" ou do argumento "prog=", está disponível para mensagens
de ajuda usando o especificador de formato "%(prog)s".

   >>> parser = argparse.ArgumentParser(prog='myprogram')
   >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
   >>> parser.print_help()
   usage: myprogram [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo of the myprogram program


usage
-----

Por padrão, "ArgumentParser" calcula a mensagem de uso a partir dos
argumentos que contém:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo', nargs='?', help='foo help')
   >>> parser.add_argument('bar', nargs='+', help='bar help')
   >>> parser.print_help()
   usage: PROG [-h] [--foo [FOO]] bar [bar ...]

   positional arguments:
    bar          bar help

   optional arguments:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

A mensagem padrão pode ser substituído com o argumento nomeado
"usage=":

   >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
   >>> parser.add_argument('--foo', nargs='?', help='foo help')
   >>> parser.add_argument('bar', nargs='+', help='bar help')
   >>> parser.print_help()
   usage: PROG [options]

   positional arguments:
    bar          bar help

   optional arguments:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

O especificador de formato "%(prog)s" está disponível para preencher o
nome do programa em suas mensagens de uso.


description
-----------

A maioria das chamadas para o construtor "ArgumentParser" usará o
argumento nomeado  "description=". Este argumento fornece uma breve
descrição do que o programa faz e como funciona. Nas mensagens de
ajuda, a descrição é exibida entre a string de uso da linha de comando
e as mensagens de ajuda para os vários argumentos:

   >>> parser = argparse.ArgumentParser(description='A foo that bars')
   >>> parser.print_help()
   usage: argparse.py [-h]

   A foo that bars

   optional arguments:
    -h, --help  show this help message and exit

Por padrão, a descrição terá sua linha quebrada para que se encaixe no
espaço fornecido. Para alterar esse comportamento, consulte o
argumento formatter_class.


epilog
------

Alguns programas gostam de exibir uma descrição adicional do programa
após a descrição dos argumentos. Esse texto pode ser especificado
usando o argumento "epilog=" para "ArgumentParser":

   >>> parser = argparse.ArgumentParser(
   ...     description='A foo that bars',
   ...     epilog="And that's how you'd foo a bar")
   >>> parser.print_help()
   usage: argparse.py [-h]

   A foo that bars

   optional arguments:
    -h, --help  show this help message and exit

   And that's how you'd foo a bar

Tal como acontece com o argumento description, o texto de "epilog="
tem sua quebra de linha habilitada por padrão, mas este comportamento
pode ser ajustado com o argumento formatter_class para
"ArgumentParser".


parents
-------

Às vezes, vários analisadores sintáticos compartilham um conjunto
comum de argumentos. Ao invés de repetir as definições desses
argumentos, um único analisador com todos os argumentos compartilhados
e passado para o argumento "parents=" para "ArgumentParser" pode ser
usado. O argumento "parents=" pega uma lista de objetos
"ArgumentParser", coleta todas as ações posicionais e opcionais deles,
e adiciona essas ações ao objeto "ArgumentParser" sendo construído:

   >>> parent_parser = argparse.ArgumentParser(add_help=False)
   >>> parent_parser.add_argument('--parent', type=int)

   >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
   >>> foo_parser.add_argument('foo')
   >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
   Namespace(foo='XXX', parent=2)

   >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
   >>> bar_parser.add_argument('--bar')
   >>> bar_parser.parse_args(['--bar', 'YYY'])
   Namespace(bar='YYY', parent=None)

Observe que a maioria dos analisadores sintáticos pais especificará
"add_help=False". Caso contrário, o "ArgumentParser" verá duas opções
"-h/--help" (uma no pai e outra no filho) e levantará um erro.

Nota:

  Você deve inicializar totalmente os analisadores sintáticos antes de
  passá-los via "parents=". Se você alterar os analisadores pais após
  o analisador filho, essas mudanças não serão refletidas no filho.


formatter_class
---------------

Objetos "ArgumentParser" permitem que a  formação do texto de ajuda
seja personalizada por meio da especificação de uma classe de
formatação alternativa. Atualmente, há quatro dessas classes:

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter
class argparse.MetavarTypeHelpFormatter

"RawDescriptionHelpFormatter" e "RawTextHelpFormatter" dão mais
controle sobre como as descrições textuais são exibidas. Por padrão,
objetos "ArgumentParser" quebram em linha os textos description e
epilog nas mensagens de ajuda da linha de comando:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     description='''this description
   ...         was indented weird
   ...             but that is okay''',
   ...     epilog='''
   ...             likewise for this epilog whose whitespace will
   ...         be cleaned up and whose words will be wrapped
   ...         across a couple lines''')
   >>> parser.print_help()
   usage: PROG [-h]

   this description was indented weird but that is okay

   optional arguments:
    -h, --help  show this help message and exit

   likewise for this epilog whose whitespace will be cleaned up and whose words
   will be wrapped across a couple lines

Passar "RawDescriptionHelpFormatter" como "formatter_class=" indica
que description e epilog já estão formatados corretamente e não devem
ter suas linhas quebradas:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.RawDescriptionHelpFormatter,
   ...     description=textwrap.dedent('''\
   ...         Please do not mess up this text!
   ...         --------------------------------
   ...             I have indented it
   ...             exactly the way
   ...             I want it
   ...         '''))
   >>> parser.print_help()
   usage: PROG [-h]

   Please do not mess up this text!
   --------------------------------
      I have indented it
      exactly the way
      I want it

   optional arguments:
    -h, --help  show this help message and exit

"RawTextHelpFormatter" mantém espaços em branco para todos os tipos de
texto de ajuda, incluindo descrições de argumentos. No entanto, várias
novas linhas são substituídas por uma. Se você deseja preservar várias
linhas em branco, adicione espaços entre as novas linhas.

"ArgumentDefaultsHelpFormatter" adiciona automaticamente informações
sobre os valores padrão para cada uma das mensagens de ajuda do
argumento:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
   >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
   >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
   >>> parser.print_help()
   usage: PROG [-h] [--foo FOO] [bar [bar ...]]

   positional arguments:
    bar         BAR! (default: [1, 2, 3])

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   FOO! (default: 42)

"MetavarTypeHelpFormatter" usa o nome de argumento type para cada
argumento como o nome de exibição para seus valores (em vez de usar o
dest como o formatador regular faz):

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.MetavarTypeHelpFormatter)
   >>> parser.add_argument('--foo', type=int)
   >>> parser.add_argument('bar', type=float)
   >>> parser.print_help()
   usage: PROG [-h] [--foo int] float

   positional arguments:
     float

   optional arguments:
     -h, --help  show this help message and exit
     --foo int


prefix_chars
------------

A maioria das opções de linha de comando usará "-" como prefixo, por
exemplo, "-f/--foo". Analisadores sintáticos que precisam ter suporte
a caracteres de prefixo diferentes ou adicionais, por exemplo, para
opções como "+f" ou "/foo", podem especificá-las usando o argumento
"prefix_chars=" para o construtor ArgumentParser:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
   >>> parser.add_argument('+f')
   >>> parser.add_argument('++bar')
   >>> parser.parse_args('+f X ++bar Y'.split())
   Namespace(bar='Y', f='X')

O argumento "prefix_chars=" é padronizado como "'-'". Fornecer um
conjunto de caracteres que não inclua "-" fará com que as opções
"-f/--foo" não sejam permitidas.


fromfile_prefix_chars
---------------------

Sometimes, for example when dealing with a particularly long argument
lists, it may make sense to keep the list of arguments in a file
rather than typing it out at the command line.  If the
"fromfile_prefix_chars=" argument is given to the "ArgumentParser"
constructor, then arguments that start with any of the specified
characters will be treated as files, and will be replaced by the
arguments they contain.  For example:

   >>> with open('args.txt', 'w') as fp:
   ...     fp.write('-f\nbar')
   >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
   >>> parser.add_argument('-f')
   >>> parser.parse_args(['-f', 'foo', '@args.txt'])
   Namespace(f='bar')

Os argumentos lidos de um arquivo devem, por padrão, ser um por linha
(mas veja também "convert_arg_line_to_args()") e são tratados como se
estivessem no mesmo lugar que o argumento de referência do arquivo
original na linha de comando. Portanto, no exemplo acima, a expressão
"['-f', 'foo', '@args.txt']" é considerada equivalente à expressão
"['-f', 'foo', '-f', 'bar']".

O argumento "fromfile_prefix_chars=" é padronizado como "None",
significando que os argumentos nunca serão tratados como referências
de arquivo.


argument_default
----------------

Geralmente, os padrões dos argumentos são especificados passando um
padrão para "add_argument()" ou chamando os métodos "set_defaults()"
com um conjunto específico de pares nome-valor. Às vezes, no entanto,
pode ser útil especificar um único padrão para todo o analisador para
argumentos. Isso pode ser feito passando o argumento nomeado
"argument_default=" para "ArgumentParser". Por exemplo, para suprimir
globalmente a criação de atributos em chamadas "parse_args()",
fornecemos "argument_default=SUPPRESS":

   >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar', nargs='?')
   >>> parser.parse_args(['--foo', '1', 'BAR'])
   Namespace(bar='BAR', foo='1')
   >>> parser.parse_args([])
   Namespace()


allow_abbrev
------------

Normalmente, quando você passa uma lista de argumentos para o método
"parse_args()" de um "ArgumentParser", ele reconhece as abreviações de
opções longas.

Este recurso pode ser desabilitado configurando "allow_abbrev" para
"False":

   >>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
   >>> parser.add_argument('--foobar', action='store_true')
   >>> parser.add_argument('--foonley', action='store_false')
   >>> parser.parse_args(['--foon'])
   usage: PROG [-h] [--foobar] [--foonley]
   PROG: error: unrecognized arguments: --foon

Novo na versão 3.5.


conflict_handler
----------------

Objetos "ArgumentParser" não permitem duas ações com a mesma string de
opções. Por padrão, objetos "ArgumentParser" levantam uma exceção se
for feita uma tentativa de criar um argumento com uma string de opção
que já esteja em uso:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   Traceback (most recent call last):
    ..
   ArgumentError: argument --foo: conflicting option string(s): --foo

Às vezes (por exemplo, ao usar os parents) pode ser útil simplesmente
substituir quaisquer argumentos mais antigos com a mesma string de
opções. Para obter este comportamento, o valor "'resolve'" pode ser
fornecido ao argumento "conflict_handler=" de "ArgumentParser":

   >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   >>> parser.print_help()
   usage: PROG [-h] [-f FOO] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    -f FOO      old foo help
    --foo FOO   new foo help

Observe que os objetos "ArgumentParser" só removem uma ação se todas
as suas strings de opção forem substituídas. Assim, no exemplo acima,
a antiga ação "-f/--foo" é mantida como a ação "-f", porque apenas a
string de opção "--foo" foi substituída.


add_help
--------

Por padrão, os objetos ArgumentParser adicionam uma opção que
simplesmente exibe a mensagem de ajuda do analisador. Por exemplo,
considere um arquivo chamado "myprogram.py" contendo o seguinte
código:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--foo', help='foo help')
   args = parser.parse_args()

Se "-h" ou "--help" for fornecido na linha de comando, a ajuda do
ArgumentParser será impressa:

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help

Às vezes, pode ser útil desabilitar o acréscimo desta opção de ajuda.
Isto pode ser feito passando "False" como o argumento "add_help=" para
a classe "ArgumentParser":

   >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
   >>> parser.add_argument('--foo', help='foo help')
   >>> parser.print_help()
   usage: PROG [--foo FOO]

   optional arguments:
    --foo FOO  foo help

A opção de ajuda é normalmente "-h/--help". A exceção a isso é se o
"prefix_chars=" for especificado e não incluir "-", neste caso "-h" e
"--help" não são opções válidas. Neste caso, o primeiro caractere em
"prefix_chars" é usado para prefixar as opções de ajuda:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
   >>> parser.print_help()
   usage: PROG [+h]

   optional arguments:
     +h, ++help  show this help message and exit


O método add_argument()
=======================

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

   Define como um único argumento de linha de comando deve ser
   analisado. Cada parâmetro tem sua própria descrição mais detalhada
   abaixo, mas resumidamente são eles:

   * name or flags - Um nome ou uma lista de strings de opções, por
     exemplo. "foo" ou "-f, --foo".

   * action - O tipo básico de ação a ser executada quando esse
     argumento é encontrado na linha de comando.

   * nargs - O número de argumentos de linha de comando que devem ser
     consumidos.

   * const - Um valor constante exigido por algumas seleções action e
     nargs.

   * default - The value produced if the argument is absent from the
     command line.

   * type - O tipo para o qual o argumento de linha de comando deve
     ser convertido.

   * choices - Um contêiner dos valores permitidos para o argumento.

   * required - Se a opção de linha de comando pode ou não ser omitida
     (somente opcionais).

   * help - Uma breve descrição do que o argumento faz.

   * metavar - Um nome para o argumento nas mensagens de uso.

   * dest - O nome do atributo a ser adicionado ao objeto retornado
     por "parse_args()".

As seções a seguir descrevem como cada um deles é usado.


name ou flags
-------------

O método "add_argument()" define quando um argumento opcional, como
"-f" ou "--foo", ou um argumento posicional, como uma lista de nomes
de arquivos, é esperada. Os primeiros argumentos passados ao método
"add_argument()" devem ser uma série de flags, ou um simples nome de
argumento.  Por exemplo, um argumento opcional deve ser criado como:

   >>> parser.add_argument('-f', '--foo')

enquanto um argumento posicional pode ser criado como:

   >>> parser.add_argument('bar')

Quando "parse_args()" é chamado, argumentos opcionais serão
identificados pelo prefixo "-", e os argumentos restantes serão
considerados posicionais:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['BAR'])
   Namespace(bar='BAR', foo=None)
   >>> parser.parse_args(['BAR', '--foo', 'FOO'])
   Namespace(bar='BAR', foo='FOO')
   >>> parser.parse_args(['--foo', 'FOO'])
   usage: PROG [-h] [-f FOO] bar
   PROG: error: the following arguments are required: bar


action
------

Objetos "ArgumentParser" associam argumentos de linha de comando com
ações. Essas ações podem fazer praticamente qualquer coisa com os
argumentos de linha de comando associados a elas, embora a maioria das
ações simplesmente adicione um atributo ao objeto retornado por
"parse_args()". O argumento nomeado "action" especifica como os
argumentos da linha de comando devem ser tratados. As ações fornecidas
são:

* "'store'" - Isso apenas armazena o valor do argumento. Esta é a ação
  padrão. Por exemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo')
     >>> parser.parse_args('--foo 1'.split())
     Namespace(foo='1')

* "'store_const'" - Isso armazena o valor especificado pelo argumento
  nomeado const. A ação "'store_const'" é mais comumente usada com
  argumentos opcionais que especificam algum tipo de sinalizador. Por
  exemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_const', const=42)
     >>> parser.parse_args(['--foo'])
     Namespace(foo=42)

* "'store_true'" e "'store_false'" - Estes são casos especiais de
  "'store_const'" usados para armazenar os valores "True" e "False"
  respectivamente. Além disso, eles criam valores padrão de "False" e
  "True" respectivamente. Por exemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_true')
     >>> parser.add_argument('--bar', action='store_false')
     >>> parser.add_argument('--baz', action='store_false')
     >>> parser.parse_args('--foo --bar'.split())
     Namespace(foo=True, bar=False, baz=True)

* "'append'" - Isso armazena uma lista e anexa cada valor de argumento
  à lista. Isso é útil para permitir que uma opção seja especificada
  várias vezes. Exemplo de uso:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='append')
     >>> parser.parse_args('--foo 1 --foo 2'.split())
     Namespace(foo=['1', '2'])

* "'append_const'" - Isso armazena uma lista e anexa o valor
  especificado pelo argumento nomeado const à lista. (Observe que o
  argumento nomeado const tem como padrão "None".) A ação
  "'append_const'" é normalmente útil quando vários argumentos
  precisam armazenar constantes na mesma lista. Por exemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
     >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
     >>> parser.parse_args('--str --int'.split())
     Namespace(types=[<class 'str'>, <class 'int'>])

* "'count'" - Isso conta o número de vezes que um argumento nomeado
  ocorre. Por exemplo, isso é útil para aumentar os níveis de
  verbosidade:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--verbose', '-v', action='count', default=0)
     >>> parser.parse_args(['-vvv'])
     Namespace(verbose=3)

  Observe que o *padrão* será "None", a menos que seja explicitamente
  definido como *0*.

* "'help'" - Isso imprime uma mensagem de ajuda completa para todas as
  opções no analisador sintático atual e sai. Por padrão, uma ação de
  ajuda é adicionada automaticamente ao analisador sintático. Veja
  "ArgumentParser" para detalhes de como a saída é criada.

* "'version'" - Isso espera um argumento nomeado "version=" na chamada
  "add_argument()" e imprime informações de versão e sai quando
  invocado:

     >>> import argparse
     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
     >>> parser.parse_args(['--version'])
     PROG 2.0

You may also specify an arbitrary action by passing an Action subclass
or other object that implements the same interface.  The recommended
way to do this is to extend "Action", overriding the "__call__" method
and optionally the "__init__" method.

Um exemplo de uma ação personalizada:

   >>> class FooAction(argparse.Action):
   ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
   ...         if nargs is not None:
   ...             raise ValueError("nargs not allowed")
   ...         super(FooAction, self).__init__(option_strings, dest, **kwargs)
   ...     def __call__(self, parser, namespace, values, option_string=None):
   ...         print('%r %r %r' % (namespace, values, option_string))
   ...         setattr(namespace, self.dest, values)
   ...
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action=FooAction)
   >>> parser.add_argument('bar', action=FooAction)
   >>> args = parser.parse_args('1 --foo 2'.split())
   Namespace(bar=None, foo=None) '1' None
   Namespace(bar='1', foo=None) '2' '--foo'
   >>> args
   Namespace(bar='1', foo='2')

Para mais detalhes, veja "Action".


nargs
-----

Os objetos ArgumentParser geralmente associam um único argumento de
linha de comando a uma única ação a ser executada. O argumento nomeado
"nargs" associa um número diferente de argumentos de linha de comando
com uma única ação. Os valores suportados são:

* "N" (um inteiro). Os argumentos "N" da linha de comando serão
  reunidos em uma lista. Por exemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs=2)
     >>> parser.add_argument('bar', nargs=1)
     >>> parser.parse_args('c --foo a b'.split())
     Namespace(bar=['c'], foo=['a', 'b'])

  Observe que "nargs=1" produz uma lista de um item. Isso é diferente
  do padrão, em que o item é produzido sozinho.

* "'?'". Um argumento será consumido da linha de comando, se possível,
  e produzido como um único item. Se nenhum argumento de linha de
  comando estiver presente, o valor de default será produzido. Observe
  que, para argumentos opcionais, há um caso adicional - a string de
  opções está presente, mas não é seguida por um argumento de linha de
  comando. Neste caso o valor de const será produzido. Alguns exemplos
  para ilustrar isso:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
     >>> parser.add_argument('bar', nargs='?', default='d')
     >>> parser.parse_args(['XX', '--foo', 'YY'])
     Namespace(bar='XX', foo='YY')
     >>> parser.parse_args(['XX', '--foo'])
     Namespace(bar='XX', foo='c')
     >>> parser.parse_args([])
     Namespace(bar='d', foo='d')

  Um dos usos mais comuns de "nargs='?'" é permitir arquivos de
  entrada e saída opcionais:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
     ...                     default=sys.stdin)
     >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
     ...                     default=sys.stdout)
     >>> parser.parse_args(['input.txt', 'output.txt'])
     Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
               outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
     >>> parser.parse_args([])
     Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
               outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

* "'*'". Todos os argumentos de linha de comando presentes são
  reunidos em uma lista. Note que geralmente não faz muito sentido ter
  mais de um argumento posicional com "nargs='*'", mas vários
  argumentos opcionais com "nargs='*'" são possíveis. Por exemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='*')
     >>> parser.add_argument('--bar', nargs='*')
     >>> parser.add_argument('baz', nargs='*')
     >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
     Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

* "'+'". Assim como "'*'", todos os argumentos de linha de comando
  presentes são reunidos em uma lista. Além disso, uma mensagem de
  erro será gerada se não houver pelo menos um argumento de linha de
  comando presente. Por exemplo:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('foo', nargs='+')
     >>> parser.parse_args(['a', 'b'])
     Namespace(foo=['a', 'b'])
     >>> parser.parse_args([])
     usage: PROG [-h] foo [foo ...]
     PROG: error: the following arguments are required: foo

* "argparse.REMAINDER".  All the remaining command-line arguments are
  gathered into a list.  This is commonly useful for command line
  utilities that dispatch to other command line utilities:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--foo')
     >>> parser.add_argument('command')
     >>> parser.add_argument('args', nargs=argparse.REMAINDER)
     >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
     Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

Se o argumento nomeado "nargs" não for fornecido, o número de
argumentos consumidos é determinado pela action. Geralmente, isso
significa que um único argumento de linha de comando será consumido e
um único item (não uma lista) será produzido.


const
-----

O argumento "const" de "add_argument()" é usado para manter valores
constantes que não são lidos da linha de comando, mas são necessários
para as várias ações "ArgumentParser". Os dois usos mais comuns são:

* Quando "add_argument()" é chamado com "action='store_const'" ou
  "action='append_const'". Essas ações adicionam o valor "const" a um
  dos atributos do objeto retornado por "parse_args()". Consulte a
  descrição da action para obter exemplos.

* Quando "add_argument()" é chamado com strings de opções (como "-f"
  ou "--foo") e "nargs='?'". Isso cria um argumento opcional que pode
  ser seguido por zero ou um argumento de linha de comando. Ao
  analisar a linha de comando, se a string de opções for encontrada
  sem nenhum argumento de linha de comando seguindo, o valor de
  "const" será assumido. Veja a descrição de nargs para exemplos.

Com as ações "'store_const'" e "'append_const'", o argumento nomeado
"const" deve ser fornecido. Para outras ações, o padrão é "None".


default
-------

Todos os argumentos opcionais e alguns argumentos posicionais podem
ser omitidos na linha de comando. O argumento nomeado "default" de
"add_argument()", cujo valor padrão é "None", especifica qual valor
deve ser usado se o argumento de linha de comando não estiver
presente. Para argumentos opcionais, o valor "default" é usado quando
a string de opção não estava presente na linha de comando:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', default=42)
   >>> parser.parse_args(['--foo', '2'])
   Namespace(foo='2')
   >>> parser.parse_args([])
   Namespace(foo=42)

Se o valor "default" for uma string, o analisador analisa o valor como
se fosse um argumento de linha de comando. Em particular, o analisador
aplica qualquer argumento de conversão type, se fornecido, antes de
definir o atributo no valor de retorno "Namespace". Caso contrário, o
analisador usa o valor como está:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--length', default='10', type=int)
   >>> parser.add_argument('--width', default=10.5, type=int)
   >>> parser.parse_args()
   Namespace(length=10, width=10.5)

For positional arguments with nargs equal to "?" or "*", the "default"
value is used when no command-line argument was present:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('foo', nargs='?', default=42)
   >>> parser.parse_args(['a'])
   Namespace(foo='a')
   >>> parser.parse_args([])
   Namespace(foo=42)

Providing "default=argparse.SUPPRESS" causes no attribute to be added
if the command-line argument was not present:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
   >>> parser.parse_args([])
   Namespace()
   >>> parser.parse_args(['--foo', '1'])
   Namespace(foo='1')


tipo
----

By default, "ArgumentParser" objects read command-line arguments in as
simple strings. However, quite often the command-line string should
instead be interpreted as another type, like a "float" or "int".  The
"type" keyword argument of "add_argument()" allows any necessary type-
checking and type conversions to be performed.  Common built-in types
and functions can be used directly as the value of the "type"
argument:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('foo', type=int)
   >>> parser.add_argument('bar', type=open)
   >>> parser.parse_args('2 temp.txt'.split())
   Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

See the section on the default keyword argument for information on
when the "type" argument is applied to default arguments.

To ease the use of various types of files, the argparse module
provides the factory FileType which takes the "mode=", "bufsize=",
"encoding=" and "errors=" arguments of the "open()" function.  For
example, "FileType('w')" can be used to create a writable file:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar', type=argparse.FileType('w'))
   >>> parser.parse_args(['out.txt'])
   Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

"type=" can take any callable that takes a single string argument and
returns the converted value:

   >>> def perfect_square(string):
   ...     value = int(string)
   ...     sqrt = math.sqrt(value)
   ...     if sqrt != int(sqrt):
   ...         msg = "%r is not a perfect square" % string
   ...         raise argparse.ArgumentTypeError(msg)
   ...     return value
   ...
   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('foo', type=perfect_square)
   >>> parser.parse_args(['9'])
   Namespace(foo=9)
   >>> parser.parse_args(['7'])
   usage: PROG [-h] foo
   PROG: error: argument foo: '7' is not a perfect square

The choices keyword argument may be more convenient for type checkers
that simply check against a range of values:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('foo', type=int, choices=range(5, 10))
   >>> parser.parse_args(['7'])
   Namespace(foo=7)
   >>> parser.parse_args(['11'])
   usage: PROG [-h] {5,6,7,8,9}
   PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

See the choices section for more details.


choices
-------

Some command-line arguments should be selected from a restricted set
of values. These can be handled by passing a container object as the
*choices* keyword argument to "add_argument()".  When the command line
is parsed, argument values will be checked, and an error message will
be displayed if the argument was not one of the acceptable values:

   >>> parser = argparse.ArgumentParser(prog='game.py')
   >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
   >>> parser.parse_args(['rock'])
   Namespace(move='rock')
   >>> parser.parse_args(['fire'])
   usage: game.py [-h] {rock,paper,scissors}
   game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
   'paper', 'scissors')

Note that inclusion in the *choices* container is checked after any
type conversions have been performed, so the type of the objects in
the *choices* container should match the type specified:

   >>> parser = argparse.ArgumentParser(prog='doors.py')
   >>> parser.add_argument('door', type=int, choices=range(1, 4))
   >>> print(parser.parse_args(['3']))
   Namespace(door=3)
   >>> parser.parse_args(['4'])
   usage: doors.py [-h] {1,2,3}
   doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Any object that supports the "in" operator can be passed as the
*choices* value, so "dict" objects, "set" objects, custom containers,
etc. are all supported.


required
--------

In general, the "argparse" module assumes that flags like "-f" and "--
bar" indicate *optional* arguments, which can always be omitted at the
command line. To make an option *required*, "True" can be specified
for the "required=" keyword argument to "add_argument()":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', required=True)
   >>> parser.parse_args(['--foo', 'BAR'])
   Namespace(foo='BAR')
   >>> parser.parse_args([])
   usage: argparse.py [-h] [--foo FOO]
   argparse.py: error: option --foo is required

As the example shows, if an option is marked as "required",
"parse_args()" will report an error if that option is not present at
the command line.

Nota:

  Required options are generally considered bad form because users
  expect *options* to be *optional*, and thus they should be avoided
  when possible.


help
----

The "help" value is a string containing a brief description of the
argument. When a user requests help (usually by using "-h" or "--help"
at the command line), these "help" descriptions will be displayed with
each argument:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', action='store_true',
   ...                     help='foo the bars before frobbling')
   >>> parser.add_argument('bar', nargs='+',
   ...                     help='one of the bars to be frobbled')
   >>> parser.parse_args(['-h'])
   usage: frobble [-h] [--foo] bar [bar ...]

   positional arguments:
    bar     one of the bars to be frobbled

   optional arguments:
    -h, --help  show this help message and exit
    --foo   foo the bars before frobbling

The "help" strings can include various format specifiers to avoid
repetition of things like the program name or the argument default.
The available specifiers include the program name, "%(prog)s" and most
keyword arguments to "add_argument()", e.g. "%(default)s", "%(type)s",
etc.:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('bar', nargs='?', type=int, default=42,
   ...                     help='the bar to %(prog)s (default: %(default)s)')
   >>> parser.print_help()
   usage: frobble [-h] [bar]

   positional arguments:
    bar     the bar to frobble (default: 42)

   optional arguments:
    -h, --help  show this help message and exit

As the help string supports %-formatting, if you want a literal "%" to
appear in the help string, you must escape it as "%%".

"argparse" supports silencing the help entry for certain options, by
setting the "help" value to "argparse.SUPPRESS":

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
   >>> parser.print_help()
   usage: frobble [-h]

   optional arguments:
     -h, --help  show this help message and exit


metavar
-------

When "ArgumentParser" generates help messages, it needs some way to
refer to each expected argument.  By default, ArgumentParser objects
use the dest value as the "name" of each object.  By default, for
positional argument actions, the dest value is used directly, and for
optional argument actions, the dest value is uppercased.  So, a single
positional argument with "dest='bar'" will be referred to as "bar". A
single optional argument "--foo" that should be followed by a single
command-line argument will be referred to as "FOO".  An example:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo FOO] bar

   positional arguments:
    bar

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO

An alternative name can be specified with "metavar":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', metavar='YYY')
   >>> parser.add_argument('bar', metavar='XXX')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo YYY] XXX

   positional arguments:
    XXX

   optional arguments:
    -h, --help  show this help message and exit
    --foo YYY

Note that "metavar" only changes the *displayed* name - the name of
the attribute on the "parse_args()" object is still determined by the
dest value.

Different values of "nargs" may cause the metavar to be used multiple
times. Providing a tuple to "metavar" specifies a different display
for each of the arguments:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', nargs=2)
   >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
   >>> parser.print_help()
   usage: PROG [-h] [-x X X] [--foo bar baz]

   optional arguments:
    -h, --help     show this help message and exit
    -x X X
    --foo bar baz


dest
----

Most "ArgumentParser" actions add some value as an attribute of the
object returned by "parse_args()".  The name of this attribute is
determined by the "dest" keyword argument of "add_argument()".  For
positional argument actions, "dest" is normally supplied as the first
argument to "add_argument()":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['XXX'])
   Namespace(bar='XXX')

For optional argument actions, the value of "dest" is normally
inferred from the option strings.  "ArgumentParser" generates the
value of "dest" by taking the first long option string and stripping
away the initial "--" string.  If no long option strings were
supplied, "dest" will be derived from the first short option string by
stripping the initial "-" character.  Any internal "-" characters will
be converted to "_" characters to make sure the string is a valid
attribute name.  The examples below illustrate this behavior:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('-f', '--foo-bar', '--foo')
   >>> parser.add_argument('-x', '-y')
   >>> parser.parse_args('-f 1 -x 2'.split())
   Namespace(foo_bar='1', x='2')
   >>> parser.parse_args('--foo 1 -y 2'.split())
   Namespace(foo_bar='1', x='2')

"dest" allows a custom attribute name to be provided:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', dest='bar')
   >>> parser.parse_args('--foo XXX'.split())
   Namespace(bar='XXX')


Action classes
--------------

Action classes implement the Action API, a callable which returns a
callable which processes arguments from the command-line. Any object
which follows this API may be passed as the "action" parameter to
"add_argument()".

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Action objects are used by an ArgumentParser to represent the
information needed to parse a single argument from one or more strings
from the command line. The Action class must accept the two positional
arguments plus any keyword arguments passed to
"ArgumentParser.add_argument()" except for the "action" itself.

Instances of Action (or return value of any callable to the "action"
parameter) should have attributes "dest", "option_strings", "default",
"type", "required", "help", etc. defined. The easiest way to ensure
these attributes are defined is to call "Action.__init__".

Action instances should be callable, so subclasses must override the
"__call__" method, which should accept four parameters:

* "parser" - The ArgumentParser object which contains this action.

* "namespace" - The "Namespace" object that will be returned by
  "parse_args()".  Most actions add an attribute to this object using
  "setattr()".

* "values" - The associated command-line arguments, with any type
  conversions applied.  Type conversions are specified with the type
  keyword argument to "add_argument()".

* "option_string" - The option string that was used to invoke this
  action. The "option_string" argument is optional, and will be absent
  if the action is associated with a positional argument.

The "__call__" method may perform arbitrary actions, but will
typically set attributes on the "namespace" based on "dest" and
"values".


The parse_args() method
=======================

ArgumentParser.parse_args(args=None, namespace=None)

   Convert argument strings to objects and assign them as attributes
   of the namespace.  Return the populated namespace.

   Previous calls to "add_argument()" determine exactly what objects
   are created and how they are assigned. See the documentation for
   "add_argument()" for details.

   * args - List of strings to parse.  The default is taken from
     "sys.argv".

   * namespace - An object to take the attributes.  The default is a
     new empty "Namespace" object.


Option value syntax
-------------------

The "parse_args()" method supports several ways of specifying the
value of an option (if it takes one).  In the simplest case, the
option and its value are passed as two separate arguments:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x')
   >>> parser.add_argument('--foo')
   >>> parser.parse_args(['-x', 'X'])
   Namespace(foo=None, x='X')
   >>> parser.parse_args(['--foo', 'FOO'])
   Namespace(foo='FOO', x=None)

For long options (options with names longer than a single character),
the option and value can also be passed as a single command-line
argument, using "=" to separate them:

   >>> parser.parse_args(['--foo=FOO'])
   Namespace(foo='FOO', x=None)

For short options (options only one character long), the option and
its value can be concatenated:

   >>> parser.parse_args(['-xX'])
   Namespace(foo=None, x='X')

Several short options can be joined together, using only a single "-"
prefix, as long as only the last option (or none of them) requires a
value:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', action='store_true')
   >>> parser.add_argument('-y', action='store_true')
   >>> parser.add_argument('-z')
   >>> parser.parse_args(['-xyzZ'])
   Namespace(x=True, y=True, z='Z')


Argumentos inválidos
--------------------

While parsing the command line, "parse_args()" checks for a variety of
errors, including ambiguous options, invalid types, invalid options,
wrong number of positional arguments, etc.  When it encounters such an
error, it exits and prints the error along with a usage message:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo', type=int)
   >>> parser.add_argument('bar', nargs='?')

   >>> # invalid type
   >>> parser.parse_args(['--foo', 'spam'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: argument --foo: invalid int value: 'spam'

   >>> # invalid option
   >>> parser.parse_args(['--bar'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: no such option: --bar

   >>> # wrong number of arguments
   >>> parser.parse_args(['spam', 'badger'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: extra arguments found: badger


Argumentos contendo "-"
-----------------------

The "parse_args()" method attempts to give errors whenever the user
has clearly made a mistake, but some situations are inherently
ambiguous.  For example, the command-line argument "-1" could either
be an attempt to specify an option or an attempt to provide a
positional argument. The "parse_args()" method is cautious here:
positional arguments may only begin with "-" if they look like
negative numbers and there are no options in the parser that look like
negative numbers:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x')
   >>> parser.add_argument('foo', nargs='?')

   >>> # no negative number options, so -1 is a positional argument
   >>> parser.parse_args(['-x', '-1'])
   Namespace(foo=None, x='-1')

   >>> # no negative number options, so -1 and -5 are positional arguments
   >>> parser.parse_args(['-x', '-1', '-5'])
   Namespace(foo='-5', x='-1')

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-1', dest='one')
   >>> parser.add_argument('foo', nargs='?')

   >>> # negative number options present, so -1 is an option
   >>> parser.parse_args(['-1', 'X'])
   Namespace(foo=None, one='X')

   >>> # negative number options present, so -2 is an option
   >>> parser.parse_args(['-2'])
   usage: PROG [-h] [-1 ONE] [foo]
   PROG: error: no such option: -2

   >>> # negative number options present, so both -1s are options
   >>> parser.parse_args(['-1', '-1'])
   usage: PROG [-h] [-1 ONE] [foo]
   PROG: error: argument -1: expected one argument

If you have positional arguments that must begin with "-" and don't
look like negative numbers, you can insert the pseudo-argument "'--'"
which tells "parse_args()" that everything after that is a positional
argument:

   >>> parser.parse_args(['--', '-f'])
   Namespace(foo='-f', one=None)


Argument abbreviations (prefix matching)
----------------------------------------

The "parse_args()" method by default allows long options to be
abbreviated to a prefix, if the abbreviation is unambiguous (the
prefix matches a unique option):

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-bacon')
   >>> parser.add_argument('-badger')
   >>> parser.parse_args('-bac MMM'.split())
   Namespace(bacon='MMM', badger=None)
   >>> parser.parse_args('-bad WOOD'.split())
   Namespace(bacon=None, badger='WOOD')
   >>> parser.parse_args('-ba BA'.split())
   usage: PROG [-h] [-bacon BACON] [-badger BADGER]
   PROG: error: ambiguous option: -ba could match -badger, -bacon

An error is produced for arguments that could produce more than one
options. This feature can be disabled by setting allow_abbrev to
"False".


Além do "sys.argv"
------------------

Sometimes it may be useful to have an ArgumentParser parse arguments
other than those of "sys.argv".  This can be accomplished by passing a
list of strings to "parse_args()".  This is useful for testing at the
interactive prompt:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument(
   ...     'integers', metavar='int', type=int, choices=range(10),
   ...     nargs='+', help='an integer in the range 0..9')
   >>> parser.add_argument(
   ...     '--sum', dest='accumulate', action='store_const', const=sum,
   ...     default=max, help='sum the integers (default: find the max)')
   >>> parser.parse_args(['1', '2', '3', '4'])
   Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
   >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
   Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])


O objeto Namespace
------------------

class argparse.Namespace

   Simple class used by default by "parse_args()" to create an object
   holding attributes and return it.

This class is deliberately simple, just an "object" subclass with a
readable string representation. If you prefer to have dict-like view
of the attributes, you can use the standard Python idiom, "vars()":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> args = parser.parse_args(['--foo', 'BAR'])
   >>> vars(args)
   {'foo': 'BAR'}

It may also be useful to have an "ArgumentParser" assign attributes to
an already existing object, rather than a new "Namespace" object.
This can be achieved by specifying the "namespace=" keyword argument:

   >>> class C:
   ...     pass
   ...
   >>> c = C()
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
   >>> c.foo
   'BAR'


Other utilities
===============


Sub-comandos
------------

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, help][, metavar])

   Many programs split up their functionality into a number of sub-
   commands, for example, the "svn" program can invoke sub-commands
   like "svn checkout", "svn update", and "svn commit".  Splitting up
   functionality this way can be a particularly good idea when a
   program performs several different functions which require
   different kinds of command-line arguments. "ArgumentParser"
   supports the creation of such sub-commands with the
   "add_subparsers()" method.  The "add_subparsers()" method is
   normally called with no arguments and returns a special action
   object.  This object has a single method, "add_parser()", which
   takes a command name and any "ArgumentParser" constructor
   arguments, and returns an "ArgumentParser" object that can be
   modified as usual.

   Descrição de parâmetros:

   * title - title for the sub-parser group in help output; by default
     "subcommands" if description is provided, otherwise uses title
     for positional arguments

   * description - description for the sub-parser group in help
     output, by default "None"

   * prog - usage information that will be displayed with sub-command
     help, by default the name of the program and any positional
     arguments before the subparser argument

   * parser_class - class which will be used to create sub-parser
     instances, by default the class of the current parser (e.g.
     ArgumentParser)

   * action - the basic type of action to be taken when this argument
     is encountered at the command line

   * dest - name of the attribute under which sub-command name will be
     stored; by default "None" and no value is stored

   * required - Whether or not a subcommand must be provided, by
     default "False" (added in 3.7)

   * help - help for sub-parser group in help output, by default
     "None"

   * metavar - string presenting available sub-commands in help; by
     default it is "None" and presents sub-commands in form {cmd1,
     cmd2, ..}

   Alguns exemplos de uso:

      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='sub-command help')
      >>>
      >>> # create the parser for the "a" command
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)

   Note that the object returned by "parse_args()" will only contain
   attributes for the main parser and the subparser that was selected
   by the command line (and not any other subparsers).  So in the
   example above, when the "a" command is specified, only the "foo"
   and "bar" attributes are present, and when the "b" command is
   specified, only the "foo" and "baz" attributes are present.

   Similarly, when a help message is requested from a subparser, only
   the help for that particular parser will be printed.  The help
   message will not include parent parser or sibling parser messages.
   (A help message for each subparser command, however, can be given
   by supplying the "help=" argument to "add_parser()" as above.)

      >>> parser.parse_args(['--help'])
      usage: PROG [-h] [--foo] {a,b} ...

      positional arguments:
        {a,b}   sub-command help
          a     a help
          b     b help

      optional arguments:
        -h, --help  show this help message and exit
        --foo   foo help

      >>> parser.parse_args(['a', '--help'])
      usage: PROG a [-h] bar

      positional arguments:
        bar     bar help

      optional arguments:
        -h, --help  show this help message and exit

      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]

      optional arguments:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help

   The "add_subparsers()" method also supports "title" and
   "description" keyword arguments.  When either is present, the
   subparser's commands will appear in their own group in the help
   output.  For example:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(title='subcommands',
      ...                                    description='valid subcommands',
      ...                                    help='additional help')
      >>> subparsers.add_parser('foo')
      >>> subparsers.add_parser('bar')
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...

      optional arguments:
        -h, --help  show this help message and exit

      subcommands:
        valid subcommands

        {foo,bar}   additional help

   Furthermore, "add_parser" supports an additional "aliases"
   argument, which allows multiple strings to refer to the same
   subparser. This example, like "svn", aliases "co" as a shorthand
   for "checkout":

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
      >>> checkout.add_argument('foo')
      >>> parser.parse_args(['co', 'bar'])
      Namespace(foo='bar')

   One particularly effective way of handling sub-commands is to
   combine the use of the "add_subparsers()" method with calls to
   "set_defaults()" so that each subparser knows which Python function
   it should execute.  For example:

      >>> # sub-command functions
      >>> def foo(args):
      ...     print(args.x * args.y)
      ...
      >>> def bar(args):
      ...     print('((%s))' % args.z)
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')
      >>> parser_foo.add_argument('-x', type=int, default=1)
      >>> parser_foo.add_argument('y', type=float)
      >>> parser_foo.set_defaults(func=foo)
      >>>
      >>> # create the parser for the "bar" command
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

   This way, you can let "parse_args()" do the job of calling the
   appropriate function after argument parsing is complete.
   Associating functions with actions like this is typically the
   easiest way to handle the different actions for each of your
   subparsers.  However, if it is necessary to check the name of the
   subparser that was invoked, the "dest" keyword argument to the
   "add_subparsers()" call will work:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
      >>> subparser1 = subparsers.add_parser('1')
      >>> subparser1.add_argument('-x')
      >>> subparser2 = subparsers.add_parser('2')
      >>> subparser2.add_argument('y')
      >>> parser.parse_args(['2', 'frobble'])
      Namespace(subparser_name='2', y='frobble')

   Alterado na versão 3.7: New *required* keyword argument.


Objetos FileType
----------------

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

   The "FileType" factory creates objects that can be passed to the
   type argument of "ArgumentParser.add_argument()".  Arguments that
   have "FileType" objects as their type will open command-line
   arguments as files with the requested modes, buffer sizes,
   encodings and error handling (see the "open()" function for more
   details):

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
      >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
      >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
      Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

   FileType objects understand the pseudo-argument "'-'" and
   automatically convert this into "sys.stdin" for readable "FileType"
   objects and "sys.stdout" for writable "FileType" objects:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', type=argparse.FileType('r'))
      >>> parser.parse_args(['-'])
      Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

   Novo na versão 3.4: The *encodings* and *errors* keyword arguments.


Grupos de Argumentos
--------------------

ArgumentParser.add_argument_group(title=None, description=None)

   By default, "ArgumentParser" groups command-line arguments into
   "positional arguments" and "optional arguments" when displaying
   help messages. When there is a better conceptual grouping of
   arguments than this default one, appropriate groups can be created
   using the "add_argument_group()" method:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group = parser.add_argument_group('group')
      >>> group.add_argument('--foo', help='foo help')
      >>> group.add_argument('bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--foo FOO] bar

      group:
        bar    bar help
        --foo FOO  foo help

   The "add_argument_group()" method returns an argument group object
   which has an "add_argument()" method just like a regular
   "ArgumentParser".  When an argument is added to the group, the
   parser treats it just like a normal argument, but displays the
   argument in a separate group for help messages.  The
   "add_argument_group()" method accepts *title* and *description*
   arguments which can be used to customize this display:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

   Note that any arguments not in your user-defined groups will end up
   back in the usual "positional arguments" and "optional arguments"
   sections.


Exclusão Mútua
--------------

ArgumentParser.add_mutually_exclusive_group(required=False)

   Create a mutually exclusive group. "argparse" will make sure that
   only one of the arguments in the mutually exclusive group was
   present on the command line:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

   The "add_mutually_exclusive_group()" method also accepts a
   *required* argument, to indicate that at least one of the mutually
   exclusive arguments is required:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group(required=True)
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args([])
      usage: PROG [-h] (--foo | --bar)
      PROG: error: one of the arguments --foo --bar is required

   Note that currently mutually exclusive argument groups do not
   support the *title* and *description* arguments of
   "add_argument_group()".


Parser defaults
---------------

ArgumentParser.set_defaults(**kwargs)

   Most of the time, the attributes of the object returned by
   "parse_args()" will be fully determined by inspecting the command-
   line arguments and the argument actions.  "set_defaults()" allows
   some additional attributes that are determined without any
   inspection of the command line to be added:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('foo', type=int)
      >>> parser.set_defaults(bar=42, baz='badger')
      >>> parser.parse_args(['736'])
      Namespace(bar=42, baz='badger', foo=736)

   Note that parser-level defaults always override argument-level
   defaults:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='bar')
      >>> parser.set_defaults(foo='spam')
      >>> parser.parse_args([])
      Namespace(foo='spam')

   Parser-level defaults can be particularly useful when working with
   multiple parsers.  See the "add_subparsers()" method for an example
   of this type.

ArgumentParser.get_default(dest)

   Get the default value for a namespace attribute, as set by either
   "add_argument()" or by "set_defaults()":

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='badger')
      >>> parser.get_default('foo')
      'badger'


Imprimindo a ajuda
------------------

In most typical applications, "parse_args()" will take care of
formatting and printing any usage or error messages.  However, several
formatting methods are available:

ArgumentParser.print_usage(file=None)

   Print a brief description of how the "ArgumentParser" should be
   invoked on the command line.  If *file* is "None", "sys.stdout" is
   assumed.

ArgumentParser.print_help(file=None)

   Print a help message, including the program usage and information
   about the arguments registered with the "ArgumentParser".  If
   *file* is "None", "sys.stdout" is assumed.

There are also variants of these methods that simply return a string
instead of printing it:

ArgumentParser.format_usage()

   Return a string containing a brief description of how the
   "ArgumentParser" should be invoked on the command line.

ArgumentParser.format_help()

   Return a string containing a help message, including the program
   usage and information about the arguments registered with the
   "ArgumentParser".


Análise parcial
---------------

ArgumentParser.parse_known_args(args=None, namespace=None)

Sometimes a script may only parse a few of the command-line arguments,
passing the remaining arguments on to another script or program. In
these cases, the "parse_known_args()" method can be useful.  It works
much like "parse_args()" except that it does not produce an error when
extra arguments are present.  Instead, it returns a two item tuple
containing the populated namespace and the list of remaining argument
strings.

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action='store_true')
   >>> parser.add_argument('bar')
   >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
   (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Aviso:

  Prefix matching rules apply to "parse_known_args()". The parser may
  consume an option even if it's just a prefix of one of its known
  options, instead of leaving it in the remaining arguments list.


Customizing file parsing
------------------------

ArgumentParser.convert_arg_line_to_args(arg_line)

   Arguments that are read from a file (see the
   *fromfile_prefix_chars* keyword argument to the "ArgumentParser"
   constructor) are read one argument per line.
   "convert_arg_line_to_args()" can be overridden for fancier reading.

   This method takes a single argument *arg_line* which is a string
   read from the argument file.  It returns a list of arguments parsed
   from this string. The method is called once per line read from the
   argument file, in order.

   A useful override of this method is one that treats each space-
   separated word as an argument.  The following example demonstrates
   how to do this:

      class MyArgumentParser(argparse.ArgumentParser):
          def convert_arg_line_to_args(self, arg_line):
              return arg_line.split()


Métodos existentes
------------------

ArgumentParser.exit(status=0, message=None)

   This method terminates the program, exiting with the specified
   *status* and, if given, it prints a *message* before that.

ArgumentParser.error(message)

   This method prints a usage message including the *message* to the
   standard error and terminates the program with a status code of 2.


Intermixed parsing
------------------

ArgumentParser.parse_intermixed_args(args=None, namespace=None)

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)

A number of Unix commands allow the user to intermix optional
arguments with positional arguments.  The "parse_intermixed_args()"
and "parse_known_intermixed_args()" methods support this parsing
style.

These parsers do not support all the argparse features, and will raise
exceptions if unsupported features are used.  In particular,
subparsers, "argparse.REMAINDER", and mutually exclusive groups that
include both optionals and positionals are not supported.

The following example shows the difference between
"parse_known_args()" and "parse_intermixed_args()": the former returns
"['2', '3']" as unparsed arguments, while the latter collects all the
positionals into "rest".

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('cmd')
   >>> parser.add_argument('rest', nargs='*', type=int)
   >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
   (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
   >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
   Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

"parse_known_intermixed_args()" returns a two item tuple containing
the populated namespace and the list of remaining argument strings.
"parse_intermixed_args()" raises an error if there are any remaining
unparsed argument strings.

Novo na versão 3.7.


Upgrading optparse code
=======================

Originally, the "argparse" module had attempted to maintain
compatibility with "optparse".  However, "optparse" was difficult to
extend transparently, particularly with the changes required to
support the new "nargs=" specifiers and better usage messages.  When
most everything in "optparse" had either been copy-pasted over or
monkey-patched, it no longer seemed practical to try to maintain the
backwards compatibility.

The "argparse" module improves on the standard library "optparse"
module in a number of ways including:

* Tratando argumentos posicionais.

* Supporting sub-commands.

* Allowing alternative option prefixes like "+" and "/".

* Handling zero-or-more and one-or-more style arguments.

* Producing more informative usage messages.

* Providing a much simpler interface for custom "type" and "action".

A partial upgrade path from "optparse" to "argparse":

* Replace all "optparse.OptionParser.add_option()" calls with
  "ArgumentParser.add_argument()" calls.

* Replace "(options, args) = parser.parse_args()" with "args =
  parser.parse_args()" and add additional
  "ArgumentParser.add_argument()" calls for the positional arguments.
  Keep in mind that what was previously called "options", now in the
  "argparse" context is called "args".

* Replace "optparse.OptionParser.disable_interspersed_args()" by using
  "parse_intermixed_args()" instead of "parse_args()".

* Replace callback actions and the "callback_*" keyword arguments with
  "type" or "action" arguments.

* Replace string names for "type" keyword arguments with the
  corresponding type objects (e.g. int, float, complex, etc).

* Replace "optparse.Values" with "Namespace" and
  "optparse.OptionError" and "optparse.OptionValueError" with
  "ArgumentError".

* Replace strings with implicit arguments such as "%default" or
  "%prog" with the standard Python syntax to use dictionaries to
  format strings, that is, "%(default)s" and "%(prog)s".

* Replace the OptionParser constructor "version" argument with a call
  to "parser.add_argument('--version', action='version', version='<the
  version>')".
