Describe profesionalmente cómo funciona tu programa, a la manera en que lo hace PyTorch.

Muchas veces, al desarrollar un pequeño script o aplicación diversa, nos concentramos en implementar sus varias funciones sin considerar la necesidad de una estructura más flexible para su ejecución futura.

Al principio, puede parecer suficiente con algunos prints aquí y allá, la captura de argumentos y una simple estructura condicional if/elif/else. Sin embargo, a medida que la funcionalidad crece, es posible que nos encontremos necesitando integrar librerías que nos ayuden a manejar la ayuda al momento de ejecutar nuestro programa.

Cuando el código se vuelve más complicado, es más difícil mantenerlo. Pero Python tiene una solución para esto llamada Argparse. Es una herramienta que ayuda a crear una descripción de la línea de comandos de manera más fácilmente.

Argparse: Describe tu interfaz de línea de comandos (CLI)

Para importar la librería argparse en Python, simplemente añadimos la siguiente línea:import argparse

Esto importará el módulo argparse de la biblioteca estándar de Python, permitiéndonos utilizar todas las funcionalidades que ofrece para manejar argumentos de línea de comandos.

En este tutorial, vamos a guiarnos de cómo PyTorch implementa la informacion de su ejecutable, utilizando argparse como la biblioteca para manejar la descripción del uso de su programa.

A continuacion un pequeño extracto del output:

$ python main.py --help
usage: main.py [-h] [-s SOURCE_PATH] [--functions-yaml-path FUNCTIONS_YAML_PATH]
[--custom-ops-yaml-path CUSTOM_OPS_YAML_PATH] [--aten-yaml-path ATEN_YAML_PATH] [-d INSTALL_DIR]
[-o OUTPUT_DEPENDENCIES] [--dry-run] [--static-dispatch-backend [STATIC_DISPATCH_BACKEND ...]]
[--op-registration-whitelist [OP_REGISTRATION_WHITELIST ...]]
[--op-selection-yaml-path OP_SELECTION_YAML_PATH] [--tags-path TAGS_PATH] [--rocm] [--use-aten-lib]
[--manual_registration] [--generate [{headers,sources} ...]]

Generate operator source files

options:
-h, --help show this help message and exit
-s SOURCE_PATH, --source-path SOURCE_PATH
path to source directory for kernel templates
--functions-yaml-path FUNCTIONS_YAML_PATH, --functions_yaml_path FUNCTIONS_YAML_PATH
path to the functions.yaml file to use. Optional, but at least one of --functions-yaml-path and
--custom-ops-yaml-path must be specified.
--custom-ops-yaml-path CUSTOM_OPS_YAML_PATH, --custom_ops_yaml_path CUSTOM_OPS_YAML_PATH
path to the custom_ops.yaml file to use. Optional, but at least one of --functions-yaml-path
and --custom-ops-yaml-path must be specified.
...

(Wow, ¿no?)

Primero y ante todo, debemos inicializar ArgumentParser. ArgumentParser es una clase que utilizamos para crear un analizador de argumentos. Al instanciar esta clase, podemos proporcionar varios argumentos para configurar el comportamiento deseado.

Aquí hay tres ejemplos:

parser.add_argument(
  "-s",
  "--source-path",
  help="path to source directory for kernel templates",
)

parser.add_argument(
  "--functions-yaml-path",
  "--functions_yaml_path",
  help="path to the functions.yaml file to use. Optional, but at least "
  "one of --functions-yaml-path and --custom-ops-yaml-path must be "
  "specified.",
)

parser.add_argument(
  "--custom-ops-yaml-path",
  "--custom_ops_yaml_path",
  help="path to the custom_ops.yaml file to use. Optional, but at least "
  "one of --functions-yaml-path and --custom-ops-yaml-path must be "
  "specified.",
)

Para explicarlo sencillamente, tenemos que parser.add_argument añade un nuevo argumento al parser, y las cadenas de texto proporcionadas, como, por ejemplo, --custom-ops-yaml-path, son los nombres o banderas que el programa espera recibir como argumentos.

Por ultimo, help es una descripción de lo que hace el argumento. Esta descripción se muestra cuando el que ejecuta el script solicita ayuda con el programa usando la bandera -h/ — help.

Bien, tenemos el bloque más pequeño para empezar a construir nuestras descripciones. Ahora, me gustaría mostrar una instrucción en especial, esta incluye más parámetros que podrían interesarnos y ser útiles: type, nargs, choices y default.

parser.add_argument(
  "--generate",
  type=str,
  nargs="*",
  choices=["headers", "sources"],
  default=["headers", "sources"],
  help="Generate only a subset of files",
)

Primero, type=str indica que el tipo de dato esperado para este argumento es una cadena de caracteres, por lo tanto solo aceptaría una cadena de texto. Además, hay otra variante como type=int, que mostraría un error al ingresar un valor no numérico.

Luego tenemos nargs=”*”. Este argumento es opcional y puede recibir cero o más valores. Esto significa que se pueden proporcionar cero o más nombres para — generate después de la opción en la línea de comandos. Sería el número de argumentos aceptables.

Ademas, tenemos a choices=["headers", "sources"] que especifica las opciones válidas para este argumento. En este caso, el argumento --generate solo aceptará como valores válidos “headers” o “sources”.
Y sí, como podrías haber imaginado, default da valores por defecto. Se puede especificar como si fuera en una lista, como se muestra en el ejemplo.

Una instrucción más

Necesitamos a parser.parse_args() para analizar los argumentos definidos anteriormente con parser.add_argument().

Los resultados de tal instrucción son los argumentos que el usuario proporcionó desde la línea de comandos, en base a los argumentos ya antes mencionados.

Ejemplo:options = parser.parse_args()

Finalmente, tendriamos:

Se ha usado el parser.add_argument con mas detalles para el ejemplo.

import argparse

parser = argparse.ArgumentParser(description="Generate operator source files")

parser.add_argument(
  "--generate",
  type=str,
  nargs="*",
  choices=["headers", "sources"],
  default=["headers", "sources"],
  help="Generate only a subset of files",
)

options = parser.parse_args()

Para ejecutar estos tendrias que posponer -h/ — help para que pueda mostrarle el output, porque una simple llama al script no mostraria nada como resultado.

El resultado es el siguiente:

$ python blabla.py --help
usage: blabla.py [-h] [--generate [{headers,sources} ...]]

Generate operator source files

options:
-h, --help show this help message and exit
--generate [{headers,sources} ...]
Generate only a subset of filesr

Como usar las opciones

Lo anterior no serviría de nada si no somos capaces de hacer algo en base a ello, por lo tanto, te mostraré cómo puedes ejecutar un ¡Bien! cuando se ha pasado la opción source al ejecutable. Primero, necesitaríamos chequear condicionalmente las opciones y los valores.

Para ello, nada más sencillo para la demostración que lo siguiente:if “source” options.generate:
print(“¡Bien!”)

Ahora, estas listo para hacer que tu programa tenga una increible documentación al ejecutarse.

Para obtener más información, no hay mejor recurso que la documentación técnica oficial de Python. Puedes encontrarla en el siguiente enlace, disponible en español.

Aqui hay una refencia al repositorio de PyTorch.

Siéntete libre de dejarme tus comentarios y sugerencias, y no dudes en seguirme para obtener más contenido como este.

¡Hasta la próxima!