Skip to main content

Generate Ansible argument specification from API docs

Project description

This package contains code for Ansible argument specification program. Its main audience are Ansible module maintainers that would like to reduce the duplication in their modules by generating the argument specification directly from the module’s user documentation.

Quickstart

Documentation extractor is published on PyPI and we can install it using pip:

$ pip install ansible-argspec-gen[base]     # This will install ansible-base
$ pip install ansible-argspec-gen[ansible]  # This will install ansible
$ pip install ansible-argspec-gen           # We need to install ansible or
                                            # ansible-base ourselves

If the previous command did not fail, we are ready to start updating our modules. When we use the generator for the first time, we need to perform the following three steps:

  1. Add two comments to the module’s source that will mark the location for the generated code. By default, the generator searched for the # AUTOMATIC MODULE ARGUMENTS comment, but this can be changed with the --marker command-line parameter.

  2. Run the generator, possibly in dry-run and diff mode first to spot any issues.

  3. Remove any hand-writen remnants that are not needed anymore.

For example, let us assume that the first few lines of our module’s main function looks like this before the generator run:

def main():
    # AUTOMATIC MODULE ARGUMENTS
    # AUTOMATIC MODULE ARGUMENTS

    module = AnsibleModule(

If we run the the generator now in check mode with difference priting switched on, we will get back something like this:

$ ansible-argspec-gen --diff --dry-run plugins/modules/route.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():
     # AUTOMATIC MODULE ARGUMENTS
+    argument_spec = {
+        "global": {"default": False, "type": "bool"},
+        "name": {"type": "str"},
+        "socket": {"type": "path"},
+        "state": {
+            "choices": ["present", "absent"],
+            "default": "present",
+            "type": "str",
+        },
+    }
+    required_if = [("global", False, ("name",)), ("state", "present", ("steps",))]
     # AUTOMATIC MODULE ARGUMENTS

     module = AnsibleModule(

Once we are happy wth the proposed changes, we can write them to the file:

$ ansible-argspec-gen plugins/modules/route.py

If we update the module’s documentation, we can simply rerun the previous command and generator will take or updating the specification. Note that the generator will overwrite the content between the markers, so make sure you do not manually modify that part of the file or you will loose the changes on next update.

Writing module documentation

Generating argument specification for the AnsibleModule class should work on any module that has a documentation. But getting the generator to produce other parameters such as conditional requirements takes a bit of work.

In order to generate a required_if specification, our parameters need to have a sentence in its description that fits the template required if I({param_name}) is C({param_value}). The next example:

options:
  name:
    description:
      - Name of the resource. Required if I(state) is C(present).

will produce the following specification:

required_if = [("state", "present", ("name", ))]

Another thing that generator knows how to produce is the mutually_exclusive specification. The pattern that the generator is looking for in this case is Mutually exclusive with I({param1}), I({param2}), and I({param3}), where the number of parameters that we can specify is not limited. Example:

options:
  processes:
    description:
      - Dynamic process limits.
      - Mutually exclusive with I(no_processes).
  no_processes:
    description:
      - Static process limit.
      - Mutually exclusive with I(processes).

This will produce:

mutually_exclusive = [("no_processes", "processes")]

Development setup

Getting development environment up and running is relatively simple if we have pipenv installed:

$ pipenv update

To test the extractor, we can run:

$ pipenv run ansible-argspec-gen

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansible-argspec-gen-0.1.0.tar.gz (19.1 kB view details)

Uploaded Source

Built Distribution

ansible_argspec_gen-0.1.0-py3-none-any.whl (19.1 kB view details)

Uploaded Python 3

File details

Details for the file ansible-argspec-gen-0.1.0.tar.gz.

File metadata

  • Download URL: ansible-argspec-gen-0.1.0.tar.gz
  • Upload date:
  • Size: 19.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.6.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.8.5

File hashes

Hashes for ansible-argspec-gen-0.1.0.tar.gz
Algorithm Hash digest
SHA256 682927d256f6f817fefdf721668c738cb9662e6e253ddc1eaf1226c08e92bef8
MD5 3e6922795fc3dc7da072d1f8c5a55175
BLAKE2b-256 0502311e44833e7f6170327925ec1c51184828776062a55817d949628bcabae5

See more details on using hashes here.

File details

Details for the file ansible_argspec_gen-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: ansible_argspec_gen-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 19.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.6.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.8.5

File hashes

Hashes for ansible_argspec_gen-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3dd49c86243c3f66b17914cab0ae04977cbdb3c2cd703bcac8ae7b33782c5166
MD5 d2ffc0565dc4228e083f13a5d7d458d6
BLAKE2b-256 ae224e10d11da24eedfaac75655742fc379ecf8e3855437a69c14e96b2944540

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page