0
# Formatter Management
1

2
Functions for working with output formatters that convert highlighted tokens into various formats including HTML, LaTeX, RTF, SVG, terminal colors, and image formats.
3

4
## Capabilities
5

6
### Formatter Discovery by Name
7

8
Get a formatter instance by its alias.
9

10
```python { .api }
11
def get_formatter_by_name(_alias: str, **options):
12
    """
13
    Get formatter instance by alias with options.
14
    
15
    Parameters:
16
    - _alias: Short identifier for formatter (e.g., 'html', 'latex', 'terminal')
17
    - **options: Formatter-specific options
18
    
19
    Returns:
20
    Formatter instance configured with the given options
21
    
22
    Raises:
23
    ClassNotFound: If no formatter with that alias is found
24
    """
25
```
26

27
Usage example:
28

29
```python
30
from pygments.formatters import get_formatter_by_name
31

32
# HTML formatter with custom CSS class
33
html_formatter = get_formatter_by_name('html', cssclass='highlight')
34

35
# LaTeX formatter for documents
36
latex_formatter = get_formatter_by_name('latex')
37

38
# Terminal formatter with 256 colors
39
terminal_formatter = get_formatter_by_name('terminal256')
40

41
# HTML formatter with line numbers
42
html_with_lines = get_formatter_by_name('html', linenos=True)
43
```
44

45
### Formatter Discovery by Filename
46

47
Get a formatter based on output filename patterns.
48

49
```python { .api }
50
def get_formatter_for_filename(fn: str, **options):
51
    """
52
    Get formatter for output filename with options.
53
    
54
    Parameters:
55
    - fn: Output file name to determine formatter
56
    - **options: Formatter-specific options
57
    
58
    Returns:
59
    Formatter instance appropriate for the file type
60
    
61
    Raises:
62
    ClassNotFound: If no formatter matches the filename
63
    """
64
```
65

66
Usage example:
67

68
```python
69
from pygments.formatters import get_formatter_for_filename
70

71
# Automatically choose formatter based on extension
72
html_formatter = get_formatter_for_filename('output.html')
73
latex_formatter = get_formatter_for_filename('document.tex')
74
rtf_formatter = get_formatter_for_filename('document.rtf')
75
```
76

77
### Formatter Enumeration
78

79
List all available formatters.
80

81
```python { .api }
82
def get_all_formatters() -> Iterator[type]:
83
    """
84
    Return generator of all available formatter classes.
85
    
86
    Yields:
87
    Formatter classes (not instances)
88
    """
89
```
90

91
Usage example:
92

93
```python
94
from pygments.formatters import get_all_formatters
95

96
# List all available formatters
97
for formatter_class in get_all_formatters():
98
    print(f"Name: {formatter_class.name}")
99
    print(f"Aliases: {', '.join(formatter_class.aliases)}")
100
    if formatter_class.filenames:
101
        print(f"Files: {', '.join(formatter_class.filenames)}")
102
    print()
103

104
# Find HTML-related formatters
105
html_formatters = [
106
    cls for cls in get_all_formatters()
107
    if 'html' in cls.name.lower() or 'html' in cls.aliases
108
]
109
```
110

111
### Class-Only Discovery
112

113
Find formatter classes without instantiating them.
114

115
```python { .api }
116
def find_formatter_class(_alias: str):
117
    """
118
    Find formatter class by alias without instantiation.
119
    
120
    Parameters:
121
    - _alias: Formatter alias
122
    
123
    Returns:
124
    Formatter class or None if not found
125
    """
126
```
127

128
### Custom Formatter Loading
129

130
Load custom formatters from files.
131

132
```python { .api }
133
def load_formatter_from_file(filename: str, formattername: str = "CustomFormatter", **options):
134
    """
135
    Load custom formatter from file.
136
    
137
    Parameters:
138
    - filename: Path to Python file containing formatter class
139
    - formattername: Name of formatter class in file (default "CustomFormatter")
140
    - **options: Options passed to formatter constructor
141
    
142
    Returns:
143
    Custom formatter instance
144
    
145
    Raises:
146
    ClassNotFound: If file cannot be loaded or class not found
147
    """
148
```
149

150
## Common Formatter Types
151

152
### HTML Formatter
153

154
```python
155
from pygments.formatters import HtmlFormatter
156

157
# Basic HTML
158
formatter = HtmlFormatter()
159

160
# HTML with line numbers and CSS class
161
formatter = HtmlFormatter(linenos=True, cssclass='codehilite')
162

163
# Inline styles (no CSS classes)
164
formatter = HtmlFormatter(noclasses=True)
165

166
# Full HTML document
167
formatter = HtmlFormatter(full=True, title='Code Sample')
168
```
169

170
### Terminal Formatters
171

172
```python
173
from pygments.formatters import TerminalFormatter, Terminal256Formatter, TerminalTrueColorFormatter
174

175
# Basic terminal colors (8/16 colors)
176
terminal_fmt = TerminalFormatter()
177

178
# 256-color terminal
179
terminal256_fmt = Terminal256Formatter()
180

181
# True color terminal (24-bit)
182
truecolor_fmt = TerminalTrueColorFormatter()
183
```
184

185
### LaTeX Formatter
186

187
```python
188
from pygments.formatters import LatexFormatter
189

190
# Basic LaTeX
191
latex_fmt = LatexFormatter()
192

193
# LaTeX with line numbers
194
latex_fmt = LatexFormatter(linenos=True)
195

196
# Embedded LaTeX (for inclusion in documents)
197
latex_fmt = LatexFormatter(verboptions="frame=single")
198
```
199

200
### Image Formatters
201

202
```python
203
from pygments.formatters import ImageFormatter
204

205
# PNG image (requires Pillow)
206
img_fmt = ImageFormatter(format='png')
207

208
# GIF with custom font
209
img_fmt = ImageFormatter(format='gif', font_name='Courier New')
210
```
211

212
## Common Formatter Options
213

214
Most formatters support these options:
215

216
- `style` (str): Color scheme name (default 'default')
217
- `full` (bool): Generate complete document (default False)
218
- `title` (str): Document title when full=True
219
- `encoding` (str): Output encoding
220
- `outencoding` (str): Override encoding option
221

222
### HTML-Specific Options
223

224
- `linenos` (bool): Add line numbers
225
- `cssclass` (str): CSS class name (default 'highlight')
226
- `noclasses` (bool): Use inline styles instead of CSS classes
227
- `prestyles` (str): Inline styles for `<pre>` tag
228
- `wrapcode` (bool): Wrap code in `<code>` tags
229

230
### LaTeX-Specific Options
231

232
- `linenos` (bool): Add line numbers
233
- `verboptions` (str): Options for fancyvrb package
234
- `commandprefix` (str): Command prefix for LaTeX commands
235

236
### Terminal-Specific Options
237

238
- `bg` (str): Background color ('light' or 'dark')
239
- `colorscheme` (dict): Custom color mapping
240

241
## Error Handling
242

243
- **ClassNotFound**: No formatter found for the given criteria
244
- **OptionError**: Invalid formatter options provided
245
- **ImportError**: Missing dependencies (e.g., Pillow for image formats)
246

247
## Output Examples
248

249
```python
250
from pygments import highlight
251
from pygments.lexers import PythonLexer
252
from pygments.formatters import HtmlFormatter, LatexFormatter, Terminal256Formatter
253

254
code = "print('Hello, World!')"
255
lexer = PythonLexer()
256

257
# HTML output
258
html = highlight(code, lexer, HtmlFormatter())
259
# '<div class="highlight"><pre><span></span><span class="nb">print</span>...'
260

261
# LaTeX output  
262
latex = highlight(code, lexer, LatexFormatter())
263
# '\\begin{Verbatim}[commandchars=\\\\\\{\\}]...'
264

265
# Terminal output with colors
266
terminal = highlight(code, lexer, Terminal256Formatter())
267
# ANSI color codes for terminal display
268
```