Merge branch 'rename-extra-config'

Author: PeterJCLaw

README.md

@@ -69,7 +69,7 @@ LIGHTWEIGHT_QUEUE_REDIS_PORT = 12345
 and then running:
 
 ```
-$ python manage.py queue_runner --config=special.py
+$ python manage.py queue_runner --extra-settings=special.py
 ```
 
 will result in the runner to use the settings from the specified configuration
@@ -149,10 +149,13 @@ part of a pool:
 $ python manage.py queue_runner --machine 2 --of 4
 ```
 
-Alternatively a runner can be told explicitly which configuration to use:
+Alternatively a runner can be told explicitly how to behave by having
+extra settings loaded (any `LIGHTWEIGHT_QUEUE_*` constants found in the file
+will replace equivalent django settings) and being configured to run exactly as
+the settings describe:
 
 ```
-$ python manage.py queue_runner --exact-configuration --config=special.py
+$ python manage.py queue_runner --exact-configuration --extra-settings=special.py
 ```
 
 When using `--exact-configuration` the number of workers is configured exactly,
@@ -188,7 +191,7 @@ $ python manage.py queue_runner --machine 3 --of 3
 will result in one worker for `queue1` on the current machine, while:
 
 ```
-$ python manage.py queue_runner --exact-configuration --config=special.py
+$ python manage.py queue_runner --exact-configuration --extra-settings=special.py
 ```
 
 will result in two workers on the current machine.

django_lightweight_queue/management/commands/queue_configuration.py

@@ -1,26 +1,46 @@
+import warnings
 from typing import Any
 
 from django.core.management.base import BaseCommand, CommandParser
 
 from ... import app_settings
-from ...utils import get_backend, get_queue_counts, load_extra_config
+from ...utils import get_backend, get_queue_counts, load_extra_settings
+from ...constants import SETTING_NAME_PREFIX
 from ...cron_scheduler import get_cron_config
 
 
 class Command(BaseCommand):
     def add_arguments(self, parser: CommandParser) -> None:
-        parser.add_argument(
+        extra_settings_group = parser.add_mutually_exclusive_group()
+        extra_settings_group.add_argument(
             '--config',
             action='store',
             default=None,
-            help="The path to an additional django-style config file to load",
+            help="The path to an additional django-style config file to load "
+                 "(this spelling is deprecated in favour of '--extra-settings')",
+        )
+        extra_settings_group.add_argument(
+            '--extra-settings',
+            action='store',
+            default=None,
+            help="The path to an additional django-style settings file to load. "
+                 f"{SETTING_NAME_PREFIX}* settings discovered in this file will "
+                 "override those from the default Django settings.",
         )
 
     def handle(self, **options: Any) -> None:
-        # Configuration overrides
-        extra_config = options['config']
+        extra_config = options.pop('config')
         if extra_config is not None:
-            load_extra_config(extra_config)
+            warnings.warn(
+                "Use of '--config' is deprecated in favour of '--extra-settings'.",
+                category=DeprecationWarning,
+            )
+            options['extra_settings'] = extra_config
+
+        # Configuration overrides
+        extra_settings = options['extra_settings']
+        if extra_settings is not None:
+            load_extra_settings(extra_settings)
 
         print("django-lightweight-queue")
         print("========================")

django_lightweight_queue/management/commands/queue_runner.py

@@ -1,3 +1,4 @@
+import warnings
 from typing import Any, Dict, Optional
 
 import daemonize
@@ -10,8 +11,14 @@
 )
 
 from ...types import QueueName
-from ...utils import get_logger, get_backend, get_middleware, load_extra_config
+from ...utils import (
+    get_logger,
+    get_backend,
+    get_middleware,
+    load_extra_settings,
+)
 from ...runner import runner
+from ...constants import SETTING_NAME_PREFIX
 from ...machine_types import Machine, PooledMachine, DirectlyConfiguredMachine
 
 
@@ -51,23 +58,42 @@ def add_arguments(self, parser: CommandParser) -> None:
             default=None,
             help="Only run the given queue, useful for local debugging",
         )
-        parser.add_argument(
+        extra_settings_group = parser.add_mutually_exclusive_group()
+        extra_settings_group.add_argument(
             '--config',
             action='store',
             default=None,
-            help="The path to an additional django-style config file to load",
+            help="The path to an additional django-style config file to load "
+                 "(this spelling is deprecated in favour of '--extra-settings')",
+        )
+        extra_settings_group.add_argument(
+            '--extra-settings',
+            action='store',
+            default=None,
+            help="The path to an additional django-style settings file to load. "
+                 f"{SETTING_NAME_PREFIX}* settings discovered in this file will "
+                 "override those from the default Django settings.",
         )
         parser.add_argument(
             '--exact-configuration',
             action='store_true',
             help="Run queues on this machine exactly as specified. Requires the"
-                 " use of the '--config' option in addition. It is an error to"
-                 " use this option together with either '--machine' or '--of'.",
+                 " use of the '--extra-settings' option in addition. It is an"
+                 " error to use this option together with either '--machine' or"
+                 " '--of'.",
         )
 
     def validate_and_normalise(self, options: Dict[str, Any]) -> None:
+        extra_config = options.pop('config')
+        if extra_config is not None:
+            warnings.warn(
+                "Use of '--config' is deprecated in favour of '--extra-settings'.",
+                category=DeprecationWarning,
+            )
+            options['extra_settings'] = extra_config
+
         if options['exact_configuration']:
-            if not options['config']:
+            if not options['extra_settings']:
                 raise CommandError(
                     "Must provide a value for '--config' when using "
                     "'--exact-configuration'.",
@@ -110,9 +136,9 @@ def touch_filename(name: str) -> Optional[str]:
                 return None
 
         # Configuration overrides
-        extra_config = options['config']
+        extra_config = options['extra_settings']
         if extra_config is not None:
-            load_extra_config(extra_config)
+            load_extra_settings(extra_config)
 
         logger.info("Starting queue master")
 

django_lightweight_queue/utils.py

@@ -32,7 +32,7 @@
 FIVE_SECONDS = datetime.timedelta(seconds=5)
 
 
-def load_extra_config(file_path: str) -> None:
+def load_extra_settings(file_path: str) -> None:
     # Based on https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly
     spec = importlib.util.spec_from_file_location('extra_settings', file_path)
     extra_settings = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]

tests/_demo_extra_config.py renamed to tests/_demo_extra_settings.py

@@ -1,7 +1,7 @@
 from django_lightweight_queue.types import QueueName
 
 LIGHTWEIGHT_QUEUE_BACKEND_OVERRIDES = {
-    QueueName('test-queue'): 'tests.test_extra_config.TestBackend',
+    QueueName('test-queue'): 'tests.test_extra_settings.TestBackend',
 }
 
 LIGHTWEIGHT_QUEUE_REDIS_PASSWORD = 'a very bad password'

tests/_demo_extra_config_falsey.py renamed to tests/_demo_extra_settings_falsey.py

@@ -7,7 +7,7 @@
 from django_lightweight_queue import app_settings
 from django_lightweight_queue.job import Job
 from django_lightweight_queue.types import QueueName, WorkerNumber
-from django_lightweight_queue.utils import get_backend, load_extra_config
+from django_lightweight_queue.utils import get_backend, load_extra_settings
 from django_lightweight_queue.backends.base import BaseBackend
 
 TESTS_DIR = Path(__file__).parent
@@ -24,7 +24,7 @@ def length(self, queue: QueueName) -> int:
         pass
 
 
-class ExtraConfigTests(SimpleTestCase):
+class ExtraSettingsTests(SimpleTestCase):
     def setUp(self) -> None:
         get_backend.cache_clear()
         super().setUp()
@@ -34,8 +34,8 @@ def tearDown(self) -> None:
         get_backend.cache_clear()
         super().tearDown()
 
-    def test_updates_configuration(self) -> None:
-        load_extra_config(str(TESTS_DIR / '_demo_extra_config.py'))
+    def test_updates_settings(self) -> None:
+        load_extra_settings(str(TESTS_DIR / '_demo_extra_settings.py'))
 
         backend = get_backend('test-queue')
         self.assertIsInstance(backend, TestBackend)
@@ -44,17 +44,17 @@ def test_updates_configuration(self) -> None:
 
     def test_warns_about_unexpected_settings(self) -> None:
         with self.assertWarnsRegex(Warning, r'Ignoring unexpected setting.+\bNOT_REDIS_PASSWORD\b'):
-            load_extra_config(str(TESTS_DIR / '_demo_extra_config_unexpected.py'))
+            load_extra_settings(str(TESTS_DIR / '_demo_extra_settings_unexpected.py'))
 
         self.assertEqual('expected', app_settings.REDIS_PASSWORD)
 
-    def test_updates_configuration_with_falsey_values(self) -> None:
-        load_extra_config(str(TESTS_DIR / '_demo_extra_config.py'))
-        load_extra_config(str(TESTS_DIR / '_demo_extra_config_falsey.py'))
+    def test_updates_settings_with_falsey_values(self) -> None:
+        load_extra_settings(str(TESTS_DIR / '_demo_extra_settings.py'))
+        load_extra_settings(str(TESTS_DIR / '_demo_extra_settings_falsey.py'))
 
         self.assertIsNone(app_settings.REDIS_PASSWORD)
         self.assertFalse(app_settings.ATOMIC_JOBS)
 
     def test_rejects_missing_file(self) -> None:
         with self.assertRaises(FileNotFoundError):
-            load_extra_config(str(TESTS_DIR / '_no_such_file.py'))
+            load_extra_settings(str(TESTS_DIR / '_no_such_file.py'))