0
# PyFiglet
1

2
A pure Python implementation of FIGlet for creating ASCII art text from regular text using various fonts. PyFiglet converts plain text into stylized ASCII art output without requiring external dependencies, supporting the complete FIGlet font ecosystem with proper kerning and smushing for authentic character spacing.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import pyfiglet
14
from pyfiglet import Figlet, figlet_format, print_figlet
15
```
16

17
## Basic Usage
18

19
```python
20
import pyfiglet
21

22
# Simple text conversion
23
text = "Hello World"
24
ascii_art = pyfiglet.figlet_format(text)
25
print(ascii_art)
26

27
# Using a specific font
28
ascii_art = pyfiglet.figlet_format(text, font="big")
29
print(ascii_art)
30

31
# Using the Figlet class for more control
32
fig = pyfiglet.Figlet(font='slant', width=100)
33
ascii_art = fig.renderText(text)
34
print(ascii_art)
35

36
# Direct printing with colors (on supported terminals)
37
pyfiglet.print_figlet("Colored", colors="red:blue")
38
```
39

40
## Architecture
41

42
PyFiglet follows a multi-layered architecture:
43

44
- **Figlet**: Main rendering class that coordinates font loading, text processing, and output generation
45
- **FigletFont**: Font loading and parsing system supporting .flf, .tlf format files and ZIP archives
46
- **FigletString**: Enhanced string class with ASCII art manipulation methods (reverse, flip, normalization)
47
- **Rendering Engine**: Internal pipeline handling character smushing, kerning, justification, and line wrapping
48

49
The design supports the complete FIGlet specification while maintaining compatibility with existing FIGlet fonts and rendering behavior.
50

51
## Capabilities 
52

53
### Text Rendering
54

55
Core functionality for converting text to ASCII art using various fonts, with support for customization options including width, direction, and justification.
56

57
```python { .api }
58
def figlet_format(text: str, font: str = "standard", **kwargs) -> FigletString: ...
59
def print_figlet(text: str, font: str = "standard", colors: str = ":", **kwargs) -> None: ...
60
```
61

62
[Text Rendering](./text-rendering.md)
63

64
### Font Management
65

66
Comprehensive font system including discovery, validation, installation, and information retrieval for FIGlet fonts.
67

68
```python { .api }
69
class FigletFont:
70
    @classmethod
71
    def getFonts(cls) -> list[str]: ...
72
    @classmethod
73
    def infoFont(cls, font: str, short: bool = False) -> str: ...
74
    @staticmethod
75
    def installFonts(file_name: str) -> None: ...
76
```
77

78
[Font Management](./font-management.md)
79

80
### Advanced Rendering Control
81

82
Fine-grained control over text rendering including direction, justification, width constraints, and output manipulation.
83

84
```python { .api }
85
class Figlet:
86
    def __init__(self, font: str = "standard", direction: str = "auto", justify: str = "auto", width: int = 80): ...
87
    def renderText(self, text: str) -> FigletString: ...
88
    def setFont(self, **kwargs: str) -> None: ...
89
```
90

91
[Advanced Rendering](./advanced-rendering.md)
92

93
### String Manipulation
94

95
Enhanced string processing capabilities for ASCII art including reversing, flipping, and whitespace normalization.
96

97
```python { .api }
98
class FigletString:
99
    def reverse(self) -> FigletString: ...
100
    def flip(self) -> FigletString: ...
101
    def strip_surrounding_newlines(self) -> str: ...
102
    def normalize_surrounding_newlines(self) -> str: ...
103
```
104

105
[String Manipulation](./string-manipulation.md)
106

107
### Color Support
108

109
ANSI color support for terminal output with foreground/background color specifications and RGB color values.
110

111
```python { .api }
112
def parse_color(color: str) -> str: ...
113
def color_to_ansi(color: str, isBackground: bool) -> str: ...
114
```
115

116
[Color Support](./color-support.md)
117

118
### Command Line Interface
119

120
Full-featured command line interface with extensive options for font selection, text formatting, color output, and font management.
121

122
```python { .api }
123
def main() -> int: ...
124
```
125

126
[Command Line Interface](./cli.md)
127

128
## Exception Handling
129

130
PyFiglet provides a comprehensive exception hierarchy for error handling:
131

132
```python { .api }
133
class FigletError(Exception): ...
134
class FontNotFound(FigletError): ...
135
class FontError(FigletError): ...
136
class CharNotPrinted(FigletError): ...
137
class InvalidColor(FigletError): ...
138
```
139

140
These exceptions enable precise error handling for different failure modes including missing fonts, invalid font files, insufficient display width, and invalid color specifications.
141

142
## Constants
143

144
```python { .api }
145
DEFAULT_FONT: str  # "standard" 
146
COLOR_CODES: dict[str, int]  # ANSI color name to code mapping
147
SHARED_DIRECTORY: str  # Platform-specific shared font directory
148
```