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

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

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from django_spire.core.management.commands.spire_startapp_pkg.reporter import Reporter
+
+
+class PermissionInheritanceHandler:
+    """
+    Handles permission inheritance configuration for nested Django apps.
+
+    This class manages the interactive collection of permission inheritance
+    settings when creating child apps that may inherit permissions from parent apps.
+    """
+
+    def __init__(self, reporter: Reporter):
+        """
+        Initializes the handler with a reporter for user interaction.
+
+        :param reporter: Reporter instance for displaying prompts and messages.
+        """
+
+        self.reporter = reporter
+
+    def collect_inheritance_data(self, components: list[str]) -> dict[str, Any]:
+        """
+        Collects permission inheritance configuration from the user.
+
+        Prompts the user to determine if the new app should inherit permissions
+        from its parent app, and if so, collects the necessary parent model information.
+
+        :param components: List of app path components.
+        :return: Dictionary containing inheritance configuration data.
+        """
+
+        if len(components) <= 2:
+            return {
+                'inherit_permissions': False,
+                'parent_model_instance_name': '',
+                'parent_permission_prefix': '',
+            }
+
+        if not self._should_inherit_permissions():
+            return {
+                'inherit_permissions': False,
+                'parent_model_instance_name': '',
+                'parent_permission_prefix': '',
+            }
+
+        return {
+            'inherit_permissions': True,
+            'parent_model_instance_name': self._collect_parent_model_instance_name(components),
+            'parent_model_path': self._collect_parent_model_path(components),
+            'parent_permission_prefix': self._collect_parent_permission_prefix(components),
+        }
+
+    def _build_default_parent_model_path(self, components: list[str]) -> str:
+        """
+        Builds a default parent model path based on app components.
+
+        :param components: List of app path components.
+        :return: Default parent model path string.
+        """
+
+        parent_name = components[-2]
+        parent_model_class = ''.join(word.title() for word in parent_name.split('_'))
+        return '.'.join(components[:-1]) + f'.models.{parent_model_class}'
+
+    def _build_default_parent_permission_prefix(self, components: list[str]) -> str:
+        """
+        Builds a default parent permission prefix based on app components.
+
+        :param components: List of app path components.
+        :return: Default permission prefix string.
+        """
+
+        parent_parts = components[1:-1]
+        return '_'.join(parent_parts).lower()
+
+    def _collect_parent_model_instance_name(self, components: list[str]) -> str:
+        """
+        Prompts the user for the parent model instance name.
+
+        :param components: List of app path components.
+        :return: User-provided or default parent model instance name.
+        """
+
+        parent_name = components[-2]
+        default = parent_name.lower()
+
+        self.reporter.write(
+            f'\nEnter the parent model instance name (default: "{default}")',
+            self.reporter.style_notice
+        )
+
+        user_input = input('Press Enter to use default or type a custom name: ').strip()
+        return user_input if user_input else default
+
+    def _collect_parent_model_path(self, components: list[str]) -> str:
+        """
+        Prompts the user for the parent model path.
+
+        :param components: List of app path components.
+        :return: User-provided or default parent model path.
+        """
+
+        default = self._build_default_parent_model_path(components)
+
+        self.reporter.write(
+            f'\nEnter the parent model path (default: "{default}")',
+            self.reporter.style_notice
+        )
+
+        user_input = input('Press Enter to use default or type a custom path: ').strip()
+        return user_input if user_input else default
+
+    def _collect_parent_permission_prefix(self, components: list[str]) -> str:
+        """
+        Prompts the user for the parent permission prefix.
+
+        :param components: List of app path components.
+        :return: User-provided or default parent permission prefix.
+        """
+
+        default = self._build_default_parent_permission_prefix(components)
+
+        self.reporter.write(
+            f'\nEnter the parent permission prefix (default: "{default}")',
+            self.reporter.style_notice
+        )
+
+        user_input = input('Press Enter to use default or type a custom prefix: ').strip()
+        return user_input if user_input else default
+
+    def _should_inherit_permissions(self) -> bool:
+        """
+        Prompts the user to confirm permission inheritance.
+
+        :return: True if user wants to inherit permissions, False otherwise.
+        """
+
+        self.reporter.write('\nDo you want this app to inherit permissions from its parent? (y/n)', self.reporter.style_notice)
+        user_input = input('Default is "n": ').strip().lower()
+        return user_input == 'y'

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

@@ -1,84 +1,171 @@
 from __future__ import annotations
 
-from typing_extensions import Callable, TYPE_CHECKING
+from string import Template
+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.filesystem import FileSystemInterface
 
-class BaseTemplateProcessor:
-    @staticmethod
-    def apply_replacement(text: str, replacements: dict[str, str]) -> str:
-        for old, new in replacements.items():
-            text = text.replace(old, new)
 
-        return text
+class TemplateEngine:
+    """
+    Renders template strings with variable replacements.
 
-    def replace_content(self, path: Path, components: list[str]) -> None:
-        replacement = generate_replacement_map(components)
+    This class uses Python's string.Template to safely substitute
+    placeholders in template files with actual values.
+    """
 
-        with open(path, 'r', encoding='utf-8') as handle:
-            content = handle.read()
+    def render(self, text: str, replacements: dict[str, str]) -> str:
+        """
+        Renders a template string by replacing placeholders with values.
 
-        updated_content = self.apply_replacement(content, replacement)
+        :param text: Template string containing ${variable} placeholders.
+        :param replacements: Dictionary mapping placeholder names to their values.
+        :return: Rendered string with all placeholders replaced.
+        """
 
-        with open(path, 'w', encoding='utf-8') as handle:
-            handle.write(updated_content)
+        template = Template(text)
+        return template.safe_substitute(replacements)
 
-    def rename_file(self, path: Path, components: list[str]) -> None:
-        replacement = generate_replacement_map(components)
-        new_name = self.apply_replacement(path.name, replacement)
 
-        if new_name != path.name:
-            new_path = path.parent / new_name
-            path.rename(new_path)
+class TemplateProcessor:
+    """
+    Processes template files for Django app generation.
+
+    This class handles the replacement of placeholders in template files
+    and manages file renaming based on user configuration.
+    """
+
+    def __init__(self, engine: TemplateEngine, filesystem: FileSystemInterface):
+        """
+        Initializes the processor with an engine and file system.
+
+        :param engine: Template engine for rendering strings.
+        :param filesystem: File system interface for file operations.
+        """
+
+        self._engine = engine
+        self._filesystem = filesystem
 
-    def _process_files(
+    def process_app_templates(
         self,
         directory: Path,
         components: list[str],
-        pattern: str,
-        file_filter: Callable[[Path], bool] | None = None
+        user_inputs: dict[str, str] | None = None
     ) -> None:
-        for path in directory.rglob(pattern):
-            if file_filter and not file_filter(path):
-                continue
-
-            self.replace_content(path, components)
-            self.rename_file(path, components)
-
-
-class AppTemplateProcessor(BaseTemplateProcessor):
-    def replace_app_name(self, directory: Path, components: list[str]) -> None:
-        self._process_files(
-            directory,
-            components,
-            '*.template',
-            lambda path: path.is_file()
-        )
-
-        self._process_files(
-            directory,
-            components,
-            '*.py',
-            lambda path: path.is_file()
-        )
+        """
+        Processes all template files in an app directory.
+
+        Replaces placeholders in .template files, renames them, and updates
+        content in .py files based on user inputs.
+
+        :param directory: Root directory containing template files.
+        :param components: List of app path components.
+        :param user_inputs: Optional dictionary of user-provided configuration values.
+        """
+
+        for file_path in self._filesystem.iterate_files(directory, '*.template'):
+            self._process_file(file_path, components, user_inputs)
+
+        for file_path in self._filesystem.iterate_files(directory, '*.py'):
+            self._replace_content(file_path, components, user_inputs)
+            self._rename_file(file_path, components, user_inputs)
 
         self._rename_template_files(directory)
 
+    def process_html_templates(
+        self,
+        directory: Path,
+        components: list[str],
+        user_inputs: dict[str, str] | None = None
+    ) -> None:
+        """
+        Processes all HTML template files in a directory.
+
+        Replaces placeholders in .template files and renames them to remove
+        the .template extension.
+
+        :param directory: Root directory containing HTML template files.
+        :param components: List of app path components.
+        :param user_inputs: Optional dictionary of user-provided configuration values.
+        """
+
+        for file_path in self._filesystem.iterate_files(directory, '*.template'):
+            self._process_file(file_path, components, user_inputs)
+
+        self._rename_template_files(directory)
+
+    def _process_file(
+        self,
+        path: Path,
+        components: list[str],
+        user_inputs: dict[str, str] | None = None
+    ) -> None:
+        """
+        Processes a single template file.
+
+        Replaces content placeholders and renames the file based on configuration.
+
+        :param path: Path to the template file.
+        :param components: List of app path components.
+        :param user_inputs: Optional dictionary of user-provided configuration values.
+        """
+
+        self._replace_content(path, components, user_inputs)
+        self._rename_file(path, components, user_inputs)
+
+    def _rename_file(
+        self,
+        path: Path,
+        components: list[str],
+        user_inputs: dict[str, str] | None = None
+    ) -> None:
+        """
+        Renames a file by replacing placeholders in its filename.
+
+        :param path: Current path of the file.
+        :param components: List of app path components.
+        :param user_inputs: Optional dictionary of user-provided configuration values.
+        """
+
+        replacement = generate_replacement_map(components, user_inputs)
+        new_name = self._engine.render(path.name, replacement)
+
+        if new_name != path.name:
+            new_path = path.parent / new_name
+            self._filesystem.rename(path, new_path)
+
     def _rename_template_files(self, directory: Path) -> None:
-        for template_file in directory.rglob('*.py.template'):
-            new_name = template_file.name.replace('.py.template', '.py')
-            new_path = template_file.parent / new_name
-            template_file.rename(new_path)
+        """
+        Removes .template extensions from all template files in a directory.
 
+        :param directory: Directory to search for .template files.
+        """
 
-class HTMLTemplateProcessor(BaseTemplateProcessor):
-    def replace_template_names(self, directory: Path, components: list[str]) -> None:
-        self._process_files(
-            directory,
-            components,
-            '*.html'
-        )
+        for template_file in self._filesystem.iterate_files(directory, '*.template'):
+            new_name = template_file.name.replace('.template', '')
+            new_path = template_file.parent / new_name
+            self._filesystem.rename(template_file, new_path)
+
+    def _replace_content(
+        self,
+        path: Path,
+        components: list[str],
+        user_inputs: dict[str, str] | None = None
+    ) -> None:
+        """
+        Replaces placeholders in a file's content.
+
+        :param path: Path to the file to process.
+        :param components: List of app path components.
+        :param user_inputs: Optional dictionary of user-provided configuration values.
+        """
+
+        replacement = generate_replacement_map(components, user_inputs)
+        content = self._filesystem.read_file(path)
+        updated_content = self._engine.render(content, replacement)
+        self._filesystem.write_file(path, updated_content)

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

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from django.apps import apps
+from django.conf import settings
+
+
+class AppRegistryInterface(Protocol):
+    """
+    Protocol defining the interface for Django app registry operations.
+
+    This protocol specifies methods for querying registered apps and
+    validating app component paths.
+    """
+
+    def get_installed_apps(self) -> list[str]: ...
+    def get_missing_components(self, components: list[str]) -> list[str]: ...
+    def get_valid_root_apps(self) -> set[str]: ...
+    def is_app_registered(self, app_path: str) -> bool: ...
+
+
+class AppRegistry:
+    """
+    Manages Django app registration information.
+
+    This class provides methods to query which apps are installed in the
+    Django project and validate app component hierarchies.
+    """
+
+    def get_installed_apps(self) -> list[str]:
+        """
+        Gets a list of all installed app names.
+
+        :return: List of fully qualified app names from Django's app registry.
+        """
+
+        return [config.name for config in apps.get_app_configs()]
+
+    def get_missing_components(self, components: list[str]) -> list[str]:
+        """
+        Identifies which app components in a path are not registered.
+
+        For a path like ['app', 'human_resource', 'employee'], this checks
+        if 'app', 'app.human_resource', and 'app.human_resource.employee'
+        are registered, and returns those that are missing.
+
+        :param components: List of app path components to check.
+        :return: List of unregistered component paths.
+        """
+
+        registry = self.get_installed_apps()
+        missing = []
+
+        total = len(components)
+
+        for i in range(total):
+            component = '.'.join(components[: i + 1])
+
+            if component not in registry and i > 0:
+                missing.append(component)
+
+        return missing
+
+    def get_valid_root_apps(self) -> set[str]:
+        """
+        Gets all valid root app names from INSTALLED_APPS.
+
+        Returns root-level apps (first component before a dot) that can be
+        used as parent apps, excluding Django's built-in apps.
+
+        :return: Set of valid root app names.
+        """
+
+        return {
+            app.split('.')[0]
+            for app in settings.INSTALLED_APPS
+            if '.' in app and app.split('.')[0] != 'django'
+        }
+
+    def is_app_registered(self, app_path: str) -> bool:
+        """
+        Checks if an app path is registered in Django.
+
+        :param app_path: Dot-separated app path to check.
+        :return: True if the app is registered, False otherwise.
+        """
+
+        return app_path in self.get_installed_apps()