lily_website

📜 Animation Service

⬅️ Back 🏠 Docs Root

This module defines the UIAnimationService class, which provides functionalities for displaying various types of loading and waiting animations in the Telegram bot’s interface. It integrates with the ViewSender to update messages dynamically, enhancing user experience during asynchronous operations.

AnimationType Enum

class AnimationType(Enum):
    PROGRESS_BAR = "progress_bar"
    INFINITE = "infinite"
    NONE = "none"

An enumeration defining the types of animations that can be displayed.

PollerFunc Type Alias

PollerFunc = Callable[[], Awaitable[tuple[UnifiedViewDTO, bool]]]

A type alias for an asynchronous callable that takes no arguments and returns a tuple containing a UnifiedViewDTO and a boolean indicating whether the polling should continue (True) or stop (False).

UIAnimationService Class

The UIAnimationService orchestrates different animation scenarios, such as showing a loading indicator during data fetching, polling for status updates, or displaying progress for timed operations.

Initialization (__init__)

def __init__(self, sender: ViewSender):

Initializes the UIAnimationService.

Core Methods

run_delayed_fetch Method

async def run_delayed_fetch(
    self,
    fetch_func: PollerFunc,
    delay: float = 3.0,
    step_interval: float = 1.0,
    loading_text: str = "🔍 <b>Поиск...</b>",
    animation_type: AnimationType = AnimationType.PROGRESS_BAR,
) -> None:

This method runs an animation for a specified delay duration, and then performs a single data fetch at the end. It’s suitable for operations like search or scanning where a single backend request is made after a short wait.

Process:

  1. Displays an animation for delay seconds, updating the animation frame every step_interval.
  2. After the animation, calls fetch_func once.
  3. Sends the final UnifiedViewDTO returned by fetch_func.

run_polling_loop Method

async def run_polling_loop(
    self,
    check_func: PollerFunc,
    timeout: float = 60.0,
    step_interval: float = 2.0,
    loading_text: str = "⏳ <b>Ожидание...</b>",
    animation_type: AnimationType = AnimationType.INFINITE,
) -> None:

This method continuously polls a check_func until a condition is met or a timeout is reached. It’s used for scenarios like waiting for combat results or arena queues, where the bot repeatedly checks a status.

Process:

  1. Repeatedly calls check_func at step_interval.
  2. If check_func indicates is_waiting=True, it updates the animation in the UnifiedViewDTO and sends it.
  3. The loop exits when is_waiting becomes False or timeout is reached.

run_timed_polling Method

async def run_timed_polling(
    self,
    check_func: PollerFunc,
    duration: float = 5.0,
    step_interval: float = 1.0,
    loading_text: str = "🚶 <b>Перемещение...</b>",
    animation_type: AnimationType = AnimationType.PROGRESS_BAR,
) -> None:

This method performs an initial check, then displays a progress bar animation for a specified duration, and continues polling if the operation is still ongoing. It’s suitable for operations that have an expected duration, like character movement, where the result might be stored in Redis.

Process:

  1. Performs an initial check using check_func.
  2. Displays a PROGRESS_BAR animation for duration seconds.
  3. If check_func still indicates is_waiting=True after duration, it transitions to an INFINITE animation mode and continues polling indefinitely until is_waiting becomes False.

Atomic Helpers (Private Methods)

_poll_check Method

async def _poll_check(self, func: PollerFunc) -> tuple[UnifiedViewDTO, bool]:

Executes the provided polling function (func) and ensures its return value is a (UnifiedViewDTO, bool) tuple.

Returns: tuple[UnifiedViewDTO, bool]: The result of the polling function.

_inject_animation Method

def _inject_animation(self, view_dto: UnifiedViewDTO, anim_str: str) -> None:

Injects the generated animation string into the text of the UnifiedViewDTO’s content. If the content text contains {ANIMATION}, it replaces it; otherwise, it appends the animation string.

_send Method

async def _send(self, view_dto: UnifiedViewDTO) -> None:

Sends the UnifiedViewDTO using the ViewSender instance.

_create_temp_content Method

def _create_temp_content(self, text: str):

Creates a temporary ViewResultDTO with the given text, used for displaying animation frames.

Returns: ViewResultDTO: A new ViewResultDTO instance.

Animation Generators (Private Methods)

_generate_animation Method

def _generate_animation(self, step: int, total_steps: int, text: str, animation_type: AnimationType) -> str:

Generates the animation string based on the specified animation_type.

Returns: str: The generated animation string.

_gen_infinite_bar Method

def _gen_infinite_bar(self, step: int, text: str) -> str:

Generates an infinite “snake” or running indicator animation string.

Returns: str: The infinite bar animation string (e.g., “Text [□■□□□]”).

_gen_progress_bar Method

def _gen_progress_bar(self, step: int, total_steps: int, text: str) -> str:

Generates a progress bar animation string.

Returns: str: The progress bar animation string (e.g., “Text [■■□□□] 40%”).