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