"argparse" --- Analisador sintático 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 o tutorial do argparse.

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 analisador sintático
-------------------------------

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 necessá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, exit_on_error=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")

   * exit_on_error - Determina se ArgumentParser sai ou não com
     informações de erro quando ocorre um erro. (padrão: "True")

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

   Alterado na versão 3.8: Em versões anteriores, *allow_abbrev*
   também desabilitava o agrupamento de sinalizadores curtos, como
   "-vv" para significar "-v -v".

   Alterado na versão 3.9: O parâmetro *exit_on_error* 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 ...]

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

Às vezes, por exemplo, ao lidar com uma lista de argumentos
particularmente longa, pode fazer sentido manter a lista de argumentos
em um arquivo em vez de digitá-la na linha de comando. Se o argumento
"fromfile_prefix_chars=" for dado ao construtor "ArgumentParser",
então os argumentos que começam com qualquer um dos caracteres
especificados serão tratados como arquivos e serão substituídos pelos
argumentos que eles contêm. Por exemplo:

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


exit_on_error
-------------

Normalmente, quando você passa uma lista de argumentos inválidos para
o método "parse_args()" de um "ArgumentParser", ele sairá com
informações de erro.

Se o usuário quiser detectar erros manualmente, o recurso pode ser
habilitado configurando "exit_on_error" para "False":

   >>> parser = argparse.ArgumentParser(exit_on_error=False)
   >>> parser.add_argument('--integers', type=int)
   _StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
   >>> try:
   ...     parser.parse_args('--integers a'.split())
   ... except argparse.ArgumentError:
   ...     print('Catching an argumentError')
   ...
   Catching an argumentError

Novo na versão 3.9.


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 ou 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 - O valor produzido se o argumento estiver ausente da
     linha de comando e se estiver ausente do objeto espaço de nomes.

   * 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


ação
----

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

* "'extend'" - Isso armazena uma lista e estende cada valor de
  argumento para a lista. Exemplo de uso:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
     >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
     Namespace(foo=['f1', 'f2', 'f3', 'f4'])

  Novo na versão 3.8.

Você também pode especificar uma ação arbitrária passando uma
subclasse Action ou outro objeto que implemente a mesma interface. O
"BooleanOptionalAction" está disponível em "argparse" e adiciona
suporte para ações booleanas como "--foo" e "--no-foo":

   >>> import argparse
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
   >>> parser.parse_args(['--no-foo'])
   Namespace(foo=False)

Novo na versão 3.9.

A maneira recomendada de criar uma ação personalizada é estender
"Action", substituindo o método "__call__" e opcionalmente os métodos
"__init__" e "format_usage".

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

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 espaço de nomes de destino já tiver um atributo definido, a ação
*default* não o substituirá:

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

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)

Para argumentos posicionais com nargs igual a "?" ou "*", o valor
"default" é usado quando nenhum argumento de linha de comando estava
presente:

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

Fornecer "default=argparse.SUPPRESS" faz com que nenhum atributo seja
adicionado se o argumento da linha de comando não estiver presente:

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


tipo
----

Por padrão, o analisador sintático lê argumentos de linha de comando
como strings simples. No entanto, muitas vezes a string da linha de
comando deve ser interpretada como outro tipo, como "float" ou "int".
O argumento nomeado "type" para "add_argument()" permite que qualquer
verificação de tipo e conversões de tipo necessárias sejam realizadas.

Se o argumento nomeado type for usado com default, o conversor de tipo
só será aplicado se o padrão for uma string.

O argumento para "type" pode ser qualquer chamável que aceite uma
única string. Se a função levantar "ArgumentTypeError", "TypeError" ou
"ValueError", a exceção será capturada e uma mensagem de erro bem
formatada será exibida. Nenhum outro tipo de exceção é tratado.

Tipos e funções embutidas comuns podem ser usados como conversores de
tipo:

   import argparse
   import pathlib

   parser = argparse.ArgumentParser()
   parser.add_argument('count', type=int)
   parser.add_argument('distance', type=float)
   parser.add_argument('street', type=ascii)
   parser.add_argument('code_point', type=ord)
   parser.add_argument('source_file', type=open)
   parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
   parser.add_argument('datapath', type=pathlib.Path)

Funções definidas pelo usuário também podem ser usadas:

   >>> def hyphenated(string):
   ...     return '-'.join([word[:4] for word in string.casefold().split()])
   ...
   >>> parser = argparse.ArgumentParser()
   >>> _ = parser.add_argument('short_title', type=hyphenated)
   >>> parser.parse_args(['"The Tale of Two Cities"'])
   Namespace(short_title='"the-tale-of-two-citi')

A função "bool()" não é recomendada como conversor de tipo. Tudo o que
ele faz é converter strings vazias em "False" e strings não vazias em
"True". Geralmente não é isso que se deseja.

Em geral, o argumento nomeado "type" é uma conveniência que só deve
ser usada para conversões simples que só podem gerar uma das três
exceções suportadas. Qualquer coisa com tratamento de erros ou
gerenciamento de recursos mais interessante deve ser feita
posteriormente, após a análise dos argumentos.

For example, JSON or YAML conversions have complex error cases that
require better reporting than can be given by the "type" keyword.  A
"JSONDecodeError" would not be well formatted and a "FileNotFound"
exception would not be handled at all.

Mesmo "FileType" tem suas limitações para uso com o argumento nomeado
"type". Se um argumento usar *FileType* e um argumento subsequente
falhar, um erro será relatado, mas o arquivo não será fechado
automaticamente. Neste caso, seria melhor esperar até que o analisador
tenha sido executado e então usar a instrução "with" para gerenciar os
arquivos.

Para verificadores de tipo que simplesmente verificam um conjunto fixo
de valores, considere usar o argumento nomeado choices.


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 container can be passed as the *choices* value, so "list" objects,
"set" objects, and custom containers are all supported.

O uso de "enum.Enum" não é recomendado porque é difícil controlar sua
aparência no uso, na ajuda e nas mensagens de erro.

Formatted choices overrides the default *metavar* which is normally
derived from *dest*.  This is usually what you want because the user
never sees the *dest* parameter.  If this display isn't desirable
(perhaps because there are many choices), just specify an explicit
metavar.


required
--------

Em geral, o módulo "argparse" presume que sinalizadores como "-f" e "
--bar" indicam argumentos *opcionais*, que sempre podem ser omitidos
na linha de comando. Para tornar uma opção obrigatória, "True" pode
ser especificado para o argumento nomeado "required=" para
"add_argument()":

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

Como mostra o exemplo, se uma opção estiver marcada como "required",
"parse_args()" reportará um erro se essa opção não estiver presente na
linha de comando.

Nota:

  As opções obrigatórias são geralmente consideradas inadequadas
  porque os usuários esperam que as *opções* sejam *opcionais* e,
  portanto, devem ser evitadas quando possível.


help
----

O valor "help" é uma string contendo uma breve descrição do argumento.
Quando um usuário solicita ajuda (geralmente usando "-h" ou "--help"
na linha de comando), estas descrições de "help" serão exibidas com
cada argumento:

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

As strings "help" podem incluir vários especificadores de formato para
evitar a repetição de coisas como o nome do programa ou o argumento
default. Os especificadores disponíveis incluem o nome do programa,
"%(prog)s" e a maioria dos argumentos nomeados para "add_argument()",
por exemplo. "%(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

Como a string de ajuda oferece suporte à formatação com %, se você
quiser que um literal "%" apareça na string de ajuda, você deve
escapá-lo como "%%".

"argparse" oferece suporte a silenciar a entrada de ajuda para certas
opções, definindo o valor "help" como "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
-------

Quando "ArgumentParser" gera mensagens de ajuda, ele precisa de alguma
forma de se referir a cada argumento esperado. Por padrão, os objetos
ArgumentParser usam o valor dest como o "nome" de cada objeto. Por
padrão, para ações de argumentos posicionais, o valor dest é usado
diretamente, e para ações de argumentos opcionais, o valor dest é
maiúsculo. Portanto, um único argumento posicional com "dest='bar'"
será referido como "bar". Um único argumento opcional "--foo" que deve
ser seguido por um único argumento de linha de comando será referido
como "FOO". Um exemplo:

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

Um nome alternativo pode ser especificado com "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

Observe que "metavar" apenas altera o nome *exibido* - o nome do
atributo no objeto "parse_args()" ainda é determinado pelo valor dest.

Valores diferentes de "nargs" podem fazer com que o metavar seja usado
múltiplas vezes. Fornecer uma tupla para "metavar" especifica uma
exibição diferente para cada um dos argumentos:

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

A maioria das ações "ArgumentParser" adiciona algum valor como um
atributo do objeto retornado por "parse_args()". O nome deste atributo
é determinado pelo argumento nomeado "dest" de "add_argument()". Para
ações de argumento posicional, "dest" é normalmente fornecido como o
primeiro argumento para "add_argument()":

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

Para ações de argumentos opcionais, o valor de "dest" é normalmente
inferido das strings de opções. "ArgumentParser" gera o valor de
"dest" pegando a primeira string de opção longa e removendo a string
inicial "--". Se nenhuma string de opção longa for fornecida, "dest"
será derivado da primeira string de opção curta removendo o caractere
"-" inicial.  Quaisquer caracteres "-" internos serão convertidos em
caracteres "_" para garantir que a string seja um nome de atributo
válido. Os exemplos abaixo ilustram esse comportamento:

   >>> 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" permite que um nome de atributo personalizado seja fornecido:

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


Classes de ação
---------------

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)

Objetos de ação são usados por um ArgumentParser para representar as
informações necessárias para analisar um único argumento de uma ou
mais strings da linha de comando. A classe Action deve aceitar os dois
argumentos posicionais mais quaisquer argumentos nomeados passados
para "ArgumentParser.add_argument()", exceto o próprio "action".

Instâncias de Action (ou valor de retorno de qualquer callable para o
parâmetro "action") devem ter atributos "dest", "option_strings",
"default", "type", "required", "help", etc. definidos. A maneira mais
fácil de garantir que esses atributos sejam definidos é chamar
"Action.__init__".

As instâncias de Action devem ser chamáveis, portanto, as subclasses
devem substituir o método "__call__", que deve aceitar quatro
parâmetros:

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

O método "__call__" pode executar ações arbitrárias, mas normalmente
definirá atributos em "namespace" com base em "dest" e "values".

As subclasses de Action podem definir um método "format_usage" que não
recebe argumento e retorna uma string que será usada ao exibir a
mensagem de uso do programa. Se tal método não for fornecido, um
padrão sensato será usado.


O método parse_args()
=====================

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

   Converte strings de argumento em objetos e os atribui como
   atributos do espaço de nomes. Retorna o espaço de nomes preenchido.

   Chamadas anteriores para "add_argument()" determinam exatamente
   quais objetos são criados e como eles são atribuídos. Veja a
   documentação para "add_argument()" para detalhes.

   * args - Lista de strings para analisar. O padrão é obtido de
     "sys.argv".

   * namespace - Um objeto para receber os atributos. O padrão é um
     novo objeto "Namespace" vazio.


Sintaxe de valores da opção
---------------------------

O método "parse_args()" provê várias maneiras de especificar o valor
de uma opção (se ele pegar uma). No caso mais simples, a opção e seu
valor são passados como dois argumentos separados:

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

Para opções longas (opções com nomes maiores que um único caractere),
a opção e o valor também podem ser passados como um único argumento de
linha de comando, usando "=" para separá-los:

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

Para opções curtas (opções com apenas um caractere), a opção e seu
valor podem ser concatenados:

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

Várias opções curtas podem ser unidas, usando apenas um único prefixo
"-", desde que apenas a última opção (ou nenhuma delas) exija um
valor:

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

Ao analisar a linha de comando, "parse_args()" verifica uma variedade
de erros, incluindo opções ambíguas, tipos inválidos, opções
inválidas, número incorreto de argumentos posicionais, etc. Quando
encontra tal erro, ele sai e imprime o erro junto com uma mensagem de
uso:

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

O método "parse_args()" tenta mostrar erros sempre que o usuário
claramente cometeu um erro, mas algumas situações são inerentemente
ambíguas. Por exemplo, o argumento de linha de comando "-1" pode ser
uma tentativa de especificar uma opção ou uma tentativa de fornecer um
argumento posicional. O método "parse_args()" é cauteloso aqui:
argumentos posicionais só podem começar com "-" se eles se parecerem
com números negativos e não houver opções no analisador sintático que
se pareçam com números negativos:

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

Se você tiver argumentos posicionais que devem começar com "-" e não
se parecem com números negativos, você pode inserir o pseudoargumento
"'--'" que informa "parse_args()" que tudo depois disso é um argumento
posicional:

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


Abreviações de argumento (correspondência de prefixo)
-----------------------------------------------------

O método "parse_args()" por padrão permite que opções longas sejam
abreviadas para um prefixo, se a abreviação não for ambígua (o prefixo
corresponde a uma opção única):

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

Um erro é produzido para argumentos que podem produzir mais de uma
opção. Este recurso pode ser desabilitado definindo allow_abbrev como
"False".


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

Às vezes, pode ser útil ter uma insância de ArgumentParser analisando
argumentos diferentes daqueles de "sys.argv". Isso pode ser feito
passando uma lista de strings para "parse_args()". Isso é útil para
testar no prompt interativo:

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

   Classe simples usada por padrão por "parse_args()" para criar um
   objeto contendo atributos e retorná-lo.

Esta classe é deliberadamente simples, apenas uma subclasse "object"
com uma representação de string legível. Se você preferir ter uma
visão dos atributos do tipo dict, você pode usar o idioma padrão do
Python, "vars()":

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

Também pode ser útil ter um "ArgumentParser" atribuindo atributos a um
objeto já existente, em vez de um novo objeto "Namespace". Isso pode
ser obtido especificando o argumento nomeado "namespace=":

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


Outros utilitários
==================


Subcomandos
-----------

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 - o tipo básico de ação a ser executada quando esse
     argumento é encontrado na linha de comando

   * dest - nome do atributo sob o qual o nome do subcomando será
     armazenado; por padrão "None" e nenhum valor é armazenado

   * required - Se um subcomando deve ou não ser fornecido, por padrão
     "False" (adicionado em 3.7)

   * help - ajuda para o grupo de subanalisadores na saída de ajuda,
     por padrão "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 que o objeto retornado por "parse_args()" conterá apenas
   atributos para o analisador principal e o subanalisador que foi
   selecionado pela linha de comando (e não quaisquer outros
   subanalisadores). Então, no exemplo acima, quando o comando "a" é
   especificado, apenas os atributos "foo" e "bar" estão presentes, e
   quando o comando "b" é especificado, apenas os atributos "foo" e
   "baz" estão presentes.

   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

   O método "add_subparsers()" também oferece suporte aos argumentos
   nomeados "title" e "description". Quando qualquer um deles estiver
   presente, os comandos do subanalisador aparecerão em seu próprio
   grupo na saída de ajuda. Por exemplo:

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

   Além disso, "add_parser" oferece suporte a um argumento "aliases"
   adicional, que permite que múltiplas strings se refiram ao mesmo
   subanalisador sintático. Este exemplo, como "svn", alias "co" como
   uma abreviação para "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')

   Uma maneira particularmente eficaz de lidar com subcomandos é
   combinar o uso do método "add_subparsers()" com chamadas para
   "set_defaults()" para que cada subanalisador sintático saiba qual
   função Python deve executar. Por exemplo:

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

   Dessa forma, você pode deixar "parse_args()" fazer o trabalho de
   chamar a função apropriada após a análise sintática do argumento
   ser concluída. Associar funções com ações como essa é normalmente a
   maneira mais fácil de lidar com as diferentes ações para cada um
   dos seus subanalisadores. No entanto, se for necessário verificar o
   nome do subanalisador que foi invocado, o argumento nomeado "dest"
   para a chamada "add_subparsers()" funcionará:

      >>> 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: Novo argumento nomeado *required*.


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

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

   A fábrica "FileType" cria objetos que podem ser passados para o
   argumento de tipo de "ArgumentParser.add_argument()". Argumentos
   que têm objetos "FileType" como seu tipo abrirão argumentos de
   linha de comando como arquivos com os modos solicitados, tamanhos
   de buffer, codificações e tratamento de erros (veja a função
   "open()" para mais detalhes):

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

   O método "add_argument_group()" retorna um objeto de grupo de
   argumentos que tem um método "add_argument()" como um
   "ArgumentParser" regular. Quando um argumento é adicionado ao
   grupo, o analisador o trata como um argumento normal, mas exibe o
   argumento em um grupo separado para mensagens de ajuda. O método
   "add_argument_group()" aceita argumentos *title* e *description*
   que podem ser usados para personalizar esta exibição:

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

   Observe que quaisquer argumentos que não estejam nos grupos
   definidos pelo usuário retornarão às seções usuais de "argumentos
   posicionais" e "argumentos opcionais".


Exclusão mútua
--------------

ArgumentParser.add_mutually_exclusive_group(required=False)

   Cria um grupo mutuamente exclusivo. "argparse" garantirá que apenas
   um dos argumentos no grupo mutuamente exclusivo esteja presente na
   linha de comando:

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

   O método "add_mutually_exclusive_group()" também aceita um
   argumento *obrigatório*, para indicar que pelo menos um dos
   argumentos mutuamente exclusivos é necessário:

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


Padrões do analisador sintático
-------------------------------

ArgumentParser.set_defaults(**kwargs)

   Na maioria das vezes, os atributos do objeto retornado por
   "parse_args()" serão totalmente determinados pela inspeção dos
   argumentos da linha de comando e das ações dos argumentos.
   "set_defaults()" permite que alguns atributos adicionais que são
   determinados sem qualquer inspeção da linha de comando sejam
   adicionados:

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

   Observe que os padrões no nível do analisador sempre substituem os
   padrões no nível do argumento:

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

   Padrões de nível de analisador podem ser particularmente úteis ao
   trabalhar com vários analisadores. Veja o método "add_subparsers()"
   para um exemplo desse tipo.

ArgumentParser.get_default(dest)

   Obtém o valor padrão para um atributo de espaço de nomes, conforme
   definido por "add_argument()" ou por "set_defaults()":

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


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

Na maioria das aplicações típicas, "parse_args()" cuidará da
formatação e da impressão de quaisquer mensagens de uso ou erro. No
entanto, vários métodos de formatação estão disponíveis:

ArgumentParser.print_usage(file=None)

   Imprime uma breve descrição de como o "ArgumentParser" deve ser
   invocado na linha de comando. Se *file* for "None", "sys.stdout"
   será presumido.

ArgumentParser.print_help(file=None)

   Imprime uma mensagem de ajuda, incluindo o uso do programa e
   informações sobre os argumentos registrados com o "ArgumentParser".
   Se *file* for "None", "sys.stdout" será presumido.

Também há variantes desses métodos que simplesmente retornam uma
string em vez de imprimi-la:

ArgumentParser.format_usage()

   Retorna uma string contendo uma breve descrição de como o
   "ArgumentParser" deve ser invocado na linha de comando.

ArgumentParser.format_help()

   Retorna uma string contendo uma mensagem de ajuda, incluindo o uso
   do programa e informações sobre os argumentos registrados com o
   "ArgumentParser".


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

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

Às vezes, um script pode analisar apenas alguns dos argumentos da
linha de comando, passando os argumentos restantes para outro script
ou programa. Nesses casos, o método "parse_known_args()" pode ser
útil. Ele funciona muito como "parse_args()", exceto que não produz um
erro quando argumentos extras estão presentes. Em vez disso, ele
retorna uma tupla de dois itens contendo o espaço de nomes preenchido
e a lista de strings de argumentos restantes.

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


Personalizando a análise de arquivos
------------------------------------

ArgumentParser.convert_arg_line_to_args(arg_line)

   Argumentos lidos de um arquivo (veja o argumento nomeado
   *fromfile_prefix_chars* para o construtor "ArgumentParser") são
   lidos com um argumento por linha. "convert_arg_line_to_args()" pode
   ser substituído para uma leitura mais sofisticada.

   Este método recebe um único argumento *arg_line* que é uma string
   lida do arquivo de argumentos. Ele retorna uma lista de argumentos
   analisados dessa string. O método é chamado uma vez por linha lida
   do arquivo de argumentos, em ordem.

   Uma substituição útil desse método é aquela que trata cada palavra
   separada por espaços como um argumento. O exemplo a seguir
   demonstra como fazer isso:

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


Métodos de saída
----------------

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. The user
   can override this method to handle these steps differently:

      class ErrorCatchingArgumentParser(argparse.ArgumentParser):
          def exit(self, status=0, message=None):
              if status:
                  raise Exception(f'Exiting because of an error: {message}')
              exit(status)

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.


Análise misturada
-----------------

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

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

Vários comandos Unix permitem que o usuário misture argumentos
opcionais com argumentos posicionais. Os métodos
"parse_intermixed_args()" e "parse_known_intermixed_args()" oferecem
suporte a esse estilo de análise.

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.

O exemplo a seguir mostra a diferença entre "parse_known_args()" e
"parse_intermixed_args()": o primeiro retorna "['2', '3']" como
argumentos não analisados, enquanto o último coleta todos os
posicionais em "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()" retorna uma tupla de dois itens
contendo o espaço de nomes preenchido e a lista de strings de
argumentos restantes. "parse_intermixed_args()" levanta um erro se
houver strings de argumentos não analisadas restantes.

Novo na versão 3.7.


Atualizando código optparse
===========================

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.

* Permitir prefixos alternativos de opções como "+" e "/".

* Manipular argumentos de estilo "zero ou mais" e "um ou mais".

* Produzir mensagens de uso mais informativas.

* Fornecer uma interface muito mais simples para "type" e "action"
  personalizados.

Um caminho de atualização parcial de "optparse" para "argparse":

* Substituir todas as chamadas de "optparse.OptionParser.add_option()"
  por chamadas de "ArgumentParser.add_argument()".

* Substituir "(options, args) = parser.parse_args()" por "args =
  parser.parse_args()" e adicionar chamadas adicionais a
  "ArgumentParser.add_argument()" para os argumentos posicionais.
  Tenha em mente que o que anteriormente era chamado de "options",
  agora no contexto do "argparse" é chamado de "args".

* Substituir "optparse.OptionParser.disable_interspersed_args()"
  usando "parse_intermixed_args()" em vez de "parse_args()".

* Substituir ações de função de retorno e argumentos nomeados
  "callback_*" por argumentos "type" ou "action".

* Substituir nomes de strings para argumentos nomeados "type" pelos
  objetos de tipo correspondentes (por exemplo, int, float, complex,
  etc).

* Substituir "optparse.Values" por "Namespace" e
  "optparse.OptionError" e "optparse.OptionValueError" por
  "ArgumentError".

* Substituir strings com argumentos implícitos tal como "%default" ou
  "%prog" pela sintaxe padrão do Python para usar dicionários para
  formatar strings, ou seja, "%(default)s" e "%(prog)s".

* Substituir o argumento "version" do construtor do OptionParser por
  uma chamada a "parser.add_argument('--version', action='version',
  version='<the version>')".
