0
# File I/O Operations
1

2
Functions and methods for reading DOT files and strings, plus comprehensive output generation in various formats including images, vector graphics, and DOT files.
3

4
## Capabilities
5

6
### DOT Input Functions
7

8
Functions for parsing DOT language input from files and strings to create pydot graph objects.
9

10
```python { .api }
11
def graph_from_dot_file(path, encoding=None):
12
    """
13
    Load graphs from DOT file.
14
    
15
    Parameters:
16
    - path (str|bytes): Path to DOT file
17
    - encoding (str, optional): File encoding (default: None for auto-detection)
18
    
19
    Returns:
20
    list[Dot]|None: List of Dot objects or None if parsing fails
21
    """
22

23
def graph_from_dot_data(s):
24
    """
25
    Create graphs from DOT description string.
26
    
27
    Parameters:
28
    - s (str): DOT language string
29
    
30
    Returns:
31
    list[Dot]|None: List of Dot objects or None if parsing fails
32
    """
33
```
34

35
### Output Generation Methods
36

37
The Dot class provides comprehensive output generation through dynamically created methods for each supported format.
38

39
#### Image Formats
40

41
Generate raster and vector image files:
42

43
```python { .api }
44
# PNG format
45
def create_png(self, prog=None, encoding=None):
46
    """Create PNG image as bytes."""
47
    
48
def write_png(self, path, prog=None, encoding=None):
49
    """Write PNG image to file."""
50

51
# SVG format  
52
def create_svg(self, prog=None, encoding=None):
53
    """Create SVG vector image as bytes."""
54
    
55
def write_svg(self, path, prog=None, encoding=None):
56
    """Write SVG vector image to file."""
57

58
# PDF format
59
def create_pdf(self, prog=None, encoding=None):
60
    """Create PDF document as bytes."""
61
    
62
def write_pdf(self, path, prog=None, encoding=None):
63
    """Write PDF document to file."""
64

65
# JPEG format
66
def create_jpeg(self, prog=None, encoding=None):
67
    """Create JPEG image as bytes."""
68
    
69
def write_jpeg(self, path, prog=None, encoding=None):
70
    """Write JPEG image to file."""
71

72
# GIF format
73
def create_gif(self, prog=None, encoding=None):
74
    """Create GIF image as bytes."""
75
    
76
def write_gif(self, path, prog=None, encoding=None):
77
    """Write GIF image to file."""
78
```
79

80
#### DOT Format Output
81

82
Generate DOT language representations:
83

84
```python { .api }
85
def create_dot(self, prog=None, encoding=None):
86
    """
87
    Create GraphViz-processed DOT output as bytes.
88
    
89
    This version is processed by GraphViz and includes layout information.
90
    """
91
    
92
def write_dot(self, path, prog=None, encoding=None):
93
    """Write GraphViz-processed DOT output to file."""
94

95
def write_raw(self, path):
96
    """
97
    Write raw pydot DOT output to file.
98
    
99
    This version is generated directly by pydot without GraphViz processing.
100
    """
101

102
def to_string(self):
103
    """
104
    Generate raw DOT string representation.
105
    
106
    Returns:
107
    str: DOT language representation
108
    """
109
```
110

111
#### Additional Formats
112

113
Support for specialized formats:
114

115
```python { .api }
116
# PostScript formats
117
def create_ps(self, prog=None, encoding=None): ...
118
def write_ps(self, path, prog=None, encoding=None): ...
119
def create_ps2(self, prog=None, encoding=None): ...  
120
def write_ps2(self, path, prog=None, encoding=None): ...
121

122
# Plain text formats
123
def create_plain(self, prog=None, encoding=None): ...
124
def write_plain(self, path, prog=None, encoding=None): ...
125

126
# Interactive formats
127
def create_xdot(self, prog=None, encoding=None): ...
128
def write_xdot(self, path, prog=None, encoding=None): ...
129

130
# Map formats for web
131
def create_cmap(self, prog=None, encoding=None): ...
132
def write_cmap(self, path, prog=None, encoding=None): ...
133
def create_cmapx(self, prog=None, encoding=None): ...
134
def write_cmapx(self, path, prog=None, encoding=None): ...
135
```
136

137
### All Supported Output Formats
138

139
Complete list of supported formats (23 total): canon, cmap, cmapx, cmapx_np, dia, dot, fig, gd, gd2, gif, hpgl, imap, imap_np, ismap, jpe, jpeg, jpg, mif, mp, pcl, pdf, pic, plain, plain-ext, png, ps, ps2, svg, svgz, vml, vmlz, vrml, vtx, wbmp, xdot, xlib
140

141
### GraphViz Program Selection
142

143
All output methods accept optional parameters:
144

145
```python { .api }
146
# Parameters for all create_* and write_* methods:
147
# - prog (str, optional): GraphViz program to use ('dot', 'neato', 'fdp', 'sfdp', 'twopi', 'circo')
148
# - encoding (str, optional): Output encoding (default: None)
149
```
150

151
## Usage Examples
152

153
### Loading from DOT Files
154

155
```python
156
import pydot
157

158
# Load graph from file
159
graphs = pydot.graph_from_dot_file("network.dot")
160
if graphs:
161
    graph = graphs[0]  # Get first graph
162
    print(f"Loaded graph: {graph.get_name()}")
163

164
# Load with specific encoding
165
graphs = pydot.graph_from_dot_file("unicode_graph.dot", encoding="utf-8")
166
```
167

168
### Parsing DOT Strings
169

170
```python
171
dot_string = '''
172
digraph G {
173
    A -> B [label="edge"];
174
    B -> C [color=blue];
175
    C -> A [style=dashed];
176
}
177
'''
178

179
graphs = pydot.graph_from_dot_data(dot_string)
180
if graphs:
181
    graph = graphs[0]
182
    print(f"Nodes: {len(graph.get_nodes())}")
183
    print(f"Edges: {len(graph.get_edges())}")
184
```
185

186
### Generating Different Output Formats
187

188
```python
189
import pydot
190

191
# Create a simple graph
192
graph = pydot.Dot("output_example", graph_type="digraph")
193
graph.add_node(pydot.Node("A", shape="box"))
194
graph.add_node(pydot.Node("B", shape="circle"))
195
graph.add_edge(pydot.Edge("A", "B"))
196

197
# Generate PNG image
198
graph.write_png("diagram.png")
199

200
# Generate SVG for web
201
graph.write_svg("diagram.svg")
202

203
# Generate PDF for printing
204
graph.write_pdf("diagram.pdf")
205

206
# Get raw DOT string
207
dot_source = graph.to_string()
208
print(dot_source)
209

210
# Get GraphViz-processed DOT with layout
211
processed_dot = graph.create_dot()
212
with open("processed.dot", "wb") as f:
213
    f.write(processed_dot)
214
```
215

216
### Using Different Layout Engines
217

218
```python
219
# Use different GraphViz programs for layout
220
graph.write_png("dot_layout.png", prog="dot")      # Hierarchical
221
graph.write_png("neato_layout.png", prog="neato")  # Spring model
222
graph.write_png("circo_layout.png", prog="circo")  # Circular
223
graph.write_png("fdp_layout.png", prog="fdp")      # Force-directed
224
```
225

226
### Getting Output as Bytes
227

228
```python
229
# Get image data as bytes for further processing
230
png_data = graph.create_png()
231
svg_data = graph.create_svg()
232

233
# Use with web frameworks, image processing libraries, etc.
234
from PIL import Image
235
import io
236

237
image = Image.open(io.BytesIO(png_data))
238
image.show()
239
```