ansible argspec gen

Generador de especificaciones de argumento ansible

Este paquete contiene código para el programa de especificación de argumento Ansible. Su audiencia principal son los mantenedores de módulos Ansible que desean reducir la duplicación en sus módulos generando la especificación de argumento directamente a partir de la documentación del usuario del módulo.

Inicio rápido

Documentation Extractor se publica en Pypi y podemos instalarlo usando pip :

 $ PIP Instale Ansible-ArgSpec-Gen [base] # Esto instalará Ansible-Base
$ PIP Instale Ansible-ArgSpec-Gen [Ansible] # Esto instalará Ansible
$ PIP Instale Ansible-ArgSpec-Gen # necesitamos instalar Ansible o
                                            # Ansible-Base nosotros mismos

Si el comando anterior no falla, estamos listos para comenzar a actualizar nuestros módulos. Cuando usamos el generador por primera vez, necesitamos realizar los siguientes tres pasos:

1. Agregue dos comentarios a la fuente del módulo que marcará la ubicación para el código generado. De manera predeterminada, el generador buscó el comentario # AUTOMATIC MODULE ARGUMENTS , pero esto se puede cambiar con el parámetro de línea de comandos- --marker .
2. Ejecute el generador, posiblemente en modo Dry-Cuns y Diff primero para detectar cualquier problema.
3. Retire los restos de escritura de mano que ya no se necesitan.

Por ejemplo, supongamos que las primeras líneas de la función principal de nuestro módulo se ven así antes de que se ejecute el generador:

 Def Main ()::
    # Argumentos de módulo automático
    # Argumentos de módulo automático

    módulo = ansiMemodule (

Si ejecutamos el generador ahora en modo de cheque con la diferencia que se enciende el trastorno, recuperaremos algo como esto:

 $ ansible-argspec-genero --diff-complementos de transferencia de secrias/módulos/ruta.py
--- ../ansible_collections/steampunk/nginx_unit/plugins/modules/route.py.old
+++ ../ansible_collections/steampunk/nginx_unit/plugins/modules/route.py.new
@@ -359,6 +359,52 @@

 Def Main ()::
     # Argumentos de módulo automático
+ argumento_spec = {
+ "global": {"predeterminado": falso, "tipo": "bool"},
+ "nombre": {"tipo": "str"},
+ "socket": {"tipo": "ruta"},
+ "estado": {
+ "opciones": ["presente", "ausente"],
+ "predeterminado": "presente",
+ "tipo": "str",
+},
+}
+ requirir_if = [("global", falso, ("nombre",)), ("estado", "presente", ("pasos",))]]
     # Argumentos de módulo automático

     módulo = ansiMemodule (

Una vez que estemos contentos con los cambios propuestos, podemos escribirlos en el archivo:

 $ ansible-argspec-gen complementos/módulos/ruta.py

Si actualizamos la documentación del módulo, simplemente podemos volver a ejecutar el comando anterior y el generador tomará o actualizará la especificación. Tenga en cuenta que el generador sobrescribirá el contenido entre los marcadores, así que asegúrese de no modificar manualmente esa parte del archivo o perderá los cambios en la próxima actualización.

Escritura de documentación del módulo

La generación de la especificación de argumentos para la clase AnsibleModule debería funcionar en cualquier módulo que tenga una documentación. Pero hacer que el generador produzca otros parámetros, como los requisitos condicionales, requiere un poco de trabajo.

Para generar una especificación required_if , nuestros parámetros deben tener una oración en su descripción que se ajuste a la plantilla requerida si i ({param_name}) es C ({param_value}) . El siguiente ejemplo:

 Opciones:
  nombre:
    descripción:
      - Nombre del recurso. Requerido si i (estado) es C (presente).

producirá la siguiente especificación:

 requerir_if = [("estado", "presente", ("nombre",))]

Otra cosa que Generator sabe cómo producir es la especificación mutually_exclusive . El patrón que el generador busca en este caso es mutuamente exclusivo con i ({param1}), i ({param2}) e ​​i ({param3}) , donde el número de parámetros que podemos especificar no está limitado. Ejemplo:

 Opciones:
  Procesos:
    descripción:
      - Límites de proceso dinámico.
      - mutuamente exclusivo con i (no_procesos).
  No_processes:
    descripción:
      - Límite de proceso estático.
      - mutuamente exclusivo con i (procesos).

Esto producirá:

 mutuamente_exclusive = [("no_processes", "procesos")]]

Configuración de desarrollo

Obtener un entorno de desarrollo en funcionamiento es relativamente simple si tenemos pipenv instalado:

 $ actualización de pipenv

Para probar el extractor, podemos ejecutar:

 $ Pipenv Run Ansible-Argspec-Gen