"argparse" --- Parser for command-line options, arguments and subcommands
*************************************************************************

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

The "argparse" module makes it easy to write user-friendly command-
line interfaces. The program defines what arguments it requires, and
"argparse" will figure out how to parse those out of "sys.argv".  The
"argparse" module also automatically generates help and usage
messages.  The module will also issue errors when users give the
program invalid arguments.

The "argparse" module's support for command-line interfaces is built
around an instance of "argparse.ArgumentParser".  It is a container
for argument specifications and has options that apply to the parser
as whole:

   parser = argparse.ArgumentParser(
                       prog='ProgramName',
                       description='What the program does',
                       epilog='Text at the bottom of help')

O método "ArgumentParser.add_argument()" anexa especificações de
argumentos individuais ao analisador. Ele oferece suporte a argumentos
posicionais, opções que aceitam valores e sinalizadores liga/desliga:

   parser.add_argument('filename')           # positional argument
   parser.add_argument('-c', '--count')      # option that takes a value
   parser.add_argument('-v', '--verbose',
                       action='store_true')  # on/off flag

O método "ArgumentParser.parse_args()" executa o analisador e coloca
os dados extraídos em um objeto "argparse.Namespace":

   args = parser.parse_args()
   print(args.filename, args.count, args.verbose)

Nota:

  If you're looking a guide about how to upgrade optparse code to
  argparse, see Upgrading Optparse Code.


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:
     "os.path.basename(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
     (por padrão, nenhum texto)

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

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

By default, "ArgumentParser" calculates the name of the program to
display in help messages depending on the way the Python interpreter
was run:

* The "base name" of "sys.argv[0]" if a file was passed as argument.

* The Python interpreter name followed by "sys.argv[0]" if a directory
  or a zipfile was passed as argument.

* The Python interpreter name followed by "-m" followed by the module
  or package name if the "-m" option was used.

This default is almost always desirable because it will make the help
messages match the string that was used to invoke the program on the
command line. However, to change this default behavior, another value
can be supplied using the "prog=" argument to "ArgumentParser":

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

   options:
    -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]

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


usage
-----

By default, "ArgumentParser" calculates the usage message from the
arguments it contains. The default message can be overridden with the
"usage=" keyword argument:

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

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

Most calls to the "ArgumentParser" constructor will use the
"description=" keyword argument.  This argument gives a brief
description of what the program does and how it works.  In help
messages, the description is displayed between the command-line usage
string and the help messages for the various arguments.

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

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

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

   options:
    -h, --help  show this help message and exit

"RawTextHelpFormatter" maintains whitespace for all sorts of help
text, including argument descriptions. However, multiple newlines are
replaced with one. If you wish to preserve multiple blank lines, add
spaces between the newlines.

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

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

   options:
     -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 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', encoding=sys.getfilesystemencoding()) 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']".

"ArgumentParser" usa *tratador de erros e codificação do sistema de
arquivos* para ler o arquivo que contém argumentos.

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

Alterado na versão 3.12: "ArgumentParser" changed encoding and errors
to read arguments files from default (e.g.
"locale.getpreferredencoding(False)" and ""strict"") to the
*filesystem encoding and error handler*. Arguments file should be
encoded in UTF-8 instead of ANSI Codepage on Windows.


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

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

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

By default, ArgumentParser objects add an option which simply displays
the parser's help message. If "-h" or "--help" is supplied at the
command line, the ArgumentParser help will be printed.

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

   options:
    --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]

   options:
     +h, ++help  show this help message and exit


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

Normally, when you pass an invalid argument list to the "parse_args()"
method of an "ArgumentParser", it will print a *message* to
"sys.stderr" and exit with a status code of 2.

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

Adicionado 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 - Uma sequência 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()" deve saber se um argumento opcional, como
"-f" ou "--foo", ou um argumento posicional, como uma lista de nomes
de arquivos, é esperado. Os primeiros argumentos passados ​​para
"add_argument()" devem, portanto, ser uma série de sinalizadores ou um
simples nome de argumento.

Por exemplo, um argumento opcional poderia 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'" - This just stores the argument's value.  This is the
  default action.

* "'store_const'" - Isso armazena o valor especificado pelo argumento
  nomeado const; observe que o argumento nomeado const tem como padrão
  "None". 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'" and "'store_false'" - These are special cases of
  "'store_const'" used for storing the values "True" and "False"
  respectively.  In addition, they create default values of "False"
  and "True" respectively:

     >>> 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.  É útil permitir que uma opção seja especificada várias
  vezes. Se o valor padrão não estiver vazio, os elementos padrão
  estarão presentes no valor analisado da opção, com quaisquer valores
  da linha de comando anexados após esses valores padrão. 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'])

  Adicionado na versão 3.8.

Only actions that consume command-line arguments (e.g. "'store'",
"'append'" or "'extend'") can be used with positional arguments.

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)

Adicionado 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. Veja também Especificando argumentos ambíguos. 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

If the "nargs" keyword argument is not provided, the number of
arguments consumed is determined by the action.  Generally this means
a single command-line argument will be consumed and a single item (not
a list) will be produced. Actions that do not consume command-line
arguments (e.g. "'store_const'") set "nargs=0".


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. Se "const" não for
  fornecido "add_argument()", será recebido um valor padrão de "None".

* 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á presumido como sendo "None". Veja a descrição de nargs
  para exemplos.

Alterado na versão 3.11: "const=None" por padrão, incluindo quando
"action='append_const'" ou "action='store_const'".


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)

If the target namespace already has an attribute set, the action
*default* will not overwrite it:

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

For required arguments, the "default" value is ignored. For example,
this applies to positional arguments with nargs values other than "?"
or "*", or optional arguments marked as "required=True".

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

Por exemplo, conversões JSON ou YAML têm casos de erros complexos que
exigem relatórios melhores do que os fornecidos pelo argumento nomeado
"type". Um "JSONDecodeError" não seria bem formatado e uma exceção
"FileNotFoundError" não seria tratada.

Even "FileType" has its limitations for use with the "type" keyword.
If one argument uses "FileType" and then a subsequent argument fails,
an error is reported but the file is not automatically closed.  In
this case, it would be better to wait until after the parser has run
and then use the "with"-statement to manage the files.

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


choices
-------

Alguns argumentos de linha de comando devem ser selecionados em um
conjunto restrito de valores. Eles podem ser tratados passando um
objeto sequência como o argumento nomeado *choices* para
"add_argument()". Quando a linha de comando for analisada, os valores
dos argumentos serão verificados e uma mensagem de erro será exibida
se o argumento não for um dos valores aceitáveis:

   >>> 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* sequence is checked after any
type conversions have been performed, so the type of the objects in
the *choices* sequence should match the type specified.

Qualquer sequência pode ser passada como o valor *choices*, portanto
objetos "list", objetos "tuple" e sequências personalizadas são todos
suportados.

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

As opções formatadas substituem o *metavar* padrão que normalmente é
derivado de *dest*. Geralmente é isso que você deseja porque o usuário
nunca vê o parâmetro *dest*. Se esta exibição não for desejável
(talvez porque haja muitas opções), basta especificar um metavar
explícito.


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

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.

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)

   options:
    -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]

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

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

   options:
    -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]

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

As classes de ação implementam a API de Action, um chamável que
retorna um chamável que processa argumentos da linha de comando.
Qualquer objeto que siga esta API pode ser passado como parâmetro
"action" para "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".

   Action subclasses can define a "format_usage" method that takes no
   argument and return a string which will be used when printing the
   usage of the program. If such method is not provided, a sensible
   default will be used.


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)

See also the argparse howto on ambiguous arguments for more details.


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_strings][, dest][, required][, help][, metavar])

   Many programs split up their functionality into a number of
   subcommands, for example, the "svn" program can invoke subcommands
   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 subcommands 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 subcommands in help; by
     default it is "None" and presents subcommands 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='subcommand 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=('X', 'Y', 'Z'), 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}   subcommand help
          a     a help
          b     b help

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

      options:
        -h, --help  show this help message and exit

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

      options:
        -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} ...

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

      >>> # subcommand 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(required=True)
      >>>
      >>> # 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'>)

   Alterado na versão 3.4: Added the *encodings* and *errors*
   parameters.


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

ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])

   By default, "ArgumentParser" groups command-line arguments into
   "positional arguments" and "options" 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

   The optional, keyword-only parameters argument_default and
   conflict_handler allow for finer-grained control of the behavior of
   the argument group. These parameters have the same meaning as in
   the "ArgumentParser" constructor, but apply specifically to the
   argument group rather than the entire parser.

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

   Alterado na versão 3.11: Calling "add_argument_group()" on an
   argument group is deprecated. This feature was never supported and
   does not always work correctly. The function exists on the API by
   accident through inheritance and will be removed in the future.


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()". However, a mutually exclusive group can be
   added to an argument group that has a title and description. For
   example:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_argument_group('Group title', 'Group description')
      >>> exclusive_group = group.add_mutually_exclusive_group(required=True)
      >>> exclusive_group.add_argument('--foo', help='foo help')
      >>> exclusive_group.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [-h] (--foo FOO | --bar BAR)

      options:
        -h, --help  show this help message and exit

      Group title:
        Group description

        --foo FOO   foo help
        --bar BAR   bar help

   Alterado na versão 3.11: Calling "add_argument_group()" or
   "add_mutually_exclusive_group()" on a mutually exclusive group is
   deprecated. These features were never supported and do not always
   work correctly. The functions exist on the API by accident through
   inheritance and will be removed in the future.


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* to "sys.stderr"
   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
   "sys.stderr" 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, 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.

   Adicionado na versão 3.7.


Exceções
========

exception argparse.ArgumentError

   An error from creating or using an argument (optional or
   positional).

   The string value of this exception is the message, augmented with
   information about the argument that caused it.

exception argparse.ArgumentTypeError

   Raised when something goes wrong converting a command line string
   to a type.

-[ Guias e tutoriais ]-

* Tutorial de Argparse

* Upgrading optparse code
