django_manage: deprecate venv creation when missing (#5405)

* deprecate venv creation when missing

* add changelog fragment

* fix sanity checks

* Update changelogs/fragments/5404-django-manage-venv-deprecation.yml

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

* Update plugins/modules/web_infrastructure/django_manage.py

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

* Update plugins/modules/web_infrastructure/django_manage.py

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

* minor change to help future removal of feature

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

changelogs/fragments/5404-django-manage-venv-deprecation.yml

@@ -0,0 +1,5 @@
+deprecated_features:
+  - >-
+    django_manage - the behavior of "creating the virtual environment when missing"
+    is being deprecated and will be removed in community.general version 9.0.0
+    (https://github.com/ansible-collections/community.general/pull/5405).

plugins/modules/web_infrastructure/django_manage.py

@@ -123,15 +123,28 @@ options:
     type: str
     required: false
     aliases: [test_runner]
+  ack_venv_creation_deprecation:
+    description:
+      - >-
+        When a I(virtualenv) is set but the virtual environment does not exist, the current behavior is
+        to create a new virtual environment. That behavior is deprecated and if that case happens it will
+        generate a deprecation warning. Set this flag to C(true) to suppress the deprecation warning.
+      - Please note that you will receive no further warning about this being removed until the module
+        will start failing in such cases from community.general 9.0.0 on.
+    type: bool
+    version_added: 5.8.0
+
 notes:
   - >
     B(ATTENTION - DEPRECATION): Support for Django releases older than 4.1 will be removed in
     community.general version 9.0.0 (estimated to be released in May 2024).
     Please notice that Django 4.1 requires Python 3.8 or greater.
   - C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the I(virtualenv) parameter
-    is specified.
+    is specified. This requirement is deprecated and will be removed in community.general version 9.0.0.
   - This module will create a virtualenv if the I(virtualenv) parameter is specified and a virtual environment does not already
-    exist at the given location.
+    exist at the given location. This behavior is deprecated and will be removed in community.general version 9.0.0.
+  - The parameter I(virtualenv) will remain in use, but it will require the specified virtualenv to exist.
+    The recommended way to create one in Ansible is by using M(ansible.builtin.pip).
   - This module assumes English error messages for the C(createcachetable) command to detect table existence,
     unfortunately.
   - To be able to use the C(migrate) command with django versions < 1.7, you must have C(south) installed and added
@@ -213,6 +226,17 @@ def _ensure_virtualenv(module):
     activate = os.path.join(vbin, 'activate')
 
     if not os.path.exists(activate):
+        # In version 9.0.0, if the venv is not found, it should fail_json() here.
+        if not module.params['ack_venv_creation_deprecation']:
+            module.deprecate(
+                'The behavior of "creating the virtual environment when missing" is being '
+                'deprecated and will be removed in community.general version 9.0.0. '
+                'Set the module parameter `ack_venv_creation_deprecation: true` to '
+                'prevent this message from showing up when creating a virtualenv.',
+                version='9.0.0',
+                collection_name='community.general',
+            )
+
         virtualenv = module.get_bin_path('virtualenv', True)
         vcmd = [virtualenv, venv_param]
         rc, out_venv, err_venv = module.run_command(vcmd)
@@ -302,6 +326,7 @@ def main():
             skip=dict(type='bool'),
             merge=dict(type='bool'),
             link=dict(type='bool'),
+            ack_venv_creation_deprecation=dict(type='bool'),
         ),
     )