django-spire 0.23.4__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

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+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 FileSystem
+
+
+class TemplateEngine:
+    """
+    Renders template strings with variable replacements.
+
+    This class uses Python's string.Template to safely substitute
+    placeholders in template files with actual values.
+    """
+
+    def render(self, text: str, replacements: dict[str, str]) -> str:
+        """
+        Renders a template string by replacing placeholders with values.
+
+        :param text: Template string containing ${variable} placeholders.
+        :param replacements: Dictionary mapping placeholder names to their values.
+        :return: Rendered string with all placeholders replaced.
+        """
+
+        template = Template(text)
+        return template.safe_substitute(replacements)
+
+
+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: FileSystem):
+        """
+        Initializes the processor with an engine and file system.
+
+        :param engine: Template engine for rendering strings.
+        :param filesystem: File system for file operations.
+        """
+
+        self._engine = engine
+        self._filesystem = filesystem
+
+    def process_app_templates(
+        self,
+        directory: Path,
+        components: list[str],
+        user_inputs: dict[str, str] | None = None
+    ) -> None:
+        """
+        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:
+        """
+        Removes .template extensions from all template files in a directory.
+
+        :param directory: Directory to search for .template files.
+        """
+
+        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,73 @@
+from __future__ import annotations
+
+from django.apps import apps
+from django.conf import settings
+
+
+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()

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

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+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 typing import Callable
+
+    from django.core.management.base import BaseCommand
+
+
+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 format_app_item(self, item: Path) -> str:
+        """
+        Formats an app file or directory name for display.
+
+        Removes the .template extension from Python files.
+
+        :param item: Path to the item to format.
+        :return: Formatted item name.
+        """
+
+        return item.name.replace('.py.template', '.py')
+
+    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.
+        """
+
+        self.write(f'The templates for app "{app}" already exist at {destination}', self.style_warning)
+
+    def report_tree_structure(
+        self,
+        title: str,
+        base: Path,
+        components: list[str],
+        registry: list[str],
+        template: Path,
+        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.transform_app_component
+
+        self.command.stdout.write(title)
+        current = base
+
+        for i, component in enumerate(components):
+            latest = components[: i + 1]
+            replacement = generate_replacement_map(latest)
+
+            component = transformation(i, component)
+            current = current / component
+            app = '.'.join(latest)
+            indent = self.INDENTATION * i
+
+            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 + 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,
+        template: Path,
+        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)
+
+        for item in items:
+            if item.name in ignore:
+                continue
+
+            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 + self.INDENTATION,
+                    formatter
+                )
+
+    def _sort_template_items(self, path: Path) -> tuple[bool, str]:
+        """
+        Sorts template items with directories first, then by name.
+
+        :param path: Path to sort.
+        :return: Tuple for sorting (is_file, lowercase_name).
+        """
+
+        return (path.is_file(), path.name.lower())