getopt — C-style parser for command line options

Código fuente: Lib/getopt.py

Nota

El módulo getopt es un analizador de opciones de línea de comando cuya API está diseñada para que los usuarios de la función C getopt() estén familiarizados. Los usuarios que no estén familiarizados con la función C getopt() o que deseen escribir menos código y obtener mejor ayuda y mensajes de error deberían considerar el uso del módulo argparse.

Este módulo ayuda a los scripts a analizar los argumentos de la línea de comandos en sys.argv. Admite las mismas convenciones que la función Unix getopt() (incluidos los significados especiales de los argumentos de la forma “-” y “--“). También se pueden usar opciones largas similares a las admitidas por el software GNU a través de un tercer argumento opcional.

Este módulo proporciona dos funciones y una excepción:

getopt.getopt(args, shortopts, longopts=[])

Analiza las opciones de la línea de comandos y la lista de parámetros. args es la lista de argumentos a analizar, sin la referencia principal al programa en ejecución. Por lo general, esto significa sys.argv[:]. shortopts es la cadena de letras de opciones que el script quiere reconocer, con opciones que requieren un argumento seguido de dos puntos (':'; es decir, el mismo formato que Unix getopt() usa).

Nota

A diferencia de GNU getopt(), después de un argumento no-opcional, todos los argumentos adicionales se consideran también no-opcionales. Esto es similar a la forma en que funcionan los sistemas Unix que no son GNU.

longopts, si se especifica, debe ser una lista de cadenas con los nombres de las opciones largas que deben admitirse. Los caracteres principales '-' no deben incluirse en el nombre de la opción. Las opciones largas que requieren un argumento deben ir seguidas de un signo igual ('='). Los argumentos opcionales no son compatibles. Para aceptar solo opciones largas, shortopts debe ser una cadena vacía. Las opciones largas en la línea de comando pueden reconocerse siempre que proporcionen un prefijo del nombre de la opción que coincida exactamente con una de las opciones aceptadas. Por ejemplo, si longopts es ['foo', 'frob'], la opción --fo coincidirá como --foo, pero --f no coincidirá de forma exclusiva, por lo que se lanzará GetoptError.

El valor de retorno consta de dos elementos: el primero es una lista de pares (option, value); el segundo es la lista de argumentos del programa que quedan después de que se eliminó la lista de opciones (esta es una porción final de args). Cada par de opción y valor retornado tiene la opción como su primer elemento, con un guión para las opciones cortas (por ejemplo, '-x') o dos guiones para las opciones largas (por ejemplo, '--long-option'), y el argumento de la opción como su segundo elemento, o una cadena vacía si la opción no tiene argumento. Las opciones aparecen en la lista en el mismo orden en que se encontraron, lo que permite múltiples ocurrencias. Las opciones largas y cortas pueden ser mixtas.

getopt.gnu_getopt(args, shortopts, longopts=[])

Esta función funciona como getopt(), excepto que el modo de escaneo estilo GNU se usa por defecto. Esto significa que los argumentos opcionales y no opcionales pueden estar mezclados. La función getopt() detiene el procesamiento de opciones tan pronto como se encuentra un argumento no-opcionales.

Si el primer carácter de la cadena de opciones es '+', o si la variable de entorno POSIXLY_CORRECT está configurada, el procesamiento de opciones se detiene tan pronto como se encuentre un argumento que no sea de opción.

exception getopt.GetoptError

Esto se lanza cuando se encuentra una opción no reconocida en la lista de argumentos o cuando una opción que requiere un argumento no recibe ninguna. El argumento de la excepción es una cadena que indica la causa del error. Para opciones largas, un argumento dado a una opción que no requiere una también provocará que se lance esta excepción. Los atributos msg y opt dan el mensaje de error y la opción relacionada; si no hay una opción específica con la cual se relaciona la excepción, opt es una cadena vacía.

exception getopt.error

Alias para GetoptError; para compatibilidad con versiones anteriores.

Un ejemplo que usa solo opciones 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 nombres largos de opciones es 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']

In a script, typical usage is something like this:

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"
    # ...

if __name__ == "__main__":
    main()

Note that an equivalent command line interface could be produced with less code and more informative help and error messages by using the argparse module:

import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    args = parser.parse_args()
    # ... do something with args.output ...
    # ... do something with args.verbose ..

Ver también

Módulo argparse

Opción de línea de comando alternativa y biblioteca de análisis de argumentos.