Spinners for Terminals

0.0.24 · maintenance · verified Sat Apr 11

A Python port of the `cli-spinners` Node.js library, this package provides access to over 60 different terminal spinner definitions. Each definition includes the animation frames and the recommended interval between frames. It serves as a data source for spinner designs rather than a full-featured spinning utility. For more advanced usage, such as animating spinners with context managers or decorators, other libraries like `halo` or `yaspin` are often recommended as wrappers. The current version is 0.0.24, released in February 2020. [1, 2, 6]

Warnings

gotcha This library primarily provides *definitions* of spinners (animation frames and intervals) as a Python port of `cli-spinners`. It *does not* include built-in functionality to directly animate or display these spinners in the terminal. Users often expect methods like `start()` or `stop()` which are not part of this package.
Fix: To animate spinners, users must implement custom display logic using the `Spinners.<name>.value` data (as shown in the quickstart), or integrate with more feature-rich wrapper libraries like `halo` or `yaspin`, which offer high-level APIs for terminal spinners. [2, 8]
gotcha The `spinners` library has not been updated since February 2020 (v0.0.24). While functional for its intended purpose of providing spinner definitions, it is not actively maintained for new features or direct animation capabilities. The GitHub README explicitly suggests using `halo` for Python as a more modern and feature-rich alternative for actual spinner animation.
Fix: For projects requiring ongoing support, more advanced features (e.g., text, colors, context managers), and active development, consider using `halo` or `yaspin`. These libraries often build upon similar spinner data but provide a comprehensive API for terminal interaction. [1, 2, 8]

Install

pip install spinners Install stable version

Imports

Spinners
```
from spinners import Spinners
```
The library exposes all spinner definitions as members of the `Spinners` Enum. Individual spinner data (frames and interval) are accessed via `Spinners.<spinner_name>.value`.

Quickstart

This quickstart demonstrates how to import the `Spinners` Enum and access the raw frame sequences and intervals for a specific spinner. It then provides a basic, manual loop to illustrate how this data can be used to animate a spinner in the terminal. It's important to note that this library only provides the spinner definitions; the animation logic itself needs to be implemented by the user or by using a wrapper library.

import time
from spinners import Spinners

# Get the data for a specific spinner (e.g., 'dots')
dots_spinner_data = Spinners.dots.value

print(f"Spinner frames for 'dots': {dots_spinner_data['frames']}")
print(f"Spinner interval for 'dots': {dots_spinner_data['interval']}ms")

# --- This library provides data; animation must be custom or via another library ---
# Example of manually animating a spinner based on its data:
print("\nManually animating 'dots' spinner for 2 seconds:")
end_time = time.time() + 2
while time.time() < end_time:
    for frame in dots_spinner_data['frames']:
        print(f"\r{frame} Loading...", end="", flush=True)
        time.sleep(dots_spinner_data['interval'] / 1000.0) # Convert ms to seconds

print("\rDone!         ") # Clear the line and print Done

view raw JSON →