argparse
— Analisador sintático para opções de linha de comando, argumentos e subcomandos¶
Adicionado na versão 3.2.
Código-fonte: Lib/argparse.py
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 e mensagens de uso. O módulo também vai emitir erros quando o usuário prover argumentos inválidos para o programa.
O suporte do módulo argparse
para interfaces de linha de comando é construído em torno de uma instância de argparse.ArgumentParser
. É um contêiner para especificações de argumentos e possui opções que se aplicam ao analisador sintático como um todo:
parser = argparse.ArgumentParser(
prog='NomePrograma',
description='O que o programa faz',
epilog='Texto na parte inferior da memsagem de ajuda')
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') # argumento posicional
parser.add_argument('-c', '--count') # a opção recebe um valor
parser.add_argument('-v', '--verbose',
action='store_true') # sinalizador de ligar/desligar
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 for 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ídosformatter_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 - Determines whether or not
ArgumentParser
exits with error info when an error occurs. (default: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, ArgumentParser
calcula o nome do programa a ser exibido nas mensagens de ajuda dependendo da maneira como o interpretador Python foi executado:
O
nome base
desys.argv[0]
se um arquivo foi passado como argumento.O nome do interpretador Python seguido por
sys.argv[0]
se um diretório ou um arquivo zip foi passado como argumento.O nome do interpretador Python seguido por
-m
seguido pelo nome do módulo ou pacote se a opção-m
foi usada.
Este padrão é quase sempre desejável porque fará com que as mensagens de ajuda correspondam à string que foi usada para invocar o programa na linha de comando. No entanto, para alterar esse comportamento padrão, outro valor pode ser fornecido usando o argumento prog=
para ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='meuprograma')
>>> parser.print_help()
usage: meuprograma [-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='meuprograma')
>>> parser.add_argument('--foo', help='foo do programa %(prog)s')
>>> parser.print_help()
usage: meuprograma [-h] [--foo FOO]
options:
-h, --help show this help message and exit
--foo FOO foo do programa meuprograma
usage¶
Por padrão, ArgumentParser
calcula a mensagem de uso a partir dos argumentos que contém. A mensagem padrão pode ser substituída pelo 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
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¶
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.
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='Um foo que faz bars',
... epilog="E é assim que você faria foo de bar")
>>> parser.print_help()
usage: argparse.py [-h]
Um foo que faz bars
options:
-h, --help show this help message and exit
E é assim que você faria foo de 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='''esta descrição
... foi indentada de forma estranha,
... mas está tudo bem''',
... epilog='''
... da mesma forma para este epílogo, cujos espaços vão
... ser apagados e cujas palavras serão quebradas
... em algumas linhas''')
>>> parser.print_help()
usage: PROG [-h]
this description was indented weird but that is okay
options:
-h, --help show this help message and exit
da mesma forma para este epílogo, cujos espaços vão ser apagados e
cujas palavras serão quebradas em algumas linhas
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('''\
... Por favor, não bagunce este texto!
... --------------------------------
... Eu indentei o texto
... exatamente na forma
... que quero que fique
... '''))
>>> parser.print_help()
usage: PROG [-h]
Por favor, não bagunce este texto!
--------------------------------
Eu indentei o texto
exatamente na forma
que quero que fique
options:
-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])
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¶
Most command-line options will use -
as the prefix, e.g. -f/--foo
.
Parsers that need to support different or additional prefix
characters, e.g. for options
like +f
or /foo
, may specify them using the prefix_chars=
argument
to the ArgumentParser
constructor:
>>> 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
alterou a codificação e os erros para ler arquivos de argumentos do padrão (por exemplo, locale.getpreferredencoding(False)
e "strict"
) para tratador de erros e codificação do sistema de arquivos. O arquivo de argumentos deve ser codificado em UTF-8 em vez de página de código ANSI no 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='ajuda antiga de foo')
>>> parser.add_argument('--foo', help='nova ajuda de foo')
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='ajuda antiga de foo')
>>> parser.add_argument('--foo', help='nova ajuda de foo')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
options:
-h, --help show this help message and exit
-f FOO ajuda antiga de foo
--foo FOO nova ajuda de foo
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='ajuda de foo')
>>> parser.print_help()
usage: PROG [--foo FOO]
options:
--foo FOO ajuda de foo
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¶
Normalmente, quando você passa uma lista de argumentos inválidos para o método parse_args()
de uma instância de ArgumentParser
, ele vai exibir uma message para sys.stderr
e vai sair com o código de status de 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('Capturando um argumentError')
...
Capturando um 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][, deprecated])¶
Define como um único argumento de linha de comando deve ser analisado. Cada parâmetro tem sua própria descrição mais detalhada abaixo, mas resumidamente são eles:
name or flags - Either a name or a list of option strings, e.g.
'foo'
or'-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()
.deprecated - Se o uso do argumento foi descontinuado ou não.
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
action¶
Objetos ArgumentParser
associam argumentos de linha de comando com ações. Essas ações podem fazer praticamente qualquer coisa com os argumentos de linha de comando associados a elas, embora a maioria das ações simplesmente adicione um atributo ao objeto retornado por parse_args()
. O argumento nomeado action
especifica como os argumentos da linha de comando devem ser tratados. As ações fornecidas são:
'store'
- Isso apenas armazena o valor do argumento. Esta é a ação padrão.'store_const'
- Isso armazena o valor especificado pelo argumento nomeado const; observe que o argumento nomeado const tem como padrãoNone
. 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 valoresTrue
eFalse
respectivamente. Além disso, eles criam valores padrão deFalse
eTrue
respectivamente.>>> 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ãoNone
. 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'>])
'extend'
- Isso armazena uma lista e anexa cada item da lista de argumentos multivalorada a ela. A ação'extend'
é normalmente usada com o valor do argumento nomeado nargs'+'
ou'*'
. Observe que quando nargs éNone
(o padrão) ou'?'
, cada caractere da string do argumento será anexado à 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.
'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. VejaArgumentParser
para detalhes de como a saída é criada.'version'
- Isso espera um argumento nomeadoversion=
na chamadaadd_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
Somente ações que consomem argumentos de linha de comando (por exemplo, 'store'
, 'append'
ou 'extend'
) podem ser usadas com argumentos posicionais.
- class argparse.BooleanOptionalAction¶
You may also specify an arbitrary action by passing an
Action
subclass or other object that implements the same interface. TheBooleanOptionalAction
is available inargparse
and adds support for boolean actions such as--foo
and--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.
The recommended way to create a custom action is to extend Action
,
overriding the __call__()
method and optionally the __init__()
and
format_usage()
methods.
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¶
ArgumentParser
objects usually associate a single command-line argument with a
single action to be taken. The nargs
keyword argument associates a
different number of command-line arguments with a single action.
See also Especificando argumentos ambíguos. The supported values are:
N
(um inteiro). Os argumentosN
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 comnargs='*'
, mas vários argumentos opcionais comnargs='*'
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 por action. Geralmente, isso significa que um único argumento de linha de comando será usado e um único item (não uma lista) será produzido. Ações que não fazem uso de argumentos da linha de comando (por exemplo, 'store_const'
) definem 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 comaction='store_const'
ouaction='append_const'
. Essas ações adicionam o valorconst
a um dos atributos do objeto retornado porparse_args()
. Consulte a descrição da action para obter exemplos. Seconst
não for fornecidoadd_argument()
, será recebido um valor padrão deNone
.Quando
add_argument()
é chamado com strings de opções (como-f
ou--foo
) enargs='?'
. 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 deconst
será presumido como sendoNone
. 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)
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)
Para argumentos obrigatórios, isto é, marcados com required, o valor default
é ignorado. Por exemplo, isso se aplica a argumentos posicionais com valores de nargs diferentes de ?
ou *
, ou argumentos opcionais marcados como 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')
type¶
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(['"Um conto de duas cidades"'])
Namespace(short_title='"um-cont-de-duas-cida')
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.
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¶
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=['pedra', 'papel', 'tesoura'])
>>> parser.parse_args(['padra'])
Namespace(move='padr')
>>> parser.parse_args(['fogo'])
usage: game.py [-h] {pedra,papel,tesoura}
game.py: error: argument move: invalid choice: 'fogo' (choose from 'pedra',
'papel', 'tesoura')
Observe que a inclusão na sequência choices é verificada após qualquer conversão de type ter sido realizada, portanto o tipo dos objetos na sequência choices deve corresponder ao type especificado.
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¶
In general, the argparse
module assumes that flags like -f
and --bar
indicate optional arguments, which can always be omitted at the command line.
To make an option required, True
can be specified for the required=
keyword argument to add_argument()
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-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.
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
supports silencing the help entry for certain options, by
setting the help
value to argparse.SUPPRESS
:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
options:
-h, --help show this help message and exit
metavar¶
When ArgumentParser
generates help messages, it needs some way to refer
to each expected argument. By default, ArgumentParser
objects use the dest
value as the “name” of each object. By default, for positional argument
actions, the dest value is used directly, and for optional argument actions,
the dest value is uppercased. So, a single positional argument with
dest='bar'
will be referred to as bar
. A single
optional argument --foo
that should be followed by a single command-line argument
will be referred to as FOO
. An example:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo FOO] bar
positional arguments:
bar
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')
deprecated¶
Durante a vida de um projeto, alguns argumentos podem precisar ser removidos da linha de comando. Antes de removê-los, você deve informar aos seus usuários que os argumentos estão descontinuados e serão removidos. O argumento nomeado deprecated
de add_argument()
, cujo padrão é False
, especifica se o argumento está descontinuado e será removido no futuro. Para argumentos, se deprecated
for True
, então um aviso será enviado para sys.stderr
(saída de erro) quando o argumento for usado:
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)
Adicionado na versão 3.13.
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)¶
Action
objects are used by anArgumentParser
to represent the information needed to parse a single argument from one or more strings from the command line. TheAction
class must accept the two positional arguments plus any keyword arguments passed toArgumentParser.add_argument()
except for theaction
itself.Instances of
Action
(or return value of any callable to theaction
parameter) should have attributesdest
,option_strings
,default
,type
,required
,help
, etc. defined. The easiest way to ensure these attributes are defined is to callAction.__init__()
.- __call__(parser, namespace, values, option_string=None)¶
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 byparse_args()
. Most actions add an attribute to this object usingsetattr()
.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 thenamespace
based ondest
andvalues
.
- format_usage()¶
Action
subclasses can define aformat_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.
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.
Previous calls to
add_argument()
determine exactly what objects are created and how they are assigned. See the documentation foradd_argument()
for details.
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='?')
>>> # tipo inválido
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'
>>> # opção inválida
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar
>>> # número errado de argumentos
>>> 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='?')
>>> # nenhuma opção de número negativo, então -1 é um argumento posicional
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')
>>> # nenhuma opção de número negativo, então -1 e -5 são argumentos posicionais
>>> 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='?')
>>> # opção de número negativo presente, então -1 é uma opção
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')
>>> # opção de número negativo presente, então -2 é uma opção
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2
>>> # opções de número negativo presentes, então ambos -1s são opções
>>> 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)
Veja também o tutorial do argparse sobre argumentos ambíguos para mais detalhes.
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
¶
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¶
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 objetoNamespace
. Isso pode ser obtido especificando o argumento nomeadonamespace=
:>>> 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][, dest][, required][, help][, metavar])¶
Many programs split up their functionality into a number of subcommands, for example, the
svn
program can invoke subcommands likesvn checkout
,svn update
, andsvn 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 theadd_subparsers()
method. Theadd_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 anyArgumentParser
constructor arguments, and returns anArgumentParser
object that can be modified as usual.Descrição de parâmetros:
title - título para o grupo de subanalisadores na saída de ajuda; por padrão “subcomandos” se a descrição for fornecida, caso contrário, usa o título para argumentos posicionais
description - descrição para o grupo de subanalisadores na saída de ajuda, por padrão
None
prog - informações de uso que serão exibidas com a ajuda do subcomando, por padrão o nome do programa e quaisquer argumentos posicionais antes do argumento do subanalisador
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 é armazenadorequired - 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 que apresenta os subcomandos disponíveis na ajuda; por padrão é
None
e apresenta os subcomandos no formato {cmd1, cmd2, ..}
Alguns exemplos de uso:
>>> # cria o analisador de nível superior >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo', action='store_true', help='foo help') >>> subparsers = parser.add_subparsers(help='subcommand help') >>> >>> # cria o analisador para o comando "a" >>> parser_a = subparsers.add_parser('a', help='a help') >>> parser_a.add_argument('bar', type=int, help='bar help') >>> >>> # cria o analisador para o comando "b" >>> parser_b = subparsers.add_parser('b', help='b help') >>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help') >>> >>> # analisa algumas listas de argumentos >>> 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 comandoa
é especificado, apenas os atributosfoo
ebar
estão presentes, e quando o comandob
é especificado, apenas os atributosfoo
ebaz
estão presentes.Similarmente, quando uma mensagem de ajuda é solicitada de um subanalisador, somente a ajuda para aquele parser em particular será impressa. A mensagem de ajuda não incluirá mensagens do analisador sintático pai ou do analisador sintático irmão. (Uma mensagem de ajuda para cada comando do subanalisador, entretanto, pode ser dada fornecendo o argumento
help=
paraadd_parser()
como acima.)>>> 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
O método
add_subparsers()
também oferece suporte aos argumentos nomeadostitle
edescription
. 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} ... options: -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. Este exemplo, comosvn
, aliasco
como uma abreviação paracheckout
:>>> 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')
add_parser()
oferece suporte também um argumento adicional deprecated, que permite descontinuar o subanalisador.>>> import argparse >>> parser = argparse.ArgumentParser(prog='chicken.py') >>> subparsers = parser.add_subparsers() >>> run = subparsers.add_parser('run') >>> fly = subparsers.add_parser('fly', deprecated=True) >>> parser.parse_args(['fly']) chicken.py: warning: command 'fly' is deprecated Namespace()
Adicionado na versão 3.13.
Uma maneira particularmente eficaz de lidar com subcomandos é combinar o uso do método
add_subparsers()
com chamadas paraset_defaults()
para que cada subanalisador saiba qual função Python ele deve executar. Por exemplo:>>> # funções do subanalisador functions >>> def foo(args): ... print(args.x * args.y) ... >>> def bar(args): ... print('((%s))' % args.z) ... >>> # cria o analisador de nível superior >>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(required=True) >>> >>> # cria o analisador do comando "foo" >>> 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) >>> >>> # cria o analisador do comando "foo" >>> parser_bar = subparsers.add_parser('bar') >>> parser_bar.add_argument('z') >>> parser_bar.set_defaults(func=bar) >>> >>> # analisa os argumentos e chama a função que for selecionada >>> args = parser.parse_args('foo 1 -x 2'.split()) >>> args.func(args) 2.0 >>> >>> # analisa os argumentos e chama a função que foi selecionada >>> 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 nomeadodest
para a chamadaadd_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: New required keyword-only parameter.
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 deArgumentParser.add_argument()
. Argumentos que têm objetosFileType
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çãoopen()
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'>)
Objetos FileType entendem o pseudoargumento
'-'
e o convertem automaticamente emsys.stdin
para objetosFileType
legíveis esys.stdout
para objetosFileType
graváveis:>>> 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: Adicionados os parâmetros encodings e errors.
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 theadd_argument_group()
method:>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> group = parser.add_argument_group('grupo') >>> group.add_argument('--foo', help='ajuda de foo') >>> group.add_argument('bar', help='ajuda de bar') >>> parser.print_help() usage: PROG [--foo FOO] bar grupo: bar ajuda de bar --foo FOO ajuda de foo
The
add_argument_group()
method returns an argument group object which has anadd_argument()
method just like a regularArgumentParser
. 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. Theadd_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('grupo1', 'descrição do grupo1') >>> group1.add_argument('foo', help='ajuda de foo') >>> group2 = parser.add_argument_group('grupo2', 'descrição do grupo2') >>> group2.add_argument('--bar', help='ajuda de bar') >>> parser.print_help() usage: PROG [--bar BAR] foo grupo1: descrição de grupo1 foo ajuda de foo grupo2: descrição de grupo2 --bar BAR ajuda de bar
Os parâmetros opcionais somente-nomeados argument_default e conflict_handler permitem um controle mais refinado do comportamento do grupo de argumentos. Esses parâmetros têm o mesmo significado que no construtor
ArgumentParser
, mas se aplicam especificamente ao grupo de argumentos em vez de ao analisador sintático inteiro.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”.
Alterado na versão 3.11: Chamar
add_argument_group()
em um grupo de argumentos está descontinuado. Esse recurso nunca foi suportado e nem sempre funciona corretamente. A função existe na API por acidente por herança e será removida no futuro.
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
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
Observe que atualmente grupos de argumentos mutuamente exclusivos não oferecem suporte aos argumentos title e description de
add_argument_group()
. No entanto, um grupo mutuamente exclusivo pode ser adicionado a um grupo de argumentos que tenha um título e uma descrição. Por exemplo:>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_argument_group('Título do grupo', 'Descrição do grupo') >>> exclusive_group = group.add_mutually_exclusive_group(required=True) >>> exclusive_group.add_argument('--foo', help='ajuda de foo') >>> exclusive_group.add_argument('--bar', help='ajuda de bar') >>> parser.print_help() usage: PROG [-h] (--foo FOO | --bar BAR) options: -h, --help show this help message and exit Título do grupo: Descrição do grupo --foo FOO foo help --bar BAR bar help
Alterado na versão 3.11: Chamar
add_argument_group()
ouadd_mutually_exclusive_group()
em um grupo mutuamente exclusivo está descontinuado. Esses recursos nunca foram suportados e nem sempre funcionam corretamente. As funções existem na API por acidente por herança e serão removidas no futuro.
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 porset_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 forNone
,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 forNone
,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 comoparse_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
As regras de correspondência de prefixo se aplicam a parse_known_args()
. O analisador pode usar uma opção mesmo que seja apenas um prefixo de uma de suas opções conhecidas, em vez de deixá-la na lista de argumentos restantes.
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)¶
Este método encerra o programa, saindo com o status especificado e, se fornecido, imprime uma message para
sys.stderr
antes disso. O usuário pode sobrescrever este método para lidar com essas etapas de forma diferente: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)¶
Este método imprime uma mensagem de uso, incluindo a message, em
sys.stderr
e encerra o programa com um código de status 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()
eparse_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, 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()
eparse_intermixed_args()
: o primeiro retorna['2', '3']
como argumentos não analisados, enquanto o último coleta todos os posicionais emrest
.>>> 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.Adicionado na versão 3.7.
Exceções¶
- exception argparse.ArgumentError¶
Um erro ao criar ou usar um argumento (opcional ou posicional).
O valor da string dessa exceção é a mensagem, complementada com informações sobre o argumento que a causou.
- exception argparse.ArgumentTypeError¶
Levantada quando algo dá errado ao converter uma string de linha de comando em um tipo.
Guias e tutoriais