feat!: add sources for release 1.0.0

Author: paduszyk

src/management_commands/conf.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import re
+from keyword import iskeyword
+from typing import ClassVar
+
+import appconf
+
+
+def _is_identifier(s: str) -> bool:
+    return s.isidentifier() and not iskeyword(s)
+
+
+def _is_dotted_path(s: str, /, *, min_parts: int = 0) -> bool:
+    if not (dotted_path_match := re.match(r"^[^\d\W]\w*(\.[^\d\W]\w*)*$", s)):
+        return False
+
+    parts = dotted_path_match.group().split(".")
+
+    return len(parts) >= min_parts and all(map(_is_identifier, parts))
+
+
+class ManagementCommandsConf(appconf.AppConf):  # type: ignore[misc]
+    PATHS: ClassVar[dict[str, str]] = {}
+
+    MODULES: ClassVar[list[str]] = []
+
+    SUBMODULES: ClassVar[list[str]] = []
+
+    ALIASES: ClassVar[dict[str, list[str]]] = {}
+
+    class ImproperlyConfigured(Exception):
+        def __init__(self, msg: str, code: str | None = None) -> None:
+            super().__init__(msg)
+
+            self.code = code
+
+    def improperly_configured(
+        self,
+        msg: str,
+        code: str | None = None,
+    ) -> ImproperlyConfigured:
+        msg = re.sub(
+            rf"({'|'.join(dir(self))})",
+            lambda m: f"{self._meta.prefixed_name(m.group(0))}",
+            msg,
+        )
+
+        return self.__class__.ImproperlyConfigured(msg, code)
+
+    def configure_paths(self, setting_value: dict[str, str]) -> dict[str, str]:
+        for key, value in setting_value.items():
+            if not _is_identifier(key):
+                msg = (
+                    f"invalid key {key!r} in PATHS; "
+                    f"keys must be valid Python identifiers"
+                )
+
+                raise self.improperly_configured(msg, "paths.key")
+
+            if not _is_dotted_path(value, min_parts=2):
+                msg = (
+                    f"invalid value for PATHS[{key!r}]; "
+                    f"values must be valid absolute dotted paths with at least 2 parts"
+                )
+
+                raise self.improperly_configured(msg, "paths.value")
+
+        return setting_value
+
+    def _configure_path_list(
+        self,
+        setting_name: str,
+        setting_value: list[str],
+    ) -> list[str]:
+        for index, item in enumerate(setting_value):
+            if not _is_dotted_path(item):
+                msg = (
+                    f"invalid value for {setting_name.upper()}[{index}]; "
+                    f"items must be valid absolute dotted paths"
+                )
+
+                raise self.improperly_configured(msg, f"{setting_name}.item")
+
+        return setting_value
+
+    def configure_modules(self, setting_value: list[str]) -> list[str]:
+        return self._configure_path_list("modules", setting_value)
+
+    def configure_submodules(self, setting_value: list[str]) -> list[str]:
+        configured_value = self._configure_path_list("submodules", setting_value)
+
+        if "management.commands" not in configured_value:
+            configured_value.insert(0, "management.commands")
+
+        return configured_value
+
+    def configure_aliases(
+        self,
+        setting_value: dict[str, list[str]],
+    ) -> dict[str, list[str]]:
+        for key, value in setting_value.items():
+            if not _is_identifier(key):
+                msg = (
+                    f"invalid key {key!r} in ALIASES; "
+                    f"keys must be valid Python identifiers"
+                )
+
+                raise self.improperly_configured(msg, "aliases.key")
+
+            for index, item in enumerate(value):
+                argv = item.split()
+
+                try:
+                    command = argv[0]
+                except IndexError as exc:
+                    msg = (
+                        f"empty item found in ALIASES[{key!r}][{index}]; "
+                        f"items must not be empty"
+                    )
+
+                    raise self.improperly_configured(msg, "aliases.empty") from exc
+
+                if command == key:
+                    msg = (
+                        f"invalid value for ALIASES[{key!r}][{index}]; "
+                        f"items must not refer to the aliases they are defined by"
+                    )
+
+                    raise self.improperly_configured(msg, "aliases.self_reference")
+
+        return setting_value
+
+
+settings = ManagementCommandsConf()

src/management_commands/core.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from contextlib import suppress
+
+from django.apps.registry import apps
+from django.core.management.base import BaseCommand
+from django.utils.module_loading import import_string
+
+from .conf import settings
+from .exceptions import (
+    CommandAppLookupError,
+    CommandClassLookupError,
+    CommandImportError,
+    CommandTypeError,
+)
+
+
+def import_command_class(dotted_path: str) -> type[BaseCommand]:
+    try:
+        command_class: type = import_string(dotted_path)
+    except ImportError as exc:
+        raise CommandImportError(dotted_path) from exc
+
+    if not (isinstance(command_class, type) and issubclass(command_class, BaseCommand)):
+        raise CommandTypeError(command_class)
+
+    return command_class
+
+
+def get_command_paths(name: str, app_label: str | None = None) -> list[str]:
+    if not app_label:
+        app_names = [
+            "django.core",
+            *(app_config.name for app_config in reversed(list(apps.get_app_configs()))),
+        ]
+
+        modules_paths = [f"{module}.{name}.Command" for module in settings.MODULES]
+    else:
+        try:
+            app_config = apps.get_app_config(app_label)
+        except LookupError as exc:
+            raise CommandAppLookupError(app_label) from exc
+        else:
+            app_names = [app_config.name]
+
+        modules_paths = []
+
+    submodules_paths: list[str] = []
+    for app_name in app_names:
+        for submodule in settings.SUBMODULES:
+            if app_name == "django.core" and submodule != "management.commands":
+                continue
+
+            submodules_paths.append(f"{app_name}.{submodule}.{name}.Command")
+
+    return modules_paths + submodules_paths
+
+
+def load_command_class(name: str, app_label: str | None = None) -> type[BaseCommand]:
+    command_paths = get_command_paths(name, app_label)
+
+    for command_path in command_paths:
+        with suppress(CommandImportError, CommandTypeError):
+            return import_command_class(command_path)
+
+    raise CommandClassLookupError(name, app_label)

src/management_commands/exceptions.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from django.core.management.base import BaseCommand
+
+
+class ManagementCommandsException(Exception):
+    msg: str
+
+    def __init__(self, msg: str | None = None, **kwargs: str) -> None:
+        super().__init__(
+            msg
+            if msg
+            else (
+                msg_template.format(**kwargs)
+                if (msg_template := getattr(type(self), "msg", None)) and kwargs
+                else ""
+            ),
+        )
+
+
+class CommandClassLookupError(ManagementCommandsException):
+    msg = "command {command_name!r} is not registered from {app_info}"
+
+    def __init__(
+        self,
+        command_name: str | None = None,
+        app_name: str | None = None,
+    ) -> None:
+        super().__init__(
+            **(
+                {
+                    "command_name": command_name,
+                    "app_info": (
+                        f"the {app_name!r} app"
+                        if app_name
+                        else "any of the installed apps"
+                    ),
+                }
+                if command_name
+                else {}
+            ),
+        )
+
+
+class CommandAppLookupError(ManagementCommandsException):
+    msg = "app {app_name!r} is not installed"
+
+    def __init__(self, app_name: str | None = None) -> None:
+        super().__init__(**({"app_name": app_name} if app_name else {}))
+
+
+class CommandImportError(ManagementCommandsException, ImportError):
+    msg = "class {class_name!r} could not be imported from the {module_path!r} module"
+
+    def __init__(self, command_class_path: str | None = None) -> None:
+        super().__init__(
+            **({"module_path": parts[0], "class_name": parts[1]})
+            if (command_class_path and (parts := command_class_path.rsplit(".", 1)))
+            else {},
+        )
+
+
+class CommandTypeError(ManagementCommandsException):
+    msg = "class {class_path!r} is not a subclass of {base_command_class_path!r}"
+
+    def __init__(self, class_: type | None = None) -> None:
+        super().__init__(
+            **(
+                {
+                    "class_path": self._class_path(class_),
+                    "base_command_class_path": self._class_path(BaseCommand),
+                }
+                if class_
+                else {}
+            ),
+        )
+
+    @staticmethod
+    def _class_path(class_: type) -> str:
+        return f"{class_.__module__}.{class_.__qualname__}"

src/management_commands/management.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from django.core.management import ManagementUtility as BaseManagementUtility
+from django.core.management.color import color_style
+
+from .conf import settings
+from .core import import_command_class, load_command_class
+
+if TYPE_CHECKING:
+    from django.core.management.base import BaseCommand
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
+class ManagementUtility(BaseManagementUtility):
+    @override
+    def main_help_text(self, commands_only: bool = False) -> str:
+        usage = super().main_help_text(commands_only=commands_only)
+
+        style = color_style()
+
+        commands_usage = (
+            [
+                style.NOTICE("[django-management-commands: paths]"),
+                *[f"    {path}" for path in paths],
+                "",
+            ]
+            if (paths := settings.PATHS)
+            else []
+        )
+        aliases_usage = (
+            [
+                style.NOTICE("[django-management-commands: aliases]"),
+                *[f"    {alias}" for alias in aliases],
+                "",
+            ]
+            if (aliases := settings.ALIASES)
+            else []
+        )
+
+        usage_list = usage.split("\n")
+        usage_list.append("")
+        usage_list.extend(commands_usage)
+        usage_list.extend(aliases_usage)
+
+        return "\n".join(usage_list)
+
+    @override
+    def fetch_command(self, subcommand: str) -> BaseCommand:
+        if dotted_path := settings.PATHS.get(subcommand):
+            command_class = import_command_class(dotted_path)
+        else:
+            try:
+                app_label, name = subcommand.rsplit(".", 1)
+            except ValueError:
+                app_label, name = None, subcommand
+
+            command_class = load_command_class(name, app_label)
+
+        return command_class()
+
+    @override
+    def execute(self) -> None:
+        try:
+            name = self.argv[1]
+        except IndexError:
+            super().execute()
+        else:
+            if name in settings.PATHS:
+                utility = self.__class__([self.prog_name, name, *self.argv[2:]])
+                super(ManagementUtility, utility).execute()
+            elif alias_exprs := settings.ALIASES.get(name):
+                for alias_expr in alias_exprs:
+                    argv = alias_expr.split()
+
+                    utility = ManagementUtility([self.prog_name, *argv])
+                    utility.execute()
+            else:
+                super().execute()
+
+
+def execute_from_command_line(argv: list[str] | None = None) -> None:
+    utility = ManagementUtility(argv)
+    utility.execute()