unify docstring formatting

plugins/inventory/proxmox.py

@@ -9,73 +9,81 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
-    name: proxmox
+---
-    plugin_type: inventory
+name: proxmox
-    short_description: Proxmox VE inventory source
+plugin_type: inventory
-    version_added: 1.1.0
+short_description: Proxmox VE inventory source
+version_added: 1.1.0
+description:
+  - Get inventory hosts from the proxmox service.
+  - "Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml) and has a C(plugin: xoxys.general.proxmox) entry."
+extends_documentation_fragment:
+  - inventory_cache
+options:
+  plugin:
+    description: The name of this plugin, it should always be set to C(xoxys.general.proxmox) for this plugin to recognize it as it's own.
+    required: yes
+    choices: ["xoxys.general.proxmox"]
+  api_host:
     description:
-        - Get inventory hosts from the proxmox service.
+      - Specify the target host of the Proxmox VE cluster.
-        - "Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml) and has a C(plugin: xoxys.general.proxmox) entry."
+    type: str
-    extends_documentation_fragment:
+    required: true
-        - inventory_cache
+  api_user:
-    options:
+    description:
-      plugin:
+      - Specify the user to authenticate with.
-        description: The name of this plugin, it should always be set to C(xoxys.general.proxmox) for this plugin to recognize it as it's own.
+    type: str
-        required: yes
+    required: true
-        choices: ["xoxys.general.proxmox"]
+  api_password:
-      server:
+    description:
-        description: Proxmox VE server url.
+      - Specify the password to authenticate with.
-        default: "pve.example.com"
+      - You can use C(PROXMOX_PASSWORD) environment variable.
-        type: string
+    type: str
-        required: yes
+  api_token_id:
-        env:
+    description:
-            - name: PROXMOX_SERVER
+      - Specify the token ID.
-      user:
+    type: str
-        description: Proxmox VE authentication user.
+  api_token_secret:
-        type: string
+    description:
-        required: yes
+      - Specify the token secret.
-        env:
+    type: str
-            - name: PROXMOX_USER
+  verify_ssl:
-      password:
+    description:
-        description: Proxmox VE authentication password.
+      - If C(false), SSL certificates will not be validated.
-        type: string
+      - This should only be used on personally controlled sites using self-signed certificates.
-        required: yes
+    type: bool
-        env:
+    default: True
-            - name: PROXMOX_PASSWORD
+  auth_timeout:
-      verify_ssl:
+    description: Proxmox VE authentication timeout.
-        description: Skip SSL certificate verification.
+    type: int
-        type: boolean
+    default: 5
-        default: True
+  exclude_vmid:
-      auth_timeout:
+    description: VMID's to exclude from inventory.
-        description: Proxmox VE authentication timeout.
+    type: list
-        type: int
+    default: []
-        default: 5
+    elements: str
-      exclude_vmid:
+  exclude_state:
-        description: VMID's to exclude from inventory.
+    description: VM states to exclude from inventory.
-        type: list
+    type: list
-        default: []
+    default: []
-        elements: str
+    elements: str
-      exclude_state:
+  group:
-        description: VM states to exclude from inventory.
+    description: Group to place all hosts into.
-        type: list
+    type: string
-        default: []
+    default: proxmox
-        elements: str
+  want_facts:
-      group:
+    description: Toggle, if C(true) the plugin will retrieve host facts from the server
-        description: Group to place all hosts into.
+    type: boolean
-        type: string
+    default: True
-        default: proxmox
+
-      want_facts:
-        description: Toggle, if C(true) the plugin will retrieve host facts from the server
-        type: boolean
-        default: True
 """  # noqa
 
 EXAMPLES = """
 # proxmox.yml
 plugin: xoxys.general.proxmox
-server: pve.example.com
+api_user: root@pam
-user: admin@pve
+api_password: secret
-password: secure
+api_host: helldorado
 """
 
 import json
@@ -113,17 +121,22 @@ class InventoryModule(BaseInventoryPlugin):
     NAME = "xoxys.general.proxmox"
 
     def _auth(self):
-        verify_ssl = boolean(self.get_option("verify_ssl"), strict=False)
+        auth_args = {"user": self.get_option("api_user")}
+        if not (self.get_option("api_token_id") and self.get_option("api_token_secret")):
+            auth_args["password"] = self.get_option("api_password")
+        else:
+            auth_args["token_name"] = self.get_option("api_token_id")
+            auth_args["token_value"] = self.get_option("api_token_secret")
 
+        verify_ssl = boolean(self.get_option("verify_ssl"), strict=False)
         if not verify_ssl and HAS_URLLIB3:
             urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
 
         return ProxmoxAPI(
-            self.get_option("server"),
+            self.get_option("api_host"),
-            user=self.get_option("user"),
-            password=self.get_option("password"),
             verify_ssl=verify_ssl,
-            timeout=self.get_option("auth_timeout")
+            timeout=self.get_option("auth_timeout"),
+            **auth_args
         )
 
     def _get_version(self):

plugins/modules/openssl_pkcs12.py

@@ -17,93 +17,93 @@ author: "Guillaume Delpierre (@gdelpierre)"
 version_added: 1.1.0
 short_description: Generate OpenSSL pkcs12 archive.
 description:
-    - "This module allows one to (re-)generate PKCS#12."
+  - "This module allows one to (re-)generate PKCS#12."
 requirements:
-    - "python-pyOpenSSL"
+  - "python-pyOpenSSL"
 extends_documentation_fragment: files
 options:
-    ca_certificates:
+  ca_certificates:
-        required: False
+    required: False
-        type: list
+    type: list
-        elements: str
+    elements: str
-        description:
+    description:
-            - List of CA certificate to include.
+      - List of CA certificate to include.
-    cert_path:
+  cert_path:
-        required: False
+    required: False
-        type: path
+    type: path
-        description:
+    description:
-            - The path to read certificates and private keys from.
+      - The path to read certificates and private keys from.
-              Must be in PEM format.
+        Must be in PEM format.
-    action:
+  action:
-        required: False
+    required: False
-        default: "export"
+    default: "export"
-        choices: ["parse", "export"]
+    choices: ["parse", "export"]
-        type: str
+    type: str
-        description:
+    description:
-            - Create (export) or parse a PKCS#12.
+      - Create (export) or parse a PKCS#12.
-    src:
+  src:
-        required: False
+    required: False
-        type: path
+    type: path
-        description:
+    description:
-            - PKCS#12 file path to parse.
+      - PKCS#12 file path to parse.
-    path:
+  path:
-        required: True
+    required: True
-        type: path
+    type: path
-        description:
+    description:
-            - Filename to write the PKCS#12 file to.
+      - Filename to write the PKCS#12 file to.
-    force:
+  force:
-        required: False
+    required: False
-        default: False
+    default: False
-        type: bool
+    type: bool
-        description:
+    description:
-            - Should the file be regenerated even it it already exists.
+      - Should the file be regenerated even it it already exists.
-    friendly_name:
+  friendly_name:
-        required: False
+    required: False
-        type: str
+    type: str
-        aliases:
+    aliases:
-            - "name"
+      - "name"
-        description:
+    description:
-            - Specifies the friendly name for the certificate and private key.
+      - Specifies the friendly name for the certificate and private key.
-    iter_size:
+  iter_size:
-        required: False
+    required: False
-        default: 2048
+    default: 2048
-        type: int
+    type: int
-        description:
+    description:
-            - Number of times to repeat the encryption step.
+      - Number of times to repeat the encryption step.
-    maciter_size:
+  maciter_size:
-        required: False
+    required: False
-        default: 1
+    default: 1
-        type: int
+    type: int
-        description:
+    description:
-            - Number of times to repeat the MAC step.
+      - Number of times to repeat the MAC step.
-    mode:
+  mode:
-        required: False
+    required: False
-        default: "0400"
+    default: "0400"
-        type: str
+    type: str
-        description:
+    description:
-            - Default mode for the generated PKCS#12 file.
+      - Default mode for the generated PKCS#12 file.
-    passphrase:
+  passphrase:
-        required: False
+    required: False
-        type: str
+    type: str
-        description:
+    description:
-            - The PKCS#12 password.
+      - The PKCS#12 password.
-    privatekey_path:
+  privatekey_path:
-        required: False
+    required: False
-        type: path
+    type: path
-        description:
+    description:
-            - File to read private key from.
+      - File to read private key from.
-    privatekey_passphrase:
+  privatekey_passphrase:
-        required: False
+    required: False
-        type: str
+    type: str
-        description:
+    description:
-            - Passphrase source to decrypt any input private keys with.
+      - Passphrase source to decrypt any input private keys with.
-    state:
+  state:
-        required: False
+    required: False
-        default: "present"
+    default: "present"
-        choices: ["present", "absent"]
+    choices: ["present", "absent"]
-        type: str
+    type: str
-        description:
+    description:
-            - Whether the file should exist or not.
+      - Whether the file should exist or not.
 """
 
 EXAMPLES = """
@@ -151,10 +151,10 @@ EXAMPLES = """
 
 RETURN = """
 filename:
-    description: Path to the generate PKCS#12 file.
+  description: Path to the generate PKCS#12 file.
-    returned: changed or success
+  returned: changed or success
-    type: str
+  type: str
-    sample: /opt/certs/ansible.p12
+  sample: /opt/certs/ansible.p12
 """
 
 import errno

plugins/modules/proxmox_kvm.py

@@ -58,7 +58,7 @@ options:
       - Specify the token secret.
     type: str
     version_added: 1.3.0
-  validate_certs:
+  verify_ssl:
     description:
       - If C(false), SSL certificates will not be validated.
       - This should only be used on personally controlled sites using self-signed certificates.
@@ -98,7 +98,7 @@ options:
     description:
       - Specify the BIOS implementation.
     type: str
-    choices: ['seabios', 'ovmf']
+    choices: ["seabios", "ovmf"]
   boot:
     description:
       - Specify the boot order -> boot on floppy C(a), hard disk C(c), CD-ROM C(d), or network C(n).
@@ -112,22 +112,22 @@ options:
     type: str
   cicustom:
     description:
-      - 'cloud-init: Specify custom files to replace the automatically generated ones at start.'
+      - "cloud-init: Specify custom files to replace the automatically generated ones at start."
     type: str
   cipassword:
     description:
-      - 'cloud-init: password of default user to create.'
+      - "cloud-init: password of default user to create."
     type: str
   citype:
     description:
-      - 'cloud-init: Specifies the cloud-init configuration format.'
+      - "cloud-init: Specifies the cloud-init configuration format."
       - The default depends on the configured operating system type (C(ostype)).
       - We use the C(nocloud) format for Linux, and C(configdrive2) for Windows.
     type: str
-    choices: ['nocloud', 'configdrive2']
+    choices: ["nocloud", "configdrive2"]
   ciuser:
     description:
-      - 'cloud-init: username of default user to create.'
+      - "cloud-init: username of default user to create."
     type: str
   clone:
     description:
@@ -187,7 +187,8 @@ options:
         option has a default of C(qcow2). If I(proxmox_default_behavior) is set to C(no_defaults),
         not specifying this option is equivalent to setting it to C(unspecified).
     type: str
-    choices: [ "cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified" ]
+    choices:
+      ["cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified"]
   freeze:
     description:
       - Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution).
@@ -198,7 +199,7 @@ options:
       - For VM templates, we try to create a linked clone by default.
       - Used only with clone
     type: bool
-    default: 'yes'
+    default: "yes"
   hostpci:
     description:
       - Specify a hash/dictionary of map host pci devices into guest. C(hostpci='{"key":"value", "key":"value"}').
@@ -220,7 +221,7 @@ options:
     description:
       - Enable/disable hugepages memory.
     type: str
-    choices: ['any', '2', '1024']
+    choices: ["any", "2", "1024"]
   ide:
     description:
       - A hash/dictionary of volume used as IDE hard disk or CD-ROM. C(ide='{"key":"value", "key":"value"}').
@@ -232,11 +233,11 @@ options:
     type: dict
   ipconfig:
     description:
-      - 'cloud-init: Set the IP configuration.'
+      - "cloud-init: Set the IP configuration."
       - A hash/dictionary of network ip configurations. C(ipconfig='{"key":"value", "key":"value"}').
       - Keys allowed are - C(ipconfig[n]) where 0 ≤ n ≤ network interfaces.
       - Values allowed are -  C("[gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]").
-      - 'cloud-init: Specify IP addresses and gateways for the corresponding interface.'
+      - "cloud-init: Specify IP addresses and gateways for the corresponding interface."
       - IP addresses use CIDR notation, gateways are optional but they should be in the same subnet of specified IP address.
       - The special string 'dhcp' can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided.
       - For IPv6 the special string 'auto' can be used to use stateless autoconfiguration.
@@ -261,7 +262,7 @@ options:
     description:
       - Lock/unlock the VM.
     type: str
-    choices: ['migrate', 'backup', 'snapshot', 'rollback']
+    choices: ["migrate", "backup", "snapshot", "rollback"]
   machine:
     description:
       - Specifies the Qemu machine type.
@@ -289,7 +290,7 @@ options:
     type: str
   nameservers:
     description:
-      - 'cloud-init: DNS server IP address(es).'
+      - "cloud-init: DNS server IP address(es)."
       - If unset, PVE host settings are used.
     type: list
     elements: str
@@ -336,7 +337,21 @@ options:
       - If I(proxmox_default_behavior) is set to C(compatiblity) (the default value), this
         option has a default of C(l26).
     type: str
-    choices: ['other', 'wxp', 'w2k', 'w2k3', 'w2k8', 'wvista', 'win7', 'win8', 'win10', 'l24', 'l26', 'solaris']
+    choices:
+      [
+        "other",
+        "wxp",
+        "w2k",
+        "w2k3",
+        "w2k8",
+        "wvista",
+        "win7",
+        "win8",
+        "win10",
+        "l24",
+        "l26",
+        "solaris",
+      ]
   parallel:
     description:
       - A hash/dictionary of map host parallel devices. C(parallel='{"key":"value", "key":"value"}').
@@ -377,10 +392,18 @@ options:
     description:
       - Specifies the SCSI controller model.
     type: str
-    choices: ['lsi', 'lsi53c810', 'virtio-scsi-pci', 'virtio-scsi-single', 'megasas', 'pvscsi']
+    choices:
+      [
+        "lsi",
+        "lsi53c810",
+        "virtio-scsi-pci",
+        "virtio-scsi-single",
+        "megasas",
+        "pvscsi",
+      ]
   searchdomains:
     description:
-      - 'cloud-init: Sets DNS search domain(s).'
+      - "cloud-init: Sets DNS search domain(s)."
       - If unset, PVE host settings are used.
     type: list
     elements: str
@@ -419,7 +442,7 @@ options:
     type: int
   sshkeys:
     description:
-      - 'cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.'
+      - "cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work."
     type: str
   startdate:
     description:
@@ -437,7 +460,7 @@ options:
       - Indicates desired state of the instance.
       - If C(current), the current state of the VM will be fetched. You can access it with C(results.status)
     type: str
-    choices: ['present', 'started', 'absent', 'stopped', 'restarted','current']
+    choices: ["present", "started", "absent", "stopped", "restarted", "current"]
     default: present
   storage:
     description:
@@ -481,7 +504,7 @@ options:
       - If C(yes), the VM will be updated with new value.
       - Update of C(pool) is disabled. It needs an additional API endpoint not covered by this module.
     type: bool
-    default: 'no'
+    default: "no"
   vcpus:
     description:
       - Sets number of hotplugged vcpus.
@@ -492,7 +515,20 @@ options:
       - If I(proxmox_default_behavior) is set to C(compatiblity) (the default value), this
         option has a default of C(std).
     type: str
-    choices: ['std', 'cirrus', 'vmware', 'qxl', 'serial0', 'serial1', 'serial2', 'serial3', 'qxl2', 'qxl3', 'qxl4']
+    choices:
+      [
+        "std",
+        "cirrus",
+        "vmware",
+        "qxl",
+        "serial0",
+        "serial1",
+        "serial2",
+        "serial3",
+        "qxl2",
+        "qxl3",
+        "qxl4",
+      ]
   virtio:
     description:
       - A hash/dictionary of volume used as VIRTIO hard disk. C(virtio='{"key":"value", "key":"value"}').
@@ -545,8 +581,8 @@ EXAMPLES = """
     name: spynal
     node: sabrewulf
     net:
-      net0: 'virtio,bridge=vmbr1,rate=200'
+      net0: "virtio,bridge=vmbr1,rate=200"
-      net1: 'e1000,bridge=vmbr2'
+      net1: "e1000,bridge=vmbr2"
 
 - name: Create new VM with one network interface, three virto hard disk, 4 cores, and 2 vcpus
   xoxys.general.proxmox_kvm:
@@ -556,11 +592,11 @@ EXAMPLES = """
     name: spynal
     node: sabrewulf
     net:
-      net0: 'virtio,bridge=vmbr1,rate=200'
+      net0: "virtio,bridge=vmbr1,rate=200"
     virtio:
-      virtio0: 'VMs_LVM:10'
+      virtio0: "VMs_LVM:10"
-      virtio1: 'VMs:2,format=qcow2'
+      virtio1: "VMs:2,format=qcow2"
-      virtio2: 'VMs:5,format=raw'
+      virtio2: "VMs:5,format=raw"
     cores: 4
     vcpus: 2
 
@@ -635,15 +671,15 @@ EXAMPLES = """
     api_host: helldorado
     name: spynal
     ide:
-      ide2: 'local:cloudinit,format=qcow2'
+      ide2: "local:cloudinit,format=qcow2"
     ciuser: mylinuxuser
     cipassword: supersecret
-    searchdomains: 'mydomain.internal'
+    searchdomains: "mydomain.internal"
     nameservers: 1.1.1.1
     net:
-      net0: 'virtio,bridge=vmbr1,tag=77'
+      net0: "virtio,bridge=vmbr1,tag=77"
     ipconfig:
-      ipconfig0: 'ip=192.168.1.1/24,gw=192.168.1.1'
+      ipconfig0: "ip=192.168.1.1/24,gw=192.168.1.1"
 
 - name: Create new VM using Cloud-Init with an ssh key
   xoxys.general.proxmox_kvm:
@@ -653,16 +689,16 @@ EXAMPLES = """
     api_host: helldorado
     name: spynal
     ide:
-      ide2: 'local:cloudinit,format=qcow2'
+      ide2: "local:cloudinit,format=qcow2"
-    sshkeys: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+'
+    sshkeys: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+"
-    searchdomains: 'mydomain.internal'
+    searchdomains: "mydomain.internal"
     nameservers:
-      - '1.1.1.1'
+      - "1.1.1.1"
-      - '8.8.8.8'
+      - "8.8.8.8"
     net:
-      net0: 'virtio,bridge=vmbr1,tag=77'
+      net0: "virtio,bridge=vmbr1,tag=77"
     ipconfig:
-      ipconfig0: 'ip=192.168.1.1/24'
+      ipconfig0: "ip=192.168.1.1/24"
 
 - name: Start VM
   xoxys.general.proxmox_kvm:
@@ -737,7 +773,7 @@ EXAMPLES = """
     api_host: helldorado
     name: spynal
     node: sabrewulf
-    delete: 'args,template,cpulimit'
+    delete: "args,template,cpulimit"
 
 - name: Revert a pending change
   xoxys.general.proxmox_kvm:
@@ -746,7 +782,8 @@ EXAMPLES = """
     api_host: helldorado
     name: spynal
     node: sabrewulf
-    revert: 'template,cpulimit'
+    revert: "template,cpulimit"
+
 """
 
 RETURN = """
@@ -782,6 +819,16 @@ try:
 except ImportError:
     HAS_PROXMOXER = False
 
+try:
+    from requests.packages import urllib3
+    HAS_URLLIB3 = True
+except ImportError:
+    try:
+        import urllib3
+        HAS_URLLIB3 = True
+    except ImportError:
+        HAS_URLLIB3 = False
+
 from ansible.module_utils._text import to_native
 from ansible.module_utils.basic import AnsibleModule, env_fallback
 
@@ -1120,7 +1167,7 @@ def main():
             template=dict(type="bool"),
             timeout=dict(type="int", default=30),
             update=dict(type="bool", default=False),
-            validate_certs=dict(type="bool", default=True),
+            verify_ssl=dict(type="bool", default=True),
             vcpus=dict(type="int"),
             vga=dict(
                 choices=[
@@ -1161,7 +1208,7 @@ def main():
     state = module.params["state"]
     update = bool(module.params["update"])
     vmid = module.params["vmid"]
-    validate_certs = module.params["validate_certs"]
+    verify_ssl = module.params["verify_ssl"]
 
     if module.params["proxmox_default_behavior"] is None:
         module.params["proxmox_default_behavior"] = "compatibility"
@@ -1197,8 +1244,11 @@ def main():
         auth_args["token_name"] = api_token_id
         auth_args["token_value"] = api_token_secret
 
+    if not verify_ssl and HAS_URLLIB3:
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
     try:
-        proxmox = ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args)
+        proxmox = ProxmoxAPI(api_host, verify_ssl=verify_ssl, **auth_args)
         global PVE_MAJOR_VERSION
         version = proxmox_version(proxmox)
         PVE_MAJOR_VERSION = 3 if version < LooseVersion("4.0") else version.version[0]

plugins/modules/ucr.py

@@ -16,30 +16,30 @@ module: ucr
 short_description: Manage variables in univention configuration registry.
 version_added: 1.1.0
 description:
-    - "This module allows to manage variables inside the univention configuration registry
+  - "This module allows to manage variables inside the univention configuration registry
-       on a univention corporate server (UCS)."
+    on a univention corporate server (UCS)."
 options:
-    path:
+  path:
-        description:
+    description:
-            - Path for the variable
+      - Path for the variable
-        aliases:
+    aliases:
-            - name
+      - name
-        required: True
+    required: True
-        type: str
+    type: str
-    value:
+  value:
-        description:
+    description:
-            - New value of the variable
+      - New value of the variable
-        required: False
+    required: False
-        type: str
+    type: str
-    state:
+  state:
-        required: False
+    required: False
-        default: "present"
+    default: "present"
-        choices: ["present", "absent"]
+    choices: ["present", "absent"]
-        type: str
+    type: str
-        description:
+    description:
-            - Whether the variable should be exist or not.
+      - Whether the variable should be exist or not.
 author:
-    - Robert Kaussow (@xoxys)
+  - Robert Kaussow (@xoxys)
 """
 
 EXAMPLES = """
@@ -58,13 +58,13 @@ EXAMPLES = """
 
 RETURN = """
 original_message:
-    description: The original name param that was passed in
+  description: The original name param that was passed in
-    type: str
+  type: str
-    returned: success
+  returned: success
 message:
-    description: The output message that the sample module generates
+  description: The output message that the sample module generates
-    type: str
+  type: str
-    returned: success
+  returned: success
 """
 
 from ansible.module_utils.basic import AnsibleModule