# `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=[])

  Analisa opções de linha de comando e lista de parâmetros. args é a lista de argumentos a ser analisada, sem a referência inicial para o programa em execução. Normalmente, isso significa `sys.argv[1:]`. shortopts é a string de letras de opção que o script deseja reconhecer, com opções que requerem um argumento seguido por dois pontos (`':'`) e opções que aceitam o argumento opcional seguido por dois caracteres de dois pontos (`'::'`); ou seja, o mesmo formato que Unix `getopt()` usa.

  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, se especificado, deve ser uma lista de strings com os nomes das opções longas que devem ser suportadas. Os caracteres `'--'` no início não devem ser incluídos no nome da opção. Opções longas que requerem um argumento devem ser seguidas por um sinal de igual (`'='`). Opções longas que aceitam um argumento opcional devem ser seguidas por um sinal de igualdade e ponto de interrogação (`'=?'`). Para aceitar apenas opções longas, shortopts deve ser uma string vazia. Opções longas na linha de comando podem ser reconhecidas, desde que forneçam um prefixo do nome da opção que corresponda exatamente a uma das opções aceitas. Por exemplo, se longopts for `['foo', 'frob']`, a opção `--fo` irá corresponder a `--foo`, mas `--f` não corresponderá exclusivamente, então `GetoptError` será levantada.

  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: Argumentos opcionais são suportados.

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ção `getopt()` 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 ambiente `POSIXLY_CORRECT` estiver definida, então o processamento da opção para assim que um argumento não opcional for encontrado.

  Se o primeiro caractere da string de opção for `'-'`, argumentos não opcionais seguidos por opções serão adicionados à lista de pares opção-valor como um par que tem `None` como primeiro elemento e a lista de argumentos não opcionais como segundo elemento. O segundo elemento do resultado `gnu_getopt()` é uma lista de argumentos do programa após a última opção.

  Alterado na versão 3.14: Suporte para retornar opções misturadas e argumentos não opcionais em ordem.

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 `msg` e `opt` fornecem 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']

Argumentos opcionais devem ser especificados explicitamente:

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

A ordem dos argumentos opcionais e não opcionais pode ser preservada:

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

Ver também

Módulo `optparse`

  Análise de opções de linha de comando declarativa.

Módulo `argparse`

  Opção de linha de comando e biblioteca de análise de argumentos mais opinativa.