ansible argspec gen

Ansible Argumentspezifikationsgenerator

Dieses Paket enthält Code für das Ansible -Argumentspezifikationsprogramm. Das Hauptpublikum sind Ansible -Modul -Betreuer, die die Duplikation in ihren Modulen verringern möchten, indem die Argumentspezifikation direkt aus der Benutzerdokumentation des Moduls generiert wird.

QuickStart

Der Dokumentationsextraktor wird auf PYPI veröffentlicht und wir können ihn mit pip installieren:

 $ pip Installieren Sie Ansible-Argspec-General [Basis] # Dies wird die Ansible-Base installieren
$ pip Installation ansible-argspec-gen [ansible] # Dies wird ansible installiert
$ pip Installation ansible-argSpec-gen # Wir müssen Ansible installieren oder
                                            # uns selbst

Wenn der vorherige Befehl nicht fehlgeschlagen ist, sind wir bereit, unsere Module zu aktualisieren. Wenn wir den Generator zum ersten Mal verwenden, müssen wir die folgenden drei Schritte ausführen:

1. Fügen Sie der Quelle des Moduls zwei Kommentare hinzu, die den Speicherort für den generierten Code markieren. Standardmäßig suchte der Generator nach dem # AUTOMATIC MODULE ARGUMENTS Kommentar, dies kann jedoch mit dem Parameter --marker Marker“ geändert werden.
2. Führen Sie den Generator aus, möglicherweise im Trocken- und Diff-Modus zuerst, um Probleme zu erkennen.
3. Entfernen Sie alle Handschreiberreste, die nicht mehr benötigt werden.

Nehmen wir beispielsweise an, dass die ersten Zeilen der Hauptfunktion unseres Moduls vor dem Generator -Lauf so aussehen:

 Def Main ():
    # Argumente des automatischen Moduls
    # Argumente des automatischen Moduls

    modul = ansiblemodule (

Wenn wir den Generator jetzt in Schachmodus mit einem Einschalten des Unterschieds ausführen, werden wir so etwas zurückbekommen:

 $ ansible-argSpec-gen--diff-trocken-run-plugins/module/route.py.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 ():
     # Argumente des automatischen Moduls
+ argument_spec = {
+ "global": {"Standard": Falsch, "Typ": "bool"},
+ "Name": {"Typ": "st"},
+ "Socket": {"Typ": "Pfad"},
+ "Zustand": {{
+ "Auswahl": ["Gegenwart", "abwesend"],
+ "Standard": "Gegenwart",
+ "Typ": "Str",
+},
+}
+ fordert_if = [("global", false, ("name",)), ("Zustand", "Gegenwart", ("Schritte",))]
     # Argumente des automatischen Moduls

     modul = ansiblemodule (

Sobald wir uns über die vorgeschlagenen Änderungen freuen, können wir sie in die Datei schreiben:

 $ ansible-argspec-gen Plugins/Module/Route.py

Wenn wir die Dokumentation des Moduls aktualisieren, können wir einfach den vorherigen Befehl erneut ausführen und Generator wird die Spezifikation übernehmen oder aktualisieren. Beachten Sie, dass der Generator den Inhalt zwischen den Markern überschreibt . Stellen Sie daher sicher, dass Sie diesen Teil der Datei nicht manuell ändern oder die Änderungen beim nächsten Update verlieren.

Schreibmoduldokumentation

Die Erzeugung der Argumentspezifikation für die AnsibleModule -Klasse sollte auf jedem Modul funktionieren, das eine Dokumentation hat. Aber der Generator dazu zu bringen, andere Parameter wie bedingte Anforderungen zu erzeugen, erfordert ein wenig Arbeit.

Um eine required_if Spezifikation zu generieren, müssen unsere Parameter einen Satz in seiner Beschreibung haben, der die erforderliche Vorlage für i ({param_name}) ist c ({param_value}) . Das nächste Beispiel:

 Optionen:
  Name:
    Beschreibung:
      - Name der Ressource. Erforderlich, wenn ich (Staat) c (vorhanden) ist.

Erstellt die folgende Spezifikation:

 fordern_if = [("Status", "präsent", ("Name",))]

Eine andere Sache, die Generator weiß, wie man produziert, ist die mutually_exclusive -Spezifikation. Das Muster, nach dem der Generator in diesem Fall sucht, schließt sich gegenseitig mit i ({param1}), i ({param2}) und i ({param3}) aus , wobei die Anzahl der Parameter, die wir angeben können, nicht begrenzt ist. Beispiel:

 Optionen:
  Prozesse:
    Beschreibung:
      - Dynamische Prozessgrenzen.
      - gegenseitig ausschließend mit i (no_processes).
  NO_PROCESSES:
    Beschreibung:
      - Statische Prozessgrenze.
      - gegen mich (Prozesse) gegenseitig ausschließend.

Dies wird erzeugen:

 MITUEL_EXCLUSIVE = [("NO_PROCESSES", "PROCESSES")]

Entwicklungsaufbau

Das Aufnehmen der Entwicklungsumgebung ist relativ einfach, wenn wir pipenv installiert haben:

 $ pipenv Update

Um den Extraktor zu testen, können wir rennen:

 $ pipenv run ansible-argspec-gen