reporter

django_spire.core.management.commands.spire_startapp_pkg.reporter

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.

Initializes the reporter with a Django management command.

Parameters:

• command (BaseCommand) –

  Django BaseCommand instance for accessing stdout and styling.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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

ICON_FILE = '📄' class-attribute instance-attribute

ICON_FOLDER_CLOSED = '📁' class-attribute instance-attribute

ICON_FOLDER_OPEN = '📂' class-attribute instance-attribute

INDENTATION = ' ' class-attribute instance-attribute

command = command instance-attribute

style_error = command.style.ERROR instance-attribute

style_notice = command.style.NOTICE instance-attribute

style_success = command.style.SUCCESS instance-attribute

style_warning = command.style.WARNING instance-attribute

format_app_item

Formats an app file or directory name for display.

Removes the .template extension from Python files.

Parameters:

• item (Path) –

  Path to the item to format.

Returns:

• str –

  Formatted item name.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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')

format_html_item

Formats an HTML template file or directory name for display.

Applies variable replacements and removes .template extensions.

Parameters:

• item (Path) –

  Path to the item to format.

• replacement (dict[str, str]) –

  Dictionary of placeholder replacements.

Returns:

• str –

  Formatted item name with placeholders replaced.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.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

prompt_confirmation

Prompts the user for yes/no confirmation.

Parameters:

• message (str) –

  Confirmation prompt message.

Returns:

• bool –

  True if user responds with 'y', False otherwise.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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'

report_app_creation_success

Reports successful creation of an app.

Parameters:

• app (str) –

  Name of the app that was created.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_app_exists

Reports that an app already exists at the destination.

Parameters:

• app (str) –

  Name of the app.

• destination (Path) –

  Path where the app already exists.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_creating_app

Reports that an app is being created.

Parameters:

• app (str) –

  Name of the app being created.

• destination (Path) –

  Path where the app will be created.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_creating_templates

Reports that templates are being created for an app.

Parameters:

• app (str) –

  Name of the app.

• destination (Path) –

  Path where templates will be created.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_installed_apps_suggestion

Suggests which app to add to INSTALLED_APPS in settings.py.

Parameters:

• missing_components (list[str]) –

  List of missing app components.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_missing_components

Reports which app components are not yet registered.

Parameters:

• missing_components (list[str]) –

  List of unregistered app component paths.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_templates_creation_success

Reports successful creation of templates for an app.

Parameters:

• app (str) –

  Name of the app whose templates were created.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_templates_exist

Reports that templates already exist for an app.

Parameters:

• app (str) –

  Name of the app.

• destination (Path) –

  Path where templates already exist.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

report_tree_structure

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.

Parameters:

• title (str) –

  Title to display above the tree structure.

• base (Path) –

  Base directory path.

• components (list[str]) –

  List of app path components.

• registry (list[str]) –

  List of registered apps.

• template (Path) –

  Path to template directory.

• formatter (Callable[[Path], str]) –

  Function to format item names for display.

• transformation (Callable[[int, str], str] | None, default: None ) –

  Optional function to transform component names.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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)

transform_app_component

Transforms an app component name (default: no transformation).

Parameters:

• _index (int) –

  Index of the component in the path.

• component (str) –

  Component name to transform.

Returns:

• str –

  Transformed component name.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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

transform_html_component

Transforms an HTML component name (replaces first component with 'templates').

Parameters:

• index (int) –

  Index of the component in the path.

• component (str) –

  Component name to transform.

Returns:

• str –

  Transformed component name.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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

write

Writes a styled message to the console.

Parameters:

• message (str) –

  Message to display.

• style (Callable[[str], str]) –

  Styling function to apply to the message.

Source code in django_spire/core/management/commands/spire_startapp_pkg/reporter.py

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))