django-spire 0.16.13__tar.gz → 0.17.0__tar.gz

{django_spire-0.16.13 → django_spire-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-spire
-Version: 0.16.13
+Version: 0.17.0
 Summary: A project for Django Spire
 Author-email: Brayden Carlson <braydenc@stratusadv.com>, Nathan Johnson <nathanj@stratusadv.com>
 License: Copyright (c) 2024 Stratus Advanced Technologies and Contributors.

{django_spire-0.16.13 → django_spire-0.17.0}/django_spire/consts.py

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

django_spire-0.17.0/django_spire/core/management/commands/spire_startapp.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.core.management.base import BaseCommand
+
+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 (
+    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 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.
+
+        :param args: Positional arguments (not used).
+        :param kwargs: Keyword arguments (not used).
+        """
+
+        filesystem = FileSystem()
+        path_config = PathConfig.default()
+        path_resolver = PathResolver()
+        registry = AppRegistry()
+        reporter = Reporter(self)
+
+        template_engine = TemplateEngine()
+        template_processor = TemplateProcessor(template_engine, filesystem)
+
+        validator = AppValidator(reporter, registry, path_resolver, filesystem)
+
+        user_input_collector = UserInputCollector(reporter, validator)
+
+        config_factory = AppConfigFactory(path_resolver)
+
+        template_builder = TemplateBuilder(reporter)
+
+        app_generator = AppGenerator(filesystem, template_processor, reporter, path_config)
+        # template_generator = TemplateGenerator(filesystem, template_processor, reporter, path_config)
+
+        user_inputs = user_input_collector.collect_all_inputs()
+        app_path = user_inputs['app_path']
+
+        validator.validate_app_format(app_path)
+
+        config = config_factory.create_config(app_path, user_inputs)
+        validator.validate_root_app(config.components)
+
+        reporter.write(
+            f'\nChecking app components: {config.components}\n',
+            reporter.style_notice
+        )
+
+        missing = registry.get_missing_components(config.components)
+
+        if missing:
+            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]]:
+                module_config = config_factory.create_config(module, user_inputs)
+                app_generator.generate(module_config)
+                # template_generator.generate(module_config)
+
+            reporter.report_installed_apps_suggestion(missing)
+        else:
+            reporter.write('All component(s) exist.', reporter.style_success)

django_spire-0.17.0/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-0.17.0/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-0.17.0/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-0.17.0/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)

django_spire-0.17.0/django_spire/core/management/commands/spire_startapp_pkg/generator.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.core.management.base import CommandError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from django_spire.core.management.commands.spire_startapp_pkg.config import AppConfig, PathConfig
+    from django_spire.core.management.commands.spire_startapp_pkg.filesystem import FileSystemInterface
+    from django_spire.core.management.commands.spire_startapp_pkg.processor import TemplateProcessor
+    from django_spire.core.management.commands.spire_startapp_pkg.reporter import ReporterInterface
+
+
+class AppGenerator:
+    """
+    Generates Django app structures from templates.
+
+    This class handles the creation of new Django apps by copying template
+    files and processing them with user-provided configuration.
+    """
+
+    def __init__(
+        self,
+        filesystem: FileSystemInterface,
+        processor: TemplateProcessor,
+        reporter: ReporterInterface,
+        path_config: PathConfig
+    ):
+        """
+        Initializes the AppGenerator with required dependencies.
+
+        :param filesystem: File system interface for file operations.
+        :param processor: Template processor for replacing placeholders.
+        :param reporter: Reporter for user feedback and output.
+        :param path_config: Configuration containing template paths.
+        """
+
+        self._filesystem = filesystem
+        self._path_config = path_config
+        self._processor = processor
+        self._reporter = reporter
+
+    def generate(self, config: AppConfig) -> None:
+        """
+        Generates a new Django app from templates.
+
+        Creates the app directory, copies template files, and processes
+        them with user configuration. Skips generation if the app already exists.
+
+        :param config: Configuration for the app to generate.
+        """
+
+        if self._filesystem.has_content(config.destination):
+            self._reporter.report_app_exists(config.app_path, config.destination)
+            return
+
+        self._validate_template_exists(self._path_config.app_template, 'app template')
+        self._reporter.report_creating_app(config.app_path, config.destination)
+
+        self._filesystem.create_directory(config.destination)
+        self._filesystem.copy_tree(self._path_config.app_template, config.destination)
+
+        self._processor.process_app_templates(
+            config.destination,
+            config.components,
+            config.user_inputs
+        )
+
+        self._reporter.report_app_creation_success(config.app_path)
+
+    def _validate_template_exists(self, path: Path, template_type: str) -> None:
+        """
+        Validates that a template directory exists.
+
+        :param path: Path to the template directory.
+        :param template_type: Description of the template type for error messages.
+        :raises CommandError: If the template directory does not exist.
+        """
+
+        if not self._filesystem.exists(path):
+            self._reporter.write('\n', self._reporter.style_notice)
+
+            message = (
+                f'Template directory "{path}" is missing. '
+                f'Ensure you have a valid {template_type}.'
+            )
+
+            raise CommandError(message)
+
+
+class TemplateGenerator:
+    """
+    Generates HTML templates for Django apps.
+
+    This class handles the creation of HTML template files including
+    forms, cards, pages, and items for new Django apps.
+    """
+
+    def __init__(
+        self,
+        filesystem: FileSystemInterface,
+        processor: TemplateProcessor,
+        reporter: ReporterInterface,
+        path_config: PathConfig
+    ):
+        """
+        Initializes the TemplateGenerator with required dependencies.
+
+        :param filesystem: File system interface for file operations.
+        :param processor: Template processor for replacing placeholders.
+        :param reporter: Reporter for user feedback and output.
+        :param path_config: Configuration containing template paths.
+        """
+
+        self._filesystem = filesystem
+        self._path_config = path_config
+        self._processor = processor
+        self._reporter = reporter
+
+    def generate(self, config: AppConfig) -> None:
+        """
+        Generates HTML templates for a new Django app.
+
+        Creates the template directory, copies template files, and processes
+        them with user configuration. Skips generation if templates already exist.
+
+        :param config: Configuration for the templates to generate.
+        """
+
+        if self._filesystem.has_content(config.template_destination):
+            self._reporter.report_templates_exist(config.app_path, config.template_destination)
+            return
+
+        self._validate_template_exists(self._path_config.html_template, 'templates template')
+        self._reporter.report_creating_templates(config.app_path, config.template_destination)
+
+        self._filesystem.create_directory(config.template_destination)
+        self._filesystem.copy_tree(self._path_config.html_template, config.template_destination)
+
+        self._processor.process_html_templates(
+            config.template_destination,
+            config.components,
+            config.user_inputs
+        )
+
+        self._reporter.report_templates_creation_success(config.app_path)
+
+    def _validate_template_exists(self, path: Path, template_type: str) -> None:
+        """
+        Validates that a template directory exists.
+
+        :param path: Path to the template directory.
+        :param template_type: Description of the template type for error messages.
+        :raises CommandError: If the template directory does not exist.
+        """
+
+        if not self._filesystem.exists(path):
+            self._reporter.write('\n', self._reporter.style_notice)
+
+            message = (
+                f'Template directory "{path}" is missing. '
+                f'Ensure you have a valid {template_type}.'
+            )
+
+            raise CommandError(message)