0
# Core Operations
1

2
Primary document management and file I/O operations for creating and saving SVG drawings. The Drawing class serves as the main entry point and container for all SVG content.
3

4
## Capabilities
5

6
### Drawing Class
7

8
The main SVG document container and factory for all SVG elements. Acts as both document root and element creation interface.
9

10
```python { .api }
11
class Drawing:
12
    """
13
    Main SVG document container and factory for all SVG elements
14
    Inherits from SVG (container) and ElementFactory (element creation)
15
    """
16
    def __init__(filename="noname.svg", size=('100%', '100%'), profile='full', debug=True, **extra):
17
        """
18
        Create new SVG drawing
19
        
20
        Args:
21
            filename: Filesystem filename for saving (default: "noname.svg")
22
            size: 2-tuple (width, height) for document size (default: ('100%', '100%'))
23
            profile: 'tiny' or 'full' - SVG profile specification (default: 'full')
24
            debug: Enable element validation (default: True)
25
            **extra: Additional SVG attributes
26
        """
27
```
28

29
**Usage Examples:**
30

31
```python
32
import svgwrite
33

34
# Basic drawing with default settings
35
dwg = svgwrite.Drawing('output.svg')
36

37
# Tiny profile for mobile/embedded use
38
dwg = svgwrite.Drawing('mobile.svg', profile='tiny', size=('240px', '320px'))
39

40
# Full profile with custom dimensions
41
dwg = svgwrite.Drawing('desktop.svg', profile='full', size=(800, 600))
42

43
# Disable validation for performance
44
dwg = svgwrite.Drawing('fast.svg', debug=False)
45
```
46

47
### File Operations
48

49
Methods for saving and serializing SVG documents to various output formats.
50

51
```python { .api }
52
def save(pretty=False, indent=2):
53
    """
54
    Write SVG XML to the filename specified in constructor
55
    
56
    Args:
57
        pretty: Format XML with indentation (default: False)
58
        indent: Number of spaces for indentation when pretty=True (default: 2)
59
    """
60

61
def saveas(filename, pretty=False, indent=2):
62
    """
63
    Write SVG XML to specified filename
64
    
65
    Args:
66
        filename: Target filename for output
67
        pretty: Format XML with indentation (default: False)
68
        indent: Number of spaces for indentation when pretty=True (default: 2)
69
    """
70

71
def write(fileobj, pretty=False, indent=2):
72
    """
73
    Write SVG XML to file-like object
74
    
75
    Args:
76
        fileobj: File-like object supporting write()
77
        pretty: Format XML with indentation (default: False)
78
        indent: Number of spaces for indentation when pretty=True (default: 2)
79
    """
80

81
def tostring():
82
    """
83
    Get SVG document as XML string
84
    
85
    Returns:
86
        str: Complete SVG document as XML string
87
    """
88

89
def get_xml():
90
    """
91
    Get ElementTree XML representation
92
    
93
    Returns:
94
        xml.etree.ElementTree.Element: Root XML element
95
    """
96
```
97

98
**Usage Examples:**
99

100
```python
101
import svgwrite
102

103
dwg = svgwrite.Drawing('example.svg')
104
dwg.add(dwg.circle((50, 50), 25, fill='blue'))
105

106
# Basic save to filename from constructor
107
dwg.save()
108

109
# Save with pretty formatting
110
dwg.save(pretty=True, indent=4)
111

112
# Save to different filename
113
dwg.saveas('copy.svg', pretty=True)
114

115
# Write to file object
116
with open('output.svg', 'w') as f:
117
    dwg.write(f, pretty=True)
118

119
# Get as string for processing
120
svg_content = dwg.tostring()
121
print(len(svg_content))  # Check size
122

123
# Get XML tree for manipulation
124
xml_tree = dwg.get_xml()
125
```
126

127
### Element Management
128

129
Methods for adding and managing child elements within the drawing.
130

131
```python { .api }
132
def add(element):
133
    """
134
    Add child element to the drawing
135
    
136
    Args:
137
        element: SVG element to add (created via factory methods)
138
    
139
    Returns:
140
        element: The added element for method chaining
141
    """
142

143
def insert(index, element):
144
    """
145
    Insert element at specific position
146
    
147
    Args:
148
        index: Position index for insertion
149
        element: SVG element to insert
150
    
151
    Returns:
152
        element: The inserted element
153
    """
154
```
155

156
**Usage Examples:**
157

158
```python
159
import svgwrite
160

161
dwg = svgwrite.Drawing('elements.svg')
162

163
# Create and add elements
164
rect = dwg.rect((10, 10), (100, 50), fill='red')
165
circle = dwg.circle((75, 75), 25, fill='blue')
166

167
# Add to drawing
168
dwg.add(rect)
169
dwg.add(circle)
170

171
# Method chaining
172
dwg.add(dwg.line((0, 0), (100, 100), stroke='black'))
173

174
# Insert at specific position
175
dwg.insert(0, dwg.text('Title', insert=(10, 20)))
176
```
177

178
### Stylesheet Management
179

180
Methods for managing CSS stylesheets and font embedding within SVG documents.
181

182
```python { .api }
183
def add_stylesheet(href, title, alternate="no", media="screen"):
184
    """
185
    Add external stylesheet reference
186
    
187
    Args:
188
        href: URL or path to CSS stylesheet
189
        title: Stylesheet title
190
        alternate: "yes" or "no" for alternate stylesheet (default: "no")
191
        media: CSS media type (default: "screen")
192
    """
193

194
def embed_stylesheet(content):
195
    """
196
    Embed CSS styles directly in SVG document
197
    
198
    Args:
199
        content: CSS stylesheet content as string
200
    """
201

202
def embed_font(name, filename):
203
    """
204
    Embed local font file as base64 data URI
205
    
206
    Args:
207
        name: Font family name for CSS reference
208
        filename: Path to font file (TTF, OTF, WOFF, etc.)
209
    """
210

211
def embed_google_web_font(name, uri):
212
    """
213
    Embed Google Web Font from CDN
214
    
215
    Args:
216
        name: Font family name
217
        uri: Google Fonts CSS URI
218
    """
219
```
220

221
**Usage Examples:**
222

223
```python
224
import svgwrite
225

226
dwg = svgwrite.Drawing('styled.svg')
227

228
# Link external stylesheet
229
dwg.add_stylesheet('styles.css', 'Main Styles')
230

231
# Embed CSS directly
232
css_styles = """
233
    .title { font-family: Arial; font-size: 24px; }
234
    .highlight { fill: yellow; stroke: red; }
235
"""
236
dwg.embed_stylesheet(css_styles)
237

238
# Embed local font
239
dwg.embed_font('CustomFont', 'assets/custom.ttf')
240

241
# Use Google Fonts
242
dwg.embed_google_web_font(
243
    'Roboto', 
244
    'https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;700'
245
)
246

247
# Use in elements
248
dwg.add(dwg.text('Styled Text', insert=(10, 30), class_='title'))
249
```
250

251
### Jupyter Integration
252

253
Special method for displaying SVG content in Jupyter notebooks.
254

255
```python { .api }
256
def _repr_svg_():
257
    """
258
    Return SVG string for Jupyter notebook display
259
    
260
    Returns:
261
        str: SVG content for notebook rendering
262
    """
263
```
264

265
**Usage Examples:**
266

267
```python
268
# In Jupyter notebook
269
import svgwrite
270

271
dwg = svgwrite.Drawing(size=('200px', '100px'))
272
dwg.add(dwg.circle((100, 50), 40, fill='lightblue'))
273

274
# Display automatically in notebook cell
275
dwg  # Calls _repr_svg_() automatically
276
```
277

278
### Font and Stylesheet Embedding
279

280
Methods for embedding external resources directly into SVG documents.
281

282
```python { .api }
283
def embed_stylesheet(content):
284
    """
285
    Add CSS stylesheet to defs section
286
    
287
    Args:
288
        content: CSS stylesheet content as string
289
    
290
    Returns:
291
        Style: Style element added to defs
292
    """
293

294
def embed_font(name, filename):
295
    """
296
    Embed font file as base64 encoded data
297
    
298
    Args:
299
        name: Font family name for CSS font-face declaration
300
        filename: Path to local font file (TTF, OTF, WOFF, etc.)
301
    """
302

303
def embed_google_web_font(name, uri):
304
    """
305
    Embed Google Web Font as base64 encoded data
306
    
307
    Args:
308
        name: Font family name for CSS font-face declaration
309
        uri: Google Fonts request URI (e.g., 'http://fonts.googleapis.com/css?family=Indie+Flower')
310
    """
311
```
312

313
**Usage Examples:**
314

315
```python
316
import svgwrite
317

318
dwg = svgwrite.Drawing('styled.svg')
319

320
# Embed custom CSS
321
css_content = """
322
.highlight { fill: yellow; stroke: red; stroke-width: 2px; }
323
.shadow { filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.5)); }
324
"""
325
dwg.embed_stylesheet(css_content)
326

327
# Embed local font file
328
dwg.embed_font('CustomFont', 'fonts/custom.ttf')
329

330
# Embed Google Web Font
331
dwg.embed_google_web_font('IndieFlower', 
332
                          'http://fonts.googleapis.com/css?family=Indie+Flower')
333

334
# Use embedded resources
335
styled_text = dwg.text('Styled Text', insert=(10, 50), 
336
                       font_family='CustomFont', class_='highlight shadow')
337
dwg.add(styled_text)
338

339
web_font_text = dwg.text('Web Font Text', insert=(10, 100),
340
                         font_family='IndieFlower', font_size='24px')
341
dwg.add(web_font_text)
342
```
343

344
### Container Features
345

346
Since Drawing inherits from SVG container, it supports all container operations for grouping and organizing elements.
347

348
```python { .api }
349
# Inherited container methods
350
def g(**extra):
351
    """Create group container for organizing elements"""
352

353
def defs(**extra):
354
    """Create definitions container for reusable elements"""
355

356
def svg(insert=None, size=None, **extra):
357
    """Create nested SVG container"""
358

359
def symbol(**extra):
360
    """Create symbol definition for reuse with <use> elements"""
361
```
362

363
**Usage Examples:**
364

365
```python
366
import svgwrite
367

368
dwg = svgwrite.Drawing('organized.svg')
369

370
# Create definitions for reuse
371
defs = dwg.defs()
372
gradient = dwg.linearGradient(start=(0, 0), end=(100, 0))
373
gradient.add_stop_color(0, 'red')
374
gradient.add_stop_color(1, 'blue')
375
defs.add(gradient)
376
dwg.add(defs)
377

378
# Create groups for organization
379
header_group = dwg.g(id='header')
380
header_group.add(dwg.rect((0, 0), (200, 50), fill=gradient.get_paint_server()))
381
header_group.add(dwg.text('Header', insert=(10, 30)))
382
dwg.add(header_group)
383

384
# Nested SVG for complex layouts
385
nested = dwg.svg(insert=(10, 60), size=(180, 100))
386
nested.add(dwg.circle((90, 50), 30, fill='green'))
387
dwg.add(nested)
388
```