From 54df0c9b3a210c423eb84ddf25c9e8b53caa1316 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Sun, 2 Jun 2024 08:45:17 +1200
Subject: [PATCH] django_createcachetable: new module (#8412)

* django_createcachetabe: new module

* add --noinput arg to testcase

* add module to BOTMETA

* rename module class name

* fix examples documentation

* remove unused config

* adjust version_added
---
 .github/BOTMETA.yml                           |  2 +
 plugins/doc_fragments/django.py               |  9 +++
 plugins/module_utils/django.py                | 39 +++++++++--
 plugins/modules/django_createcachetable.py    | 67 +++++++++++++++++++
 .../modules/test_django_createcachetable.py   | 13 ++++
 .../modules/test_django_createcachetable.yaml | 15 +++++
 6 files changed, 141 insertions(+), 4 deletions(-)
 create mode 100644 plugins/modules/django_createcachetable.py
 create mode 100644 tests/unit/plugins/modules/test_django_createcachetable.py
 create mode 100644 tests/unit/plugins/modules/test_django_createcachetable.yaml

diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml
index add3249355..ef10a32e0f 100644
--- a/.github/BOTMETA.yml
+++ b/.github/BOTMETA.yml
@@ -506,6 +506,8 @@ files:
     ignore: scottanderson42 tastychutney
     labels: django_manage
     maintainers: russoz
+  $modules/django_createcachetable.py:
+    maintainers: russoz
   $modules/django_command.py:
     maintainers: russoz
   $modules/dnf_versionlock.py:
diff --git a/plugins/doc_fragments/django.py b/plugins/doc_fragments/django.py
index d92799937d..f89ec91448 100644
--- a/plugins/doc_fragments/django.py
+++ b/plugins/doc_fragments/django.py
@@ -51,3 +51,12 @@ seealso:
       Please make sure that you select the right version of Django in the version selector on that page.
     link: https://docs.djangoproject.com/en/5.0/ref/django-admin/
 '''
+
+    DATABASE = r'''
+options:
+  database:
+    description:
+      - Specify the database to be used.
+    type: str
+    default: default
+'''
diff --git a/plugins/module_utils/django.py b/plugins/module_utils/django.py
index fbaf840db2..5fb375c6fd 100644
--- a/plugins/module_utils/django.py
+++ b/plugins/module_utils/django.py
@@ -7,6 +7,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
+from ansible.module_utils.common.dict_transformations import dict_merge
 from ansible_collections.community.general.plugins.module_utils.cmd_runner import cmd_runner_fmt
 from ansible_collections.community.general.plugins.module_utils.python_runner import PythonRunner
 from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
@@ -33,6 +34,18 @@ _django_std_arg_fmts = dict(
     skip_checks=cmd_runner_fmt.as_bool("--skip-checks"),
 )
 
+_django_database_args = dict(
+    database=dict(type="str", default="default"),
+)
+
+_args_menu = dict(
+    std=(django_std_args, _django_std_arg_fmts),
+    database=(_django_database_args, {"database": cmd_runner_fmt.as_opt_eq_val("--database")}),
+    noinput=({}, {"noinput": cmd_runner_fmt.as_fixed("--noinput")}),
+    dry_run=({}, {"dry_run": cmd_runner_fmt.as_bool("--dry-run")}),
+    check=({}, {"check": cmd_runner_fmt.as_bool("--check")}),
+)
+
 
 class _DjangoRunner(PythonRunner):
     def __init__(self, module, arg_formats=None, **kwargs):
@@ -55,15 +68,30 @@ class DjangoModuleHelper(ModuleHelper):
     arg_formats = {}
     django_admin_arg_order = ()
     use_old_vardict = False
+    _django_args = []
+    _check_mode_arg = ""
 
     def __init__(self):
-        argument_spec = dict(django_std_args)
-        argument_spec.update(self.module.get("argument_spec", {}))
-        self.module["argument_spec"] = argument_spec
+        self.module["argument_spec"], self.arg_formats = self._build_args(self.module.get("argument_spec", {}),
+                                                                          self.arg_formats,
+                                                                          *(["std"] + self._django_args))
         super(DjangoModuleHelper, self).__init__(self.module)
         if self.django_admin_cmd is not None:
             self.vars.command = self.django_admin_cmd
 
+    @staticmethod
+    def _build_args(arg_spec, arg_format, *names):
+        res_arg_spec = {}
+        res_arg_fmts = {}
+        for name in names:
+            args, fmts = _args_menu[name]
+            res_arg_spec = dict_merge(res_arg_spec, args)
+            res_arg_fmts = dict_merge(res_arg_fmts, fmts)
+        res_arg_spec = dict_merge(res_arg_spec, arg_spec)
+        res_arg_fmts = dict_merge(res_arg_fmts, arg_format)
+
+        return res_arg_spec, res_arg_fmts
+
     def __run__(self):
         runner = _DjangoRunner(self.module,
                                default_args_order=self.django_admin_arg_order,
@@ -71,7 +99,10 @@ class DjangoModuleHelper(ModuleHelper):
                                venv=self.vars.venv,
                                check_rc=True)
         with runner() as ctx:
-            results = ctx.run()
+            run_params = self.vars.as_dict()
+            if self._check_mode_arg:
+                run_params.update({self._check_mode_arg: self.check_mode})
+            results = ctx.run(**run_params)
             self.vars.stdout = ctx.results_out
             self.vars.stderr = ctx.results_err
             self.vars.cmd = ctx.cmd
diff --git a/plugins/modules/django_createcachetable.py b/plugins/modules/django_createcachetable.py
new file mode 100644
index 0000000000..b038e0358f
--- /dev/null
+++ b/plugins/modules/django_createcachetable.py
@@ -0,0 +1,67 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024, Alexei Znamensky <russoz@gmail.com>
+# 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
+
+DOCUMENTATION = """
+module: django_createcachetable
+author:
+  - Alexei Znamensky (@russoz)
+short_description: Wrapper for C(django-admin createcachetable)
+version_added: 9.1.0
+description:
+  - This module is a wrapper for the execution of C(django-admin createcachetable).
+extends_documentation_fragment:
+  - community.general.attributes
+  - community.general.django
+  - community.general.django.database
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+"""
+
+EXAMPLES = """
+- name: Create cache table in the default database
+  community.general.django_createcachetable:
+    settings: myproject.settings
+
+- name: Create cache table in the other database
+  community.general.django_createcachetable:
+    database: myotherdb
+    settings: fancysite.settings
+    pythonpath: /home/joedoe/project/fancysite
+    venv: /home/joedoe/project/fancysite/venv
+"""
+
+RETURN = """
+run_info:
+  description: Command-line execution information.
+  type: dict
+  returned: success and O(verbosity) >= 3
+"""
+
+from ansible_collections.community.general.plugins.module_utils.django import DjangoModuleHelper
+
+
+class DjangoCreateCacheTable(DjangoModuleHelper):
+    module = dict(
+        supports_check_mode=True,
+    )
+    django_admin_cmd = "createcachetable"
+    django_admin_arg_order = "noinput database dry_run"
+    _django_args = ["noinput", "database", "dry_run"]
+    _check_mode_arg = "dry_run"
+
+
+def main():
+    DjangoCreateCacheTable.execute()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tests/unit/plugins/modules/test_django_createcachetable.py b/tests/unit/plugins/modules/test_django_createcachetable.py
new file mode 100644
index 0000000000..5a4b89c0c1
--- /dev/null
+++ b/tests/unit/plugins/modules/test_django_createcachetable.py
@@ -0,0 +1,13 @@
+# Copyright (c) Alexei Znamensky (russoz@gmail.com)
+# 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_collections.community.general.plugins.modules import django_createcachetable
+from .helper import Helper
+
+
+Helper.from_module(django_createcachetable, __name__)
diff --git a/tests/unit/plugins/modules/test_django_createcachetable.yaml b/tests/unit/plugins/modules/test_django_createcachetable.yaml
new file mode 100644
index 0000000000..1808b163fb
--- /dev/null
+++ b/tests/unit/plugins/modules/test_django_createcachetable.yaml
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alexei Znamensky (russoz@gmail.com)
+# 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
+
+---
+- id: command_success
+  input:
+    settings: whatever.settings
+  run_command_calls:
+    - command: [/testbin/python, -m, django, createcachetable, --no-color, --settings=whatever.settings, --noinput, --database=default]
+      environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: true}
+      rc: 0
+      out: "whatever\n"
+      err: ""