collection 교체

collection/community/general/plugins/modules/django_manage.py

@@ -1,8 +1,10 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2013, Scott Anderson <scottanderson42@gmail.com>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2022, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2013, Scott Anderson <scottanderson42@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
@@ -11,117 +13,166 @@ __metaclass__ = type
 DOCUMENTATION = '''
 ---
 module: django_manage
-short_description: Manages a Django application.
+short_description: Manages a Django application
 description:
-    - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the
-      C(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation.
+  - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the
+    O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation.
+extends_documentation_fragment:
+  - community.general.attributes
+attributes:
+  check_mode:
+    support: none
+  diff_mode:
+    support: none
 options:
   command:
     description:
-      - The name of the Django management command to run. Built in commands are C(cleanup), C(collectstatic),
-        C(flush), C(loaddata), C(migrate), C(syncdb), C(test), and C(validate).
-      - Other commands can be entered, but will fail if they're unknown to Django.  Other commands that may
+      - The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation.
+      - >
+        V(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be
+        removed in community.general 9.0.0. Use V(clearsessions) instead.
+      - V(collectstatic) - Collects the static files into C(STATIC_ROOT).
+      - V(createcachetable) - Creates the cache tables for use with the database cache backend.
+      - V(flush) - Removes all data from the database.
+      - V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database.
+      - V(migrate) - Synchronizes the database state with models and migrations.
+      - >
+        V(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7).
+        This parameter will be removed in community.general 9.0.0. Use V(migrate) instead.
+      - V(test) - Runs tests for all installed apps.
+      - >
+        V(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be
+        removed in community.general 9.0.0. Use V(check) instead.
+      - Other commands can be entered, but will fail if they are unknown to Django.  Other commands that may
         prompt for user input should be run with the C(--noinput) flag.
-      - The module will perform some basic parameter validation (when applicable) to the commands C(cleanup),
-        C(collectstatic), C(createcachetable), C(flush), C(loaddata), C(migrate), C(syncdb), C(test), and C(validate).
     type: str
     required: true
   project_path:
     description:
-      - The path to the root of the Django application where B(manage.py) lives.
+      - The path to the root of the Django application where C(manage.py) lives.
     type: path
     required: true
     aliases: [app_path, chdir]
   settings:
     description:
-      - The Python path to the application's settings module, such as C(myapp.settings).
+      - The Python path to the application's settings module, such as V(myapp.settings).
     type: path
     required: false
   pythonpath:
     description:
       - A directory to add to the Python path. Typically used to include the settings module if it is located
         external to the application directory.
+      - This would be equivalent to adding O(pythonpath)'s value to the E(PYTHONPATH) environment variable.
     type: path
     required: false
     aliases: [python_path]
   virtualenv:
     description:
-      - An optional path to a I(virtualenv) installation to use while running the manage application.
+      - An optional path to a C(virtualenv) installation to use while running the manage application.
     type: path
     aliases: [virtual_env]
   apps:
     description:
-      - A list of space-delimited apps to target. Used by the C(test) command.
+      - A list of space-delimited apps to target. Used by the V(test) command.
     type: str
     required: false
   cache_table:
     description:
-      - The name of the table used for database-backed caching. Used by the C(createcachetable) command.
+      - The name of the table used for database-backed caching. Used by the V(createcachetable) command.
     type: str
     required: false
   clear:
     description:
       - Clear the existing files before trying to copy or link the original file.
-      - Used only with the C(collectstatic) command. The C(--noinput) argument will be added automatically.
+      - Used only with the V(collectstatic) command. The C(--noinput) argument will be added automatically.
     required: false
-    default: no
+    default: false
     type: bool
   database:
     description:
-      - The database to target. Used by the C(createcachetable), C(flush), C(loaddata), C(syncdb),
-        and C(migrate) commands.
+      - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb),
+        and V(migrate) commands.
     type: str
     required: false
   failfast:
     description:
-      - Fail the command immediately if a test fails. Used by the C(test) command.
+      - Fail the command immediately if a test fails. Used by the V(test) command.
     required: false
     default: false
     type: bool
     aliases: [fail_fast]
   fixtures:
     description:
-      - A space-delimited list of fixture file names to load in the database. B(Required) by the C(loaddata) command.
+      - A space-delimited list of fixture file names to load in the database. B(Required) by the V(loaddata) command.
     type: str
     required: false
   skip:
     description:
-     - Will skip over out-of-order missing migrations, you can only use this parameter with C(migrate) command.
+      - Will skip over out-of-order missing migrations, you can only use this parameter with V(migrate) command.
     required: false
     type: bool
   merge:
     description:
-     - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this
-       parameter with C(migrate) command.
+      - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this
+        parameter with V(migrate) command.
     required: false
     type: bool
   link:
     description:
-     - Will create links to the files instead of copying them, you can only use this parameter with
-       C(collectstatic) command.
+      - Will create links to the files instead of copying them, you can only use this parameter with
+        V(collectstatic) command.
     required: false
     type: bool
   testrunner:
     description:
-      - "From the Django docs: Controls the test runner class that is used to execute tests."
+      - Controls the test runner class that is used to execute tests.
       - This parameter is passed as-is to C(manage.py).
     type: str
     required: false
     aliases: [test_runner]
+  ack_venv_creation_deprecation:
+    description:
+      - >-
+        When a O(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 V(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:
-  - C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the I(virtualenv) parameter
-    is specified.
-  - 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.
-  - This module assumes English error messages for the C(createcachetable) command to detect table existence,
+  - >
+    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 O(virtualenv) parameter
+    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 O(virtualenv) parameter is specified and a virtual environment does not already
+    exist at the given location. This behavior is deprecated and will be removed in community.general version 9.0.0.
+  - The parameter O(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 V(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
+  - To be able to use the V(migrate) command with django versions < 1.7, you must have C(south) installed and added
     as an app in your settings.
-  - To be able to use the C(collectstatic) command, you must have enabled staticfiles in your settings.
-  - Your C(manage.py) application must be executable (rwxr-xr-x), and must have a valid shebang,
-    i.e. C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
+  - To be able to use the V(collectstatic) command, you must have enabled staticfiles in your settings.
+  - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang,
+    for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
+seealso:
+  - name: django-admin and manage.py Reference
+    description: Reference for C(django-admin) or C(manage.py) commands.
+    link: https://docs.djangoproject.com/en/4.1/ref/django-admin/
+  - name: Django Download page
+    description: The page showing how to get Django and the timeline of supported releases.
+    link: https://www.djangoproject.com/download/
+  - name: What Python version can I use with Django?
+    description: From the Django FAQ, the response to Python requirements for the framework.
+    link: https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
 requirements: [ "virtualenv", "django" ]
-author: "Scott Anderson (@tastychutney)"
+author:
+  - Alexei Znamensky (@russoz)
+  - Scott Anderson (@tastychutney)
 '''
 
 EXAMPLES = """
@@ -182,6 +233,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)
@@ -271,6 +333,7 @@ def main():
             skip=dict(type='bool'),
             merge=dict(type='bool'),
             link=dict(type='bool'),
+            ack_venv_creation_deprecation=dict(type='bool'),
         ),
     )
 
@@ -279,6 +342,21 @@ def main():
     project_path = module.params['project_path']
     virtualenv = module.params['virtualenv']
 
+    try:
+        _deprecation = dict(
+            cleanup="clearsessions",
+            syncdb="migrate",
+            validate="check",
+        )
+        module.deprecate(
+            'The command {0} has been deprecated as it is no longer supported in recent Django versions.'
+            'Please use the command {1} instead that provide similar capability.'.format(command_bin, _deprecation[command_bin]),
+            version='9.0.0',
+            collection_name='community.general'
+        )
+    except KeyError:
+        pass
+
     for param in specific_params:
         value = module.params[param]
         if value and param not in command_allowed_param_map[command_bin]: