"optparse" --- Parser for command line options
**********************************************

**Source code:** Lib/optparse.py

======================================================================


Choosing an argument parsing library
====================================

The standard library includes three argument parsing libraries:

* "getopt": a module that closely mirrors the procedural C "getopt"
  API. Included in the standard library since before the initial
  Python 1.0 release.

* "optparse": a declarative replacement for "getopt" that provides
  equivalent functionality without requiring each application to
  implement its own procedural option parsing logic. Included in the
  standard library since the Python 2.3 release.

* "argparse": a more opinionated alternative to "optparse" that
  provides more functionality by default, at the expense of reduced
  application flexibility in controlling exactly how arguments are
  processed. Included in the standard library since the Python 2.7 and
  Python 3.2 releases.

In the absence of more specific argument parsing design constraints,
"argparse" is the recommended choice for implementing command line
applications, as it offers the highest level of baseline functionality
with the least application level code.

"getopt" is retained almost entirely for backwards compatibility
reasons. However, it also serves a niche use case as a tool for
prototyping and testing command line argument handling in
"getopt"-based C applications.

"optparse" should be considered as an alternative to "argparse" in the
following cases:

* an application is already using "optparse" and doesn't want to risk
  the subtle behavioural changes that may arise when migrating to
  "argparse"

* the application requires additional control over the way options and
  positional parameters are interleaved on the command line (including
  the ability to disable the interleaving feature completely)

* the application requires additional control over the incremental
  parsing of command line elements (while "argparse" does support
  this, the exact way it works in practice is undesirable for some use
  cases)

* the application requires additional control over the handling of
  options which accept parameter values that may start with "-" (such
  as delegated options to be passed to invoked subprocesses)

* the application requires some other command line parameter
  processing behavior which "argparse" does not support, but which can
  be implemented in terms of the lower level interface offered by
  "optparse"

These considerations also mean that "optparse" is likely to provide a
better foundation for library authors writing third party command line
argument processing libraries.

As a concrete example, consider the following two command line
argument parsing configurations, the first using "optparse", and the
second using "argparse":

   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)

   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)

The most obvious difference is that in the "optparse" version, the
non-option arguments are processed separately by the application after
the option processing is complete. In the "argparse" version,
positional arguments are declared and processed in the same way as the
named options.

However, the "argparse" version will also handle some parameter
combination differently from the way the "optparse" version would
handle them. For example (amongst other differences):

* supplying "-o -v" gives "output="-v"" and "verbose=False" when using
  "optparse", but a usage error with "argparse" (complaining that no
  value has been supplied for "-o/--output", since "-v" is interpreted
  as meaning the verbosity flag)

* similarly, supplying "-o --" gives "output="--"" and "args=()" when
  using "optparse", but a usage error with "argparse" (also
  complaining that no value has been supplied for "-o/--output", since
  "--" is interpreted as terminating the option processing and
  treating all remaining values as positional arguments)

* supplying "-o=foo" gives "output="=foo"" when using "optparse", but
  gives "output="foo"" with "argparse" (since "=" is special cased as
  an alternative separator for option parameter values)

Whether these differing behaviors in the "argparse" version are
considered desirable or a problem will depend on the specific command
line application use case.

Ver también:

  click is a third party argument processing library (originally based
  on "optparse"), which allows command line applications to be
  developed as a set of decorated command implementation functions.

  Other third party libraries, such as typer or msgspec-click, allow
  command line interfaces to be specified in ways that more
  effectively integrate with static checking of Python type
  annotations.


Introduction
============

"optparse" is a more convenient, flexible, and powerful library for
parsing command-line options than the minimalist "getopt" module.
"optparse" uses a more declarative style of command-line parsing: you
create an instance of "OptionParser", populate it with options, and
parse the command line. "optparse" allows users to specify options in
the conventional GNU/POSIX syntax, and additionally generates usage
and help messages for you.

A continuación puedes ver un ejemplo de uso de "optparse" mediante un
script simple:

   from optparse import OptionParser
   ...
   parser = OptionParser()
   parser.add_option("-f", "--file", dest="filename",
                     help="write report to FILE", metavar="FILE")
   parser.add_option("-q", "--quiet",
                     action="store_false", dest="verbose", default=True,
                     help="don't print status messages to stdout")

   (options, args) = parser.parse_args()

Con estas pocas líneas de código, los usuarios de tu script ahora
pueden hacer un uso "normal" del mismo mediante la línea de comandos,
por ejemplo:

   <yourscript> --file=outfile -q

A medida que analiza la línea de comandos, "optparse" establece los
atributos del objeto "options" retornado por "parse_args()" basándose
en los valores de la línea de comandos proporcionada por el usuario.
Cuando "parse_args()" termina de analizar esta línea de comandos,
"options.filename" será ""outfile"" y "options.verbose" será "False".
"optparse" admite opciones largas y cortas, fusionar opciones cortas y
asociar opciones con sus argumentos de diversas formas. Por lo tanto,
las siguientes líneas de comandos son todas equivalentes al ejemplo
previo:

   <yourscript> -f outfile --quiet
   <yourscript> --quiet --file outfile
   <yourscript> -q -foutfile
   <yourscript> -qfoutfile

Además, los usuarios pueden ejecutar uno de los siguientes:

   <yourscript> -h
   <yourscript> --help

y "optparse" imprimirá un breve resumen de las opciones de tu script:

   Usage: <yourscript> [options]

   Options:
     -h, --help            show this help message and exit
     -f FILE, --file=FILE  write report to FILE
     -q, --quiet           don't print status messages to stdout

donde el valor de *yourscript* se determina en tiempo de ejecución
(normalmente a partir de "sys.argv [0]").


Contexto
========

"optparse" was explicitly designed to encourage the creation of
programs with straightforward command-line interfaces that follow the
conventions established by the "getopt()" family of functions
available to C developers. To that end, it supports only the most
common command-line syntax and semantics conventionally used under
Unix.  If you are unfamiliar with these conventions, reading this
section will allow you to acquaint yourself with them.


Terminología
------------

argumento
   una cadena de caracteres ingresada en la línea de comandos y pasada
   mediante la shell a "execl()" o "execv()". En Python, los
   argumentos son elementos de "sys.argv[1:]" (dado que "sys.argv[0]"
   es el propio nombre del programa que se está ejecutando). Las
   shells de Unix también usan el término "*word*" ('palabra') para
   referirse a ellos.

   En ocasiones es deseable proporcionar una lista de argumentos que
   no sea "sys.argv[1:]", por lo que deberías considerar un
   'argumento' como 'un elemento de "sys.argv[1:]" o de alguna otra
   lista proporcionada como sustituto de "sys.argv[1:]"'.

opción
   un argumento utilizado para proporcionar información adicional con
   la finalidad de guiar o personalizar la ejecución de un programa.
   Existen muchas sintaxis diferentes para especificar opciones. La
   sintaxis tradicional de Unix es un guion ('-') seguido de una sola
   letra, por ejemplo "-x" o "-F". La sintaxis tradicional de Unix
   permite además fusionar múltiples opciones en un solo argumento,
   por ejemplo "-x -F" es equivalente a "-xF". Por otro lado, el
   proyecto GNU introdujo "--" seguido de una serie de palabras
   separadas por guiones, por ejemplo "--file" o "--dry-run". Estas
   son las dos únicas sintaxis para opciones que el módulo "optparse"
   proporciona.

   Algunas de las otras sintaxis para opciones que el mundo ha visto
   son:

   * un guion seguido de algunas letras, por ejemplo "-pf" (esto *no*
     es lo mismo que múltiples opciones fusionadas en un solo
     argumento)

   * un guion seguido de una palabra completa, por ejemplo "-file"
     (esto es técnicamente equivalente a la sintaxis anterior, pero
     generalmente no se ven ambas en un mismo programa)

   * un signo más seguido de una sola letra, unas pocas letras o una
     palabra, por ejemplo "+f" o "+rgb"

   * una barra seguida de una letra, de unas pocas letras o de una
     palabra, por ejemplo "/f" o "/file"

   Estas sintaxis para opciones no son compatibles con "optparse" y
   nunca lo serán. Esto es deliberado: los tres primeros no son
   estándar en ningún entorno y el último solo tiene sentido si se
   dirige exclusivamente a Windows o alguna plataforma heredada
   (*legacy*) (por ejemplo: VMS, MS-DOS).

argumento de opción
   un argumento que sigue a una opción, está estrechamente asociado
   con ella y se consume de la lista de argumentos cuando esa opción
   es consumida. Con "optparse", los argumentos de las opciones pueden
   estar en un argumento separado de su opción:

      -f foo
      --file foo

   o incluidos en el mismo argumento:

      -ffoo
      --file=foo

   Normalmente, una opción dada puede aceptar o no un argumento. Mucha
   gente desea una característica de "argumentos de opción
   opcionales", lo que implica que algunas opciones aceptarán un
   argumento si está presente y no lo aceptarán si no lo está. Esto es
   algo controvertido, porque hace que el análisis sea ambiguo: si
   "-a" toma un argumento opcional y "-b" es otra opción completamente
   distinta, ¿cómo interpretamos "-ab"? Debido a esta ambigüedad,
   "optparse" no es compatible con esta funcionalidad.

argumento posicional
   es algo que queda en la lista de argumentos después de que las
   opciones hayan sido analizadas sintácticamente, es decir, después
   de que las opciones y sus argumentos hayan sido analizados y
   eliminados de la lista de argumentos.

opción requerida
   es una opción que debe proporcionarse forzosamente en la línea de
   comandos. Ten en cuenta que la frase "opción requerida" se
   contradice a si misma. "optparse" no te impide implementar opciones
   requeridas, pero tampoco brinda mucha ayuda para ello.

Por ejemplo, considera esta hipotética linea de comandos:

   prog -v --report report.txt foo bar

"-v" y "--report" son ambas opciones. "report.txt" es un argumento de
opción, suponiendo que "--report" toma un argumento. En cambio, "foo"
y "bar" son ambos argumentos posicionales.


¿Qué finalidad tienen las opciones?
-----------------------------------

Las opciones se utilizan para poder proporcionar información adicional
con el fin de ajustar o personalizar la ejecución de un programa. Por
si aún no ha quedado claro, las opciones suelen ser *opcionales*. Un
programa debería poder ejecutarse sin problemas sin ninguna opción.
(Elija un programa aleatorio del conjunto de herramientas de Unix o
GNU. ¿Puede ejecutarse sin ninguna opción y aún así tener sentido? Las
principales excepciones son "find", "tar" y "dd"---los cuales son
todos bichos raros mutantes que han sido apropiadamente criticados por
su sintaxis no estándar y por tener interfaces confusas).

Como se ha comentado, mucha gente quiere que sus programas tengan
"opciones requeridas". Pero pensemos en ello detenidamente. ¡Si es
necesario, entonces *no es opcional*! Si hay una pieza de información
absolutamente requerida para que tu programa pueda ejecutarse
correctamente no uses opciones, para eso están los argumentos
posicionales.

Como ejemplo de un buen diseño de una interfaz de línea de comandos,
considera la humilde herramienta "cp" para copiar archivos. No tiene
mucho sentido intentar copiar archivos sin proporcionar un destino y
al menos una fuente de origen. Por lo tanto, "cp" falla si lo ejecutas
sin argumentos. Sin embargo, tiene una sintaxis flexible y útil que no
requiere ninguna opción:

   cp SOURCE DEST
   cp SOURCE ... DEST-DIR

Puedes hacer mucho simplemente con eso. La mayoría de las
implementaciones de "cp" proporcionan un montón de opciones para
modificar exactamente cómo se copian los archivos: se puede preservar
el modo y la fecha de modificación, evitar que se sigan enlaces
simbólicos, preguntar antes de sobrescribir el contenido de archivos
existentes, etc. Pero nada de esto distrae de la misión principal de
"cp", que consiste en copiar uno o varios archivos en otro directorio.


¿Qué finalidad tienen los argumentos posicionales?
--------------------------------------------------

Los argumentos posicionales son adecuados para aquellas piezas de
información que tu programa, absolutamente y sin duda alguna, requiere
para funcionar.

Una buena interfaz de usuario debería tener la menor cantidad de
requisitos absolutos posibles. Si tu programa requiere 17 piezas
distintas de información para ejecutarse correctamente, no importa
mucho *cómo* obtengas esa información del usuario; la mayoría de ellos
se rendirán y se irán antes de ejecutar con éxito el programa. Esto se
aplica tanto si la interfaz de usuario es una línea de comandos, un
archivo de configuración o una GUI: si hace demasiadas demandas a sus
usuarios, la mayoría simplemente se rendirá.

En resumen, trata de minimizar la cantidad de información que los
usuarios están absolutamente obligados a proporcionar, utiliza valores
predeterminados sensatos siempre que sea posible. Como es natural,
también deseas que tus programas sean razonablemente flexibles, para
eso están las opciones. De nuevo, no importa si son entradas en un
archivo de configuración, widgets en un cuadro de diálogo de
"Preferencias" de una GUI u opciones en la línea de comandos; cuantas
más opciones implementes, más flexible será tu programa y más
complicada se vuelve su implementación. Una excesiva flexibilidad
evidentemente también tiene inconvenientes, demasiadas opciones pueden
abrumar a los usuarios y hacer que tu código sea mucho más difícil de
mantener.


Tutorial
========

Si bien "optparse" es bastante flexible y potente, también es sencillo
de usar en la mayoría de los casos. Esta sección cubre los patrones de
código comunes a cualquier programa basado en "optparse".

En primer lugar, necesitas importar la clase OptionParser y luego, al
comienzo del programa principal, crear una instancia de ella:

   from optparse import OptionParser
   ...
   parser = OptionParser()

Ahora ya puedes comenzar a definir opciones. La sintaxis básica es:

   parser.add_option(opt_str, ...,
                     attr=value, ...)

Cada opción tiene una o más cadenas de caracteres de opción, como "-f"
o "--file" y varios atributos de opción que le dicen a "optparse" qué
esperar y qué hacer cuando encuentra esa opción en la línea de
comandos.

Normalmente, cada opción tendrá una cadena de opción corta y una
cadena de opción larga, por ejemplo:

   parser.add_option("-f", "--file", ...)

Puedes definir tantas cadenas de opción cortas y tantas largas como
desees (incluso ninguna), siempre que haya al menos una cadena de
opción en total.

Las cadenas de opción pasadas a "OptionParser.add_option()" son en
definitiva etiquetas para la opción definida por esa llamada.
Simplemente por brevedad, con frecuencia nos referiremos a *encontrar
una opción* en la línea de comandos. En realidad, "optparse" encuentra
*cadenas de caracteres de opción* y busca opciones en ellas.

Una vez que todas tus opciones estén definidas, indica a "optparse"
que analice sintácticamente la línea de comandos de tu programa:

   (options, args) = parser.parse_args()

(Si lo deseas, puedes pasar una lista de argumentos personalizada a
"parse_args()", pero eso rara vez es necesario: por defecto se usa
"sys.argv [1:]".)

"parse_args()" retorna dos valores:

* "options", un objeto que contiene valores para todas tus opciones.
  Por ejemplo, si "--file" toma un argumento de una sola cadena de
  caracteres, entonces "options.file" será el nombre del archivo
  proporcionado por el usuario o "None" si el usuario no proporcionó
  esa opción en la linea de comandos

* "args", la lista de argumentos posicionales que quedan después de
  analizar las opciones

Este tutorial solo cubre los cuatro atributos de opción más
importantes: "action", "type", "dest" (destino) y "help". De todos
ellos, "action" es el fundamental.


Comprendiendo las acciones de opción
------------------------------------

Las acciones le dicen a "optparse" qué hacer cuando encuentra una
determinada opción en la línea de comandos. Hay un conjunto fijo de
acciones codificadas en "optparse". Agregar nuevas acciones es un tema
avanzado cubierto en la sección Extendiendo el módulo optparse. La
mayoría de las acciones indican a "optparse" que almacene un valor en
alguna variable, por ejemplo, tomar una cadena de caracteres de la
línea de comandos y almacenarla en un atributo del objeto "options".

Si no se especifica una acción para la opción, "optparse" usa por
defecto "store".


La acción store
---------------

La acción para opciones más común es "store", que le dice a "optparse"
que tome el siguiente argumento (o el resto del argumento actual), se
asegure de que sea del tipo correcto y lo guarde en el destino
elegido.

Por ejemplo:

   parser.add_option("-f", "--file",
                     action="store", type="string", dest="filename")

Ahora creamos una línea de comandos simulada y le pedimos a "optparse"
que la analice:

   args = ["-f", "foo.txt"]
   (options, args) = parser.parse_args(args)

Cuando "optparse" se encuentra con la cadena de opción "-f", consume
el siguiente argumento, "foo.txt" y lo almacena en "options.filename".
Por lo tanto, después de la llamada a "parse_args()",
"options.filename" será ""foo.txt"".

Algunos de los otros tipos de opción admitidos por "optparse" son
"int" y "float". Aquí hay una opción que espera un argumento entero:

   parser.add_option("-n", type="int", dest="num")

Ten en cuenta que esta opción no tiene una cadena de opción larga, lo
cual es perfectamente aceptable. Además, no hay ninguna acción
explícita, ya que el valor predeterminado es "store".

Analicemos otra línea de comandos simulada. En esta ocasión, vamos a
proporcionar el argumento de la opción pegado junto a la misma, sin
separación entre ambos: dado que "-n42" (un argumento) es equivalente
a "-n 42" (dos argumentos), el código:

   (options, args) = parser.parse_args(["-n42"])
   print(options.num)

imprimirá "42".

Si no se especifica un tipo, "optparse" asume "string". Esto,
combinado con el hecho de que la acción predeterminada es "store",
implica que nuestro primer ejemplo puede implementarse de forma mucho
más concisa:

   parser.add_option("-f", "--file", dest="filename")

Si no se proporciona un destino, "optparse" infiere un destino por
defecto adecuado a partir de las cadenas de opción proporcionadas: si
la primera cadena de opción larga es "--foo-bar", entonces el destino
predeterminado es "foo_bar". Si no hay cadenas de opción largas,
"optparse" mira la primera cadena de opción corta: por ejemplo, el
destino predeterminado para "-f" es "f".

"optparse" también incluye el tipo incorporado "complex". La adición
de nuevos tipos se cubre en la sección Extendiendo el módulo optparse.


Manejo de opciones booleanas (flags)
------------------------------------

Las opciones flags---establecen una variable en verdadero o falso
cuando se encuentra una opción en particular--- son bastante comunes.
"optparse" las admite con dos acciones diferenciadas, "store_true" y
"store_false". Por ejemplo, puedes tener un flag "verbose" que se
activa con "-v" y se desactiva con "-q":

   parser.add_option("-v", action="store_true", dest="verbose")
   parser.add_option("-q", action="store_false", dest="verbose")

Aquí tenemos dos opciones diferentes con el mismo destino, lo cual es
totalmente correcto. Solo significa que debes tener un poco de cuidado
al establecer los valores predeterminados, lo veremos a continuación.

Cuando "optparse" encuentra "-v" en la línea de comandos, establece
"options.verbose" en "True"; cuando encuentra "-q", "options.verbose"
se establece en "False".


Otras acciones
--------------

Algunas de las otras acciones soportadas por "optparse" son:

""store_const""
   almacena un valor de constante, preestablecida vía "Option.const"

""append""
   agrega el argumento de esta opción a una lista

""count""
   incrementa un contador en uno

""callback""
   llama a una función específica

Estas acciones se tratan en la sección Guía de referencia y en la
sección Retrollamadas de opción.


Valores por defecto
-------------------

Todos los ejemplos anteriores implican establecer alguna variable (el
"destino") cuando aparecen ciertas opciones en la línea de comandos.
¿Qué pasa si esas opciones nunca se encuentran? Dado que no
proporcionamos ningún valor predeterminado, todas las variables están
establecidas en "None". Por lo general, esto está bien, pero a veces
se desea tener más control. "optparse" permite proporcionar un valor
predeterminado para cada destino, que es asignado antes de analizar la
línea de comandos.

Primero, considera el ejemplo verbose/quiet anterior. Si queremos que
"optparse" establezca "verbose" en "True" a menos que encuentre "-q",
entonces podemos hacer lo siguiente:

   parser.add_option("-v", action="store_true", dest="verbose", default=True)
   parser.add_option("-q", action="store_false", dest="verbose")

Dado que los valores predeterminados se aplican a *destination* en
lugar de a cualquier opción en particular y que estas dos opciones
tienen el mismo destino, lo anterior es exactamente equivalente a:

   parser.add_option("-v", action="store_true", dest="verbose")
   parser.add_option("-q", action="store_false", dest="verbose", default=True)

Considera lo siguiente:

   parser.add_option("-v", action="store_true", dest="verbose", default=False)
   parser.add_option("-q", action="store_false", dest="verbose", default=True)

Nuevamente, el valor predeterminado para "verbose" será "True": el
último valor predeterminado proporcionado para cualquier destino en
particular es el único que se tendrá en cuenta.

Una forma más clara de especificar valores predeterminados es el
método "set_defaults()" de OptionParser, al que puedes llamar en
cualquier momento antes de llamar a "parse_args()":

   parser.set_defaults(verbose=True)
   parser.add_option(...)
   (options, args) = parser.parse_args()

Como vimos antes, el último valor especificado para un destino de
opción dado es el que cuenta. Para mayor claridad, intenta utilizar un
método u otro para establecer valores predeterminados, no ambos.


Generando ayuda
---------------

La capacidad de "optparse" para generar ayuda y texto de uso
automáticamente es útil para crear interfaces de línea de comandos
fáciles de usar. Todo lo que tienes que hacer es proporcionar un valor
"help" para cada opción y, opcionalmente, un breve mensaje de uso para
el programa en general. A continuación hay un OptionParser al que se
le han añadido múltiples opciones fáciles de usar (documentadas):

   usage = "usage: %prog [options] arg1 arg2"
   parser = OptionParser(usage=usage)
   parser.add_option("-v", "--verbose",
                     action="store_true", dest="verbose", default=True,
                     help="make lots of noise [default]")
   parser.add_option("-q", "--quiet",
                     action="store_false", dest="verbose",
                     help="be vewwy quiet (I'm hunting wabbits)")
   parser.add_option("-f", "--filename",
                     metavar="FILE", help="write output to FILE")
   parser.add_option("-m", "--mode",
                     default="intermediate",
                     help="interaction mode: novice, intermediate, "
                          "or expert [default: %default]")

Si "optparse" encuentra "-h" o "--help" en la línea de comandos, o si
simplemente se llama al método "parser.print_help()", se imprime lo
siguiente en la salida estándar:

   Usage: <yourscript> [options] arg1 arg2

   Options:
     -h, --help            show this help message and exit
     -v, --verbose         make lots of noise [default]
     -q, --quiet           be vewwy quiet (I'm hunting wabbits)
     -f FILE, --filename=FILE
                           write output to FILE
     -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                           expert [default: intermediate]

(Si la salida de ayuda se activa mediante una opción de ayuda,
"optparse" termina la ejecución después de imprimir el texto de
ayuda.)

Estamos haciendo muchas cosas aquí con el fin de ayudar a que
"optparse" genere el mejor mensaje de ayuda posible:

* el script define su propio mensaje de uso:

     usage = "usage: %prog [options] arg1 arg2"

  "optparse" expande "% prog" en la cadena de uso reemplazándolo por
  el nombre del programa actual, es decir, "os.path.basename (sys.argv
  [0])". A continuación, la cadena expandida se imprime antes de la
  ayuda detallada de la opción.

  Si no proporcionas una cadena de uso, "optparse" usa un valor
  predeterminado anodino pero apropiado: ""Usage: %prog [options]"",
  lo cual está bien si tu script no toma ningún argumento posicional.

* cada opción simplemente define una cadena de ayuda y no se preocupa
  por el ajuste de línea. "optparse" se encarga de ajustar las líneas
  y hacer que la salida de ayuda se vea bien.

* las opciones que toman un valor indican este hecho en su mensaje de
  ayuda generado automáticamente, por ejemplo, para la opción "mode":

     -m MODE, --mode=MODE

  Aquí, a "MODE" se le denomina una metavariable: representa el
  argumento que se espera que el usuario proporcione a "-m"/"--mode".
  De forma predeterminada, "optparse" convierte el nombre de la
  variable de destino a mayúsculas y lo usa para la metavariable. En
  ocasiones, eso no es lo que se desea, por ejemplo, la opción "--
  filename" establece explícitamente "metavar="FILE"", lo que da como
  resultado la siguiente descripción de opción generada
  automáticamente:

     -f FILE, --filename=FILE

  Sin embargo, esto es importante para algo más que para ahorrar
  espacio: el texto de ayuda escrito manualmente utiliza la
  metavariable "FILE" para indicarle al usuario que hay una conexión
  entre la sintaxis semiformal "-f FILE" y la descripción semántica
  informal "escribir la salida en FILE". Esta es una manera simple
  pero efectiva de hacer que tu texto de ayuda sea mucho más claro y
  útil para los usuarios finales.

* las opciones que tienen un valor predeterminado pueden incluir
  "%default" en la cadena de ayuda, en cuyo caso, "optparse" lo
  reemplazará por el resultado de aplicar "str()" al valor por defecto
  de esa opción. Si una opción no tiene un valor por defecto (o el
  valor por defecto es "None"), "%default" se reemplazará por "none".


Agrupando opciones
~~~~~~~~~~~~~~~~~~

Cuando se trabaja con muchas opciones, suele ser conveniente
agruparlas para obtener una mejor salida de ayuda. La clase
"OptionParser" puede contener varios grupos de opciones, cada uno de
los cuales puede contener múltiples opciones.

Podemos obtener un grupo de opciones usando la clase "OptionGroup":

class optparse.OptionGroup(parser, title, description=None)

   donde

   * *parser* es la instancia de "OptionParser" en la que se insertará
     el grupo

   * *title* es el título dado al grupo

   * *description*, opcional, es la descripción larga del grupo

la clase "OptionGroup" hereda de "OptionContainer" (al igual que
"OptionParser"), por lo que el método "add_option()" se puede usar
para agregar una opción al grupo.

Una vez que se han declarado todas las opciones, usando el método
"add_option_group()" de la clase "OptionParser" el grupo se agrega al
analizador sintáctico previamente definido.

Agregar un "OptionGroup" a un analizador es fácil, continuando con el
analizador definido en la sección anterior:

   group = OptionGroup(parser, "Dangerous Options",
                       "Caution: use these options at your own risk.  "
                       "It is believed that some of them bite.")
   group.add_option("-g", action="store_true", help="Group option.")
   parser.add_option_group(group)

Esto daría como resultado la siguiente salida de ayuda:

   Usage: <yourscript> [options] arg1 arg2

   Options:
     -h, --help            show this help message and exit
     -v, --verbose         make lots of noise [default]
     -q, --quiet           be vewwy quiet (I'm hunting wabbits)
     -f FILE, --filename=FILE
                           write output to FILE
     -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                           expert [default: intermediate]

     Dangerous Options:
       Caution: use these options at your own risk.  It is believed that some
       of them bite.

       -g                  Group option.

Un ejemplo un poco más completo podría implicar el uso de más de un
grupo, ampliando el ejemplo anterior:

   group = OptionGroup(parser, "Dangerous Options",
                       "Caution: use these options at your own risk.  "
                       "It is believed that some of them bite.")
   group.add_option("-g", action="store_true", help="Group option.")
   parser.add_option_group(group)

   group = OptionGroup(parser, "Debug Options")
   group.add_option("-d", "--debug", action="store_true",
                    help="Print debug information")
   group.add_option("-s", "--sql", action="store_true",
                    help="Print all SQL statements executed")
   group.add_option("-e", action="store_true", help="Print every action done")
   parser.add_option_group(group)

lo que da como resultado la siguiente salida:

   Usage: <yourscript> [options] arg1 arg2

   Options:
     -h, --help            show this help message and exit
     -v, --verbose         make lots of noise [default]
     -q, --quiet           be vewwy quiet (I'm hunting wabbits)
     -f FILE, --filename=FILE
                           write output to FILE
     -m MODE, --mode=MODE  interaction mode: novice, intermediate, or expert
                           [default: intermediate]

     Dangerous Options:
       Caution: use these options at your own risk.  It is believed that some
       of them bite.

       -g                  Group option.

     Debug Options:
       -d, --debug         Print debug information
       -s, --sql           Print all SQL statements executed
       -e                  Print every action done

Otro método interesante, particularmente cuando se trabaja
programáticamente con grupos de opciones, es:

OptionParser.get_option_group(opt_str)

   Retorna el "OptionGroup" al que pertenece la cadena de opción corta
   o larga *opt_str* (por ejemplo, "'-o'" o "' --option'"). Si no
   existe dicho "OptionGroup", el método retorna "None".


Imprimir una cadena de caracteres con la versión del programa
-------------------------------------------------------------

De forma similar a lo que ocurre con la cadena de uso abreviada,
"optparse" también puede imprimir una cadena de versión para tu
programa. Debes proporcionar la cadena mediante el argumento "version"
de OptionParser:

   parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

"%prog" se expande al igual que en "usage". Aparte de eso, "version"
puede contener cualquier cosa que desees. Cuando se proporciona,
"optparse" agrega automáticamente una opción "--version" al
analizador. Si encuentra esta opción en la línea de comandos, expande
la cadena "version" (reemplazando "%prog"), la imprime en la salida
estándar y termina la ejecución.

Por ejemplo, si tu script se llama "/usr/bin/foo":

   $ /usr/bin/foo --version
   foo 1.0

Para imprimir y obtener la cadena de caracteres "version", se pueden
utilizar cualquiera de los siguientes métodos:

OptionParser.print_version(file=None)

   Imprime el mensaje con la versión del programa actual
   ("self.version") en *file* (por defecto, la salida estándar). Al
   igual que con "print_usage()", cualquier aparición de "%prog" en
   "self.version" se reemplaza con el nombre del programa actual. El
   método no hace nada si "self.version" está vacío o no está
   definido.

OptionParser.get_version()

   Igual que "print_version()", pero retorna la cadena de versión en
   lugar de imprimirla.


Cómo maneja los errores el módulo "optparse"
--------------------------------------------

A grandes rasgos, hay dos clases de errores de los que "optparse"
tiene que preocuparse: errores del programador y errores del usuario.
Los errores del programador suelen ser el resultado de llamadas
erróneas a "OptionParser.add_option()", como cadenas de opción no
válidas, atributos de opción desconocidos, atributos de opción que
faltan, etc. Se tratan de la forma habitual: generan una excepción (ya
sea "optparse.OptionError" o "TypeError") y hacen que el programa se
bloquee.

Manejar los errores del usuario es mucho más importante, ya que está
garantizado que sucederán sin importar cuán estable sea el código.
"optparse" puede detectar automáticamente algunos errores del usuario,
como argumentos de opción incorrectos (pasar "-n 4x" donde "-n" toma
un argumento entero) o la falta de argumentos ("-n" al final de la
línea de comandos, donde "-n" toma un argumento de cualquier tipo).
Además de esto, puedes llamar a "OptionParser.error()" para establecer
una condición de error definida por la propia aplicación:

   (options, args) = parser.parse_args()
   ...
   if options.a and options.b:
       parser.error("options -a and -b are mutually exclusive")

En cualquier caso, "optparse" maneja el error de la misma manera:
imprime el mensaje de uso del programa junto a un mensaje de error en
la salida de errores estándar y termina la ejecución con el estado de
error 2.

Considera el primero de los dos ejemplos anteriores, donde el usuario
pasa "4x" a una opción que toma un número entero:

   $ /usr/bin/foo -n 4x
   Usage: foo [options]

   foo: error: option -n: invalid integer value: '4x'

O, en el caso en el que el usuario definitivamente no pase ningún
valor:

   $ /usr/bin/foo -n
   Usage: foo [options]

   foo: error: -n option requires an argument

Los mensajes de error generados por "optparse" tienen siempre cuidado
de mencionar la opción involucrada en el error. Asegúrate de hacer lo
mismo cuando llames a "OptionParser.error()" desde el código de tu
aplicación.

Si el comportamiento del manejo de errores predeterminado de
"optparse" no se adapta a tus necesidades, deberás subclasificar
OptionParser y redefinir su método "exit()" y/o "error()".


Reuniendo todas las piezas
--------------------------

Así es como los scripts basados en "optparse" usualmente se ven:

   from optparse import OptionParser
   ...
   def main():
       usage = "usage: %prog [options] arg"
       parser = OptionParser(usage)
       parser.add_option("-f", "--file", dest="filename",
                         help="read data from FILENAME")
       parser.add_option("-v", "--verbose",
                         action="store_true", dest="verbose")
       parser.add_option("-q", "--quiet",
                         action="store_false", dest="verbose")
       ...
       (options, args) = parser.parse_args()
       if len(args) != 1:
           parser.error("incorrect number of arguments")
       if options.verbose:
           print("reading %s..." % options.filename)
       ...

   if __name__ == "__main__":
       main()


Guía de referencia
==================


Creando el analizador sintáctico (parser)
-----------------------------------------

El primer paso para poder usar "optparse" es crear una instancia de
OptionParser.

class optparse.OptionParser(...)

   El constructor de la clase OptionParser no tiene argumentos
   obligatorios, pero sí varios argumentos opcionales por palabra
   clave. Siempre deben pasarse como argumentos por palabras clave, es
   decir, no se debe confiar nunca en el orden en que se declaran los
   argumentos.

   "usage" (por defecto: ""%prog [options]"")
      El resumen de uso a imprimir cuando el programa se ejecuta
      incorrectamente o con una opción de ayuda. Cuando "optparse"
      imprime la cadena de uso, reemplaza "%prog" con
      "os.path.basename(sys.argv[0])" (o con "prog" si se proporcionó
      eso argumento por palabra clave). Para suprimir un mensaje de
      uso, se debe pasar el valor especial "optparse.SUPPRESS_USAGE".

   "option_list" (por defecto: "[]")
      Una lista de objetos Option con los que poblar el analizador.
      Las opciones en "option_list" se agregan después de cualquier
      opción en "standard_option_list" (un atributo de clase que puede
      ser establecido por las subclases de OptionParser), pero antes
      de cualquier versión u opción de ayuda. Obsoleto: usar en su
      lugar el método "add_option()", una vez creado el analizador.

   "option_class" (por defecto: *optparse.Option*)
      Clase usada por el método "add_option()" para añadir opciones al
      analizador.

   "version" (por defecto: "None")
      Una cadena de caracteres con la versión del programa a imprimir
      cuando el usuario proporciona una opción de versión. Si se
      proporciona un valor verdadero para "version", "optparse" agrega
      automáticamente una opción de versión con "--version" como única
      cadena de opción. La subcadena "%prog" se expande de la misma
      manera que en "usage".

   "conflict_handler" (por defecto: ""error"")
      Especifica qué hacer cuando se agregan al analizador opciones
      con cadenas de opción en conflicto entre si. Ver sección
      Conflictos entre opciones.

   "description" (por defecto: "None")
      Un párrafo de texto que ofrece una breve descripción del
      programa. "optparse" reformatea este párrafo para que se ajuste
      al ancho actual de la terminal y lo imprime cuando el usuario
      solicita ayuda (después de "usage", pero antes de la lista de
      opciones).

   "formatter" (por defecto: una nueva instancia de la clase
   "IndentedHelpFormatter")
      Una instancia de la clase optparse.HelpFormatter que será usada
      para imprimir el texto de ayuda. El módulo "optparse"
      proporciona dos clases concretas para este propósito:
      IndentedHelpFormatter y TitledHelpFormatter.

   "add_help_option" (por defecto: "True")
      Si es verdadero, "optparse" agregará al analizador una opción de
      ayuda (con las cadenas de opción "-h" y "--help").

   "prog"
      La cadena de caracteres a usar como substituta de
      "os.path.basename(sys.argv[0])" cuando se expanda "%prog" en
      "usage" y en "version".

   "epilog" (por defecto: "None")
      Un párrafo con texto de ayuda que se imprimirá después de la
      opción de ayuda.


Completando el analizador con opciones
--------------------------------------

Hay varias formas de agregar las opciones al analizador. La forma
preferida es mediante el método "OptionParser.add_option()", tal como
se muestra en la sección del Tutorial. El método "add_option()" se
puede llamar de dos formas diferentes:

* pasándole una instancia de Option (como la que retorna
  "make_option()")

* pasándole cualquier combinación de argumentos posicionales y por
  palabra clave que sean aceptables para "make_option()" (es decir,
  para el constructor de la clase Option), lo que creará la instancia
  Option automáticamente

La otra alternativa es pasar una lista de instancias de Option
previamente construidas al constructor OptionParser, como en el
siguiente ejemplo:

   option_list = [
       make_option("-f", "--filename",
                   action="store", type="string", dest="filename"),
       make_option("-q", "--quiet",
                   action="store_false", dest="verbose"),
       ]
   parser = OptionParser(option_list=option_list)

("make_option()" es una función fábrica para crear instancias Option.
Actualmente es simplemente un alias para el constructor Option, pero
es posible que una futura versión de "optparse" pueda dividir Option
en varias clases, en cuyo caso, "make_option()" elegirá la clase
correcta a instanciar. Esta es la razón por la que no se debe
instanciar Option directamente.)


Definiendo las opciones
-----------------------

Cada instancia de Option representa un conjunto de cadenas de opción
sinónimas para la línea de comandos, por ejemplo "-f" y "--file". Se
puede especificar cualquier número de cadenas de opción cortas o
largas, pero se debe proporcionar al menos una cadena de opción en
total.

La forma canónica de crear una instancia de "Option" es mediante el
método "add_option()" de la clase "OptionParser".

OptionParser.add_option(option)
OptionParser.add_option(*opt_str, attr=value, ...)

   Para definir una opción con solo una cadena de opción corta:

      parser.add_option("-f", attr=value, ...)

   Y para definir una opción con solo una cadena de opción larga:

      parser.add_option("--foo", attr=value, ...)

   Los argumentos por palabra clave definen atributos para el nuevo
   objeto Option. El atributo de opción más importante es "action",
   que determina en gran medida qué otros atributos son apropiados u
   obligatorios. Si se pasan atributos de opción no apropiados, o no
   se pasan los requeridos, "optparse" lanza una excepción
   "OptionError" explicando el error.

   La acción (*action*) de una opción determina que hace el módulo
   "optparse" cuando encuentra dicha opción en la línea de comandos.
   Las acciones de opción estándares codificadas en "optparse" son:

   ""store""
      almacena el argumento de esta opción (por defecto)

   ""store_const""
      almacena un valor de constante, preestablecida vía
      "Option.const"

   ""store_true""
      almacena "True"

   ""store_false""
      almacena "False"

   ""append""
      agrega el argumento de esta opción a una lista

   ""append_const""
      agrega un valor constante a una lista, preestablecido vía
      "Option.const"

   ""count""
      incrementa un contador en uno

   ""callback""
      llama a una función específica

   ""help""
      imprime un mensaje de uso que incluye todas las opciones y la
      documentación correspondiente

   (Si no se proporciona una acción, el valor predeterminado es
   ""store"". Para esta acción en concreto, también se pueden
   proporcionar los atributos de opción "type" y "dest". Consultar
   Acciones de opción estándares para más información.)

Como se puede observar, la mayoría de las acciones implican almacenar
o actualizar un valor en algún lugar. "optparse" siempre crea un
objeto especial para esto, convencionalmente llamado "options", que
resulta ser una instancia de "optparse.Values".

class optparse.Values

   Un objeto que mantiene como atributos a los nombres de los
   argumentos y los valores analizados. Normalmente se crean por
   invocación cuando llamamos "OptionParser.parse_args()", y pueden
   ser sobreescritos por una subclase personalizada pasada al
   argumento *values* de "OptionParser.parse_args()" (como se describe
   en Analizando los argumentos).

Los argumentos de opción (y algunos otros valores) se almacenan como
atributos de este objeto, de acuerdo con el atributo de opción "dest"
(destino) establecido.

Por ejemplo, cuando se llama a:

   parser.parse_args()

una de las primeras cosas que hace el módulo "optparse" es crear el
objeto "options":

   options = Values()

Si una de las opciones de este analizador es definida con:

   parser.add_option("-f", "--file", action="store", type="string", dest="filename")

y la línea de comandos que se analiza incluye cualquiera de las
siguientes variantes:

   -ffoo
   -f foo
   --file=foo
   --file foo

entonces el módulo "optparse", al encontrar esta opción, hará algo
equivalente a:

   options.filename = "foo"

Los atributos de opción "type" y "dest" son casi tan importantes como
"action", pero "action" es el único de ellos que es apropiado para
*todas* las opciones.


Atributos de opción
-------------------

class optparse.Option

   Un único argumento de línea de comando, con varios atributos
   pasados como palabras clave al constructor. Normalmente se crea con
   "OptionParser.add_option()" en lugar de directamente, y puede ser
   sobrescrito por una clase personalizada mediante el argumento
   *option_class* de "OptionParser".

Los siguientes atributos de opción pueden pasarse como argumentos por
palabra clave al método "OptionParser.add_option()". Si se pasa un
atributo de opción que no es apropiado para una opción en particular,
o no se pasa un atributo de opción obligatorio, "optparse" lanza una
excepción "OptionError".

Option.action

   (por defecto: ""store"")

   Determina el comportamiento del módulo "optparse" cuando esta
   opción se encuentra en la línea de comandos. Las opciones
   disponibles están documentadas aquí.

Option.type

   (por defecto: ""string"")

   El tipo de argumento esperado para esta opción (por ejemplo,
   ""string"" o ""int""). Los tipos de opción disponibles están
   documentados aquí.

Option.dest

   (por defecto: derivado de las cadenas de opción)

   Si la acción asociada a la opción implica escribir o modificar un
   valor en algún lugar, este atributo le dice a "optparse" dónde
   escribirlo: "dest" es el nombre de un atributo del objeto "options"
   que "optparse" construye a medida que analiza la línea de comandos.

Option.default

   El valor que se utilizará como destino de esta opción si la opción
   no aparece en la línea de comandos. Ver también
   "OptionParser.set_defaults()".

Option.nargs

   (por defecto: 1)

   Cuántos argumentos de tipo "type" deben consumirse cuando se
   encuentre esta opción. Si es mayor a 1, "optparse" almacenará una
   tupla con los valores de los argumentos en "dest".

Option.const

   Para acciones que almacenan un valor constante, el valor constante
   a almacenar.

Option.choices

   Para opciones de tipo ""choice"", la lista con las cadenas que el
   usuario puede elegir.

Option.callback

   Para las opciones con la acción ""callback"" asignada, el objeto
   invocable a llamar cuando se encuentra esta opción. Consultar la
   sección Retrollamadas de opción para obtener más detalles sobre los
   argumentos que son pasados al objeto invocable.

Option.callback_args
Option.callback_kwargs

   Argumentos posicionales y por palabra clave adicionales para ser
   pasados a "callback" después de los cuatro argumentos pasados a la
   retrollamada estándar.

Option.help

   Texto de ayuda a imprimir para esta opción cuando se enumeran todas
   las opciones disponibles, después de que el usuario proporcione una
   opción "help" (como "--help"). Si no se proporciona ningún texto de
   ayuda, la opción seguirá apareciendo, solo que sin texto de ayuda.
   Para ocultar esta opción completamente, se debe asignar al atributo
   el valor especial "optparse.SUPPRESS_HELP".

Option.metavar

   (por defecto: derivado de las cadenas de opción)

   Reemplazo para los argumentos de opción que se utilizará al
   imprimir el texto de ayuda. Consultar la sección Tutorial para ver
   un ejemplo.


Acciones de opción estándares
-----------------------------

Las diversas acciones de opción tienen requisitos y efectos
ligeramente diferentes. La mayoría de las acciones tienen varios
atributos de opción relacionados que puedes especificar para dirigir
el comportamiento del módulo "optparse". Además, algunas de ellas
tienen atributos requeridos, que se deben especificar para cualquier
opción que utilice esa acción.

* ""store"" [atributos relacionados: "type", "dest", "nargs",
  "choices"]

  La opción debe ir seguida de un argumento, que se convierte en un
  valor de acuerdo a "type" y se almacena en "dest". Si "nargs" es
  mayor que 1, se consumirán varios argumentos de la línea de
  comandos. Todos ellos se convertirán de acuerdo a "type" y se
  almacenarán en "dest" como una tupla. Consultar la sección Tipos de
  opción estándares para más información.

  Si se proporciona "choices" (una lista o tupla de cadenas de
  caracteres), el tipo por defecto es ""choice"".

  Si no se proporciona "type", el tipo por defecto es ""string"".

  Si "dest" no se proporciona, "optparse" infiere un destino de la
  primera cadena de opción larga (por ejemplo, "--foo-bar" implica que
  se usará "foo_bar" como destino). Si no hay cadenas de opción
  largas, "optparse" obtiene el destino a partir de la primera cadena
  de opción corta (por ejemplo, "-f" conlleva que se usará "f").

  Ejemplo:

     parser.add_option("-f")
     parser.add_option("-p", type="float", nargs=3, dest="point")

  Mientras analiza la línea de comandos:

     -f foo.txt -p 1 -3.5 4 -fbar.txt

  "optparse" establecerá:

     options.f = "foo.txt"
     options.point = (1.0, -3.5, 4.0)
     options.f = "bar.txt"

* ""store_const"" [atributo requerido: "const"; atributo relacionado:
  "dest"]

  El valor "const" es almacenado en "dest".

  Ejemplo:

     parser.add_option("-q", "--quiet",
                       action="store_const", const=0, dest="verbose")
     parser.add_option("-v", "--verbose",
                       action="store_const", const=1, dest="verbose")
     parser.add_option("--noisy",
                       action="store_const", const=2, dest="verbose")

  Si se encuentra "--noisy", "optparse" establecerá:

     options.verbose = 2

* ""store_true"" [atributo relacionado: "dest"]

  Un caso especial de ""store_const"" que almacena "True" en "dest".

* ""store_false"" [atributo relacionado: "dest"]

  Como ""store_true"", pero almacena "False".

  Ejemplo:

     parser.add_option("--clobber", action="store_true", dest="clobber")
     parser.add_option("--no-clobber", action="store_false", dest="clobber")

* ""append"" [atributos relacionados: "type", "dest", "nargs",
  "choices"]

  La opción debe ir seguida de un argumento, que se añade a la lista
  de "dest". Si no se proporciona un valor predeterminado para "dest",
  se crea automáticamente una lista vacía cuando "optparse" encuentra
  por primera vez esta opción en la línea de comandos. Si "nargs" es
  mayor que 1, se consumen varios argumentos y se agrega una tupla de
  longitud "nargs" a "dest".

  Los valores por defecto para los atributos "type" y "dest" son los
  mismos que para la acción ""store"".

  Ejemplo:

     parser.add_option("-t", "--tracks", action="append", type="int")

  Si se encuentra "-t3" en la línea de comandos, "optparse" procede de
  forma equivalente a:

     options.tracks = []
     options.tracks.append(int("3"))

  Si, un poco más adelante, se encuentra "--tracks=4", procede así:

     options.tracks.append(int("4"))

  La acción "append" llama al método "append" con el valor actual de
  la opción. Esto significa que cualquier valor por defecto
  especificado debe tener un método "append". También significa que si
  existe un valor por defecto, los elementos por defecto estarán
  presentes en el valor analizado para la opción, con todos los
  valores de la línea de comandos agregados a la lista a continuación
  de ellos:

     >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
     >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
     >>> opts.files
     ['~/.mypkg/defaults', 'overrides.mypkg']

* ""append_const"" [atributo requerido: "const"; atributo relacionado:
  "dest"]

  Igual que ""store_const"", pero el valor "const" se agrega a "dest".
  Como ocurre con ""append"", "dest" por defecto es "None" y se crea
  automáticamente una lista vacía la primera vez que se encuentra la
  opción en la linea de comandos.

* ""count"" [atributo relacionado: "dest"]

  Incrementa el entero almacenado en "dest". Si no se proporciona un
  valor por defecto, "dest" se establece en cero antes de
  incrementarse por primera vez.

  Ejemplo:

     parser.add_option("-v", action="count", dest="verbosity")

  La primera vez que se encuentra "-v" en la línea de comandos,
  "optparse" procede de forma equivalente a:

     options.verbosity = 0
     options.verbosity += 1

  Cada aparición posterior de "-v" da como resultado:

     options.verbosity += 1

* ""callback"" [atributo requerido: "callback"; atributos
  relacionados: "type", "nargs", "callback_args", "callback_kwargs"]

  Llama a la función especificada por "callback", que es llamada como:

     func(option, opt_str, value, parser, *args, **kwargs)

  Ver sección Retrollamadas de opción para más detalles.

* ""help""

  Imprime un mensaje de ayuda completo para todas las opciones
  presentes en el analizador de opciones actual. El mensaje de ayuda
  se construye a partir de la cadena "usage", pasada al constructor de
  OptionParser, y la cadena "help", pasada a cada opción.

  Si no se proporciona una cadena "help" para una opción, dicha opción
  seguirá apareciendo en el mensaje de ayuda. Para omitir una opción
  por completo, debe usarse el valor especial
  "optparse.SUPPRESS_HELP".

  El módulo "optparse" agrega automáticamente una opción "help" a
  todos los OptionParsers, por lo que normalmente no es necesario
  crear una.

  Ejemplo:

     from optparse import OptionParser, SUPPRESS_HELP

     # usually, a help option is added automatically, but that can
     # be suppressed using the add_help_option argument
     parser = OptionParser(add_help_option=False)

     parser.add_option("-h", "--help", action="help")
     parser.add_option("-v", action="store_true", dest="verbose",
                       help="Be moderately verbose")
     parser.add_option("--file", dest="filename",
                       help="Input file to read data from")
     parser.add_option("--secret", help=SUPPRESS_HELP)

  Si "optparse" encuentra "-h" o "--help" en la línea de comandos,
  imprimirá un mensaje de ayuda en la salida estándar como el
  siguiente (asumiendo que "sys.argv [0]" es ""foo.py""):

     Usage: foo.py [options]

     Options:
       -h, --help        Show this help message and exit
       -v                Be moderately verbose
       --file=FILENAME   Input file to read data from

  Después de imprimir el mensaje de ayuda, "optparse" termina su
  proceso con "sys.exit(0)".

* ""version""

  Imprime el número de versión proporcionado a OptionParser en la
  salida estándar y termina la ejecución. El número de versión en
  realidad es formateado e impreso por el método "print_version()" de
  OptionParser. Generalmente solo es relevante si el argumento
  "version" se proporciona al constructor de OptionParser. Al igual
  que en el caso de las opciones "help", rara vez será necesario crear
  opciones de "version", ya que "optparse" las agrega automáticamente
  cuando es necesario.


Tipos de opción estándares
--------------------------

El módulo "optparse" proporciona cinco tipos de opción incorporados:
""string"", ""int"", ""choice"", ""float"" y ""complex"". Consultar la
sección Extendiendo el módulo optparse si se necesitan agregar nuevos
tipos de opción.

Los argumentos de las opciones en la cadena ingresada no se verifican
ni se convierten de ninguna manera: el texto de la línea de comandos
se almacena en el destino (o se pasa a la retrollamada) tal cual.

Los argumentos enteros (tipo ""int"") se analizan de la siguiente
manera:

* si el número comienza con "0x", se analiza como un número
  hexadecimal

* si el número comienza con "0", se analiza como un número octal

* si el número comienza con "0b", se analiza como un número binario

* en cualquier otro caso, el número se analiza como un número decimal

La conversión se realiza llamando a "int()" con la base apropiada (2,
8, 10 o 16). Si esto falla, también lo hará "optparse", aunque
mostrando un mensaje de error más útil para el usuario.

Los argumentos de las opciones de tipo ""float"" y ""complex"" se
convierten directamente usando "float()" y "complex()"
respectivamente, con un manejo de errores similar.

Las opciones de tipo ""choice"" son un subtipo de las opciones
""string"". El atributo de opción "choices" (que es una secuencia de
cadenas) define el conjunto de argumentos de opción permitidos.
Posteriormente, "optparse.check_choice()" comparará los argumentos de
las opciones proporcionadas por el usuario con esta lista maestra y
lanzará una excepción "OptionValueError" si se proporciona una cadena
no válida.


Analizando los argumentos
-------------------------

El objetivo primario de crear y agregar opciones a un OptionParser es
llamar a su método "parse_args()".

OptionParser.parse_args(args=None, values=None)

   Analiza las opciones de la línea de comando encontradas en *args*.

   Los parámetros de entrada son

   "args"
      la lista de argumentos a procesar (por defecto: "sys.argv [1:]")

   "values"
      a "Values" object to store option arguments in (default: a new
      instance of "Values") -- if you give an existing object, the
      option defaults will not be initialized on it

   y los valores de retorno es un par "(options, args)" donde

   "options"
      el mismo objeto que se pasó como *values*, o la instancia
      "optparse.Values" creada por "optparse"

   "args"
      los argumentos posicionales que quedan en la linea de comandos
      después de que se hayan procesado todas las opciones

El uso más habitual es no proporcionar ningún argumento por palabra
clave. Si se proporciona "values", dicho argumento será modificado
mediante llamadas repetidas a "setattr()" (aproximadamente una por
cada argumento de opción a almacenar en un destino de opción) y
finalmente será retornado por el método "parse_args()".

Si el método "parse_args()" encuentra algún error en la lista de
argumentos, llama al método "error()" de OptionParser con un mensaje
de error apropiado para el usuario final. Esto causa que el proceso
termine con un estado de salida de 2 (el estado de salida tradicional
en Unix para errores en la línea de comandos).


Consultar y manipular el analizador de opciones
-----------------------------------------------

El comportamiento predeterminado del analizador de opciones se puede
personalizar ligeramente. También se puede indagar en el analizador de
opciones y ver qué hay en él. OptionParser proporciona varios métodos
para ayudar con éstos propósitos:

OptionParser.disable_interspersed_args()

   Configura el análisis para que se detenga en lo primero que
   encuentre que no sea una opción. Por ejemplo, si "-a" y "-b" son
   opciones simples que no toman argumentos, "optparse" normalmente
   acepta esta sintaxis:

      prog -a arg1 -b arg2

   y la trata de forma equivalente a:

      prog -a -b arg1 arg2

   Para deshabilitar esta funcionalidad, se debe llamar al método
   "disable_interspersed_args()". Esto restaura la sintaxis
   tradicional usada en Unix, donde el análisis de opción se detiene
   con el primer argumento que no es una opción.

   Se debe usar este método si se dispone de un procesador de comandos
   que ejecuta otro comando con sus propias opciones y se desea
   asegurarse de que estas opciones no se confunden entre si. Lo que
   puede ocurrir si, por ejemplo, cada comando tiene un conjunto
   diferente de opciones.

OptionParser.enable_interspersed_args()

   Configura el análisis para que no se detenga si encuentra un
   argumento que no sea una opción, lo que permite intercalar
   modificadores con argumentos de linea de comandos. Este es el
   comportamiento por defecto.

OptionParser.get_option(opt_str)

   Retorna la instancia de Option con la cadena de opción *opt_str*, o
   "None" si ninguna opción tiene esa cadena de opción.

OptionParser.has_option(opt_str)

   Retorna "True" si OptionParser tiene una opción con la cadena de
   opción *opt_str* (por ejemplo, "-q" o "--verbose").

OptionParser.remove_option(opt_str)

   Si "OptionParser" tiene una opción correspondiente a *opt_str*, esa
   opción es eliminada. Si esa opción proporcionó cualquier otra
   cadena de opción, todas esas cadenas de opción quedan invalidadas.
   Si *opt_str* no aparece en ninguna opción que pertenezca a este
   "OptionParser", se lanza una excepción "ValueError".


Conflictos entre opciones
-------------------------

Si no se tiene cuidado, es fácil definir opciones con cadenas de
opción en conflicto entre si:

   parser.add_option("-n", "--dry-run", ...)
   ...
   parser.add_option("-n", "--noisy", ...)

(Esto es particularmente cierto si se ha definido una subclase propia
de OptionParser con algunas opciones estándar.)

Cada vez que se agrega una opción, "optparse" comprueba si existen
conflictos con las opciones ya existentes. Si encuentra alguno, invoca
el mecanismo de manejo de conflictos actualmente establecido. Se puede
establecer el mecanismo de manejo de conflictos desde el propio
constructor:

   parser = OptionParser(..., conflict_handler=handler)

o mediante una llamada separada:

   parser.set_conflict_handler(handler)

Los administradores de conflictos disponibles son:

   ""error"" (por defecto)
      se asume que los conflictos entre opciones son un error de
      programación y, por tanto, generarán una excepción
      "OptionConflictError"

   ""resolve""
      resuelve conflictos de opciones de forma inteligente (ver más
      abajo)

Como ejemplo, vamos a definir un "OptionParser" que resuelva
conflictos de manera inteligente y agregaremos algunas opciones
conflictivas:

   parser = OptionParser(conflict_handler="resolve")
   parser.add_option("-n", "--dry-run", ..., help="do no harm")
   parser.add_option("-n", "--noisy", ..., help="be noisy")

En este punto, "optparse" detecta que una opción agregada
anteriormente ya está usando la cadena de opción "-n". Dado que
"conflict_handler" es ""resolve"", resuelve la situación eliminando
"-n" de la lista de cadenas de opción de la opción previa. Ahora "--
dry-run" es la única forma que el usuario tiene para poder activar esa
opción. Si el usuario solicita ayuda, el mensaje de ayuda reflejará la
nueva situación:

   Options:
     --dry-run     do no harm
     ...
     -n, --noisy   be noisy

Es posible reducir las cadenas de opción para una opción agregada
previamente hasta que no quede ninguna, de forma que el usuario no
tenga forma de invocar esa opción desde la línea de comandos. En ese
caso, "optparse" eliminará esa opción por completo, por lo que no
aparecerá en el texto de ayuda ni en ningún otro lugar. Continuando
con nuestro analizador de opciones existente OptionParser:

   parser.add_option("--dry-run", ..., help="new dry-run option")

En este punto, la opción original "-n"/"--dry-run" ya no es accesible,
por lo que "optparse" la elimina, dejando el siguiente texto de ayuda:

   Options:
     ...
     -n, --noisy   be noisy
     --dry-run     new dry-run option


Limpieza
--------

Las instancias de OptionParser tienen varias referencias cíclicas.
Esto no debería ser un problema para el recolector de basura de
Python, pero es posible que se desee romper las referencias cíclicas
explícitamente llamando al método "destroy()" de la instancia
OptionParser una vez que se haya terminado. Esto es particularmente
útil en aplicaciones de larga ejecución en las que OptionParser puede
terminar accediendo a grafos de objetos considerablemente grandes.


Otros métodos
-------------

OptionParser admite varios métodos públicos más:

OptionParser.set_usage(usage)

   Establece la cadena de caracteres de uso de acuerdo a las reglas
   descritas anteriormente para el argumento por palabra clave "usage"
   del constructor. Pasando "None" se establece la cadena de uso por
   defecto; use el valor especial "optparse.SUPPRESS_USAGE" para
   suprimir el mensaje de uso.

OptionParser.print_usage(file=None)

   Imprime el mensaje de uso del programa actual ("self.usage") en
   *file* (que por defecto es la salida estándar). Cualquier aparición
   de la cadena de caracteres "%prog" en "self.usage" es reemplazada
   con el nombre del programa actual. No hace nada si "self.usage"
   está vacío o no ha sido definido.

OptionParser.get_usage()

   Igual que "print_usage()" pero retorna la cadena de uso en vez de
   imprimirla.

OptionParser.set_defaults(dest=value, ...)

   Establece valores por defecto para varios destinos de opción a la
   vez. Usar el método "set_defaults()" es la forma preferida de
   establecer valores por defecto para las opciones, ya que varias
   opciones pueden compartir el mismo destino. Por ejemplo, si varias
   opciones de "mode" tienen el mismo destino, cualquiera de ellas
   puede establecer el valor por defecto, pero el último establecido
   es el que finalmente queda establecido:

      parser.add_option("--advanced", action="store_const",
                        dest="mode", const="advanced",
                        default="novice")    # overridden below
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice",
                        default="advanced")  # overrides above setting

   Para evitar esta confusión, usa el método "set_defaults()":

      parser.set_defaults(mode="advanced")
      parser.add_option("--advanced", action="store_const",
                        dest="mode", const="advanced")
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice")


Retrollamadas de opción
=======================

Cuando las acciones y tipos incorporados de "optparse" no son
suficientes para tus necesidades, tienes dos opciones: extender
"optparse" o definir una opción con una retrollamada asociada.
Extender "optparse" es más general, pero algo exagerado para muchos
casos simples. Es frecuente que una simple retrollamada sea todo lo
que necesitas.

Hay dos pasos a seguir para definir una opción con retrollamada:

* definir la opción en sí usando la acción ""callback""

* escribir la retrollamada. Esta es una función (o método) que toma al
  menos cuatro argumentos, los cuales son descritos a continuación


Definición de una opción con retrollamada
-----------------------------------------

Generalmente, la forma más sencilla de definir una opción con
retrollamada es mediante el método "OptionParser.add_option()". Aparte
de "action", el único atributo de opción que debes especificar es
"callback", que es la función a llamar:

   parser.add_option("-c", action="callback", callback=my_callback)

"callback" es una función (u otro objeto invocable), lo que implica
que "my_callback()" debe haber sido definida antes de la la creación
de esta opción con retrollamada. En este caso simple, "optparse" ni
siquiera sabe si "-c" toma algún argumento, lo que generalmente
significa que la opción no toma argumentos---la mera presencia de "-c"
en la línea de comandos es todo lo que necesita saber. Sin embargo, en
algunas circunstancias, es posible que se desee que la retrollamada
consuma una cantidad arbitraria de argumentos de la propia línea de
comandos. Es aquí donde escribir retrollamadas se vuelve complicado;
se tratará más adelante en esta sección.

"optparse" siempre pasa cuatro argumentos concretos a la retrollamada.
El método solo pasará argumentos adicionales si se especifica
explícitamente a través de "callback_args" y "callback_kwargs". Por lo
tanto, la firma mínima de la retrollamada es:

   def my_callback(option, opt, value, parser):

Los cuatro argumentos para la retrollamada se describen a
continuación.

Hay varios atributos de opción adicionales que se pueden proporcionar
cuando se define una opción con retrollamada:

"type"
   tiene su significado habitual: al igual que en las acciones
   ""store"" o ""append"", indica a "optparse" que debe consumir un
   argumento y convertirlo a "type" . Sin embargo, en lugar de
   almacenar el valor (o valores) convertido en algún lugar,
   "optparse" lo pasa a la retrollamada.

"nargs"
   también tiene su significado habitual: si se proporciona y es mayor
   que 1, "optparse" consumirá "nargs" argumentos de la línea de
   comandos, cada uno de los cuales debe ser convertible a "type".
   Hecho esto, se pasa una tupla con los valores convertidos a la
   retrollamada.

"callback_args"
   una tupla con los argumentos posicionales adicionales para pasar a
   la retrollamada

"callback_kwargs"
   un diccionario con los argumentos por palabra clave para pasar a la
   retrollamada


Cómo son invocadas las retrollamadas
------------------------------------

Todas las retrollamadas son invocadas de la siguiente forma:

   func(option, opt_str, value, parser, *args, **kwargs)

donde

"option"
   es la instancia de Option que invoca a la retrollamada

"opt_str"
   es la cadena de opción encontrada en la línea de comandos que
   activa la retrollamada. (Si se utilizó una opción larga abreviada,
   "opt_str" será la cadena de opción canónica completa--- por
   ejemplo, si el usuario ingresa "--foo" en la línea de comandos como
   una abreviatura de "--foobar", entonces "opt_str" será ""--
   foobar"".)

"value"
   es el argumento de esta opción encontrado en la línea de comandos.
   "optparse" solo esperará un argumento si "type" está establecido.
   El tipo de "value" será el tipo implícito en el tipo de la propia
   opción. Si "type" es "None" para esta opción (no se espera ningún
   argumento), entonces "value" será también "None". Si "nargs" es
   mayor que 1, "value" será una tupla con los valores del tipo
   apropiado.

"parser"
   es la instancia de OptionParser que controla todo. Su utilidad
   principal radica en que permite acceder a otros datos de interés a
   través de sus atributos de instancia:

   "parser.largs"
      la lista actual de argumentos que sobran, es decir, argumentos
      que se han consumido pero que no son opciones ni argumentos de
      opción. Siéntete libre de modificar "parser.largs", por ejemplo,
      agregando más argumentos. (Esta lista se convertirá en "args",
      el segundo valor de retorno del método "parse_args()".)

   "parser.rargs"
      la lista actual de argumentos restantes, es decir, los
      argumentos que quedan a continuación de "opt_str" y "value" (si
      corresponde), una vez eliminados ambos. Siéntete libre de
      modificar "parser.rargs", por ejemplo, consumiendo más
      argumentos.

   "parser.values"
      el objeto donde los valores de las opciones son almacenados por
      defecto (una instancia de *optparse.OptionValues*). Esto permite
      que las retrollamadas utilicen el mismo mecanismo que el resto
      de "optparse" para almacenar valores de las opciones; no es
      necesario perder el tiempo con globales o clausuras. También se
      puede acceder a los valores de las opciones o modificarlos si ya
      se encuentran en la línea de comandos.

"args"
   es una tupla de argumentos posicionales arbitrarios suministrados a
   través del atributo de opción "callback_args".

"kwargs"
   es un diccionario con argumentos por palabra clave arbitrarios
   proporcionados por "callback_kwargs".


Lanzando errores en una retrollamada
------------------------------------

La retrollamada debería lanzar una excepción "OptionValueError" si hay
algún problema con la opción o su(s) argumento(s). Esto permite a
"optparse" detectar el problema y finalizar el programa, imprimiendo
el mensaje de error que hayas proporciones en la salida de error
estándar. El mensaje debe ser claro, conciso, preciso y mencionar la
opción que causa la excepción. De lo contrario, el usuario tendrá
dificultades para descubrir qué hizo mal.


Ejemplo de retrollamada 1: una retrollamada trivial
---------------------------------------------------

Aquí hay un ejemplo de una opción con retrollamada que no tiene
argumentos y simplemente registra que se encontró la opción en la
línea de comandos:

   def record_foo_seen(option, opt_str, value, parser):
       parser.values.saw_foo = True

   parser.add_option("--foo", action="callback", callback=record_foo_seen)

Ciertamente, se puede hacer lo mismo simplemente con la acción
""store_true"".


Ejemplo de retrollamada 2: comprobar el orden de las opciones
-------------------------------------------------------------

Aquí tenemos un ejemplo un poco más interesante: registra el hecho de
que se ha encontrado "-a", pero lanza un error si viene después de
"-b" en la línea de comandos

   def check_order(option, opt_str, value, parser):
       if parser.values.b:
           raise OptionValueError("can't use -a after -b")
       parser.values.a = 1
   ...
   parser.add_option("-a", action="callback", callback=check_order)
   parser.add_option("-b", action="store_true", dest="b")


Ejemplo de retrollamada 3: comprobar el orden de las opciones (generalizado)
----------------------------------------------------------------------------

If you want to reuse this callback for several similar options (set a
flag, but blow up if "-b" has already been seen), it needs a bit of
work: the error message and the flag that it sets must be generalized.

   def check_order(option, opt_str, value, parser):
       if parser.values.b:
           raise OptionValueError("can't use %s after -b" % opt_str)
       setattr(parser.values, option.dest, 1)
   ...
   parser.add_option("-a", action="callback", callback=check_order, dest='a')
   parser.add_option("-b", action="store_true", dest="b")
   parser.add_option("-c", action="callback", callback=check_order, dest='c')


Ejemplo de retrollamada 4: comprobar una condición arbitraria
-------------------------------------------------------------

Por supuesto, puedes poner cualquier condición aquí, no estás limitado
a verificar los valores de las opciones previamente definidas. Por
ejemplo, si tienes opciones que no deberían llamarse cuando hay luna
llena, todo lo que tienes que hacer es lo siguiente:

   def check_moon(option, opt_str, value, parser):
       if is_moon_full():
           raise OptionValueError("%s option invalid when moon is full"
                                  % opt_str)
       setattr(parser.values, option.dest, 1)
   ...
   parser.add_option("--foo",
                     action="callback", callback=check_moon, dest="foo")

(La definición de "is_moon_full()" se deja como ejercicio para el
lector).


Ejemplo de retrollamada 5: argumentos fijos
-------------------------------------------

Las cosas se ponen un poco más interesantes cuando se definen opciones
con retrollamada que toman un número fijo de argumentos. Especificar
que una opción con retrollamada toma argumentos es similar a definir
una opción ""store"" o ""append"": si se define "type", entonces la
opción toma un argumento que debe poder convertirse a ese tipo; si
además se define "nargs", entonces la opción toma "nargs" argumentos.

Aquí hay un ejemplo que simplemente emula la acción ""store""
estándar:

   def store_value(option, opt_str, value, parser):
       setattr(parser.values, option.dest, value)
   ...
   parser.add_option("--foo",
                     action="callback", callback=store_value,
                     type="int", nargs=3, dest="foo")

Ten en cuenta que "optparse" se encarga de consumir 3 argumentos y
convertirlos a números enteros por ti; todo lo que tienes que hacer es
almacenarlos. (En cualquier caso, obviamente no necesitas hacer uso de
una retrollamada para este ejemplo).


Ejemplo de retrollamada 6: argumentos variables
-----------------------------------------------

Las cosas se complican si quieres que una opción pueda tomar un número
variable de argumentos. En este caso, si que deberás escribir una
retrollamada, ya que el módulo "optparse" no proporciona ninguna
capacidad incorporada para ello. Además, tienes que lidiar con ciertos
entresijos del análisis convencional de la línea de comandos de Unix,
que "optparse" normalmente maneja por ti. En concreto, las
retrollamadas deben implementar las reglas convencionales para los
argumentos "--" y "-" desnudos:

* tanto "--" como "-" pueden ser argumentos de opción

* "--" desnudo (si no es el argumento de alguna opción): detener el
  procesamiento de la línea de comandos y descartar el "--"

* "-" desnudo (si no es el argumento de alguna opción): detener el
  procesamiento de la línea de comandos pero mantener el "-"
  (añadiéndolo a "parser.largs")

Si deseas que una opción tenga un número variable de argumentos, hay
varios problemas sutiles y complicados de los que deberás preocuparte.
La implementación exacta que elijas dependerá de los sacrificios que
estés dispuesto a hacer en tu aplicación (razón por la cual, el módulo
"optparse" no admite directamente este tipo de cosas).

En cualquier caso, aquí hay un intento de una retrollamada para una
opción con un número de argumentos variable:

   def vararg_callback(option, opt_str, value, parser):
       assert value is None
       value = []

       def floatable(str):
           try:
               float(str)
               return True
           except ValueError:
               return False

       for arg in parser.rargs:
           # stop on --foo like options
           if arg[:2] == "--" and len(arg) > 2:
               break
           # stop on -a, but not on -3 or -3.0
           if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
               break
           value.append(arg)

       del parser.rargs[:len(value)]
       setattr(parser.values, option.dest, value)

   ...
   parser.add_option("-c", "--callback", dest="vararg_attr",
                     action="callback", callback=vararg_callback)


Extendiendo el módulo "optparse"
================================

Dado que los dos factores principales que controlan como el módulo
"optparse" interpreta las opciones de la línea de comandos son la
acción y el tipo de cada opción, los objetivos más probables de
extensión son agregar nuevas acciones y nuevos tipos.


Agregando nuevos tipos
----------------------

Para añadir nuevos tipos, necesitas definir tu propia subclase de la
clase "Option" de "optparse". Esta clase tiene un par de atributos que
definen los tipos de "optparse": "TYPES" y "TYPE_CHECKER".

Option.TYPES

   Una tupla con nombres de tipos. En tu subclase, simplemente define
   una nueva tupla "TYPES" que se base en la estándar.

Option.TYPE_CHECKER

   Un diccionario que asigna nombres de tipos a funciones de
   verificación de tipo. Una función de verificación de tipo tiene la
   siguiente firma:

      def check_mytype(option, opt, value)

   donde "option" es una instancia de "Option", "opt" es una cadena de
   opción (por ejemplo, "-f") y "value" es la cadena de caracteres de
   la línea de comandos que debe comprobarse y convertirse al tipo
   deseado. "check_mytype()" debería retornar un objeto del tipo
   hipotético "mytype". El valor retornado por una función de
   verificación de tipo terminará formando parte de la instancia de
   OptionValues retornada por el método "OptionParser.parse_args()" o
   será pasada a una retrollamada como parámetro "value".

   Tu función de verificación de tipo debería lanzar una excepción
   "OptionValueError" si encuentra algún problema. "OptionValueError"
   toma una cadena de caracteres como único argumento, que es pasada
   tal cual al método "error()" de la clase "OptionParser", que a su
   vez antepone a la misma el nombre del programa y la cadena
   ""error:"" e imprime todo en la salida de error estándar antes de
   finalizar el proceso.

Aquí hay un ejemplo absurdo que demuestra cómo agregar un tipo de
opción ""complex"" para analizar números complejos al estilo Python en
la línea de comandos. (Esto es aún más absurdo de lo que en principio
parece, porque en al versión 1.3 de "optparse" se agregó soporte
incorporado para números complejos, pero no importa).

Primero, las importaciones necesarias:

   from copy import copy
   from optparse import Option, OptionValueError

En primer lugar, debes definir tu verificador de tipo, ya que se hace
referencia a él más adelante (en el atributo de clase "TYPE_CHECKER"
de tu subclase de Option):

   def check_complex(option, opt, value):
       try:
           return complex(value)
       except ValueError:
           raise OptionValueError(
               "option %s: invalid complex value: %r" % (opt, value))

Finalmente, la subclase de Option:

   class MyOption (Option):
       TYPES = Option.TYPES + ("complex",)
       TYPE_CHECKER = copy(Option.TYPE_CHECKER)
       TYPE_CHECKER["complex"] = check_complex

(Si no hacemos una copia (mediante "copy()"), de
"Option.TYPE_CHECKER", terminaríamos modificando el atributo
"TYPE_CHECKER" de la clase Option de "optparse". Tratándose de Python,
nada te impide hacer eso, excepto los buenos modales y el sentido
común.)

¡Y eso es todo! Ahora puedes escribir un script que use tu nuevo tipo
de opción como cualquier otro script basado en "optparse", excepto que
debes indicarle a tu OptionParser que use MyOption en lugar de Option:

   parser = OptionParser(option_class=MyOption)
   parser.add_option("-c", type="complex")

Alternativamente, puedes crear tu propia lista de opciones y pasarla a
OptionParser; si no usas "add_option()" de la manera anterior, no
necesitas decirle a OptionParser qué clase de opción usar:

   option_list = [MyOption("-c", action="store", type="complex", dest="c")]
   parser = OptionParser(option_list=option_list)


Agregando nuevas acciones
-------------------------

Agregar nuevas acciones es un poco más complicado, dado que hay que
comprender que "optparse" establece un par de categorías para las
acciones:

Acciones "store"
   acciones que dan como resultado que "optparse" almacene un valor en
   un atributo de la instancia actual de OptionValues. Estas opciones
   requieren un atributo "dest" para que pueda ser proporcionado al
   constructor de Option.

Acciones "typed"
   acciones que toman un valor de la línea de comandos, esperando que
   sea de cierto tipo; o mejor dicho, una cadena de caracteres que se
   pueda convertir a un determinado tipo. Estas opciones requieren un
   atributo "type" para el constructor de Option.

Ambas categorías se solapan entre si: algunas acciones "store"
predeterminadas son ""store"", ""store_const"", ""append"" y
""count"", mientras que las acciones "typed" predeterminadas son
""store"", ""append"" y ""callback"".

Cuando agregas una acción, debes categorizarla enumerándola en al
menos uno de los siguientes atributos de clase de la clase Option
(todos ellos son listas de cadenas de caracteres):

Option.ACTIONS

   Todas las acciones deben aparecer en ACTIONS.

Option.STORE_ACTIONS

   Las acciones "store" también se enumeran aquí.

Option.TYPED_ACTIONS

   Las acciones "typed" también se enumeran aquí.

Option.ALWAYS_TYPED_ACTIONS

   Las acciones que siempre toman un tipo (es decir, aquellas cuyas
   opciones siempre toman un valor) también deben enumerarse aquí. La
   única consecuencia de esto es que "optparse" asigna el tipo
   predeterminado, "string", a las opciones cuya acción se enumera en
   "ALWAYS_TYPED_ACTIONS" pero que no tienen asignado un tipo
   explícito.

Para implementar realmente tu nueva acción, debes redefinir el método
"take_action()" de Option, implementando un nuevo método que reconozca
tu acción.

Por ejemplo, agreguemos una nueva acción ""extend"". Esta es similar a
la acción estándar ""append"", pero en lugar de tomar un solo valor de
la línea de comandos y agregarlo a una lista existente, ""extend""
tomará múltiples valores en una sola cadena de caracteres delimitada
por comas y amplía una lista previamente existente con ellos. Es
decir, si "--names" es una opción ""extend"" de tipo ""string"", la
línea de comandos

   --names=foo,bar --names blah --names ding,dong

daría como resultado una lista como la siguiente:

   ["foo", "bar", "blah", "ding", "dong"]

De nuevo, definimos una subclase de Option:

   class MyOption(Option):

       ACTIONS = Option.ACTIONS + ("extend",)
       STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
       TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
       ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)

       def take_action(self, action, dest, opt, value, values, parser):
           if action == "extend":
               lvalue = value.split(",")
               values.ensure_value(dest, []).extend(lvalue)
           else:
               Option.take_action(
                   self, action, dest, opt, value, values, parser)

Detalles a tener en cuenta:

* ""extend"" espera un valor en la línea de comandos y también
  almacena ese valor en algún lugar, por lo que lo agregamos tanto a
  "STORE_ACTIONS" como a "TYPED_ACTIONS".

* para asegurarnos de que "optparse" asigna el tipo predeterminado
  ""string"" a las acciones ""extend"", agregamos también la acción
  ""extend"" a "ALWAYS_TYPED_ACTIONS".

* el método "MyOption.take_action()" solo se encarga de implementar
  esta nueva acción y posteriormente le pasa el control al método
  "Option.take_action()" para las acciones estándar de "optparse".

* "values" es una instancia de la clase *optparse_parser.Values*, que
  proporciona el útil método "ensure_value()". El método
  "ensure_value()" es en esencia lo mismo que "getattr()" pero con un
  mecanismo de seguridad agregado. Es llamado como:

     values.ensure_value(attr, value)

  Si el atributo "attr" de "values" no existe o es "None", entonces
  *ensure_value()* primero lo establece en "value" y luego retorna el
  atributo actualizado ("value"). Esto es muy útil para acciones como
  ""extend"", ""append"" y ""count"", dado que todas ellas acumulan
  datos en una variable y esperan que esa variable sea de cierto tipo
  (una lista para las dos primeras, un número entero para la última).
  Usar el método "ensure_value()" significa que los scripts que usan
  tu acción no tienen que preocuparse por establecer un valor
  predeterminado para los destinos de opción en cuestión; simplemente
  pueden dejar el valor predeterminado como "None" y "secure_value()"
  se encargará de que todo esté correcto cuando sea necesario.


Excepciones
===========

exception optparse.OptionError

   Lanzada si se crea con argumentos inválidos o inconsistentes una
   instancia de "Option".

exception optparse.OptionConflictError

   Lanzada si se añaden opciones que entren en conflicto en una
   "OptionParser".

exception optparse.OptionValueError

   Lanzada si se encuentra una opción inválida en la línea de
   comandos.

exception optparse.BadOptionError

   Lanzada si se pasa una opción inválida en la línea de comandos.

exception optparse.AmbiguousOptionError

   Lanzada si se pasa una opción ambigua en la línea de comandos.
