spinners.py

Go to the documentation of this file.

# Copyright (c) 2025-present Aquin Labs Private Limited. All Rights Reserved.
"""Spinner / bullet glyphs from py-spinners (cli-spinners)."""
 
from __future__ import annotations
 
from typing import Any
 
# Status list animation: braille dots + ASCII flip.
_STATUS_SPINNERS = ("dots9", "flip")
 
 
def _spinner(name: str) -> dict[str, Any]:
    from spinners import Spinners
 
    return getattr(Spinners, name).value
 
 
def bullet_mark(*, plain: bool = False) -> str:
    """Settled glyph after the spin — plain slash, not circle/square."""
    _ = plain
    return "/"
 
 
def status_spin_sequence() -> list[tuple[str, float]]:
    """(frame, delay_seconds) for ``aquin status`` — plays dots9 then flip."""
    seq: list[tuple[str, float]] = []
    for name in _STATUS_SPINNERS:
        sp = _spinner(name)
        delay = sp["interval"] / 1000.0
        for frame in sp["frames"]:
            # Keep bullet column width predictable on blank-ish frames.
            mark = frame if frame.strip() else "-"
            seq.append((mark, delay))
    return seq
 
 
def spinner_frames(name: str = "dots") -> list[str]:
    """Frame list for an animating spinner."""
    return list(_spinner(name)["frames"])
 
 
def spinner_interval_ms(name: str = "dots") -> int:
    return int(_spinner(name)["interval"])