argparse — Analisador sintático para opções de linha de comando, argumentos e subcomandos

Novo na versão 3.2.

Código-fonte: Lib/argparse.py

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

Exemplo

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

import argparse

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

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

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

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

Process some integers.

positional arguments:
 N           an integer for the accumulator

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

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

$ python prog.py 1 2 3 4
4

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

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

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

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

Criando um analisador sintático

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

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

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

Adicionando argumentos

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

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

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

Análise de argumentos

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

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

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

Objetos ArgumentParser

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

prog

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

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

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

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

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

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

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

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

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

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

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

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

usage

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

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

positional arguments:
 bar          bar help

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

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

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

positional arguments:
 bar          bar help

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

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

description

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

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

A foo that bars

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

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

epilog

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

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

A foo that bars

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

And that's how you'd foo a bar

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

parents

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

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

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

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

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

Nota

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

formatter_class

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

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

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

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

this description was indented weird but that is okay

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

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

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

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

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

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

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

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

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

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

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

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

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

positional arguments:
  float

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

prefix_chars

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

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

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

fromfile_prefix_chars

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

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

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

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

argument_default

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

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

allow_abbrev

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

Este recurso pode ser desabilitado configurando allow_abbrev para False:

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

Novo na versão 3.5.

conflict_handler

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

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

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

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

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

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

add_help

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

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

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

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

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

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

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

optional arguments:
 --foo FOO  foo help

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

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

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

O método add_argument()

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

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

  • name 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 - The value produced if the argument is absent from the command line.

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

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

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

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

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

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

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

name ou flags

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

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

enquanto um argumento posicional pode ser criado como:

>>> parser.add_argument('bar')

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

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

ação

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Novo na versão 3.8.

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

Um exemplo de uma ação personalizada:

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

Para mais detalhes, veja Action.

nargs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const

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

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

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

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

default

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

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

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

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

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

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

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

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

tipo

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

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

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

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

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

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

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

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

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

See the choices section for more details.

choices

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

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

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

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

Any container can be passed as the choices value, so list objects, set objects, and custom containers are all supported.

required

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

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

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

Nota

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

help

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

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

positional arguments:
 bar     one of the bars to be frobbled

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

As strings help podem incluir vários especificadores de formato para evitar a repetição de coisas como o nome do programa ou o argumento default. Os especificadores disponíveis incluem o nome do programa, %(prog)s e a maioria dos argumentos nomeados para add_argument(), por exemplo. %(default)s, %(type)s, etc.:

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

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

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

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

argparse oferece suporte a silenciar a entrada de ajuda para certas opções, definindo o valor help como argparse.SUPPRESS:

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

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

metavar

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

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

positional arguments:
 bar

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

Um nome alternativo pode ser especificado com metavar:

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

positional arguments:
 XXX

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

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

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

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

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

dest

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

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

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

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

dest permite que um nome de atributo personalizado seja fornecido:

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

Classes de ação

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

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

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

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

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

  • parser - The ArgumentParser object which contains this action.

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

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

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

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

O método parse_args()

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

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

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

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

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

Sintaxe de valores da opção

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

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

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

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

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

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

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

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

Argumentos inválidos

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

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

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

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

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

Argumentos contendo -

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Além do sys.argv

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

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

O objeto Namespace

class argparse.Namespace

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

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

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

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

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

Outros utilitários

Subcomandos

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

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

Descrição de parâmetros:

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

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

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

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

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

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

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

  • help - ajuda para o grupo de subanalisadores na saída de ajuda, por padrão None

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

Alguns exemplos de uso:

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

Note que o objeto retornado por parse_args() conterá apenas atributos para o analisador principal e o subanalisador que foi selecionado pela linha de comando (e não quaisquer outros subanalisadores). Então, no exemplo acima, quando o comando a é especificado, apenas os atributos foo e bar estão presentes, e quando o comando b é especificado, apenas os atributos foo e baz estão presentes.

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

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

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

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

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

positional arguments:
  bar     bar help

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

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

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

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

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

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

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

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

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

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

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

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

Alterado na versão 3.7: Novo argumento nomeado required.

Objetos FileType

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

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

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

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

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

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

Grupos de argumentos

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

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

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

group:
  bar    bar help
  --foo FOO  foo help

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

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

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

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

Exclusão mútua

ArgumentParser.add_mutually_exclusive_group(required=False)

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

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

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

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

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

Padrões do analisador sintático

ArgumentParser.set_defaults(**kwargs)

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

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

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

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

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

ArgumentParser.get_default(dest)

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

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

Imprimindo a ajuda

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

ArgumentParser.print_usage(file=None)

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

ArgumentParser.print_help(file=None)

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

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

ArgumentParser.format_usage()

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

ArgumentParser.format_help()

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

Análise parcial

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

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

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

Aviso

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

Personalizando a análise de arquivos

ArgumentParser.convert_arg_line_to_args(arg_line)

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

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

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

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

Métodos de saída

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

This method terminates the program, exiting with the specified status and, if given, it prints a message before that. The user can override this method to handle these steps differently:

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

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

Análise misturada

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

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

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

O exemplo a seguir mostra a diferença entre parse_known_args() e parse_intermixed_args(): o primeiro retorna ['2', '3'] como argumentos não analisados, enquanto o último coleta todos os posicionais em rest.

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

parse_known_intermixed_args() retorna uma tupla de dois itens contendo o espaço de nomes preenchido e a lista de strings de argumentos restantes. parse_intermixed_args() levanta um erro se houver strings de argumentos não analisadas restantes.

Novo na versão 3.7.

Atualizando código optparse

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

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

  • Tratando argumentos posicionais.

  • Supporting sub-commands.

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

  • Manipular argumentos de estilo “zero ou mais” e “um ou mais”.

  • Produzir mensagens de uso mais informativas.

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

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

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

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

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

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

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

  • Substituir optparse.Values por Namespace e optparse.OptionError e optparse.OptionValueError por ArgumentError.

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

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