or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

basic-operations.mdcustomization.mdindex.mdnotebook-integration.mdstatus-handling.md
tile.json

tessl/pypi-halo

Beautiful terminal spinners in Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/halo@0.0.x

To install, run

npx @tessl/cli install tessl/pypi-halo@0.0.0

index.mddocs/

Halo

Beautiful terminal spinners in Python that provide elegant loading indicators for command-line interfaces and terminal applications. Halo offers rich customization options for spinner animations, colors, text placement, and status feedback, with special support for IPython and Jupyter notebook environments.

Package Information

  • Package Name: halo
  • Language: Python
  • Installation: pip install halo

Core Imports

from halo import Halo

For Jupyter notebook/IPython environments:

from halo import HaloNotebook

Basic Usage

from halo import Halo
import time

# Basic spinner with context manager
with Halo(text='Loading', spinner='dots'):
    time.sleep(2)

# Manual control
spinner = Halo(text='Processing', spinner='dots')
spinner.start()
time.sleep(2)
spinner.succeed('✓ Complete!')

# As decorator
@Halo(text='Working', spinner='dots')  
def long_task():
    time.sleep(3)
    return "result"

result = long_task()

Architecture

Halo uses a threaded architecture where each spinner runs in its own daemon thread, allowing non-blocking operation while your main code executes. The system automatically handles:

  • Cross-platform cursor management: Hide/show terminal cursor during spinner operation
  • Environment detection: Automatic adaptation for terminal, IPython, and Jupyter environments
  • Unicode support: Graceful fallback for terminals that don't support Unicode characters
  • Stream handling: Safe writing to output streams with proper error handling

The threading model ensures clean shutdown via atexit handlers and IPython cell execution hooks.

Capabilities

Basic Spinner Operations

Core functionality for creating, starting, stopping, and managing spinner lifecycle with context manager and decorator support.

class Halo:
    def __init__(
        self,
        text="",
        color="cyan", 
        text_color=None,
        spinner=None,
        animation=None,
        placement="left",
        interval=-1,
        enabled=True,
        stream=sys.stdout
    ): ...
    
    def start(self, text=None): ...
    def stop(self): ...
    def __enter__(self): ...
    def __exit__(self, type, value, traceback): ...
    def __call__(self, f): ...

Basic Operations

Customization and Styling

Configure spinner appearance including colors, text formatting, placement options, and text animations for long strings.

# Properties for dynamic customization
@property
def text(self): ...
@text.setter  
def text(self, text): ...

@property
def color(self): ...
@color.setter
def color(self, color): ...

@property
def spinner(self): ...
@spinner.setter
def spinner(self, spinner): ...

@property
def placement(self): ...
@placement.setter
def placement(self, placement): ...

Customization

Status and Result Handling

Methods for completing spinners with status indicators (success, failure, warning, info) and custom symbols.

def succeed(self, text=None): ...
def fail(self, text=None): ...  
def warn(self, text=None): ...
def info(self, text=None): ...
def stop_and_persist(self, symbol=" ", text=None): ...

Status Handling

Jupyter Notebook Integration

Specialized spinner implementation for Jupyter notebooks and IPython environments using widgets.

class HaloNotebook(Halo):
    def __init__(
        self,
        text="",
        color="cyan",
        text_color=None, 
        spinner=None,
        placement="left",
        animation=None,
        interval=-1,
        enabled=True,
        stream=sys.stdout
    ): ...

Notebook Integration

Types

# Spinner placement options
SPINNER_PLACEMENTS = ("left", "right")

# Animation types for long text
ANIMATIONS = ("bounce", "marquee")

# Supported spinner types (from spinners package)
# Common examples: "dots", "line", "star", "arrow", "bouncingBar", "bouncingBall"
SpinnerType = Union[str, Dict[str, Any]]

# Color specifications (from termcolor)
ColorType = Union[str, None]
# Supported colors: "grey", "red", "green", "yellow", "blue", "magenta", "cyan", "white"