getopt — Analisador sintático no estilo C para opções de linha de comando¶
Código-fonte: Lib/getopt.py
Nota
Este módulo é considerado completo em recursos. Uma alternativa mais declarativa e extensível para esta API é fornecida no módulo optparse. Outros aprimoramentos funcionais para processamento de parâmetros de linha de comando são fornecidos como módulos de terceiros no PyPI ou como recursos no módulo argparse.
Este módulo ajuda os scripts a analisar os argumentos da linha de comando em sys.argv. Ele suporta as mesmas convenções da função Unix getopt() (incluindo os significados especiais de argumentos da forma ‘-’ e ‘--‘). Longas opções semelhantes às suportadas pelo software GNU também podem ser usadas por meio de um terceiro argumento opcional.
Usuários que não estão familiarizados com a função Unix getopt() devem considerar usar o módulo argparse em vez disso. Usuários que estão familiarizados com a função Unix getopt(), mas gostariam de obter um comportamento equivalente enquanto escrevem menos código e obtêm melhor ajuda e mensagens de erro devem considerar usar o módulo optparse. Veja Escolhendo uma biblioteca de análise de linha de comando para detalhes adicionais.
Este módulo fornece duas funções e uma exceção:
- getopt.getopt(args, shortopts, longopts=[])¶
Parses command line options and parameter list. args is the argument list to be parsed, without the leading reference to the running program. Typically, this means
sys.argv[1:]. shortopts is the string of option letters that the script wants to recognize, with options that require an argument followed by a colon (':') and options that accept an optional argument followed by two colons ('::'); i.e., the same format that Unixgetopt()uses.Nota
Ao contrário do GNU
getopt(), após um argumento sem opção, todos os argumentos adicionais são considerados também sem opção. Isso é semelhante à maneira como os sistemas Unix não GNU funcionam.longopts, if specified, must be a list of strings with the names of the long options which should be supported. The leading
'--'characters should not be included in the option name. Long options which require an argument should be followed by an equal sign ('='). Long options which accept an optional argument should be followed by an equal sign and question mark ('=?'). To accept only long options, shortopts should be an empty string. Long options on the command line can be recognized so long as they provide a prefix of the option name that matches exactly one of the accepted options. For example, if longopts is['foo', 'frob'], the option--fowill match as--foo, but--fwill not match uniquely, soGetoptErrorwill be raised.O valor de retorno consiste em dois elementos: o primeiro é uma lista de pares
(option, value); a segunda é a lista de argumentos de programa restantes depois que a lista de opções foi removida (esta é uma fatia ao final de args). Cada par de opção e valor retornado tem a opção como seu primeiro elemento, prefixado com um hífen para opções curtas (por exemplo,'-x') ou dois hifenes para opções longas (por exemplo,'--long-option'), e o argumento da opção como seu segundo elemento, ou uma string vazia se a opção não tiver argumento. As opções ocorrem na lista na mesma ordem em que foram encontradas, permitindo assim múltiplas ocorrências. Opções longas e curtas podem ser misturadas.Alterado na versão 3.14: Optional arguments are supported.
- getopt.gnu_getopt(args, shortopts, longopts=[])¶
Esta função funciona como
getopt(), exceto que o modo de digitalização do estilo GNU é usado por padrão. Isso significa que os argumentos de opção e não opção podem ser misturados. A funçãogetopt()interrompe o processamento das opções assim que um argumento não opcional é encontrado.Se o primeiro caractere da string de opção for
'+', ou se a variável de ambientePOSIXLY_CORRECTestiver definida, então o processamento da opção para assim que um argumento não opcional for encontrado.If the first character of the option string is
'-', non-option arguments that are followed by options are added to the list of option-and-value pairs as a pair that hasNoneas its first element and the list of non-option arguments as its second element. The second element of thegnu_getopt()result is a list of program arguments after the last option.Alterado na versão 3.14: Support for returning intermixed options and non-option arguments in order.
- exception getopt.GetoptError¶
Isso é levantado quando uma opção não reconhecida é encontrada na lista de argumentos ou quando uma opção que requer um argumento não é fornecida. O argumento para a exceção é uma string que indica a causa do erro. Para opções longas, um argumento dado a uma opção que não requer uma também fará com que essa exceção seja levantada. Os atributos
msgeoptfornecem a mensagem de erro e a opção relacionada; se não houver uma opção específica à qual a exceção se relaciona,opté uma string vazia.
- exception getopt.error¶
Apelido para
GetoptError; para compatibilidade reversa.
Um exemplo usando apenas opções de estilo Unix:
>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
Usar nomes de opções longos é igualmente fácil:
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']
Optional arguments should be specified explicitly:
>>> s = '-Con -C --color=off --color a1 a2'
>>> args = s.split()
>>> args
['-Con', '-C', '--color=off', '--color', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])
>>> optlist
[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]
>>> args
['a1', 'a2']
The order of options and non-option arguments can be preserved:
>>> s = 'a1 -x a2 a3 a4 --long a5 a6'
>>> args = s.split()
>>> args
['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']
>>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])
>>> optlist
[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]
>>> args
['a6']
Em um script, o uso típico é algo assim:
import getopt, sys
def main():
try:
opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
except getopt.GetoptError as err:
# print help information and exit:
print(err) # will print something like "option -a not recognized"
usage()
sys.exit(2)
output = None
verbose = False
for o, a in opts:
if o == "-v":
verbose = True
elif o in ("-h", "--help"):
usage()
sys.exit()
elif o in ("-o", "--output"):
output = a
else:
assert False, "unhandled option"
process(args, output=output, verbose=verbose)
if __name__ == "__main__":
main()
Observe que uma interface de linha de comando equivalente pode ser produzida com menos código e mais mensagens de erro de ajuda e erro informativas usando o módulo optparse:
import optparse
if __name__ == '__main__':
parser = optparse.OptionParser()
parser.add_option('-o', '--output')
parser.add_option('-v', dest='verbose', action='store_true')
opts, args = parser.parse_args()
process(args, output=opts.output, verbose=opts.verbose)
Uma interface de linha de comando aproximadamente equivalente para este caso também pode ser produzida usando o módulo argparse:
import argparse
if __name__ == '__main__':
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--output')
parser.add_argument('-v', dest='verbose', action='store_true')
parser.add_argument('rest', nargs='*')
args = parser.parse_args()
process(args.rest, output=args.output, verbose=args.verbose)
Veja Escolhendo uma biblioteca de análise de linha de comando para detalhes sobre como a versão argparse deste código difere em comportamento da versão optparse (e getopt).