"""
Standardized message utilities for the ThrillWiki application.

This module provides helper functions for creating consistent user-facing
messages across the application. These functions ensure standardized
messaging patterns for success, error, warning, and info notifications.

Usage Examples:
    >>> from apps.core.utils.messages import success_created, error_validation
    >>> message = success_created('Park', 'Cedar Point')
    >>> # Returns: 'Cedar Point has been created successfully.'

    >>> message = error_validation('email')
    >>> # Returns: 'Please check the email field and try again.'
"""

from __future__ import annotations


def success_created(
    model_name: str,
    object_name: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate a success message for object creation.

    Args:
        model_name: The type of object created (e.g., 'Park', 'Ride')
        object_name: Optional name of the created object
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted success message

    Examples:
        >>> success_created('Park', 'Cedar Point')
        'Cedar Point has been created successfully.'

        >>> success_created('Review')
        'Review has been created successfully.'
    """
    if custom_message:
        return custom_message
    if object_name:
        return f"{object_name} has been created successfully."
    return f"{model_name} has been created successfully."


def success_updated(
    model_name: str,
    object_name: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate a success message for object update.

    Args:
        model_name: The type of object updated (e.g., 'Park', 'Ride')
        object_name: Optional name of the updated object
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted success message

    Examples:
        >>> success_updated('Park', 'Cedar Point')
        'Cedar Point has been updated successfully.'

        >>> success_updated('Profile')
        'Profile has been updated successfully.'
    """
    if custom_message:
        return custom_message
    if object_name:
        return f"{object_name} has been updated successfully."
    return f"{model_name} has been updated successfully."


def success_deleted(
    model_name: str,
    object_name: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate a success message for object deletion.

    Args:
        model_name: The type of object deleted (e.g., 'Park', 'Ride')
        object_name: Optional name of the deleted object
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted success message

    Examples:
        >>> success_deleted('Park', 'Old Park')
        'Old Park has been deleted successfully.'

        >>> success_deleted('Review')
        'Review has been deleted successfully.'
    """
    if custom_message:
        return custom_message
    if object_name:
        return f"{object_name} has been deleted successfully."
    return f"{model_name} has been deleted successfully."


def success_action(
    action: str,
    model_name: str,
    object_name: str | None = None,
) -> str:
    """
    Generate a success message for a custom action.

    Args:
        action: The action performed (e.g., 'approved', 'published')
        model_name: The type of object
        object_name: Optional name of the object

    Returns:
        Formatted success message

    Examples:
        >>> success_action('approved', 'Submission', 'New Cedar Point Photo')
        'New Cedar Point Photo has been approved successfully.'

        >>> success_action('published', 'Article')
        'Article has been published successfully.'
    """
    if object_name:
        return f"{object_name} has been {action} successfully."
    return f"{model_name} has been {action} successfully."


def error_validation(
    field_name: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate an error message for validation failures.

    Args:
        field_name: Optional field name that failed validation
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted error message

    Examples:
        >>> error_validation('email')
        'Please check the email field and try again.'

        >>> error_validation()
        'Please check the form and correct any errors.'
    """
    if custom_message:
        return custom_message
    if field_name:
        return f"Please check the {field_name} field and try again."
    return "Please check the form and correct any errors."


def error_permission(
    action: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate an error message for permission denied.

    Args:
        action: Optional action that was denied
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted error message

    Examples:
        >>> error_permission('edit this park')
        'You do not have permission to edit this park.'

        >>> error_permission()
        'You do not have permission to perform this action.'
    """
    if custom_message:
        return custom_message
    if action:
        return f"You do not have permission to {action}."
    return "You do not have permission to perform this action."


def error_not_found(
    model_name: str,
    identifier: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate an error message for object not found.

    Args:
        model_name: The type of object not found
        identifier: Optional identifier that was searched for
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted error message

    Examples:
        >>> error_not_found('Park', 'cedar-point')
        'Park "cedar-point" was not found.'

        >>> error_not_found('Ride')
        'Ride was not found.'
    """
    if custom_message:
        return custom_message
    if identifier:
        return f'{model_name} "{identifier}" was not found.'
    return f"{model_name} was not found."


def error_server(
    custom_message: str | None = None,
) -> str:
    """
    Generate an error message for server errors.

    Args:
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted error message

    Examples:
        >>> error_server()
        'An unexpected error occurred. Please try again later.'
    """
    if custom_message:
        return custom_message
    return "An unexpected error occurred. Please try again later."


def error_network(
    custom_message: str | None = None,
) -> str:
    """
    Generate an error message for network errors.

    Args:
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted error message

    Examples:
        >>> error_network()
        'Network error. Please check your connection and try again.'
    """
    if custom_message:
        return custom_message
    return "Network error. Please check your connection and try again."


def warning_permission(
    action: str | None = None,
    custom_message: str | None = None,
) -> str:
    """
    Generate a warning message for permission issues.

    Args:
        action: Optional action that requires permission
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted warning message

    Examples:
        >>> warning_permission('edit')
        'You may not have permission to edit. Please log in to continue.'

        >>> warning_permission()
        'Please log in to continue.'
    """
    if custom_message:
        return custom_message
    if action:
        return f"You may not have permission to {action}. Please log in to continue."
    return "Please log in to continue."


def warning_unsaved_changes(
    custom_message: str | None = None,
) -> str:
    """
    Generate a warning message for unsaved changes.

    Args:
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted warning message

    Examples:
        >>> warning_unsaved_changes()
        'You have unsaved changes. Are you sure you want to leave?'
    """
    if custom_message:
        return custom_message
    return "You have unsaved changes. Are you sure you want to leave?"


def warning_rate_limit(
    custom_message: str | None = None,
) -> str:
    """
    Generate a warning message for rate limiting.

    Args:
        custom_message: Optional custom message to use instead of default

    Returns:
        Formatted warning message

    Examples:
        >>> warning_rate_limit()
        'Too many requests. Please wait a moment before trying again.'
    """
    if custom_message:
        return custom_message
    return "Too many requests. Please wait a moment before trying again."


def info_message(
    message: str,
) -> str:
    """
    Generate an info message.

    Args:
        message: The information message to display

    Returns:
        The message as-is (for consistency with other functions)

    Examples:
        >>> info_message('Your session will expire in 5 minutes.')
        'Your session will expire in 5 minutes.'
    """
    return message


def info_loading(
    action: str | None = None,
) -> str:
    """
    Generate an info message for loading states.

    Args:
        action: Optional action being performed

    Returns:
        Formatted info message

    Examples:
        >>> info_loading('parks')
        'Loading parks...'

        >>> info_loading()
        'Loading...'
    """
    if action:
        return f"Loading {action}..."
    return "Loading..."


def info_processing(
    action: str | None = None,
) -> str:
    """
    Generate an info message for processing states.

    Args:
        action: Optional action being processed

    Returns:
        Formatted info message

    Examples:
        >>> info_processing('your request')
        'Processing your request...'

        >>> info_processing()
        'Processing...'
    """
    if action:
        return f"Processing {action}..."
    return "Processing..."


def confirm_delete(
    model_name: str,
    object_name: str | None = None,
) -> str:
    """
    Generate a confirmation message for deletion.

    Args:
        model_name: The type of object to delete
        object_name: Optional name of the object

    Returns:
        Formatted confirmation message

    Examples:
        >>> confirm_delete('Park', 'Cedar Point')
        'Are you sure you want to delete "Cedar Point"? This action cannot be undone.'

        >>> confirm_delete('Review')
        'Are you sure you want to delete this Review? This action cannot be undone.'
    """
    if object_name:
        return f'Are you sure you want to delete "{object_name}"? This action cannot be undone.'
    return f"Are you sure you want to delete this {model_name}? This action cannot be undone."


def format_count_message(
    count: int,
    singular: str,
    plural: str | None = None,
    zero_message: str | None = None,
) -> str:
    """
    Generate a count-aware message.

    Args:
        count: The count of items
        singular: Singular form of the message
        plural: Optional plural form (defaults to singular + 's')
        zero_message: Optional message for zero count

    Returns:
        Formatted count message

    Examples:
        >>> format_count_message(1, 'park', 'parks')
        '1 park'

        >>> format_count_message(5, 'park', 'parks')
        '5 parks'

        >>> format_count_message(0, 'park', 'parks', 'No parks found')
        'No parks found'
    """
    if count == 0 and zero_message:
        return zero_message
    if plural is None:
        plural = f"{singular}s"
    return f"{count} {singular if count == 1 else plural}"
