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

@@ -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:

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
+'''

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

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()

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__)

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: ""