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 CgetoptAPI. Included in the standard library since before the initial Python 1.0 release.optparse: a declarative replacement forgetoptthat 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 tooptparsethat 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
optparseand doesn’t want to risk the subtle behavioural changes that may arise when migrating toargparsethe 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
argparsedoes 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
argparsedoes not support, but which can be implemented in terms of the lower level interface offered byoptparse
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 -vgivesoutput="-v"andverbose=Falsewhen usingoptparse, but a usage error withargparse(complaining that no value has been supplied for-o/--output, since-vis interpreted as meaning the verbosity flag)similarly, supplying
-o --givesoutput="--"andargs=()when usingoptparse, but a usage error withargparse(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=foogivesoutput="=foo"when usingoptparse, but givesoutput="foo"withargparse(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()oexecv(). En Python, los argumentos son elementos desys.argv[1:](dado quesys.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 desys.argv[1:]o de alguna otra lista proporcionada como sustituto desys.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
-xo-F. La sintaxis tradicional de Unix permite además fusionar múltiples opciones en un solo argumento, por ejemplo-x -Fes equivalente a-xF. Por otro lado, el proyecto GNU introdujo--seguido de una serie de palabras separadas por guiones, por ejemplo--fileo--dry-run. Estas son las dos únicas sintaxis para opciones que el módulooptparseproporciona.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
+fo+rgbuna barra seguida de una letra, de unas pocas letras o de una palabra, por ejemplo
/fo/file
Estas sintaxis para opciones no son compatibles con
optparsey 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
-atoma un argumento opcional y-bes otra opción completamente distinta, ¿cómo interpretamos-ab? Debido a esta ambigüedad,optparseno 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.
optparseno 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--filetoma un argumento de una sola cadena de caracteres, entoncesoptions.fileserá el nombre del archivo proporcionado por el usuario oNonesi el usuario no proporcionó esa opción en la linea de comandosargs, 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"
optparseexpande% progen 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,
optparseusa 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.
optparsese 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,optparseconvierte 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--filenameestablece explícitamentemetavar="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
FILEpara indicarle al usuario que hay una conexión entre la sintaxis semiformal-f FILEy 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
%defaulten la cadena de ayuda, en cuyo caso,optparselo reemplazará por el resultado de aplicarstr()al valor por defecto de esa opción. Si una opción no tiene un valor por defecto (o el valor por defecto esNone),%defaultse reemplazará pornone.
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
OptionParseren la que se insertará el grupotitle 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
OptionGroupal que pertenece la cadena de opción corta o larga opt_str (por ejemplo,'-o'o' --option'). Si no existe dichoOptionGroup, el método retornaNone.
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 conprint_usage(), cualquier aparición de%progenself.versionse reemplaza con el nombre del programa actual. El método no hace nada siself.versionestá 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
optparseimprime la cadena de uso, reemplaza%progconos.path.basename(sys.argv[0])(o conprogsi se proporcionó eso argumento por palabra clave). Para suprimir un mensaje de uso, se debe pasar el valor especialoptparse.SUPPRESS_USAGE.option_list(por defecto:[])Una lista de objetos Option con los que poblar el analizador. Las opciones en
option_listse agregan después de cualquier opción enstandard_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étodoadd_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,optparseagrega automáticamente una opción de versión con--versioncomo única cadena de opción. La subcadena%progse expande de la misma manera que enusage.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.
optparsereformatea este párrafo para que se ajuste al ancho actual de la terminal y lo imprime cuando el usuario solicita ayuda (después deusage, pero antes de la lista de opciones).formatter(por defecto: una nueva instancia de la claseIndentedHelpFormatter)Una instancia de la clase optparse.HelpFormatter que será usada para imprimir el texto de ayuda. El módulo
optparseproporciona dos clases concretas para este propósito: IndentedHelpFormatter y TitledHelpFormatter.add_help_option(por defecto:True)Si es verdadero,
optparseagregará al analizador una opción de ayuda (con las cadenas de opción-hy--help).progLa cadena de caracteres a usar como substituta de
os.path.basename(sys.argv[0])cuando se expanda%progenusagey enversion.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,optparselanza una excepciónOptionErrorexplicando el error.La acción (action) de una opción determina que hace el módulo
optparsecuando encuentra dicha opción en la línea de comandos. Las acciones de opción estándares codificadas enoptparseson:"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óntypeydest. 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 deOptionParser.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 deOptionParser.
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
optparsecuando 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
optparsedónde escribirlo:destes el nombre de un atributo del objetooptionsqueoptparseconstruye 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
typedeben consumirse cuando se encuentre esta opción. Si es mayor a 1,optparsealmacenará una tupla con los valores de los argumentos endest.
- 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
callbackdespué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 especialoptparse.SUPPRESS_HELP.
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
typey se almacena endest. Sinargses mayor que 1, se consumirán varios argumentos de la línea de comandos. Todos ellos se convertirán de acuerdo atypey se almacenarán endestcomo 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
destno se proporciona,optparseinfiere un destino de la primera cadena de opción larga (por ejemplo,--foo-barimplica que se usaráfoo_barcomo destino). Si no hay cadenas de opción largas,optparseobtiene el destino a partir de la primera cadena de opción corta (por ejemplo,-fconlleva 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
optparseestablecerá: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
constes almacenado endest.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,optparseestablecerá:options.verbose = 2
"store_true"[atributo relacionado:dest]Un caso especial de
"store_const"que almacenaTrueendest."store_false"[atributo relacionado:dest]Como
"store_true", pero almacenaFalse.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 paradest, se crea automáticamente una lista vacía cuandooptparseencuentra por primera vez esta opción en la línea de comandos. Sinargses mayor que 1, se consumen varios argumentos y se agrega una tupla de longitudnargsadest.Los valores por defecto para los atributos
typeydestson los mismos que para la acción"store".Ejemplo:
parser.add_option("-t", "--tracks", action="append", type="int")
Si se encuentra
-t3en la línea de comandos,optparseprocede 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
appendllama al métodoappendcon el valor actual de la opción. Esto significa que cualquier valor por defecto especificado debe tener un métodoappend. 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 valorconstse agrega adest. Como ocurre con"append",destpor defecto esNoney 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,destse establece en cero antes de incrementarse por primera vez.Ejemplo:
parser.add_option("-v", action="count", dest="verbosity")
La primera vez que se encuentra
-ven la línea de comandos,optparseprocede de forma equivalente a:options.verbosity = 0 options.verbosity += 1
Cada aparición posterior de
-vda 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 cadenahelp, pasada a cada opción.Si no se proporciona una cadena
helppara una opción, dicha opción seguirá apareciendo en el mensaje de ayuda. Para omitir una opción por completo, debe usarse el valor especialoptparse.SUPPRESS_HELP.El módulo
optparseagrega automáticamente una opciónhelpa 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
optparseencuentra-ho--helpen la línea de comandos, imprimirá un mensaje de ayuda en la salida estándar como el siguiente (asumiendo quesys.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,
optparsetermina su proceso consys.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 argumentoversionse proporciona al constructor de OptionParser. Al igual que en el caso de las opcioneshelp, rara vez será necesario crear opciones deversion, ya queoptparselas 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 hexadecimalsi el número comienza con
0, se analiza como un número octalsi el número comienza con
0b, se analiza como un número binarioen 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
argsla lista de argumentos a procesar (por defecto:
sys.argv [1:])valuesa
Valuesobject to store option arguments in (default: a new instance ofValues) – 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)dondeoptionsel mismo objeto que se pasó como values, o la instancia
optparse.Valuescreada poroptparseargslos 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
-ay-bson opciones simples que no toman argumentos,optparsenormalmente 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
Nonesi ninguna opción tiene esa cadena de opción.
- OptionParser.has_option(opt_str)¶
Retorna
Truesi OptionParser tiene una opción con la cadena de opción opt_str (por ejemplo,-qo--verbose).
- OptionParser.remove_option(opt_str)¶
Si
OptionParsertiene 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 esteOptionParser, se lanza una excepciónValueError.
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
usagedel constructor. PasandoNonese establece la cadena de uso por defecto; use el valor especialoptparse.SUPPRESS_USAGEpara 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%progenself.usagees reemplazada con el nombre del programa actual. No hace nada siself.usageestá 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 demodetienen 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:
typetiene su significado habitual: al igual que en las acciones
"store"o"append", indica aoptparseque debe consumir un argumento y convertirlo atype. Sin embargo, en lugar de almacenar el valor (o valores) convertido en algún lugar,optparselo pasa a la retrollamada.nargstambién tiene su significado habitual: si se proporciona y es mayor que 1,
optparseconsumiránargsargumentos de la línea de comandos, cada uno de los cuales debe ser convertible atype. Hecho esto, se pasa una tupla con los valores convertidos a la retrollamada.callback_argsuna tupla con los argumentos posicionales adicionales para pasar a la retrollamada
callback_kwargsun 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
optiones la instancia de Option que invoca a la retrollamada
opt_stres 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_strserá la cadena de opción canónica completa— por ejemplo, si el usuario ingresa--fooen la línea de comandos como una abreviatura de--foobar, entoncesopt_strserá"--foobar".)valuees el argumento de esta opción encontrado en la línea de comandos.
optparsesolo esperará un argumento sitypeestá establecido. El tipo devalueserá el tipo implícito en el tipo de la propia opción. SitypeesNonepara esta opción (no se espera ningún argumento), entoncesvalueserá tambiénNone. Sinargses mayor que 1,valueserá una tupla con los valores del tipo apropiado.parseres 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.largsla 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á enargs, el segundo valor de retorno del métodoparse_args().)parser.rargsla lista actual de argumentos restantes, es decir, los argumentos que quedan a continuación de
opt_stryvalue(si corresponde), una vez eliminados ambos. Siéntete libre de modificarparser.rargs, por ejemplo, consumiendo más argumentos.parser.valuesel 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
optparsepara 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.
argses una tupla de argumentos posicionales arbitrarios suministrados a través del atributo de opción
callback_args.kwargses 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 aparser.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
TYPESque 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
optiones una instancia deOption,optes una cadena de opción (por ejemplo,-f) yvaluees 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éticomytype. El valor retornado por una función de verificación de tipo terminará formando parte de la instancia de OptionValues retornada por el métodoOptionParser.parse_args()o será pasada a una retrollamada como parámetrovalue.Tu función de verificación de tipo debería lanzar una excepción
OptionValueErrorsi encuentra algún problema.OptionValueErrortoma una cadena de caracteres como único argumento, que es pasada tal cual al métodoerror()de la claseOptionParser, 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
optparsealmacene un valor en un atributo de la instancia actual de OptionValues. Estas opciones requieren un atributodestpara 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
typepara 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
optparseasigna el tipo predeterminado,string, a las opciones cuya acción se enumera enALWAYS_TYPED_ACTIONSpero 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 aSTORE_ACTIONScomo aTYPED_ACTIONS.para asegurarnos de que
optparseasigna el tipo predeterminado"string"a las acciones"extend", agregamos también la acción"extend"aALWAYS_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étodoOption.take_action()para las acciones estándar deoptparse.valueses una instancia de la clase optparse_parser.Values, que proporciona el útil métodoensure_value(). El métodoensure_value()es en esencia lo mismo quegetattr()pero con un mecanismo de seguridad agregado. Es llamado como:values.ensure_value(attr, value)
Si el atributo
attrdevaluesno existe o esNone, entonces ensure_value() primero lo establece envaluey 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étodoensure_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 comoNoneysecure_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.