argparse
— Parser for command-line options, arguments and subcommands¶
Adicionado na versão 3.2.
Código-fonte: Lib/argparse.py
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í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 - 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
ofsys.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ã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'
and'store_false'
- These are special cases of'store_const'
used for storing the valuesTrue
andFalse
respectively. In addition, they create default values ofFalse
andTrue
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ã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'>])
'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
'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 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
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 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)
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 theaction
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 callAction.__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 usingsetattr()
.
- namespace - The
- 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
.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 foradd_argument()
for details.
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 newNamespace
object. This can be achieved by specifying thenamespace=
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 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 - 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 storedrequired - 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 thea
command is specified, only thefoo
andbar
attributes are present, and when theb
command is specified, only thefoo
andbaz
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 toadd_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 supportstitle
anddescription
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 additionalaliases
argument, which allows multiple strings to refer to the same subparser. This example, likesvn
, aliasesco
as a shorthand forcheckout
:>>> 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 toset_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, thedest
keyword argument to theadd_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 ofArgumentParser.add_argument()
. Arguments that haveFileType
objects as their type will open command-line arguments as files with the requested modes, buffer sizes, encodings and error handling (see theopen()
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 intosys.stdin
for readableFileType
objects andsys.stdout
for writableFileType
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 theadd_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 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('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()
oradd_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 byset_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 isNone
,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 isNone
,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 likeparse_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()
andparse_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()
andparse_intermixed_args()
: the former returns['2', '3']
as unparsed arguments, while the latter collects all the positionals intorest
.>>> 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