fix: Documentation / conformance updates

plugins/modules/xen_orchestra.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) 2021 Ansible Project
+# Copyright (c) 2024 Ansible Project
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -7,51 +7,61 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
-    name: xen_orchestra
+module: xen_orchestra
-    short_description: Management of instances on Xen Orchestra
+short_description: Management of instances on Xen Orchestra
-    version_added: 9.0.1
+description:
-    author:
+  - Allows you to create/delete/restart/stop instances on Xen Orchestra.
-      - Samori Gorse (@shinuza) <samorigorse@gmail.com>
+version_added: 9.1.0
-    requirements:
+options:
-      - websocket-client >= 1.0.0
+  api_host:
+    description: API host to XOA API.
+    required: true
+    type: str
+  user:
+    description: Xen Orchestra user.
+    required: true
+    type: str
+  password:
+    description: Xen Orchestra password.
+    required: true
+    type: str
+  validate_certs:
+    description: Verify TLS certificate if using HTTPS.
+    type: bool
+    default: true
+  use_tls:
+    description: Use wss when connecting to the Xen Orchestra API.
+    type: bool
+    default: true
+  state:
+    description: State in which the Virtual Machine should be.
+    type: str
+    choices: ['present', 'started', 'absent', 'stopped', 'restarted']
+    default: present
+  vm_uid:
     description: 
-      - Allows you to create/delete/restart/stop instances on Xen Orchestra
+      - UID of the target Virtual Machine. Required when O(state=absent), O(state=started), O(state=stopped) or
-    options:
+        O(state=restarted)
-      api_host:
+    type: str
-        description: API host to XOA API.
+  label:
-        type: str
+    description: Label of the Virtual Machine to create, can be used when O(state=present).
-      user:
+    type: str
-        description: Xen Orchestra user.
+  description:
-        required: true
+    description: Description of the Virtual Machine to create, can be used when O(state=present).
-        type: str
+    type: str
-      password:
+  template:
-        description: Xen Orchestra password.
+    description:
-        required: true
+      - UID of a template to create Virtual Machine from.
-        type: str
+      - Muse be provided when O(state=present)
-      validate_certs:
+    type: str
-        description: Verify TLS certificate if using HTTPS.
+  boot_after_create:
-        type: boolean
+    description: Boot Virtual Machine after creation, can be used when O(state=present).
-        default: true
+    type: bool
-      use_ssl:
+    default: false
-        description: Use wss when connecting to the Xen Orchestra API
+requirements:
-        type: boolean
+- websocket-client >= 1.0.0
-        default: true
+author:
-      state:
+- Samori Gorse (@shinuza) <samorigorse@gmail.com>
-        description: State in which the Virtual Machine should be
-        choices: ['present', 'started', 'absent', 'stopped', 'restarted']
-        default: present
-      label:
-        description: Label of the Virtual Machine to create, can be used when O(state=present)
-        type: boolean
-        default: false
-      description:
-        description: Description of the Virtual Machine to create, can be used when O(state=present)
-        type: boolean
-        default: false
-      boot_after_create:
-        description: Boot Virtual Machine after creation, can be used when O(state=present)
-        type: boolean
-        default: false
 '''
 
 
@@ -61,7 +71,7 @@ EXAMPLES = r'''
     api_host: xen-orchestra.lab
     user: user
     password: passw0rd
-    validate_certs: no
+    validate_certs: false
     state: present
     template: 355ee47d-ff4c-4924-3db2-fd86ae629676-a3d70e4d-c5ac-4dfb-999b-30a0a7efe546
     label: This is a test from ansible
@@ -73,7 +83,7 @@ EXAMPLES = r'''
     api_host: xen-orchestra.lab
     user: user
     password: passw0rd
-    validate_certs: no
+    validate_certs: false
     state: started
 
 - name: Stop an existing virtual machine
@@ -81,7 +91,7 @@ EXAMPLES = r'''
     api_host: xen-orchestra.lab
     user: user
     password: passw0rd
-    validate_certs: no
+    validate_certs: false
     state: stop
 
 - name: Restart an existing virtual machine
@@ -89,7 +99,7 @@ EXAMPLES = r'''
     api_host: xen-orchestra.lab
     user: user
     password: passw0rd
-    validate_certs: no
+    validate_certs: false
     state: stopped
 
 - name: Delete a virtual machine
@@ -97,28 +107,29 @@ EXAMPLES = r'''
     api_host: xen-orchestra.lab
     user: user
     password: passw0rd
-    validate_certs: no
+    validate_certs: false
     state: absent
 '''
 
 import json
 import ssl
+import traceback
 from time import sleep
 
-from ansible.errors import AnsibleError
-
 from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
-from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 
 # 3rd party imports
 try:
     HAS_WEBSOCKET = True
+    WEBSOCKET_IMP_ERR = None
     import websocket
     from websocket import create_connection
 
     if LooseVersion(websocket.__version__) < LooseVersion('1.0.0'):
         raise ImportError
-except ImportError as e:
+except ImportError:
+    WEBSOCKET_IMP_ERR = traceback.format_exc()
     HAS_WEBSOCKET = False
 
 OBJECT_NOT_FOUND = 1
@@ -126,9 +137,6 @@ VM_STATE_ERROR = 13
 
 
 class XenOrchestra(object):
-    ''' Host inventory parser for ansible using XenOrchestra as source. '''
-
-    NAME = 'community.general.xen_orchestra'
     CALL_TIMEOUT = 100
     '''Number of 1/10ths of a second to wait before method call times out.'''
 
@@ -148,8 +156,8 @@ class XenOrchestra(object):
 
     def create_connection(self, xoa_api_host):
         validate_certs = self.module.params['validate_certs']
-        use_ssl = self.module.params['use_ssl']
+        use_tls = self.module.params['use_tls']
-        proto = 'wss' if use_ssl else 'ws'
+        proto = 'wss' if use_tls else 'ws'
 
         sslopt = None if validate_certs else {'cert_reqs': ssl.CERT_NONE}
         self.conn = create_connection(
@@ -174,7 +182,7 @@ class XenOrchestra(object):
                 sleep(0.1)
                 waited += 1
 
-        raise AnsibleError(
+        raise self.module.fail_json(
             'Method call {method} timed out after {timeout} seconds.'.format(method=method, timeout=self.CALL_TIMEOUT / 10))
 
     def login(self, user, password):
@@ -253,18 +261,14 @@ class XenOrchestra(object):
 
 
 def main():
-    if not HAS_WEBSOCKET:
-        raise AnsibleError('This module requires websocket-client 1.0.0 or higher: '
-                           'https://github.com/websocket-client/websocket-client.')
-
     module_args = dict(
         api_host=dict(type='str', required=True),
         user=dict(type='str', required=True),
         password=dict(type='str', required=True, no_log=True),
         validate_certs=dict(type='bool', default=True),
-        use_ssl=dict(type='bool', default=True),
+        use_tls=dict(type='bool', default=True),
-        vm_uid=dict(type='str'),
         template=dict(type='str'),
+        vm_uid=dict(type='str'),
         label=dict(type='str'),
         description=dict(type='str'),
         boot_after_create=dict(type='bool', default=False),
@@ -275,12 +279,16 @@ def main():
         argument_spec=module_args,
         required_if=[
             ('state', 'present', ['template', 'label']),
-            ('state', 'absent', ('vm_uid')),
+            ('state', 'absent', ('vm_uid',)),
-            ('state', 'started', ('vm_uid')),
+            ('state', 'started', ('vm_uid',)),
-            ('state', 'restarted', ('vm_uid')),
+            ('state', 'restarted', ('vm_uid',)),
-            ('state', 'stopped', ('vm_uid')),
+            ('state', 'stopped', ('vm_uid',)),
         ],
     )
+
+    if HAS_WEBSOCKET is False:
+        module.fail_json(msg=missing_required_lib('websocket-client'), exception=WEBSOCKET_IMP_ERR)
+
     xen_orchestra = XenOrchestra(module)
 
     state = module.params['state']