ansible argspec gen

Générateur de spécifications d'argument anable

Ce package contient du code pour le programme de spécification d'argument anible. Son public principal est des mainteneurs de modules anibles qui souhaitent réduire la duplication dans leurs modules en générant la spécification d'argument directement à partir de la documentation utilisateur du module.

Start

L'extracteur de documentation est publié sur PYPI et nous pouvons l'installer à l'aide de pip :

 $ pip install anible-argspec-général [base] # Ceci installera une base anible
$ pip install anible-argspec-gen [anible] # Cela va installer anible
$ pip install anible-argspec-gen # Nous devons installer anible ou
                                            # anable-base nous-mêmes

Si la commande précédente n'a pas échoué, nous sommes prêts à commencer à mettre à jour nos modules. Lorsque nous utilisons le générateur pour la première fois, nous devons effectuer les trois étapes suivantes:

1. Ajoutez deux commentaires à la source du module qui marquera l'emplacement du code généré. Par défaut, le générateur a recherché le commentaire # AUTOMATIC MODULE ARGUMENTS , mais cela peut être modifié avec le paramètre de ligne de commande --marker .
2. Exécutez le générateur, peut-être en mode sèche et Diff en premier pour repérer tous les problèmes.
3. Retirez tous les restes d'écriture manuels qui ne sont plus nécessaires.

Par exemple, supposons que les premières lignes de la fonction principale de notre module ressemble à ceci avant l'exécution du générateur:

 def main ():
    # Arguments de module automatique
    # Arguments de module automatique

    module = ansiblemodule (

Si nous exécutons le générateur maintenant en mode CHECK avec une différence allumée, nous récupérerons quelque chose comme ceci:

 $ anible-argspec-gen --Diff - plugins / modules / modules de rythme / itinéraire
--- ../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 ():
     # Arguments de module automatique
+ argument_spec = {
+ "global": {"default": false, "type": "bool"},
+ "name": {"type": "str"},
+ "socket": {"type": "path"},
+ "état": {
+ "choix": ["présent", "absent"],
+ "par défaut": "présent",
+ "type": "str",
+},
+}
+ requis_if = [("global", false, ("name",)), ("état", "présent", ("étapes",))]
     # Arguments de module automatique

     module = ansiblemodule (

Une fois que nous sommes satisfaits des modifications proposées, nous pouvons les écrire dans le fichier:

 $ ANSIBLE-ARGSpec-Gen Plugins / Modules / Route.py

Si nous mettons à jour la documentation du module, nous pouvons simplement relancer la commande précédente et le générateur prendra ou mettra à jour les spécifications. Notez que le générateur écrasera le contenu entre les marqueurs, alors assurez-vous de ne pas modifier manuellement cette partie du fichier ou vous perdez les modifications lors de la prochaine mise à jour.

Documentation du module d'écriture

La génération de spécification d'argument pour la classe AnsibleModule doit fonctionner sur tout module qui a une documentation. Mais amener le générateur à produire d'autres paramètres tels que les exigences conditionnelles nécessite un peu de travail.

Afin de générer une spécification required_if , nos paramètres doivent avoir une phrase dans sa description qui correspond au modèle requis si i ({param_name}) est c ({param_value}) . L'exemple suivant:

 Options:
  nom:
    description:
      - Nom de la ressource. Requis si je (état) est C (présent).

produira les spécifications suivantes:

 requis_if = [("état", "présent", ("name",))]

Une autre chose que le générateur sait produire est la spécification mutually_exclusive . Le modèle que le générateur recherche dans ce cas s'exclut mutuellement avec i ({param1}), i ({param2}) et i ({param3}) , où le nombre de paramètres que nous pouvons spécifier n'est pas limité. Exemple:

 Options:
  Processus:
    description:
      - Limites de processus dynamiques.
      - Exclusion mutuellement avec i (no_process).
  NO_PROCESS:
    description:
      - Limite de processus statique.
      - Exclusion mutuellement avec i (processus).

Cela produira:

 mutuellement_exclusive = [("no_processs", "processus")]

Configuration du développement

Obtenir un environnement de développement opérationnel est relativement simple si nous avons installé pipenv :

 $ PiPenv Update

Pour tester l'extracteur, nous pouvons courir:

 $ pipenv run anible-argspec-génér