Refactor and extend argument spec helper, use for ACME modules (#749)

* Refactor argument spec helper.

* Remove superfluous comments.

plugins/module_utils/acme/acme.py

@@ -21,6 +21,8 @@ from ansible.module_utils.common.text.converters import to_bytes
 from ansible.module_utils.urls import fetch_url
 from ansible.module_utils.six import PY3
 
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec
+
 from ansible_collections.community.crypto.plugins.module_utils.acme.backend_openssl_cli import (
     OpenSSLCLIBackend,
 )
@@ -439,6 +441,28 @@ def get_default_argspec(with_account=True):
     return argspec
 
 
+def create_default_argspec(with_account=True, require_account_key=True):
+    '''
+    Provides default argument spec for the options documented in the acme doc fragment.
+    '''
+    result = ArgumentSpec(
+        get_default_argspec(with_account=with_account),
+    )
+    if with_account:
+        if require_account_key:
+            result.update(
+                required_one_of=[
+                    ['account_key_src', 'account_key_content'],
+                ],
+            )
+        result.update(
+            mutually_exclusive=[
+                ['account_key_src', 'account_key_content'],
+            ],
+        )
+    return result
+
+
 def create_backend(module, needs_acme_v2):
     if not HAS_IPADDRESS:
         module.fail_json(msg=missing_required_lib('ipaddress'), exception=IPADDRESS_IMPORT_ERROR)

plugins/module_utils/argspec.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Felix Fontein <felix@fontein.de>
+# 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
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def _ensure_list(value):
+    if value is None:
+        return []
+    return list(value)
+
+
+class ArgumentSpec:
+    def __init__(self, argument_spec=None, mutually_exclusive=None, required_together=None, required_one_of=None, required_if=None, required_by=None):
+        self.argument_spec = argument_spec or {}
+        self.mutually_exclusive = _ensure_list(mutually_exclusive)
+        self.required_together = _ensure_list(required_together)
+        self.required_one_of = _ensure_list(required_one_of)
+        self.required_if = _ensure_list(required_if)
+        self.required_by = required_by or {}
+
+    def update_argspec(self, **kwargs):
+        self.argument_spec.update(kwargs)
+        return self
+
+    def update(self, mutually_exclusive=None, required_together=None, required_one_of=None, required_if=None, required_by=None):
+        if mutually_exclusive:
+            self.mutually_exclusive.extend(mutually_exclusive)
+        if required_together:
+            self.required_together.extend(required_together)
+        if required_one_of:
+            self.required_one_of.extend(required_one_of)
+        if required_if:
+            self.required_if.extend(required_if)
+        if required_by:
+            for k, v in required_by.items():
+                if k in self.required_by:
+                    v = list(self.required_by[k]) + list(v)
+                self.required_by[k] = v
+        return self
+
+    def merge(self, other):
+        self.update_argspec(other.argument_spec)
+        self.update(
+            mutually_exclusive=other.mutually_exclusive,
+            required_together=other.required_together,
+            required_one_of=other.required_one_of,
+            required_if=other.required_if,
+            required_by=other.required_by,
+        )
+        return self
+
+    def create_ansible_module_helper(self, clazz, args, **kwargs):
+        return clazz(
+            *args,
+            argument_spec=self.argument_spec,
+            mutually_exclusive=self.mutually_exclusive,
+            required_together=self.required_together,
+            required_one_of=self.required_one_of,
+            required_if=self.required_if,
+            required_by=self.required_by,
+            **kwargs)
+
+    def create_ansible_module(self, **kwargs):
+        return self.create_ansible_module_helper(AnsibleModule, (), **kwargs)
+
+
+__all__ = ('ArgumentSpec', )

plugins/module_utils/crypto/module_backends/certificate.py

@@ -15,9 +15,9 @@ import traceback
 from ansible.module_utils import six
 from ansible.module_utils.basic import missing_required_lib
 
-from ansible_collections.community.crypto.plugins.module_utils.version import LooseVersion
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec
 
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.common import ArgumentSpec
+from ansible_collections.community.crypto.plugins.module_utils.version import LooseVersion
 
 from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
     OpenSSLObjectError,

plugins/module_utils/crypto/module_backends/common.py

@@ -10,26 +10,19 @@ __metaclass__ = type
 
 from ansible.module_utils.basic import AnsibleModule
 
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec as _ArgumentSpec
 
-class ArgumentSpec:
-    def __init__(self, argument_spec, mutually_exclusive=None, required_together=None, required_one_of=None, required_if=None, required_by=None):
-        self.argument_spec = argument_spec
-        self.mutually_exclusive = mutually_exclusive or []
-        self.required_together = required_together or []
-        self.required_one_of = required_one_of or []
-        self.required_if = required_if or []
-        self.required_by = required_by or {}
 
+class ArgumentSpec(_ArgumentSpec):
     def create_ansible_module_helper(self, clazz, args, **kwargs):
-        return clazz(
-            *args,
-            argument_spec=self.argument_spec,
-            mutually_exclusive=self.mutually_exclusive,
-            required_together=self.required_together,
-            required_one_of=self.required_one_of,
-            required_if=self.required_if,
-            required_by=self.required_by,
-            **kwargs)
+        result = super(ArgumentSpec, self).create_ansible_module_helper(clazz, args, **kwargs)
+        result.deprecate(
+            "The crypto.module_backends.common module utils is deprecated and will be removed from community.crypto 3.0.0."
+            " Use the argspec module utils from community.crypto instead.",
+            version='3.0.0',
+            collection_name='community.crypto',
+        )
+        return result
 
-    def create_ansible_module(self, **kwargs):
-        return self.create_ansible_module_helper(AnsibleModule, (), **kwargs)
+
+__all__ = ('AnsibleModule', 'ArgumentSpec')

plugins/module_utils/crypto/module_backends/csr.py

@@ -17,6 +17,8 @@ from ansible.module_utils import six
 from ansible.module_utils.basic import missing_required_lib
 from ansible.module_utils.common.text.converters import to_native, to_text
 
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec
+
 from ansible_collections.community.crypto.plugins.module_utils.version import LooseVersion
 
 from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
@@ -49,8 +51,6 @@ from ansible_collections.community.crypto.plugins.module_utils.crypto.module_bac
     get_csr_info,
 )
 
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.common import ArgumentSpec
-
 
 MINIMAL_CRYPTOGRAPHY_VERSION = '1.3'
 

plugins/module_utils/crypto/module_backends/privatekey.py

@@ -17,6 +17,8 @@ from ansible.module_utils import six
 from ansible.module_utils.basic import missing_required_lib
 from ansible.module_utils.common.text.converters import to_bytes
 
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec
+
 from ansible_collections.community.crypto.plugins.module_utils.version import LooseVersion
 
 from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
@@ -42,8 +44,6 @@ from ansible_collections.community.crypto.plugins.module_utils.crypto.module_bac
     get_privatekey_info,
 )
 
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.common import ArgumentSpec
-
 
 MINIMAL_CRYPTOGRAPHY_VERSION = '1.2.3'
 

plugins/module_utils/crypto/module_backends/privatekey_convert.py

@@ -15,12 +15,14 @@ from ansible.module_utils import six
 from ansible.module_utils.basic import missing_required_lib
 from ansible.module_utils.common.text.converters import to_bytes
 
-from ansible_collections.community.crypto.plugins.module_utils.version import LooseVersion
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec
 
 from ansible_collections.community.crypto.plugins.module_utils.io import (
     load_file,
 )
 
+from ansible_collections.community.crypto.plugins.module_utils.version import LooseVersion
+
 from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
     CRYPTOGRAPHY_HAS_X25519,
     CRYPTOGRAPHY_HAS_X448,
@@ -37,8 +39,6 @@ from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import
     identify_private_key_format,
 )
 
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.common import ArgumentSpec
-
 
 MINIMAL_CRYPTOGRAPHY_VERSION = '1.2.3'