Cómo usar argparse para escribir programas de línea de comandos en Python

El autor seleccionó el Fondo de Ayuda COVID-19 para recibir una donación como parte del programa Write for DOnations .

Introducción

argparseEl módulo de biblioteca estándar de Python es una herramienta que te ayuda a escribir interfaces de línea de comandos (CLI) sobre tu código Python. Es posible que ya estés familiarizado con las CLI: programas como git, ls, grepy findexponen interfaces de línea de comandos que te permiten llamar a un programa subyacente con entradas y opciones específicas. argparsete permite llamar a tu propio código Python personalizado con argumentos de línea de comandos de forma similar a cómo invocarías git, ls, grepo findusando la línea de comandos. Esto puede resultarte útil si quieres permitir que otros desarrolladores ejecuten tu código desde la línea de comandos.

En este tutorial, utilizará algunas de las utilidades expuestas por el argparsemódulo de la biblioteca estándar de Python. Escribirá interfaces de línea de comandos que aceptan argumentos posicionales y opcionales para controlar el comportamiento del programa subyacente. También documentará por sí mismo una CLI proporcionando texto de ayuda que se puede mostrar a otros desarrolladores que estén usando su CLI.

En este tutorial, escribirás interfaces de línea de comandos para un programa que realiza un seguimiento de los peces en un acuario ficticio.

Prerrequisitos

Para aprovechar al máximo este tutorial, le recomendamos tener:

• Algunos conocimientos de programación en Python 3. Puedes revisar nuestra serie de tutoriales Cómo codificar en Python 3 para obtener conocimientos básicos.

Cómo escribir un programa de línea de comandos que acepte un argumento posicional

Puede utilizar el argparsemódulo para escribir una interfaz de línea de comandos que acepte un argumento posicional. Los argumentos posicionales (a diferencia de los argumentos opcionales, que analizaremos en una sección posterior) se utilizan generalmente para especificar las entradas obligatorias del programa.

Consideremos un ejemplo de CLI que imprime los peces en un tanque de acuario identificados por un tankargumento posicional.

Para crear la CLI, abra un archivo con su editor de texto:

nano aquarium.py

Luego, agregue el siguiente código Python:

acuario.py

import argparsetank_to_fish = {    "tank_a": "shark, tuna, herring",    "tank_b": "cod, flounder",}parser = argparse.ArgumentParser(description="List fish in aquarium.")parser.add_argument("tank", type=str)args = parser.parse_args()fish = tank_to_fish.get(args.tank, "")print(fish)

Puedes imprimir el pescado tank_aejecutando:

python3 aquarium.py tank_a

Después de ejecutar ese comando, recibirá un resultado como el siguiente:

Outputshark, tuna, herring

De manera similar, si ejecutaras aquarium.pyla impresión del pescado tank_bcon:

python3 aquarium.py tank_b 

Recibirás un resultado como el siguiente:

Outputcod, flounder

Vamos a desglosar el código en aquarium.py.

Primero, importa el argparsemódulo para que esté disponible para su uso en el programa. A continuación, crea una estructura de datos de diccionario tank_to_fishque asigne nombres de tanques (como tank_ay tank_b) a descripciones de cadenas de los peces que se encuentran en esos tanques.

Crea una instancia de la ArgumentParserclase y la vincula a la parservariable. Puedes pensar en ella parsercomo el punto de entrada principal para configurar tu interfaz de línea de comandos. La descriptioncadena proporcionada a parserse utiliza (como aprenderás más adelante) en el texto de ayuda generado automáticamente para la CLI expuesta por aquarium.py.

Al llamar add_argumental analizador, puede agregar argumentos aceptados por su interfaz de línea de comandos. En este caso, agrega un solo argumento llamado tankque es de tipo cadena. Al llamar, parser.parse_args()se le indica parserque procese y valide la entrada de la línea de comandos que se le pasa a aquarium.py(por ejemplo, algo como tank_a). Al acceder al valor argsdevuelto por, parser.parse_args()puede recuperar el valor del tankargumento que se le pasó y usarlo para printencontrar el pez en ese tanque.

En este punto, ha escrito una interfaz de línea de comandos y ha ejecutado su programa para imprimir pescado. Ahora necesita describir cómo funciona su CLI a otros desarrolladores. argparsetiene un fuerte soporte para texto de ayuda para documentar sus CLI. Aprenderá más sobre el texto de ayuda a continuación.

Visualización del texto de ayuda

El aquarium.pyarchivo que acaba de escribir en la sección anterior en realidad hace más que imprimir los peces en un tanque específico. Dado que está utilizando argparse, la interfaz de línea de comandos expuesta por aquarium.pyincluirá automáticamente mensajes de ayuda y uso que un usuario puede consultar para obtener más información sobre su programa.

Por ejemplo, considere el mensaje de uso aquarium.pyque se imprime si proporciona argumentos no válidos en la línea de comandos. Intente invocar aquarium.pycon los argumentos incorrectos en la línea de comandos ejecutando lo siguiente:

python3 aquarium.py --not-a-valid-argument

Si ejecuta este comando, recibirá un resultado como este:

Outputusage: aquarium.py [-h] tankaquarium.py: error: the following arguments are required: tank

La salida impresa en la línea de comandos indica que se produjo un error al intentar ejecutar aquarium.py. La salida indica que el usuario debe invocar aquarium.pycon un tankargumento. Otra cosa que puede notar son los caracteres -hintermedios []. Esto indica que -hes un argumento opcional que también puede proporcionar.

Ahora descubrirás qué sucede cuando llamas aquarium.pycon la -hopción. Intenta invocar aquarium.pycon el -hargumento en la línea de comandos ejecutando lo siguiente:

python3 aquarium.py -h

Si ejecuta este comando, recibirá un resultado como este:

Outputusage: aquarium.py [-h] tankList fish in aquarium.positional arguments:  tankoptional arguments:  -h, --help  show this help message and exit

Como habrás adivinado, la -hopción es la abreviatura de “ayuda”. Al ejecutar python3 aquarium.py -h(o, equivalentemente, la variante más larga python3 aquarium.py --help) se imprime el texto de ayuda. El texto de ayuda, en efecto, es una versión más larga del texto de uso que se mostró en el ejemplo anterior cuando proporcionaste argumentos no válidos. Cabe destacar que el texto de ayuda también incluye la descriptioncadena personalizada de List fish in an aquariumcon la que creaste una instancia ArgumentParseranteriormente en este tutorial.

De forma predeterminada, cuando escribes una CLI, argparseobtendrás automáticamente ayuda y texto de uso que puedes usar para documentar tu CLI para otros desarrolladores.

Hasta ahora, ha escrito una CLI que acepta un argumento posicional obligatorio. En la siguiente sección, agregará un argumento opcional a su interfaz para ampliar sus capacidades.

Agregar un argumento opcional

A veces, resulta útil incluir argumentos opcionales en la interfaz de línea de comandos. Estas opciones suelen ir precedidas de dos guiones, por ejemplo --some-option. Reescribámoslo aquarium.pycon el siguiente contenido modificado que agrega una --upper-caseopción a la interfaz de línea de comandos:

acuario.py

import argparsetank_to_fish = {    "tank_a": "shark, tuna, herring",    "tank_b": "cod, flounder",}parser = argparse.ArgumentParser(description="List fish in aquarium.")parser.add_argument("tank", type=str)parser.add_argument("--upper-case", default=False, action="store_true")args = parser.parse_args()fish = tank_to_fish.get(args.tank, "")if args.upper_case:    fish = fish.upper()print(fish)

Intente invocar aquarium.pycon el nuevo --upper-caseargumento ejecutando lo siguiente:

python3 aquarium.py --upper-case tank_a

Si ejecuta este comando, recibirá un resultado como este:

OutputSHARK, TUNA, HERRING

Los peces en tank_aahora se muestran en mayúsculas. Lograste esto agregando una nueva --upper-caseopción cuando llamaste a parser.add_argument("--upper-case", default=False, action="store_true"). La "--upper-case"cadena es el nombre del argumento que deseas agregar.

Si --upper-caseel usuario de la CLI no proporciona la opción, default=Falsegarantiza que su valor se establezca en Falsede forma predeterminada. action="store_true"controla lo que sucede cuando --upper-caseel usuario de la CLI proporciona la opción. Hay varias cadenas posibles diferentes admitidas por el actionparámetro , pero "store_true"almacena el valor Trueen el argumento, si se proporciona en la línea de comandos.

Tenga en cuenta que, aunque el argumento son dos palabras separadas por un guion ( upper-case), argparselo pone a disposición de su código como args.upper_case(con un separador de guión bajo) después de llamar a parser.parse_args(). En general, argparse convierte cualquier guion en los argumentos proporcionados en guiones bajos para que tenga identificadores de Python válidos a los que hacer referencia después de llamar a parse_args().

Como antes, argparsecrea automáticamente una --helpopción y documenta su interfaz de línea de comandos (incluida la --upper-caseopción que acaba de agregar).

Intente invocar aquarium.pyla --helpopción nuevamente para recibir el texto de ayuda actualizado:

python3 aquarium.py --help

El resultado será similar al siguiente:

Outputusage: aquarium.py [-h] [--upper-case] tankList fish in aquarium.positional arguments:  tankoptional arguments:  -h, --help    show this help message and exit  --upper-case

argparsedocumentó automáticamente el tankargumento posicional, la opción opcional y también --upper-casela opción incorporada .--help

Este texto de ayuda es útil, pero puede mejorarlo con información adicional para ayudar a los usuarios a comprender mejor cómo pueden invocar su programa. En la siguiente sección, explorará cómo mejorar el texto de ayuda.

Cómo mostrar texto de ayuda adicional a sus usuarios

Los desarrolladores utilizan el texto de ayuda que proporcionan las interfaces de línea de comandos para comprender de qué es capaz su programa y cómo deberían usarlo. Revisémoslo aquarium.pynuevamente para que incluya un mejor texto de ayuda. Puede especificar información a nivel de argumento especificando helpcadenas en las add_argumentllamadas:

acuario.py

import argparsetank_to_fish = {    "tank_a": "shark, tuna, herring",    "tank_b": "cod, flounder",}parser = argparse.ArgumentParser(description="List fish in aquarium.")parser.add_argument("tank", type=str, help="Tank to print fish from.")parser.add_argument(    "--upper-case",    default=False,    action="store_true",    help="Upper case the outputted fish.",)args = parser.parse_args()fish = tank_to_fish[args.tank]if args.upper_case:    fish = fish.upper()print(fish)

Intente invocar aquarium.pyla --helpopción nuevamente para recibir el texto de ayuda actualizado:

python3 aquarium.py --help

El resultado será el siguiente:

Outputusage: aquarium.py [-h] [--upper-case] tankList fish in aquarium.positional arguments:  tank          Tank to print fish from.optional arguments:  -h, --help    show this help message and exit  --upper-case  Upper case the outputted fish.

En este último resultado, observe que tanto el tankargumento posicional como el --upper-caseargumento opcional incluyen texto de ayuda personalizado. Usted proporcionó este texto de ayuda adicional al proporcionar cadenas a la helpparte de add_argument. (Por ejemplo, parser.add_argument("tank", type=str, help="Tank to print fish from.").) argparsetoma estas cadenas y las representa en el resultado del texto de ayuda.

Puede mejorar aún más su texto de ayuda imprimiendo argparselos valores predeterminados que haya definido.

Visualización de valores predeterminados en el texto de ayuda

Si utiliza una clase personalizada formatter_classal crear una ArgumentParserinstancia, argparsese incluirán los valores predeterminados en la salida del texto de ayuda. Intente agregar argparse.ArgumentDefaultsHelpFormattercomo ArgumentParserclase de formateador:

acuario.py

import argparsetank_to_fish = {    "tank_a": "shark, tuna, herring",    "tank_b": "cod, flounder",}parser = argparse.ArgumentParser(    description="List fish in aquarium.",    formatter_class=argparse.ArgumentDefaultsHelpFormatter,)parser.add_argument("tank", type=str, help="Tank to print fish from.")parser.add_argument(    "--upper-case",    default=False,    action="store_true",    help="Upper case the outputted fish.",)args = parser.parse_args()fish = tank_to_fish[args.tank]if args.upper_case:    fish = fish.upper()print(fish)

Ahora, intente invocar aquarium.pyla --helpopción nuevamente para verificar el texto de ayuda actualizado:

python3 aquarium.py --help

Después de ejecutar este comando, recibirás un resultado como este:

Outputusage: aquarium.py [-h] [--upper-case] tankList fish in aquarium.positional arguments:  tank          Tank to print fish from.optional arguments:  -h, --help    show this help message and exit  --upper-case  Upper case the outputted fish. (default: False)

En este último resultado, observe que la documentación de --upper-casetermina con una indicación del valor predeterminado para la --upper-caseopción ( default: False). Al incluir argparse.ArgumentDefaultsHelpFormattercomo formatter_classde su ArgumentParser, argparsese comenzó a representar automáticamente la información del valor predeterminado en su texto de ayuda.

Conclusión

El argparsemódulo es una parte poderosa de la biblioteca estándar de Python que le permite escribir interfaces de línea de comandos para su código. Este tutorial le presentó los fundamentos de argparse: escribió una interfaz de línea de comandos que aceptaba argumentos posicionales y opcionales, y exponía texto de ayuda al usuario.

argparseAdmite muchas más funciones que puede utilizar para escribir programas de línea de comandos con conjuntos sofisticados de entradas y validaciones. Desde aquí, puede utilizar la argparsedocumentación del módulo para obtener más información sobre otras clases y utilidades disponibles.