0
# SVGLib
1

2
A pure-Python library for reading and converting SVG files to ReportLab Graphics drawings. SVGLib enables developers to convert SVG graphics into ReportLab Drawing objects that can be used for PDF generation, bitmap conversion, and integration with ReportLab's document generation framework.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
from svglib.svglib import svg2rlg
14
```
15

16
For font management:
17

18
```python
19
from svglib.svglib import register_font, find_font
20
```
21

22
For utility functions:
23

24
```python
25
from svglib.utils import normalise_svg_path
26
```
27

28
For package metadata:
29

30
```python
31
from svglib.svglib import __version__, __author__, __license__, __date__
32
```
33

34
## Basic Usage
35

36
### Python API Usage
37

38
```python
39
from svglib.svglib import svg2rlg
40
from reportlab.graphics import renderPDF, renderPM
41

42
# Convert SVG file to ReportLab Drawing
43
drawing = svg2rlg("input.svg")
44

45
# Render to PDF
46
renderPDF.drawToFile(drawing, "output.pdf")
47

48
# Render to PNG bitmap
49
renderPM.drawToFile(drawing, "output.png", fmt="PNG")
50

51
# Use with compressed SVG files (.svgz)
52
drawing = svg2rlg("compressed.svgz")  # Automatically handles decompression
53
```
54

55
### Command Line Usage
56

57
SVGLib includes `svg2pdf`, a command-line tool for converting SVG files to PDF:
58

59
```bash
60
# Convert single SVG file to PDF
61
svg2pdf input.svg
62

63
# Convert multiple files
64
svg2pdf file1.svg file2.svgz
65

66
# Specify output filename
67
svg2pdf -o output.pdf input.svg
68

69
# Use pattern for batch conversion
70
svg2pdf -o "%(base)s.pdf" path/*.svg
71

72
# Include timestamp in filename
73
svg2pdf -o "{dirname}/out-{now.hour}-{now.minute}-{now.second}-%(base)s.pdf" path/*.svg
74
```
75

76
## Architecture
77

78
SVGLib uses a three-layer architecture for SVG processing and conversion:
79

80
- **Parser Layer**: Uses lxml to parse SVG DOM, handling both plain and compressed (.svgz) files
81
- **Converter Layer**: Transforms SVG elements to ReportLab graphics through attribute and shape converters
82
- **Renderer Layer**: Generates final ReportLab Drawing objects with proper coordinate transformations and styling
83

84
The library integrates with ReportLab's graphics system, enabling converted drawings to be used in PDF documents, bitmap rendering, and ReportLab's Platypus framework for document layout.
85

86
## Capabilities
87

88
### SVG Conversion
89

90
Core functionality for converting SVG files and streams to ReportLab Drawing objects, with support for compressed files and flexible input formats.
91

92
```python { .api }
93
def svg2rlg(path, resolve_entities=False, **kwargs):
94
    """
95
    Convert an SVG file to an RLG Drawing object.
96
    
97
    Parameters:
98
    - path: str, pathlib.Path, or file-like object - SVG file path or stream
99
    - resolve_entities: bool - Enable XML entity resolution
100
    - **kwargs: Additional arguments passed to SvgRenderer
101
    
102
    Returns:
103
    Drawing: ReportLab Drawing object
104
    """
105
```
106

107
[SVG Conversion](./svg-conversion.md)
108

109
### Font Management
110

111
Font registration and lookup system for proper text rendering in converted SVG files, with automatic font discovery and ReportLab integration.
112

113
```python { .api }
114
def register_font(font_name, font_path=None, weight='normal', style='normal', rlgFontName=None):
115
    """
116
    Register a font for use in SVG conversion.
117
    
118
    Parameters:
119
    - font_name: str - Font family name
120
    - font_path: str, optional - Path to font file
121
    - weight: str - Font weight ('normal', 'bold')
122
    - style: str - Font style ('normal', 'italic')
123
    - rlgFontName: str, optional - ReportLab font name override
124
    
125
    Returns:
126
    bool: True if font registered successfully
127
    """
128

129
def find_font(font_name, weight='normal', style='normal'):
130
    """
131
    Find a registered font by family name, weight, and style.
132
    
133
    Parameters:
134
    - font_name: str - Font family name
135
    - weight: str - Font weight
136
    - style: str - Font style
137
    
138
    Returns:
139
    str or None: ReportLab font name if found
140
    """
141
```
142

143
[Font Management](./font-management.md)
144

145
### SVG Path Processing
146

147
Utility functions for parsing, normalizing, and converting SVG path data and mathematical operations for arc and bezier curve processing.
148

149
```python { .api }
150
def normalise_svg_path(attr):
151
    """
152
    Normalize SVG path data by adding operation codes.
153
    
154
    Parameters:
155
    - attr: str - SVG path data string
156
    
157
    Returns:
158
    list: Normalized path operations and coordinates
159
    """
160
```
161

162
[SVG Path Processing](./svg-path-processing.md)
163

164
### Command Line Tool
165

166
A command-line script `svg2pdf` for direct SVG to PDF conversion from the terminal, with support for batch processing and flexible output patterns.
167

168
```python { .api }
169
def svg2pdf(path, outputPat=None):
170
    """
171
    Convert an SVG file to a PDF file via command line.
172
    
173
    Parameters:
174
    - path: str - Input SVG file path (.svg or .svgz)
175
    - outputPat: str, optional - Output filename pattern with placeholders
176
    
177
    Available placeholders:
178
    - %(dirname)s: Input file directory
179
    - %(basename)s: Input filename with extension
180
    - %(base)s: Input filename without extension
181
    - %(ext)s: Input file extension
182
    - {now}: Datetime object for timestamps
183
    """
184
```
185

186
**Command Line Arguments:**
187
- Positional: Input SVG file paths (.svg or .svgz)
188
- `-o, --output PATH_PAT`: Output path pattern
189
- `-v, --version`: Print version and exit
190
- `-h, --help`: Show help message
191

192
### Package Metadata
193

194
Access to package version and metadata information.
195

196
```python { .api }
197
__version__ = "1.5.1"
198
__author__ = "Dinu Gherman" 
199
__license__ = "LGPL 3"
200
__date__ = "2023-01-07"
201
```