django-spire 0.16.13__py3-none-any.whl → 0.17.1__py3-none-any.whl

django_spire/consts.py

@@ -1,4 +1,4 @@
-__VERSION__ = '0.16.13'
+__VERSION__ = '0.17.1'
 
 
 AI_CHAT_WORKFLOW_SENDER_SETTINGS_NAME = 'AI_CHAT_WORKFLOW_NAME'

django_spire/core/management/commands/spire_startapp.py

@@ -1,80 +1,118 @@
 from __future__ import annotations
 
-import django_spire
+from typing import TYPE_CHECKING
 
-from pathlib import Path
+from django.core.management.base import BaseCommand
 
-from django.conf import settings
-from django.core.management.base import BaseCommand, CommandError
-
-from django_spire.core.management.commands.spire_startapp_pkg.manager import (
-        AppManager,
-        HTMLTemplateManager,
+from django_spire.core.management.commands.spire_startapp_pkg.builder import TemplateBuilder
+from django_spire.core.management.commands.spire_startapp_pkg.config import (
+    AppConfigFactory,
+    PathConfig,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.filesystem import FileSystem
+from django_spire.core.management.commands.spire_startapp_pkg.generator import (
+    AppGenerator,
+    # TemplateGenerator,
 )
 from django_spire.core.management.commands.spire_startapp_pkg.processor import (
-        AppTemplateProcessor,
-        HTMLTemplateProcessor
+    TemplateEngine,
+    TemplateProcessor,
 )
+from django_spire.core.management.commands.spire_startapp_pkg.registry import AppRegistry
 from django_spire.core.management.commands.spire_startapp_pkg.reporter import Reporter
+from django_spire.core.management.commands.spire_startapp_pkg.resolver import PathResolver
+from django_spire.core.management.commands.spire_startapp_pkg.user_input import UserInputCollector
+from django_spire.core.management.commands.spire_startapp_pkg.validator import AppValidator
+
+if TYPE_CHECKING:
+    from typing import Any
 
 
 class Command(BaseCommand):
+    """
+    Django management command for creating custom Spire apps.
+
+    This command guides users through an interactive wizard to create a new Django app
+    with a pre-configured structure including models, views, forms, services, and templates.
+    It handles nested app structures (e.g., app.parent.child) and validates that all
+    parent apps are properly registered before creating child apps.
+    """
+
     help = 'Create a custom Spire app.'
 
-    def __init__(self):
-        super().__init__()
+    def handle(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Main entry point for the management command.
+
+        Orchestrates the entire app creation process by initializing helper classes,
+        collecting user input through an interactive wizard, validating the app structure,
+        generating app files and templates, and providing feedback to the user.
 
-        self.app_base = Path(settings.BASE_DIR)
-        self.app_template = Path(django_spire.__file__).parent / 'core/management/commands/spire_startapp_pkg/template/app'
+        :param args: Positional arguments (not used).
+        :param kwargs: Keyword arguments (not used).
+        """
 
-        self.template_base = self.app_base / 'templates'
-        self.html_template = Path(django_spire.__file__).parent / 'template/templates'
+        filesystem = FileSystem()
+        path_config = PathConfig.default()
+        path_resolver = PathResolver()
+        registry = AppRegistry()
+        reporter = Reporter(self)
 
-        self.app_manager = AppManager(self.app_base, self.app_template)
-        self.app_processor = AppTemplateProcessor()
+        template_engine = TemplateEngine()
+        template_processor = TemplateProcessor(template_engine, filesystem)
 
-        self.html_manager = HTMLTemplateManager(self.template_base, self.html_template)
-        self.html_processor = HTMLTemplateProcessor()
+        validator = AppValidator(reporter, registry, path_resolver, filesystem)
 
-        self.reporter = Reporter(self)
+        user_input_collector = UserInputCollector(reporter, validator)
 
-    def get_app_names(self) -> list[str]:
-        from django.apps import apps
-        return [config.name for config in apps.get_app_configs()]
+        config_factory = AppConfigFactory(path_resolver)
 
-    def handle(self, *_args, **kwargs) -> None:
-        app = input('Enter the path of the app (e.g., "app.maintenance.work_order"):')
+        template_builder = TemplateBuilder(reporter)
 
-        if not app:
-            raise CommandError(self.style.ERROR('The app name is missing'))
+        app_generator = AppGenerator(filesystem, template_processor, reporter, path_config)
+        # template_generator = TemplateGenerator(filesystem, template_processor, reporter, path_config)
 
-        self.app_manager.validate_app_name_format(app)
+        user_inputs = user_input_collector.collect_all_inputs()
+        app_path = user_inputs['app_path']
 
-        components = self.app_manager.parse_app_name(app)
-        self.app_manager.is_valid_root_apps(components)
+        validator.validate_app_format(app_path)
 
-        registry = self.get_app_names()
+        config = config_factory.create_config(app_path, user_inputs)
+        validator.validate_root_app(config.components)
 
-        self.reporter.write(
-            f'Checking app components: {components}\n\n',
-            self.style.NOTICE
+        reporter.write(
+            f'\nChecking app components: {config.components}\n',
+            reporter.style_notice
         )
 
-        missing = self.app_manager.get_missing_components(components, registry)
+        missing = registry.get_missing_components(config.components)
 
         if missing:
-            self.reporter.report_missing_components(missing)
-            self.reporter.report_app_tree_structure(self.app_base, components, registry, self.app_template)
-            # self.reporter.report_html_tree_structure(self.template_base, components, registry, self.html_template)
-
-            if not self.reporter.prompt_for_confirmation('\nProceed with app creation? (y/n): '):
-                self.reporter.write('App creation aborted.', self.style.ERROR)
+            reporter.report_missing_components(missing)
+
+            template_builder.build_app_tree_structure(
+                path_resolver.get_base_dir(),
+                config.components,
+                registry.get_installed_apps(),
+                path_config.app_template
+            )
+
+            # template_builder.build_html_tree_structure(
+            #     path_resolver.get_base_dir(),
+            #     config.components,
+            #     registry.get_installed_apps(),
+            #     path_config.html_template
+            # )
+
+            if not reporter.prompt_confirmation('\nProceed with app creation? (y/n): '):
+                reporter.write('App creation aborted.', reporter.style_error)
                 return
 
             for module in [missing[-1]]:
-                self.app_manager.create_custom_app(module, self.app_processor, self.reporter)
-                # self.html_manager.create_custom_templates(module, self.html_processor, self.reporter)
+                module_config = config_factory.create_config(module, user_inputs)
+                app_generator.generate(module_config)
+                # template_generator.generate(module_config)
 
-            self.reporter.report_installed_apps_suggestion(missing)
+            reporter.report_installed_apps_suggestion(missing)
         else:
-            self.reporter.write('All component(s) exist.', self.style.SUCCESS)
+            reporter.write('All component(s) exist.', reporter.style_success)

django_spire/core/management/commands/spire_startapp_pkg/__init__.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from django_spire.core.management.commands.spire_startapp_pkg.builder import TemplateBuilder
+from django_spire.core.management.commands.spire_startapp_pkg.config import (
+    AppConfig,
+    AppConfigFactory,
+    PathConfig,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.filesystem import (
+    FileSystem,
+    FileSystemInterface,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.generator import (
+    AppGenerator,
+    TemplateGenerator,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.maps import generate_replacement_map
+from django_spire.core.management.commands.spire_startapp_pkg.permissions import PermissionInheritanceHandler
+from django_spire.core.management.commands.spire_startapp_pkg.processor import (
+    TemplateEngine,
+    TemplateProcessor,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.registry import (
+    AppRegistry,
+    AppRegistryInterface,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.reporter import (
+    Reporter,
+    ReporterInterface,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.resolver import (
+    PathResolver,
+    PathResolverInterface,
+)
+from django_spire.core.management.commands.spire_startapp_pkg.user_input import UserInputCollector
+from django_spire.core.management.commands.spire_startapp_pkg.validator import AppValidator
+
+
+__all__ = [
+    'AppConfig',
+    'AppConfigFactory',
+    'AppGenerator',
+    'AppRegistry',
+    'AppRegistryInterface',
+    'AppValidator',
+    'FileSystem',
+    'FileSystemInterface',
+    'PathConfig',
+    'PathResolver',
+    'PathResolverInterface',
+    'PermissionInheritanceHandler',
+    'Reporter',
+    'ReporterInterface',
+    'TemplateBuilder',
+    'TemplateEngine',
+    'TemplateGenerator',
+    'TemplateProcessor',
+    'UserInputCollector',
+    'generate_replacement_map',
+]

django_spire/core/management/commands/spire_startapp_pkg/builder.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django_spire.core.management.commands.spire_startapp_pkg.maps import generate_replacement_map
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from django_spire.core.management.commands.spire_startapp_pkg.reporter import ReporterInterface
+
+
+class TemplateBuilder:
+    """
+    Builds and displays tree structures for app and template creation.
+
+    This class generates visual representations of the file structure
+    that will be created for new apps and their associated templates.
+    """
+
+    def __init__(self, reporter: ReporterInterface):
+        """
+        Initializes the TemplateBuilder with a reporter for output.
+
+        :param reporter: Reporter instance for displaying output to the user.
+        """
+
+        self._reporter = reporter
+
+    def build_app_tree_structure(
+        self,
+        base: Path,
+        components: list[str],
+        registry: list[str],
+        template: Path
+    ) -> None:
+        """
+        Displays a tree structure of the app files that will be created.
+
+        This method shows the user what Python files, directories, and modules
+        will be generated for the new Django app before creation.
+
+        :param base: Base directory where the app will be created.
+        :param components: List of app path components (e.g., ['app', 'human_resource', 'employee']).
+        :param registry: List of already registered apps in the Django project.
+        :param template: Path to the app template directory.
+        """
+
+        self._reporter.report_tree_structure(
+            title='\nThe following app(s) will be created:\n\n',
+            base=base,
+            components=components,
+            registry=registry,
+            template=template,
+            formatter=self._reporter.format_app_item,
+            transformation=self._reporter.transform_app_component,
+        )
+
+    def build_html_tree_structure(
+        self,
+        base: Path,
+        components: list[str],
+        registry: list[str],
+        template: Path
+    ) -> None:
+        """
+        Displays a tree structure of the HTML template files that will be created.
+
+        This method shows the user what HTML templates, cards, forms, and pages
+        will be generated for the new Django app before creation.
+
+        :param base: Base directory where templates will be created.
+        :param components: List of app path components.
+        :param registry: List of already registered apps in the Django project.
+        :param template: Path to the HTML template directory.
+        """
+
+        replacement = generate_replacement_map(components)
+
+        def html_formatter_with_replacement(item: Path) -> str:
+            return self._reporter.format_html_item(item, replacement)
+
+        self._reporter.report_tree_structure(
+            title='\nThe following template(s) will be created:\n\n',
+            base=base,
+            components=components,
+            registry=registry,
+            template=template,
+            formatter=html_formatter_with_replacement,
+            transformation=self._reporter.transform_html_component,
+        )

django_spire/core/management/commands/spire_startapp_pkg/config.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import django_spire
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from django_spire.core.management.commands.spire_startapp_pkg.resolver import PathResolverInterface
+
+
+@dataclass(frozen=True)
+class PathConfig:
+    """
+    Configuration for template directory paths.
+
+    This class holds the paths to the app and HTML template directories
+    used for generating new Django apps.
+    """
+
+    app_template: Path
+    html_template: Path
+
+    @classmethod
+    def default(cls) -> PathConfig:
+        """
+        Creates a default PathConfig with standard template locations.
+
+        :return: PathConfig instance with paths to default app and HTML templates.
+        """
+
+        base = Path(django_spire.__file__).parent
+
+        return cls(
+            app_template=base / 'core/management/commands/spire_startapp_pkg/template/app',
+            html_template=base / 'core/management/commands/spire_startapp_pkg/template/templates'
+        )
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """
+    Configuration for a new Django app being created.
+
+    This class contains all the information needed to generate a new app,
+    including its name, path, components, destinations, and user-provided inputs.
+    """
+
+    app_name: str
+    app_path: str
+    components: list[str]
+    destination: Path
+    template_destination: Path
+    user_inputs: dict[str, str]
+
+    @property
+    def app_label(self) -> str:
+        """
+        Gets the Django app label.
+
+        :return: The app label, either from user input or derived from app name.
+        """
+
+        return self.user_inputs.get('app_label', self.app_name.lower())
+
+    @property
+    def model_name(self) -> str:
+        """
+        Gets the model class name.
+
+        :return: The model name, either from user input or TitleCase version of app name.
+        """
+
+        default = ''.join(word.title() for word in self.app_name.split('_'))
+        return self.user_inputs.get('model_name', default)
+
+
+class AppConfigFactory:
+    """
+    Factory class for creating AppConfig instances.
+
+    This class handles the creation of AppConfig objects by resolving
+    paths and processing user inputs.
+    """
+
+    def __init__(self, path_resolver: PathResolverInterface):
+        """
+        Initializes the factory with a path resolver.
+
+        :param path_resolver: Path resolver for determining file system locations.
+        """
+
+        self._path_resolver = path_resolver
+
+    def create_config(self, app_path: str, user_inputs: dict[str, str]) -> AppConfig:
+        """
+        Creates an AppConfig from an app path and user inputs.
+
+        :param app_path: Dot-separated app path (e.g., 'app.human_resource.employee').
+        :param user_inputs: Dictionary of user-provided configuration values.
+        :return: Configured AppConfig instance ready for app generation.
+        """
+
+        components = app_path.split('.')
+        app_name = user_inputs.get('app_name', components[-1])
+
+        return AppConfig(
+            app_name=app_name,
+            app_path=app_path,
+            components=components,
+            destination=self._path_resolver.get_app_destination(components),
+            template_destination=self._path_resolver.get_template_destination(components),
+            user_inputs=user_inputs
+        )

django_spire/core/management/commands/spire_startapp_pkg/filesystem.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import shutil
+
+from typing import Protocol, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import Iterator
+
+
+class FileSystemInterface(Protocol):
+    """
+    Protocol defining the interface for file system operations.
+
+    This protocol specifies the methods required for interacting with
+    the file system during app creation.
+    """
+
+    def copy_tree(self, src: Path, dst: Path) -> None: ...
+    def create_directory(self, path: Path) -> None: ...
+    def exists(self, path: Path) -> bool: ...
+    def has_content(self, path: Path) -> bool: ...
+    def iterate_files(self, path: Path, pattern: str) -> Iterator[Path]: ...
+    def read_file(self, path: Path) -> str: ...
+    def rename(self, old: Path, new: Path) -> None: ...
+    def write_file(self, path: Path, content: str) -> None: ...
+
+
+class FileSystem:
+    """
+    Implementation of file system operations for app generation.
+
+    This class provides concrete implementations of file system operations
+    needed to create directories, copy templates, and manage files.
+    """
+
+    def copy_tree(self, src: Path, dst: Path) -> None:
+        """
+        Copies an entire directory tree from source to destination.
+
+        Ignores Python cache directories and compiled files during the copy.
+
+        :param src: Source directory path to copy from.
+        :param dst: Destination directory path to copy to.
+        """
+
+        shutil.copytree(
+            src,
+            dst,
+            dirs_exist_ok=True,
+            ignore=shutil.ignore_patterns('__pycache__', '*.pyc')
+        )
+
+    def create_directory(self, path: Path) -> None:
+        """
+        Creates a directory and all necessary parent directories.
+
+        :param path: Directory path to create.
+        """
+
+        path.mkdir(parents=True, exist_ok=True)
+
+    def exists(self, path: Path) -> bool:
+        """
+        Checks if a path exists on the file system.
+
+        :param path: Path to check for existence.
+        :return: True if the path exists, False otherwise.
+        """
+
+        return path.exists()
+
+    def has_content(self, path: Path) -> bool:
+        """
+        Checks if a directory exists and contains any files or subdirectories.
+
+        :param path: Directory path to check.
+        :return: True if the directory exists and has content, False otherwise.
+        """
+
+        return self.exists(path) and any(path.iterdir())
+
+    def iterate_files(self, path: Path, pattern: str) -> Iterator[Path]:
+        """
+        Recursively finds all files matching a pattern in a directory.
+
+        :param path: Directory path to search within.
+        :param pattern: Glob pattern to match files (e.g., '*.py', '*.template').
+        :return: Iterator of matching file paths.
+        """
+
+        return path.rglob(pattern)
+
+    def read_file(self, path: Path) -> str:
+        """
+        Reads the entire contents of a text file.
+
+        :param path: File path to read.
+        :return: File contents as a string.
+        """
+
+        with open(path, 'r', encoding='utf-8') as handle:
+            return handle.read()
+
+    def rename(self, old: Path, new: Path) -> None:
+        """
+        Renames a file or directory.
+
+        :param old: Current path of the file or directory.
+        :param new: New path for the file or directory.
+        """
+
+        old.rename(new)
+
+    def write_file(self, path: Path, content: str) -> None:
+        """
+        Writes content to a text file.
+
+        :param path: File path to write to.
+        :param content: String content to write to the file.
+        """
+
+        with open(path, 'w', encoding='utf-8') as handle:
+            handle.write(content)