0
# Halo
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: halo
7
- **Language**: Python
8
- **Installation**: `pip install halo`
9

10
## Core Imports
11

12
```python
13
from halo import Halo
14
```
15

16
For Jupyter notebook/IPython environments:
17

18
```python
19
from halo import HaloNotebook
20
```
21

22
## Basic Usage
23

24
```python
25
from halo import Halo
26
import time
27

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

32
# Manual control
33
spinner = Halo(text='Processing', spinner='dots')
34
spinner.start()
35
time.sleep(2)
36
spinner.succeed('✓ Complete!')
37

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

44
result = long_task()
45
```
46

47
## Architecture
48

49
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:
50

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

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

58
## Capabilities
59

60
### Basic Spinner Operations
61

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

64
```python { .api }
65
class Halo:
66
    def __init__(
67
        self,
68
        text="",
69
        color="cyan", 
70
        text_color=None,
71
        spinner=None,
72
        animation=None,
73
        placement="left",
74
        interval=-1,
75
        enabled=True,
76
        stream=sys.stdout
77
    ): ...
78
    
79
    def start(self, text=None): ...
80
    def stop(self): ...
81
    def __enter__(self): ...
82
    def __exit__(self, type, value, traceback): ...
83
    def __call__(self, f): ...
84
```
85

86
[Basic Operations](./basic-operations.md)
87

88
### Customization and Styling
89

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

92
```python { .api }
93
# Properties for dynamic customization
94
@property
95
def text(self): ...
96
@text.setter  
97
def text(self, text): ...
98

99
@property
100
def color(self): ...
101
@color.setter
102
def color(self, color): ...
103

104
@property
105
def spinner(self): ...
106
@spinner.setter
107
def spinner(self, spinner): ...
108

109
@property
110
def placement(self): ...
111
@placement.setter
112
def placement(self, placement): ...
113
```
114

115
[Customization](./customization.md)
116

117
### Status and Result Handling
118

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

121
```python { .api }
122
def succeed(self, text=None): ...
123
def fail(self, text=None): ...  
124
def warn(self, text=None): ...
125
def info(self, text=None): ...
126
def stop_and_persist(self, symbol=" ", text=None): ...
127
```
128

129
[Status Handling](./status-handling.md)
130

131
### Jupyter Notebook Integration
132

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

135
```python { .api }
136
class HaloNotebook(Halo):
137
    def __init__(
138
        self,
139
        text="",
140
        color="cyan",
141
        text_color=None, 
142
        spinner=None,
143
        placement="left",
144
        animation=None,
145
        interval=-1,
146
        enabled=True,
147
        stream=sys.stdout
148
    ): ...
149
```
150

151
[Notebook Integration](./notebook-integration.md)
152

153
## Types
154

155
```python { .api }
156
# Spinner placement options
157
SPINNER_PLACEMENTS = ("left", "right")
158

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

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

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