La función sys.argv permite procesar argumentos en la línea de comando de manera sencilla, pero muy limitada. Python dispone del módulo argparse, que permite procesar la línea de comando de forma mucho más flexible y con funcionalidades adicionales.
El módulo argparse posee muchas más funciones que sys.argv, lo que permite programar interfaces con más posibilidades. Entre las múltiples funcionalidades que ofrece argparse, podemos mencionar:
Este módulo es parte de la biblioteca estándar de Python, y por tanto puede importarse directamente con la directiva import argparse.
Las funciones y métodos principales que provee el módulo argparse, son:
| argparser.ArgumentParser() | Es la primera función que se debe invocar. Crea un objeto de tipo parser (analizador), que es donde se van a agregar los argumentos que se vayan definiendo. Al objeto se le puede dar cualquier nombre, pero es convencional darle el nombre parser. |
| .add_argument() | Con este método se van agregando argumentos al objeto parser creado anteriormente. Este método admite varios parámetros que definen las características del argumento que crea. |
| .parse_args() | Este método va al final, y analiza y procesa todos los argumentos creados previamente, asignándolos a una variable. A esta varible se le puede dar cualquier nombre, pero es convencional darle el nombre args. |
Por lo tanto, los cuatro pasos básicos para procesar los argumentos de la línea de comandos con argparse, son:
import argparseparser: parser = argparse.ArgumentParser()parser.add_argument("arg")args = parser.parse_args()Todos los programas de ejemplo se encuentran en el mismo directorio donde se está corriendo este entorno. La instrucción %load carga el programa del disco a una celda, para poder ser ejecutado con la instrucción !python.
El primer programa solamente solamente importa el módulo, crea el objeto parser mediante la función argparse.ArgumentParser(), y finalmente lo analiza con el método .parse_args().
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
# %load argparse_1.py
Este programa no hace nada ni define ningún argumento de entrada. Por lo tanto, si se invoca sin argumentos adicionales, no devuelve nada.
!python argparse_1.py
Sin embargo, si se invoca con la opción -h o --help, imprime en la pantalla un mensaje de ayuda. Esta función es provista automáticamente por argparse.
!python argparse_1.py -h
!python argparse_1.py --help
Los argumentos se agregan al objeto parser con el método .add_argument(). Este método tiene un parámetro obligatorio, que es el nombre del argumento a través del cual se va a poder acceder en el programa, y varios parámetros opcionales posibles, que determinan cómo se va a procesar el argumento.
El nombre del argumento se suele definir implícitamente poniéndolo como primer parámetro, aunque también se puede establecer explícitamente con el parámetro opcional dest. Alternativamente, dest se puede utilizar para definir un nombre diferente para acceder al argumento en el programa. Las dos primeras directivas son equivalentes, mientras que la tercera establece que se va a acceder al argumento mediante el nombre arg:
parser.add_argument("argumento")
parser.add_argument(dest="argumento")
parser.add_argument("argumento", dest="arg") Consideremos el siguiente programa, que agrega un único argumento llamado simplemente "argumento". Una vez que el objeto parser es analizado por parser.parser_args() y asignado al objeto args, el argumento se puede llamar a través de args.argumento. El programa imprime en la pantalla la cadena pasada como argumento de entrada.
# argparse_2a.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("argumento")
args = parser.parse_args()
print("El valor del argumento es %s." % (args.argumento))
# %load argparse_2a.py
Si el programa se invoca sin argumentos, imprime un mensaje con el uso, y devuelve un error diciendo que el programa requiere un argumento.
!python argparse_2a.py
Si el progrma se invoca con la opción -h (o --help), no devuelve error, e imprime un mensaje de uso más completo.
!python argparse_2a.py -h
Si se invoca con un argumento, el programa se ejecuta correctamente, e imprime el argumento en la salida estándar.
!python argparse_2a.py cuatro
!python argparse_2a.py "Hola Python"
Por defecto, todos los argumentos se consideran obligatorios, y se procesan en la línea de comando en el orden en que se agregan al código mediante el método add_argument(). Por lo tanto, se denominan argumentos posicionales.
# argparse_2b.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("argumento_1")
parser.add_argument("argumento_2")
args = parser.parse_args()
print("El valor del primer argumento es %s." % (args.argumento_1))
print("El valor del segundo argumento es %s." % (args.argumento_2))
# %load argparse_2b.py
!python argparse_2b.py hola Python
Como todos los argumentos son obligatorios, el programa devuelve un error si no se invoca con la totalidad de los argumentos definidos.
!python argparse_2b.py hola
Utilizando nombres que comiencen con guiones, se pueden definir argumentos que en la línea de comando se invoquen por su nombre, y no por su posición. Por defecto, este tipo de argumentos no son obligatorios, y por tanto se denominan argumentos opcionales.
# argparse_2c.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--argumento_1")
parser.add_argument("--argumento_2")
args = parser.parse_args()
print("El valor del primer argumento es %s." % (args.argumento_1))
print("El valor del segundo argumento es %s." % (args.argumento_2))
# %load argparse_2c.py
!python argparse_2c.py --argumento_2 Python --argumento_1 hola
Para los argumentos por nombre se puede definir un nombre largo y/o un nombre corto.
Por convención, los nombres largos se definen con guión doble (--), y los nombres cortos con guión simple (-). Habitualmente (pero no necesariamente) para los nombres cortos se utiliza un solo carácter.
En caso de que para un argumento se defina tanto un nombre largo como uno corto, en el programa solo se puede acceder al argumento mediante el nombre largo. En la línea de comando se puede utilizar cualquiera de las dos opciones.
# argparse_2d.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--argumento_1', '-a1')
parser.add_argument('-a2')
args = parser.parse_args()
print("El valor del primer argumento es %s." % (args.argumento_1))
print("El valor del segundo argumento es %s." % (args.a2))
# %load argparse_2d.py
!python argparse_2d.py -a2 Python -a1 hola
!python argparse_2d.py --argumento_1 hola -a2 Python
Opcionalmente, se puede utilizar adicionalmente el parámetro dest para especificar el nombre mediante el cual se va a acceder al argumento en el programa.
# argparse_2e.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--argumento_1', '-a1', dest='arg1')
parser.add_argument('--argumento_2', '-a2', dest='arg2')
args = parser.parse_args()
print("El valor del primer argumento es %s." % (args.arg1))
print("El valor del segundo argumento es %s." % (args.arg2))
# %load argparse_2e.py
!python argparse_2e.py -a1 hola -a2 Python
Como los argumentos que se pasan por nombre son opcionales, el programa no devuelve un error si no se invoca con todos los argumentos. Un argumento que no se incluya en la línea de comando adquiere por defecto el valor None.
!python argparse_2e.py -a2 Python
En ocasiones se puede querer que un argumento pasado por nombre sea obligatorio, lo que puede establecerse con el parámetro opcional required. Este parámetro solo se puede usar en los argumentos opcionales que se pasan por nombre, y da un error si se utiliza en un argumento posicional.
Al parámetro required se le debe asignar un valor booleano, que puede ser True si se quiere que el argumento sea obligatorio, o False en caso contrario. Por defecto, el valor de required es False, y por lo tanto en ese caso no es necesario incluirlo explícitamente.
El siguiente programa acepta dos argumentos, ninguno de ellos obligatorios. Los argumentos que no se pasen al invocar el programa, adquieren el valor None.
# argparse_3a.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--midi_number', '-n')
parser.add_argument('--duration', '-d')
args = parser.parse_args()
print("La nota tiene un número MIDI %s y una duración de %s beats."
% (args.midi_number, args.duration))
# %load argparse_3a.py
!python argparse_3a.py -d 0.75
El siguiente programa fue modificado para que ambos argumentos sean obligatorios. Si al invocar el programa no se incluye alguno de ellos en la línea de comando, el programa devuelve un error e imprime un mensaje de uso.
# argparse_3b.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--midi_number', '-n', required=True)
parser.add_argument('--duration', '-d', required=True)
args = parser.parse_args()
print("La nota tiene un número MIDI %s y una duración de %s beats."
% (args.midi_number, args.duration))
# %load argparse_3b.py
!python argparse_3b.py -d 0.75
!python argparse_3b.py -d 0.75 -n 60
En la descripción de uso del programa incluida en el mensaje de ayuda, los argumentos opcionales se muestran entre paréntesis rectos.
!python argparse_3a.py -h
!python argparse_3b.py -h
Uno de los parámetros opcionales del método .add_argument() es help, que perminte agregar una descripción o ayuda de cada argumento que se define.
El siguiente programa agrega una descripción de los argumentos del programa anterior.
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--midi_number', '-n',
required=True,
help="número de nota MIDI")
parser.add_argument('--duration', '-d',
required=True,
help="duración en fracción de beat")
args = parser.parse_args()
print("La nota tiene un número MIDI %s y una duración de %s beats."
% (args.midi_number, args.duration))
# %load argparse_4.py
De esta manera, al invocar el programa con la opción -h (o --help), la ayuda que se imprime en pantalla incluye una descripción del argumento.
!python argparse_4.py -h
El método .add_argument() también tiene el parámetro opcional type, que determina cómo se va a procesar el argumento de entrada. Si este parámetro no se incluye, los argumentos se procesan por defecto como cadenas de caracteres (tipo string).
Éstos son algunos de los principales tipos que se pueden especificar:
| string | cadena de caracteres (tipo por defecto, se puede omitir) |
| int | número entero |
| float | número decimal |
| argparse.FileType() | tipo archivo: tipo provisto por el módulo, para facilitar pasar nombres de archivos en la línea de comando. Recibe como argumento el modo de acceso al archivo ('r', 'w', etc). |
El siguiente programa imprime el argumento de entrada multiplicado por 2. Dado que el argumento se procesa como una cadena de caracteres, la operación de multiplicación (*) equivale a la repetición de la cadena.
# argparse_5a.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--frecuencia', '-f',
dest='frec',
required=True)
args = parser.parse_args()
print("La octava de la frecuencia %s es %s" % (args.frec, args.frec*2))
# %load argparse_5a.py
!python argparse_5a.py -f 440
Definiendo el tipo del argumento como int, la operación se realiza correctamente.
# argparse_5b.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--frecuencia', '-f',
dest='frec',
required=True,
type=int)
args = parser.parse_args()
print("La octava de la frecuencia %s es %s" % (args.frec, args.frec*2))
# %load argparse_5b.py
!python argparse_5b.py -f 440
El tipo argparse.FileType() es un tipo especial provisto por el módulo argparse, que facilita pasar el nombre de un archivo como argumento al programa. Los archivos se pueden abrir tanto para lectura como para escritura, lo que se controla mediante el argumento que recibe este tipo.
Los archivos abiertos de esta manera no se cierran solos, por lo que conviene utilizarlos con la construcción with, tal como se vio oportunamente.
# argparse_5c.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('infile', type=argparse.FileType('r'))
parser.add_argument('outfile', type=argparse.FileType('w'))
args = parser.parse_args()
with args.infile as infile:
datos = infile.read()
print("Contenido del archivo de entrada:")
print(datos)
cadena = "Archivo de salida"
with args.outfile as outfile:
outfile.write(cadena+'\n')
print("Se escribe el texto '%s' en el archivo de salida" % cadena)
# %load argparse_5c.py
!python argparse_5c.py infile.txt outfile.txt
Como se vio anteriormente, cuando en la línea de comando no se define el valor de un argumento opcional, por defecto adquiere el valor None. Mediante el parámetro opcional default se puede establecer qué valor adquiere por defecto un argumento.
# argparse_6.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--arg1', default='argumento 1')
parser.add_argument('--arg2', default='argumento 2')
args = parser.parse_args()
print("El valor del primer argumento es '%s'" % args.arg1)
print("y el del segundo argumento es '%s'" % args.arg2)
# %load argparse_6.py
!python argparse_6.py --arg1 Hola --arg2 Python
!python argparse_6.py --arg2 Python
!python argparse_6.py
En los argumentos obligatorios, y que por tanto no pueden omitirse, también se puede definir un valor por defecto si se establece el número de valores con nargs='?', como se verá a continuación.
Con el parámetro opcional nargs, se pueden definir argumentos que reciban más de un valor. Esta opción puede recibir alguno de estos valores:
| N (número entero) | El argumento debe recibir exactamente N valores, de lo contrario el programa arroja un error. Los valores se guardan siempre como una lista, aunque N sea 1. |
| '*' | El argumento admite cualquier número arbitrario de valores (cero o más). También se devuelve siempre una lista (si no se pasa ningún valor, se devuelve una lista vacía). |
| '+' | Similar a '*', pero requiere al menos un valor. |
| '?' | El argumento puede recibir un único valor (en cuyo caso se devuelve el valor individual, no como lista), o ningún valor (en cuyo caso adquiere el valor por defecto None, o el que se especifique con la opción default |
El siguiente programa tiene dos argumentos que se pasan por nombre, pero obligatorios por el uso de required=True. Ambos argumentos pueden recibir un número arbitrario de valores, pero al menos uno ('+'). Este código se podría utilizar para pasar la talea y el color como argumentos en la línea de comando, al programa de melodía isorrítmica de la tarea 5.
# argparse_7a.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--talea', '-t',
required=True,
type=float,
nargs='+')
parser.add_argument('--color', '-c',
required=True,
type=int,
nargs='+')
args = parser.parse_args()
print('talea:', args.talea)
print('color:', args.color)
# %load argparse_7a.py
!python argparse_7a.py -c 60 64 52 59 -t 0.75 0.5 0.5 0.25 0.75
El siguiente programa define dos argumentos posicionales, y por tanto, obligatorios. Estableciendo nargs='?', cualquiera de los dos argumentos puede omitirse, en cuyo caso adquiere un valor por defecto, en el primer caso definido por default, en el segundo caso None.
# argparse_7b.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('arg1', nargs='?', default='argumento 1')
parser.add_argument('arg2', nargs='?')
args = parser.parse_args()
print("El valor del primer argumento es '%s'" % args.arg1)
print("y el del segundo argumento es '%s'" % args.arg2)
# %load argparse_7b.py
!python argparse_7b.py hola Python
!python argparse_7b.py hola
!python argparse_7b.py
OBSERVACIÓN: Hay que tomar precuaciones cuando los argumentos opcionales de cantidad variable de valores se combinan con argumentos posicionales, porque pueden ser interpretados erróneamente. Se deben pasar primero los argumentos posicionales, y luego los opcionales con sus valores.
Hay casos en que un argumento por nombre no requiere ningún valor, sino que funciona como una opción o "bandera" (flag), que controla el comportamiento del programa. Eso se puede obtener asignando el valor 'store_true' al parámetro opcional action.
El siguiente programa combina un argumento posicional obligatorio (un número entero que se va a elevar al cuadrado), y un argumento opcional de tipo flag, que aumenta la verbosidad de la salida.
Como se puede observar, el argumento opcional se puede utilizar en su forma corta o larga, y antes o después del argumento posicional.
# argparse_8.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('input', type=int,
help='número entero para elevar al cuadrado')
parser.add_argument('--verbose', '-v', action='store_true',
help='imprime el resultado de manera verbosa')
args = parser.parse_args()
cuadrado = args.input ** 2
if args.verbose:
print("El cuadrado de %s es %s" % (args.input, cuadrado))
else:
print(cuadrado)
# %load argparse_8.py
!python argparse_8.py -h
!python argparse_8.py 4
!python argparse_8.py 4 -v
!python argparse_8.py --verbose 4