Initial commit for django modutils and django_command module (#8349)

* Initial commit for django modutils and django_command module

* Fixed sanity, param settings required

* add stdout, stderr and cmd to django module output

* add examples and return docs to djando_command module

* multiple minor adjustments

* fix typo

* Update plugins/modules/django_command.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/django_command.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/django_command.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* move note to seealso

* add xfailing test

* Update plugins/doc_fragments/django.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/doc_fragments/django.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

.github/BOTMETA.yml

@@ -119,6 +119,8 @@ files:
     maintainers: $team_ansible_core
   $doc_fragments/:
     labels: docs_fragments
+  $doc_fragments/django.py:
+    maintainers: russoz
   $doc_fragments/hpe3par.py:
     labels: hpe3par
     maintainers: farhan7500 gautamphegde
@@ -300,6 +302,8 @@ files:
     maintainers: russoz
   $module_utils/deps.py:
     maintainers: russoz
+  $module_utils/django.py:
+    maintainers: russoz
   $module_utils/gconftool2.py:
     labels: gconftool2
     maintainers: russoz
@@ -500,6 +504,8 @@ files:
     ignore: scottanderson42 tastychutney
     labels: django_manage
     maintainers: russoz
+  $modules/django_command.py:
+    maintainers: russoz
   $modules/dnf_versionlock.py:
     maintainers: moreda
   $modules/dnf_config_manager.py:

plugins/doc_fragments/django.py

@@ -0,0 +1,53 @@
+# -*- 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
+
+
+class ModuleDocFragment(object):
+    DOCUMENTATION = r'''
+options:
+  venv:
+    description:
+      - Use the the Python interpreter from this virtual environment.
+      - Pass the path to the root of the virtualenv, not the C(bin/) directory nor the C(python) executable.
+    type: path
+  settings:
+    description:
+      - Specifies the settings module to use.
+      - The value will be passed as is to the C(--settings) argument in C(django-admin).
+    type: str
+    required: true
+  pythonpath:
+    description:
+      - Adds the given filesystem path to the Python import search path.
+      - The value will be passed as is to the C(--pythonpath) argument in C(django-admin).
+    type: path
+  traceback:
+    description:
+      - Provides a full stack trace in the output when a C(CommandError) is raised.
+    type: bool
+  verbosity:
+    description:
+      - Specifies the amount of notification and debug information in the output of C(django-admin).
+    type: int
+    choices: [0, 1, 2, 3]
+  skip_checks:
+    description:
+      - Skips running system checks prior to running the command.
+    type: bool
+
+
+notes:
+  - The C(django-admin) command is always executed using the C(C) locale, and the option C(--no-color) is always passed.
+
+seealso:
+  - name: django-admin and manage.py in official Django documentation
+    description: >-
+      Refer to this documentation for the builtin commands and options of C(django-admin).
+      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/
+'''

plugins/module_utils/django.py

@@ -0,0 +1,84 @@
+# -*- 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
+
+
+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
+
+
+django_std_args = dict(
+    # environmental options
+    venv=dict(type="path"),
+    # default options of django-admin
+    settings=dict(type="str", required=True),
+    pythonpath=dict(type="path"),
+    traceback=dict(type="bool"),
+    verbosity=dict(type="int", choices=[0, 1, 2, 3]),
+    skip_checks=dict(type="bool"),
+)
+
+_django_std_arg_fmts = dict(
+    command=cmd_runner_fmt.as_list(),
+    settings=cmd_runner_fmt.as_opt_eq_val("--settings"),
+    pythonpath=cmd_runner_fmt.as_opt_eq_val("--pythonpath"),
+    traceback=cmd_runner_fmt.as_bool("--traceback"),
+    verbosity=cmd_runner_fmt.as_opt_val("--verbosity"),
+    no_color=cmd_runner_fmt.as_fixed("--no-color"),
+    skip_checks=cmd_runner_fmt.as_bool("--skip-checks"),
+)
+
+
+class _DjangoRunner(PythonRunner):
+    def __init__(self, module, arg_formats=None, **kwargs):
+        arg_fmts = dict(arg_formats) if arg_formats else {}
+        arg_fmts.update(_django_std_arg_fmts)
+
+        super(_DjangoRunner, self).__init__(module, ["-m", "django"], arg_formats=arg_fmts, **kwargs)
+
+    def __call__(self, output_process=None, ignore_value_none=True, check_mode_skip=False, check_mode_return=None, **kwargs):
+        args_order = (
+            ("command", "no_color", "settings", "pythonpath", "traceback", "verbosity", "skip_checks") + self._prepare_args_order(self.default_args_order)
+        )
+        return super(_DjangoRunner, self).__call__(args_order, output_process, ignore_value_none, check_mode_skip, check_mode_return, **kwargs)
+
+
+class DjangoModuleHelper(ModuleHelper):
+    module = {}
+    use_old_vardict = False
+    django_admin_cmd = None
+    arg_formats = {}
+    django_admin_arg_order = ()
+
+    def __init__(self):
+        argument_spec = dict(django_std_args)
+        argument_spec.update(self.module.get("argument_spec", {}))
+        self.module["argument_spec"] = argument_spec
+        super(DjangoModuleHelper, self).__init__(self.module)
+        if self.django_admin_cmd is not None:
+            self.vars.command = self.django_admin_cmd
+
+    def __run__(self):
+        runner = _DjangoRunner(self.module,
+                               default_args_order=self.django_admin_arg_order,
+                               arg_formats=self.arg_formats,
+                               venv=self.vars.venv,
+                               check_rc=True)
+        with runner() as ctx:
+            results = ctx.run()
+            self.vars.stdout = ctx.results_out
+            self.vars.stderr = ctx.results_err
+            self.vars.cmd = ctx.cmd
+            if self.verbosity >= 3:
+                self.vars.run_info = ctx.run_info
+
+        return results
+
+    @classmethod
+    def execute(cls):
+        cls().run()

plugins/modules/django_command.py

@@ -0,0 +1,83 @@
+#!/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_command
+author:
+  - Alexei Znamensky (@russoz)
+short_description: Run Django admin commands
+version_added: 9.0.0
+description:
+  - This module allows the execution of arbitrary Django admin commands.
+extends_documentation_fragment:
+  - community.general.attributes
+  - community.general.django
+attributes:
+  check_mode:
+    support: none
+  diff_mode:
+    support: none
+options:
+  command:
+    description:
+      - Django admin command. It must be a valid command accepted by C(python -m django) at the target system.
+    type: str
+    required: true
+  extra_args:
+    type: list
+    elements: str
+    description:
+      - List of extra arguments passed to the django admin command.
+"""
+
+EXAMPLES = """
+- name: Check the project
+  community.general.django_command:
+    command: check
+    settings: myproject.settings
+
+- name: Check the project in specified python path, using virtual environment
+  community.general.django_command:
+    command: check
+    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
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import cmd_runner_fmt
+
+
+class DjangoCommand(DjangoModuleHelper):
+    module = dict(
+        argument_spec=dict(
+            command=dict(type="str", required=True),
+            extra_args=dict(type="list", elements="str"),
+        ),
+        supports_check_mode=False,
+    )
+    arg_formats = dict(
+        extra_args=cmd_runner_fmt.as_list(),
+    )
+    django_admin_arg_order = "extra_args"
+
+
+def main():
+    DjangoCommand.execute()
+
+
+if __name__ == '__main__':
+    main()

tests/unit/plugins/modules/helper.py

@@ -52,9 +52,9 @@ class _BaseContext(object):
 
         test_flags = self.test_flags()
         if test_flags.get("skip"):
-            pytest.skip()
+            pytest.skip(test_flags.get("skip"))
         if test_flags.get("xfail"):
-            pytest.xfail()
+            pytest.xfail(test_flags.get("xfail"))
 
         func()
 

tests/unit/plugins/modules/test_django_command.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_command
+from .helper import Helper
+
+
+Helper.from_module(django_command, __name__)

tests/unit/plugins/modules/test_django_command.yaml

@@ -0,0 +1,40 @@
+# -*- 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:
+    command: check
+    extra_args:
+      - babaloo
+      - yaba
+      - daba
+      - doo
+    settings: whatever.settings
+  run_command_calls:
+    - command: [/testbin/python, -m, django, check, --no-color, --settings=whatever.settings, babaloo, yaba, daba, doo]
+      environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: true}
+      rc: 0
+      out: "whatever\n"
+      err: ""
+- id: command_fail
+  input:
+    command: check
+    extra_args:
+      - babaloo
+      - yaba
+      - daba
+      - doo
+    settings: whatever.settings
+  output:
+    failed: true
+  flags:
+    xfail: not seem to be failing as it should
+  run_command_calls:
+    - command: [/testbin/python, -m, django, check, --no-color, --settings=whatever.settings, babaloo, yaba, daba, doo]
+      environ: *env-def
+      rc: 1
+      out: "whatever\n"
+      err: ""