0
# Development Tools
1

2
Development and debugging utilities for character discovery and terminal testing. These tools are primarily useful for developers creating custom animations, testing Unicode support, and debugging terminal rendering issues.
3

4
## Capabilities
5

6
### Character Discovery
7

8
Utility for exploring Unicode characters available in the terminal, particularly useful for finding special characters for custom spinners and progress bars.
9

10
```python { .api }
11
def print_chars(line_length: int = 32, max_char: int = 0x20000):
12
    """
13
    Print all Unicode characters in the terminal to help find characters for custom animations.
14
    
15
    Useful for determining which characters your terminal supports and finding cool characters
16
    to use in custom spinners or bars.
17
    
18
    Parameters:
19
    - line_length (int): Number of characters per line in output (default: 32)
20
    - max_char (int): Last character in Unicode table to display (default: 0x20000)
21
                     Maximum value is 0x10ffff. Values above the default often show
22
                     as question marks, but can be increased to explore more ranges.
23
    
24
    Returns:
25
    None (prints output directly to terminal)
26
    """
27
```
28

29
#### Usage Examples
30

31
**Basic Character Exploration**:
32
```python
33
from alive_progress.tools import print_chars
34

35
# Print all basic Unicode characters
36
print_chars()
37

38
# Output format:
39
# 0x00020:  ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
40
# 0x00040: @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _
41
# 0x00060: ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ 
42
# ...
43
```
44

45
**Custom Line Length**:
46
```python
47
# Shorter lines for narrow terminals
48
print_chars(line_length=16)
49

50
# Longer lines for wide terminals  
51
print_chars(line_length=64)
52
```
53

54
**Specific Unicode Ranges**:
55
```python
56
# Explore basic Latin and symbols (faster)
57
print_chars(max_char=0x1000)
58

59
# Explore more Unicode planes (slower, more comprehensive)
60
print_chars(max_char=0x30000)
61

62
# Full Unicode exploration (very slow)
63
print_chars(max_char=0x10ffff)
64
```
65

66
**Finding Animation Characters**:
67
```python
68
from alive_progress.tools import print_chars
69
from alive_progress.animations import frame_spinner_factory
70
from alive_progress import alive_bar
71

72
# Explore Unicode to find interesting characters
73
print_chars(max_char=0x3000)  # Look for symbols
74

75
# Test discovered characters in actual spinner
76
discovered_chars = ['◐', '◓', '◑', '◒']  # Found from exploration
77
test_spinner = frame_spinner_factory(discovered_chars)
78

79
# Test in progress bar
80
with alive_bar(100, spinner=test_spinner, title='Testing Characters') as bar:
81
    for i in range(100):
82
        bar()
83
        time.sleep(0.05)
84
```
85

86
### Terminal Testing Patterns
87

88
Common usage patterns for testing terminal capabilities and character rendering.
89

90
#### Unicode Support Testing
91

92
```python
93
from alive_progress.tools import print_chars
94

95
# Test basic Unicode blocks
96
print("Testing Basic Latin Extended:")
97
print_chars(line_length=16, max_char=0x300)
98

99
print("\nTesting Symbols and Arrows:")  
100
print_chars(line_length=16, max_char=0x2800)
101

102
print("\nTesting Box Drawing Characters:")
103
print_chars(line_length=16, max_char=0x2600)
104
```
105

106
#### Spinner Character Discovery
107

108
```python
109
from alive_progress.tools import print_chars
110
import re
111

112
# Function to help identify useful spinner characters
113
def find_spinner_chars():
114
    """Explore and test potential spinner characters."""
115
    
116
    print("=== BASIC GEOMETRIC SHAPES ===")
117
    # Unicode block: Geometric Shapes (U+25A0–U+25FF)
118
    for i in range(0x25A0, 0x2600, 16):
119
        print(f'0x{i:05x}:', end=' ')
120
        for j in range(16):
121
            if i + j <= 0x25FF:
122
                try:
123
                    print(chr(i + j), end=' ')
124
                except UnicodeEncodeError:
125
                    print('?', end=' ')
126
        print()
127
    
128
    print("\n=== BRAILLE PATTERNS ===")
129
    # Unicode block: Braille Patterns (U+2800–U+28FF)  
130
    for i in range(0x2800, 0x2900, 16):
131
        print(f'0x{i:05x}:', end=' ')
132
        for j in range(16):
133
            if i + j <= 0x28FF:
134
                try:
135
                    print(chr(i + j), end=' ')
136
                except UnicodeEncodeError:
137
                    print('?', end=' ')
138
        print()
139

140
# Run the discovery
141
find_spinner_chars()
142
```
143

144
#### Bar Character Discovery
145

146
```python
147
from alive_progress.tools import print_chars
148

149
def find_bar_chars():
150
    """Explore characters suitable for progress bars."""
151
    
152
    print("=== BLOCK ELEMENTS ===")
153
    # Unicode block: Block Elements (U+2580–U+259F)
154
    for i in range(0x2580, 0x25A0, 8):
155
        print(f'0x{i:05x}:', end=' ')
156
        for j in range(8):
157
            if i + j <= 0x259F:
158
                try:
159
                    char = chr(i + j)
160
                    print(f'{char} ', end='')
161
                except UnicodeEncodeError:
162
                    print('? ', end='')
163
        print()
164
    
165
    print("\n=== BOX DRAWING ===")
166
    # Unicode block: Box Drawing (U+2500–U+257F)
167
    for i in range(0x2500, 0x2580, 16):
168
        print(f'0x{i:05x}:', end=' ')
169
        for j in range(16):
170
            if i + j <= 0x257F:
171
                try:
172
                    print(chr(i + j), end=' ')
173
                except UnicodeEncodeError:
174
                    print('?', end=' ')
175
        print()
176

177
find_bar_chars()
178
```
179

180
### Integration with Animation Factories
181

182
Using character discovery results with animation creation tools.
183

184
```python
185
from alive_progress.tools import print_chars
186
from alive_progress.animations import frame_spinner_factory, bar_factory
187
from alive_progress import alive_bar
188
import time
189

190
# Step 1: Discover characters
191
print("Exploring Braille patterns for spinner:")
192
print_chars(line_length=16, max_char=0x28FF)
193

194
# Step 2: Select interesting characters based on output
195
braille_chars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
196

197
# Step 3: Create spinner with discovered characters
198
custom_spinner = frame_spinner_factory(braille_chars)
199

200
# Step 4: Test in progress bar
201
print("\nTesting discovered characters:")
202
with alive_bar(50, spinner=custom_spinner, title='Custom Braille Spinner') as bar:
203
    for i in range(50):
204
        time.sleep(0.1)
205
        bar()
206

207
# Step 5: Discover bar characters
208
print("\nExploring block elements for bars:")
209
print_chars(line_length=8, max_char=0x259F)
210

211
# Step 6: Create custom bar
212
block_chars = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']
213
custom_bar = bar_factory(chars=block_chars, background='░')
214

215
# Step 7: Test custom bar
216
print("\nTesting custom bar:")
217
with alive_bar(50, bar=custom_bar, spinner=custom_spinner, title='Custom Bar & Spinner') as bar:
218
    for i in range(50):
219
        time.sleep(0.1)
220
        bar()
221
```
222

223
### Troubleshooting Terminal Issues
224

225
Using print_chars to diagnose terminal rendering problems.
226

227
```python
228
from alive_progress.tools import print_chars
229
import os
230
import sys
231

232
def diagnose_terminal():
233
    """Diagnose terminal Unicode support."""
234
    
235
    print(f"Terminal type: {os.getenv('TERM', 'unknown')}")
236
    print(f"Python version: {sys.version}")
237
    print(f"Stdout encoding: {sys.stdout.encoding}")
238
    print()
239
    
240
    # Test basic ASCII
241
    print("=== ASCII TEST (should work everywhere) ===")
242
    print_chars(line_length=16, max_char=0x80)
243
    
244
    # Test extended characters
245
    print("\n=== EXTENDED CHARACTERS TEST ===")
246
    print_chars(line_length=16, max_char=0x300)
247
    
248
    # Test symbols that alive-progress commonly uses
249
    print("\n=== ALIVE-PROGRESS COMMON SYMBOLS ===")
250
    common_symbols = ['│', '█', '▌', '▊', '▋', '●', '○', '◐', '◑', '◒', '◓', '⠋', '⠙', '⠹', '⠸']
251
    for i, char in enumerate(common_symbols):
252
        if i % 8 == 0:
253
            print()
254
        try:
255
            print(f'{char} ', end='')
256
        except UnicodeEncodeError:
257
            print('? ', end='')
258
    print("\n")
259

260
# Run diagnosis
261
diagnose_terminal()
262
```