0
# Font Management
1

2
Font registration and lookup system for proper text rendering in converted SVG files. This module provides comprehensive font management capabilities with automatic font discovery and ReportLab integration.
3

4
## Capabilities
5

6
### Font Registration
7

8
Register fonts for use in SVG text rendering, with support for custom font files and automatic ReportLab integration.
9

10
```python { .api }
11
def register_font(font_name, font_path=None, weight='normal', style='normal', rlgFontName=None):
12
    """
13
    Register a font for use in SVG conversion.
14
    
15
    Parameters:
16
    - font_name: str - Font family name (e.g., 'Arial', 'Times New Roman')
17
    - font_path: str, optional - Path to font file (.ttf, .otf). If None, system font discovery is attempted
18
    - weight: str - Font weight ('normal', 'bold', or numeric weight)
19
    - style: str - Font style ('normal', 'italic')
20
    - rlgFontName: str, optional - Custom ReportLab font name override
21
    
22
    Returns:
23
    tuple: (font_name, exact_match) - ReportLab font name and boolean indicating exact match, or (None, False) if registration failed
24
    """
25
```
26

27
**Usage Examples:**
28

29
```python
30
from svglib.svglib import register_font
31

32
# Register system font by name
33
font_name, exact = register_font('Arial')
34

35
# Register font with specific weight and style
36
font_name, exact = register_font('Arial', weight='bold', style='italic')
37

38
# Register custom font file
39
font_name, exact = register_font('CustomFont', font_path='/path/to/custom_font.ttf')
40

41
# Register with custom ReportLab name
42
font_name, exact = register_font('MyFont', font_path='/fonts/myfont.ttf', rlgFontName='MyCustomRLFont')
43
```
44

45
### Font Lookup
46

47
Find registered fonts by family name, weight, and style for use in text rendering.
48

49
```python { .api }
50
def find_font(font_name, weight='normal', style='normal'):
51
    """
52
    Find a registered font by family name, weight, and style.
53
    
54
    Parameters:
55
    - font_name: str - Font family name
56
    - weight: str - Font weight ('normal', 'bold', or numeric)
57
    - style: str - Font style ('normal', 'italic')
58
    
59
    Returns:
60
    tuple: (font_name, exact_match) - ReportLab font name and boolean indicating exact match, or (None, False) if not found
61
    """
62
```
63

64
**Usage Examples:**
65

66
```python
67
from svglib.svglib import find_font
68

69
# Find normal weight font
70
rl_font, exact = find_font('Arial')
71

72
# Find bold italic font
73
rl_font, exact = find_font('Times New Roman', weight='bold', style='italic')
74

75
# Check if font exists
76
rl_font, exact = find_font('CustomFont')
77
if rl_font:
78
    print(f"CustomFont is available as {rl_font}, exact match: {exact}")
79
```
80

81
### Font Family Registration
82

83
Register complete font families with multiple variants through the FontMap class.
84

85
**Usage Example:**
86

87
```python
88
from svglib.fonts import get_global_font_map
89

90
# Register complete font family via FontMap instance
91
font_map = get_global_font_map()
92
font_map.register_font_family(
93
    'MyFamily',
94
    normal='/fonts/myfamily-regular.ttf',
95
    bold='/fonts/myfamily-bold.ttf',
96
    italic='/fonts/myfamily-italic.ttf',
97
    bolditalic='/fonts/myfamily-bolditalic.ttf'
98
)
99
```
100

101
### Font Map Management
102

103
Access the global font mapping system for advanced font management.
104

105
```python { .api }
106
def get_global_font_map():
107
    """
108
    Get the global FontMap instance.
109
    
110
    Returns:
111
    FontMap: Global font mapping instance
112
    """
113
```
114

115
### FontMap Class
116

117
Main class for managing font mappings between SVG font names and ReportLab fonts.
118

119
```python { .api }
120
class FontMap:
121
    """
122
    Managing the mapping of SVG font names to ReportLab fonts and registering
123
    them in ReportLab.
124
    """
125
    
126
    def __init__(self):
127
        """Initialize FontMap with default fonts."""
128
    
129
    def register_font_family(self, family, normal, bold=None, italic=None, bolditalic=None):
130
        """
131
        Register an entire font family with different variants.
132
        
133
        Parameters:
134
        - family: str - Font family name
135
        - normal: str - Path to normal weight font file
136
        - bold: str, optional - Path to bold weight font file
137
        - italic: str, optional - Path to italic style font file
138
        - bolditalic: str, optional - Path to bold italic font file
139
        """
140
    
141
    @staticmethod
142
    def build_internal_name(family, weight='normal', style='normal'):
143
        """
144
        Build internal font name from family, weight, and style.
145
        
146
        Parameters:
147
        - family: str - Font family name
148
        - weight: str - Font weight
149
        - style: str - Font style
150
        
151
        Returns:
152
        str: Internal font name (e.g., 'Arial-BoldItalic')
153
        """
154
    
155
    @staticmethod
156
    def guess_font_filename(basename, weight='normal', style='normal', extension='ttf'):
157
        """
158
        Guess font filename based on family, weight, and style.
159
        
160
        Parameters:
161
        - basename: str - Base font name
162
        - weight: str - Font weight
163
        - style: str - Font style
164
        - extension: str - Font file extension
165
        
166
        Returns:
167
        str: Guessed filename
168
        """
169
    
170
    def use_fontconfig(self, font_name, weight='normal', style='normal'):
171
        """
172
        Use fontconfig to find and register fonts on Unix-like systems.
173
        
174
        Parameters:
175
        - font_name: str - Font family name
176
        - weight: str - Font weight
177
        - style: str - Font style
178
        
179
        Returns:
180
        tuple: (font_path, success) - Path to font file and success status
181
        """
182
    
183
    def register_default_fonts(self):
184
        """Register default ReportLab fonts in the font map."""
185
```
186

187
**Usage Example:**
188

189
```python
190
from svglib.fonts import get_global_font_map, FontMap
191

192
# Get global font map
193
font_map = get_global_font_map()
194

195
# Create custom font map
196
custom_map = FontMap()
197

198
# Build internal font names
199
internal_name = FontMap.build_internal_name('Arial', 'bold', 'italic')
200
# Returns: 'Arial-BoldItalic'
201
```
202

203
## Constants
204

205
### Standard Font Names
206

207
Tuple of standard ReportLab font names available by default.
208

209
```python { .api }
210
STANDARD_FONT_NAMES = (
211
    'Times-Roman', 'Times-Italic', 'Times-Bold', 'Times-BoldItalic',
212
    'Helvetica', 'Helvetica-Oblique', 'Helvetica-Bold', 'Helvetica-BoldOblique',
213
    'Courier', 'Courier-Oblique', 'Courier-Bold', 'Courier-BoldOblique',
214
    'Symbol', 'ZapfDingbats',
215
)
216
```
217

218
### Default Font Settings
219

220
Default values used for font properties when not specified.
221

222
```python { .api }
223
DEFAULT_FONT_NAME = "Helvetica"
224
DEFAULT_FONT_WEIGHT = 'normal'
225
DEFAULT_FONT_STYLE = 'normal'
226
DEFAULT_FONT_SIZE = 12
227
```
228

229
**Usage Example:**
230

231
```python
232
from svglib.fonts import (
233
    STANDARD_FONT_NAMES, DEFAULT_FONT_NAME, 
234
    DEFAULT_FONT_WEIGHT, DEFAULT_FONT_STYLE, DEFAULT_FONT_SIZE
235
)
236

237
# Check if font is standard
238
font_name = 'Helvetica-Bold'
239
if font_name in STANDARD_FONT_NAMES:
240
    print(f"{font_name} is a standard ReportLab font")
241

242
# Use defaults
243
font_size = DEFAULT_FONT_SIZE  # 12
244
font_weight = DEFAULT_FONT_WEIGHT  # 'normal'
245
```