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

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

@@ -1,41 +1,186 @@
 from __future__ import annotations
 
-from typing_extensions import Callable, TYPE_CHECKING
-
-from django_spire.core.management.commands.spire_startapp_pkg.constants import (
-    INDENTATION,
-    ICON_FOLDER_OPEN,
-    ICON_FOLDER_CLOSED,
-    ICON_FILE
-)
+from string import Template
+from typing import Protocol, TYPE_CHECKING
+
 from django_spire.core.management.commands.spire_startapp_pkg.maps import generate_replacement_map
 
 if TYPE_CHECKING:
     from pathlib import Path
+    from typing import Callable
 
     from django.core.management.base import BaseCommand
 
 
+class ReporterInterface(Protocol):
+    """
+    Protocol defining the interface for reporting and user interaction.
+
+    This protocol specifies methods for displaying messages, prompts,
+    and tree structures to the user during app creation.
+    """
+
+    def prompt_confirmation(self, message: str) -> bool: ...
+    def report_app_creation_success(self, app: str) -> None: ...
+    def report_app_exists(self, app: str, destination: Path) -> None: ...
+    def report_creating_app(self, app: str, destination: Path) -> None: ...
+    def report_creating_templates(self, app: str, destination: Path) -> None: ...
+    def report_installed_apps_suggestion(self, missing_components: list[str]) -> None: ...
+    def report_missing_components(self, missing_components: list[str]) -> None: ...
+    def report_templates_creation_success(self, app: str) -> None: ...
+    def report_templates_exist(self, app: str, destination: Path) -> None: ...
+    def write(self, message: str, style: Callable[[str], str]) -> None: ...
+
+
 class Reporter:
+    """
+    Handles user interaction and console output for the app creation command.
+
+    This class manages all console output including status messages, tree
+    structures, confirmations, and styled text for the app creation process.
+    """
+
+    ICON_FILE = '📄'
+    ICON_FOLDER_CLOSED = '📁'
+    ICON_FOLDER_OPEN = '📂'
+    INDENTATION = '    '
+
     def __init__(self, command: BaseCommand):
+        """
+        Initializes the reporter with a Django management command.
+
+        :param command: Django BaseCommand instance for accessing stdout and styling.
+        """
+
         self.command = command
+        self.style_error = command.style.ERROR
+        self.style_notice = command.style.NOTICE
+        self.style_success = command.style.SUCCESS
+        self.style_warning = command.style.WARNING
 
-    def _apply_replacement(self, name: str, replacement: dict[str, str]) -> str:
-        for old, new in replacement.items():
-            name = name.replace(old, new)
+    def format_app_item(self, item: Path) -> str:
+        """
+        Formats an app file or directory name for display.
 
-        return name
+        Removes the .template extension from Python files.
 
-    def _sort_template_items(self, path: Path) -> tuple[bool, str]:
-        return (path.is_file(), path.name.lower())
+        :param item: Path to the item to format.
+        :return: Formatted item name.
+        """
 
-    def _app_transformation(self, _index: int, component: str) -> str:
-        return component
+        return item.name.replace('.py.template', '.py')
 
-    def _html_transformation(self, index: int, component: str) -> str:
-        return 'templates' if index == 0 else component
+    def format_html_item(self, item: Path, replacement: dict[str, str]) -> str:
+        """
+        Formats an HTML template file or directory name for display.
+
+        Applies variable replacements and removes .template extensions.
+
+        :param item: Path to the item to format.
+        :param replacement: Dictionary of placeholder replacements.
+        :return: Formatted item name with placeholders replaced.
+        """
+
+        if item.is_dir():
+            return item.name
+
+        template = Template(item.name)
+        filename = template.safe_substitute(replacement)
+
+        if filename.endswith('.template'):
+            filename = filename.replace('.template', '')
+
+        return filename
+
+    def prompt_confirmation(self, message: str) -> bool:
+        """
+        Prompts the user for yes/no confirmation.
+
+        :param message: Confirmation prompt message.
+        :return: True if user responds with 'y', False otherwise.
+        """
+
+        return input(message).strip().lower() == 'y'
+
+    def report_app_creation_success(self, app: str) -> None:
+        """
+        Reports successful creation of an app.
+
+        :param app: Name of the app that was created.
+        """
+
+        self.write(f'Successfully created app: {app}', self.style_success)
+
+    def report_app_exists(self, app: str, destination: Path) -> None:
+        """
+        Reports that an app already exists at the destination.
+
+        :param app: Name of the app.
+        :param destination: Path where the app already exists.
+        """
+
+        self.write(f'The app "{app}" already exists at {destination}', self.style_warning)
+
+    def report_creating_app(self, app: str, destination: Path) -> None:
+        """
+        Reports that an app is being created.
+
+        :param app: Name of the app being created.
+        :param destination: Path where the app will be created.
+        """
+
+        self.write(f'Creating app "{app}" at {destination}', self.style_notice)
+
+    def report_creating_templates(self, app: str, destination: Path) -> None:
+        """
+        Reports that templates are being created for an app.
+
+        :param app: Name of the app.
+        :param destination: Path where templates will be created.
+        """
+
+        self.write(f'Creating templates for app "{app}" at {destination}', self.style_notice)
+
+    def report_installed_apps_suggestion(self, missing_components: list[str]) -> None:
+        """
+        Suggests which app to add to INSTALLED_APPS in settings.py.
+
+        :param missing_components: List of missing app components.
+        """
+
+        self.write('\nPlease add the following to INSTALLED_APPS in settings.py:', self.style_notice)
+        self.write(f'\n {missing_components[-1]}', lambda x: x)
+
+    def report_missing_components(self, missing_components: list[str]) -> None:
+        """
+        Reports which app components are not yet registered.
+
+        :param missing_components: List of unregistered app component paths.
+        """
+
+        self.write('The following are not registered apps:', self.style_warning)
+        self.write('\n'.join(f' - {app}' for app in missing_components), lambda x: x)
+
+    def report_templates_creation_success(self, app: str) -> None:
+        """
+        Reports successful creation of templates for an app.
+
+        :param app: Name of the app whose templates were created.
+        """
+
+        self.write(f'Successfully created templates for app: {app}', self.style_success)
+
+    def report_templates_exist(self, app: str, destination: Path) -> None:
+        """
+        Reports that templates already exist for an app.
+
+        :param app: Name of the app.
+        :param destination: Path where templates already exist.
+        """
 
-    def _report_tree_structure(
+        self.write(f'The templates for app "{app}" already exist at {destination}', self.style_warning)
+
+    def report_tree_structure(
         self,
         title: str,
         base: Path,
@@ -45,8 +190,23 @@ class Reporter:
         formatter: Callable[[Path], str],
         transformation: Callable[[int, str], str] | None = None,
     ) -> None:
+        """
+        Displays a tree structure of files and directories that will be created.
+
+        Shows a hierarchical view of the app structure with appropriate icons
+        and formatting for files and directories.
+
+        :param title: Title to display above the tree structure.
+        :param base: Base directory path.
+        :param components: List of app path components.
+        :param registry: List of registered apps.
+        :param template: Path to template directory.
+        :param formatter: Function to format item names for display.
+        :param transformation: Optional function to transform component names.
+        """
+
         if transformation is None:
-            transformation = self._app_transformation
+            transformation = self.transform_app_component
 
         self.command.stdout.write(title)
         current = base
@@ -58,16 +218,61 @@ class Reporter:
             component = transformation(i, component)
             current = current / component
             app = '.'.join(latest)
-            indent = INDENTATION * i
+            indent = self.INDENTATION * i
 
-            self.command.stdout.write(f'{indent}{ICON_FOLDER_OPEN} {component}/')
+            self.command.stdout.write(f'{indent}{self.ICON_FOLDER_OPEN} {component}/')
 
             if i == len(components) - 1 and app not in registry and template.exists():
                 def local_formatter(item: Path, mapping: dict[str, str] = replacement) -> str:
                     base_name = formatter(item)
                     return self._apply_replacement(base_name, mapping)
 
-                self._show_tree_from_template(template, indent + INDENTATION, local_formatter)
+                self._show_tree_from_template(template, indent + self.INDENTATION, local_formatter)
+
+    def transform_app_component(self, _index: int, component: str) -> str:
+        """
+        Transforms an app component name (default: no transformation).
+
+        :param _index: Index of the component in the path.
+        :param component: Component name to transform.
+        :return: Transformed component name.
+        """
+
+        return component
+
+    def transform_html_component(self, index: int, component: str) -> str:
+        """
+        Transforms an HTML component name (replaces first component with 'templates').
+
+        :param index: Index of the component in the path.
+        :param component: Component name to transform.
+        :return: Transformed component name.
+        """
+
+        return 'templates' if index == 0 else component
+
+    def write(self, message: str, style: Callable[[str], str]) -> None:
+        """
+        Writes a styled message to the console.
+
+        :param message: Message to display.
+        :param style: Styling function to apply to the message.
+        """
+
+        self.command.stdout.write(style(message))
+
+    def _apply_replacement(self, name: str, replacement: dict[str, str]) -> str:
+        """
+        Applies placeholder replacements to a name string.
+
+        :param name: String containing placeholders.
+        :param replacement: Dictionary mapping placeholders to values.
+        :return: String with placeholders replaced.
+        """
+
+        for old, new in replacement.items():
+            name = name.replace(old, new)
+        return name
 
     def _show_tree_from_template(
         self,
@@ -75,6 +280,14 @@ class Reporter:
         indent: str,
         formatter: Callable[[Path], str]
     ) -> None:
+        """
+        Recursively displays a tree structure from a template directory.
+
+        :param template: Template directory path to display.
+        :param indent: Current indentation level.
+        :param formatter: Function to format item names.
+        """
+
         ignore = {'__init__.py', '__pycache__'}
 
         items = sorted(template.iterdir(), key=self._sort_template_items)
@@ -83,98 +296,22 @@ class Reporter:
             if item.name in ignore:
                 continue
 
-            icon = ICON_FOLDER_CLOSED if item.is_dir() else ICON_FILE
+            icon = self.ICON_FOLDER_CLOSED if item.is_dir() else self.ICON_FILE
             self.command.stdout.write(f'{indent}{icon} {formatter(item)}')
 
             if item.is_dir():
                 self._show_tree_from_template(
                     item,
-                    indent + INDENTATION,
+                    indent + self.INDENTATION,
                     formatter
                 )
 
-    def _app_formatter(self, item: Path) -> str:
-        return item.name.replace('.py.template', '.py')
-
-    def _html_formatter(self, item: Path, replacement: dict[str, str]) -> str:
-        if item.is_dir():
-            return item.name
-
-        return self._apply_replacement(item.name, replacement)
-
-    def report_app_tree_structure(
-        self,
-        base: Path,
-        components: list[str],
-        registry: list[str],
-        template: Path
-    ) -> None:
-        self._report_tree_structure(
-            title='\nThe following app(s) will be created:\n\n',
-            base=base,
-            components=components,
-            registry=registry,
-            template=template,
-            formatter=self._app_formatter,
-            transformation=self._app_transformation,
-        )
-
-    def report_html_tree_structure(
-        self,
-        base: Path,
-        components: list[str],
-        registry: list[str],
-        template: Path
-    ) -> None:
-        replacement = generate_replacement_map(components)
-
-        def html_formatter_with_replacement(item: Path) -> str:
-            return self._html_formatter(item, replacement)
-
-        self._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._html_transformation,
-        )
-
-    def prompt_for_confirmation(self, message: str) -> bool:
-        return input(message).strip().lower() == 'y'
-
-    def report_missing_components(self, missing_components: list[str]) -> None:
-        self.command.stdout.write(self.command.style.WARNING('The following are not registered apps:'))
-        self.command.stdout.write('\n'.join(f' - {app}' for app in missing_components))
-
-    def report_installed_apps_suggestion(self, missing_components: list[str]) -> None:
-        self.command.stdout.write(self.command.style.NOTICE('\nPlease add the following to INSTALLED_APPS in settings.py:'))
-        self.command.stdout.write(f'\n {missing_components[-1]}')
-
-    def report_app_creation_success(self, app: str) -> None:
-        message = f'Successfully created app: {app}'
-        self.write(message, self.command.style.SUCCESS)
-
-    def report_app_exists(self, app: str, destination: Path) -> None:
-        message = f'The app "{app}" already exists at {destination}'
-        self.write(message, self.command.style.WARNING)
-
-    def report_creating_app(self, app: str, destination: Path) -> None:
-        message = f'Creating app "{app}" at {destination}'
-        self.write(message, self.command.style.NOTICE)
-
-    def report_templates_exist(self, app: str, destination: Path) -> None:
-        message = f'The templates for app "{app}" already exist at {destination}'
-        self.write(message, self.command.style.WARNING)
-
-    def report_creating_templates(self, app: str, destination: Path) -> None:
-        message = f'Creating templates for app "{app}" at {destination}'
-        self.write(message, self.command.style.NOTICE)
+    def _sort_template_items(self, path: Path) -> tuple[bool, str]:
+        """
+        Sorts template items with directories first, then by name.
 
-    def report_templates_creation_success(self, app: str) -> None:
-        message = f'Successfully created templates for app: {app}'
-        self.write(message, self.command.style.SUCCESS)
+        :param path: Path to sort.
+        :return: Tuple for sorting (is_file, lowercase_name).
+        """
 
-    def write(self, message: str, func: Callable[[str], str]) -> None:
-        self.command.stdout.write(func(message))
+        return (path.is_file(), path.name.lower())

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

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from django.conf import settings
+
+
+class PathResolverInterface(Protocol):
+    """
+    Protocol defining the interface for resolving file system paths.
+
+    This protocol specifies methods for determining where apps and
+    templates should be created in the file system.
+    """
+
+    def get_app_destination(self, components: list[str]) -> Path: ...
+    def get_base_dir(self) -> Path: ...
+    def get_template_destination(self, components: list[str]) -> Path: ...
+    def get_template_dir(self) -> Path: ...
+
+
+class PathResolver:
+    """
+    Resolves file system paths for app and template creation.
+
+    This class determines where new Django apps and their templates
+    should be created based on project structure and configuration.
+    """
+
+    def __init__(self, base_dir: Path | None = None, template_dir: Path | None = None):
+        """
+        Initializes the path resolver with base directories.
+
+        :param base_dir: Optional base directory for the Django project (defaults to settings.BASE_DIR).
+        :param template_dir: Optional template directory (defaults to base_dir/templates).
+        """
+
+        self._base_dir = base_dir or Path(settings.BASE_DIR)
+        self._template_dir = template_dir or self._base_dir / 'templates'
+
+    def get_app_destination(self, components: list[str]) -> Path:
+        """
+        Gets the destination path for a new app based on its components.
+
+        For components ['app', 'human_resource', 'employee'], returns
+        Path('base_dir/app/human_resource/employee').
+
+        :param components: List of app path components.
+        :return: Full path where the app should be created.
+        """
+
+        return self._base_dir.joinpath(*components)
+
+    def get_base_dir(self) -> Path:
+        """
+        Gets the project's base directory.
+
+        :return: Base directory path for the Django project.
+        """
+
+        return self._base_dir
+
+    def get_template_destination(self, components: list[str]) -> Path:
+        """
+        Gets the destination path for templates based on app components.
+
+        Excludes the first component (root app) from the path. For components
+        ['app', 'human_resource', 'employee'], returns
+        Path('templates/human_resource/employee').
+
+        :param components: List of app path components.
+        :return: Full path where templates should be created.
+        """
+
+        template_components = components[1:] if len(components) > 1 else components
+        return self._template_dir.joinpath(*template_components)
+
+    def get_template_dir(self) -> Path:
+        """
+        Gets the project's template directory.
+
+        :return: Template directory path for the Django project.
+        """
+
+        return self._template_dir