retroflow 0.1.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- retroflow/__init__.py +45 -0
- retroflow/flowchart.py +194 -0
- retroflow/graph.py +192 -0
- retroflow/layout.py +302 -0
- retroflow/parser.py +99 -0
- retroflow/png_renderer.py +512 -0
- retroflow/py.typed +0 -0
- retroflow/renderer.py +252 -0
- retroflow-0.1.2.dist-info/METADATA +380 -0
- retroflow-0.1.2.dist-info/RECORD +12 -0
- retroflow-0.1.2.dist-info/WHEEL +4 -0
- retroflow-0.1.2.dist-info/licenses/LICENSE +21 -0
retroflow/__init__.py
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""
|
|
2
|
+
RetroFlow - Beautiful ASCII Flowcharts
|
|
3
|
+
|
|
4
|
+
A Python library for generating ASCII and PNG flowcharts with intelligent layout.
|
|
5
|
+
|
|
6
|
+
Example:
|
|
7
|
+
>>> from retroflow import FlowchartGenerator
|
|
8
|
+
>>> generator = FlowchartGenerator()
|
|
9
|
+
>>> flowchart = generator.generate('''
|
|
10
|
+
... A -> B
|
|
11
|
+
... B -> C
|
|
12
|
+
... ''')
|
|
13
|
+
>>> print(flowchart)
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from .flowchart import FlowchartGenerator, generate_flowchart
|
|
17
|
+
from .graph import Graph, create_graph
|
|
18
|
+
from .layout import LayoutAlgorithm, SimpleLayout, compute_layout
|
|
19
|
+
from .parser import ParseError, Parser, parse_flowchart
|
|
20
|
+
from .png_renderer import PNGRenderer, render_to_png
|
|
21
|
+
from .renderer import ASCIICanvas, FlowchartRenderer, render_flowchart
|
|
22
|
+
|
|
23
|
+
__version__ = "0.1.0"
|
|
24
|
+
__all__ = [
|
|
25
|
+
# Main API
|
|
26
|
+
"FlowchartGenerator",
|
|
27
|
+
"generate_flowchart",
|
|
28
|
+
# Parser
|
|
29
|
+
"parse_flowchart",
|
|
30
|
+
"ParseError",
|
|
31
|
+
"Parser",
|
|
32
|
+
# Graph
|
|
33
|
+
"Graph",
|
|
34
|
+
"create_graph",
|
|
35
|
+
# Layout
|
|
36
|
+
"compute_layout",
|
|
37
|
+
"LayoutAlgorithm",
|
|
38
|
+
"SimpleLayout",
|
|
39
|
+
# Renderers
|
|
40
|
+
"render_flowchart",
|
|
41
|
+
"FlowchartRenderer",
|
|
42
|
+
"ASCIICanvas",
|
|
43
|
+
"render_to_png",
|
|
44
|
+
"PNGRenderer",
|
|
45
|
+
]
|
retroflow/flowchart.py
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Main flowchart module.
|
|
3
|
+
|
|
4
|
+
Provides the high-level API for generating flowcharts.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from .graph import create_graph
|
|
8
|
+
from .layout import compute_layout
|
|
9
|
+
from .parser import parse_flowchart
|
|
10
|
+
from .png_renderer import render_to_png
|
|
11
|
+
from .renderer import render_flowchart
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class FlowchartGenerator:
|
|
15
|
+
"""
|
|
16
|
+
Main class for generating ASCII flowcharts.
|
|
17
|
+
|
|
18
|
+
Example:
|
|
19
|
+
generator = FlowchartGenerator()
|
|
20
|
+
flowchart = generator.generate('''
|
|
21
|
+
A -> B
|
|
22
|
+
B -> C
|
|
23
|
+
A -> C
|
|
24
|
+
''')
|
|
25
|
+
print(flowchart)
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
box_width: int = 11,
|
|
31
|
+
box_height: int = 3,
|
|
32
|
+
horizontal_spacing: int = 4,
|
|
33
|
+
vertical_spacing: int = 3,
|
|
34
|
+
layout_algorithm: str = "layered",
|
|
35
|
+
):
|
|
36
|
+
"""
|
|
37
|
+
Initialize the flowchart generator.
|
|
38
|
+
|
|
39
|
+
Args:
|
|
40
|
+
box_width: Width of each box (default: 11)
|
|
41
|
+
box_height: Height of each box (default: 3)
|
|
42
|
+
horizontal_spacing: Space between boxes horizontally (default: 4)
|
|
43
|
+
vertical_spacing: Space between boxes vertically (default: 3)
|
|
44
|
+
layout_algorithm: 'layered' or 'simple' (default: 'layered')
|
|
45
|
+
"""
|
|
46
|
+
self.box_width = box_width
|
|
47
|
+
self.box_height = box_height
|
|
48
|
+
self.horizontal_spacing = horizontal_spacing
|
|
49
|
+
self.vertical_spacing = vertical_spacing
|
|
50
|
+
self.layout_algorithm = layout_algorithm
|
|
51
|
+
|
|
52
|
+
def generate(self, input_text: str) -> str:
|
|
53
|
+
"""
|
|
54
|
+
Generate an ASCII flowchart from input text.
|
|
55
|
+
|
|
56
|
+
Args:
|
|
57
|
+
input_text: Multi-line string with connections (e.g., "A -> B")
|
|
58
|
+
|
|
59
|
+
Returns:
|
|
60
|
+
ASCII string representation of the flowchart
|
|
61
|
+
|
|
62
|
+
Raises:
|
|
63
|
+
ParseError: If input format is invalid
|
|
64
|
+
"""
|
|
65
|
+
# Parse input
|
|
66
|
+
connections = parse_flowchart(input_text)
|
|
67
|
+
|
|
68
|
+
# Create graph
|
|
69
|
+
graph = create_graph(connections)
|
|
70
|
+
|
|
71
|
+
# Compute layout
|
|
72
|
+
layout = compute_layout(
|
|
73
|
+
graph,
|
|
74
|
+
algorithm=self.layout_algorithm,
|
|
75
|
+
horizontal_spacing=self.horizontal_spacing,
|
|
76
|
+
vertical_spacing=self.vertical_spacing,
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
# Render flowchart
|
|
80
|
+
flowchart = render_flowchart(
|
|
81
|
+
graph,
|
|
82
|
+
layout,
|
|
83
|
+
box_width=self.box_width,
|
|
84
|
+
box_height=self.box_height,
|
|
85
|
+
horizontal_spacing=self.horizontal_spacing,
|
|
86
|
+
vertical_spacing=self.vertical_spacing,
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
return flowchart
|
|
90
|
+
|
|
91
|
+
def generate_with_stats(self, input_text: str) -> tuple:
|
|
92
|
+
"""
|
|
93
|
+
Generate flowchart and return statistics.
|
|
94
|
+
|
|
95
|
+
Args:
|
|
96
|
+
input_text: Multi-line string with connections
|
|
97
|
+
|
|
98
|
+
Returns:
|
|
99
|
+
Tuple of (flowchart_string, statistics_dict)
|
|
100
|
+
"""
|
|
101
|
+
connections = parse_flowchart(input_text)
|
|
102
|
+
graph = create_graph(connections)
|
|
103
|
+
|
|
104
|
+
layout = compute_layout(
|
|
105
|
+
graph,
|
|
106
|
+
algorithm=self.layout_algorithm,
|
|
107
|
+
horizontal_spacing=self.horizontal_spacing,
|
|
108
|
+
vertical_spacing=self.vertical_spacing,
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
flowchart = render_flowchart(
|
|
112
|
+
graph,
|
|
113
|
+
layout,
|
|
114
|
+
box_width=self.box_width,
|
|
115
|
+
box_height=self.box_height,
|
|
116
|
+
horizontal_spacing=self.horizontal_spacing,
|
|
117
|
+
vertical_spacing=self.vertical_spacing,
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
stats = {
|
|
121
|
+
"nodes": len(graph.nodes),
|
|
122
|
+
"edges": len(graph.edges),
|
|
123
|
+
"has_cycle": graph.has_cycle(),
|
|
124
|
+
"layout_dimensions": layout.get_layout_dimensions(),
|
|
125
|
+
"longest_path": graph.get_longest_path_length(),
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
return flowchart, stats
|
|
129
|
+
|
|
130
|
+
def save_png(
|
|
131
|
+
self, input_text: str, output_path: str = "diagram.png", **png_kwargs
|
|
132
|
+
) -> str:
|
|
133
|
+
"""
|
|
134
|
+
Generate a flowchart and save it as a high-resolution PNG image.
|
|
135
|
+
|
|
136
|
+
Args:
|
|
137
|
+
input_text: Multi-line string with connections (e.g., "A -> B")
|
|
138
|
+
output_path: Path to save the PNG file
|
|
139
|
+
**png_kwargs: Additional parameters for PNG renderer
|
|
140
|
+
|
|
141
|
+
Returns:
|
|
142
|
+
Path to the saved PNG file
|
|
143
|
+
"""
|
|
144
|
+
# Parse input
|
|
145
|
+
connections = parse_flowchart(input_text)
|
|
146
|
+
|
|
147
|
+
# Create graph
|
|
148
|
+
graph = create_graph(connections)
|
|
149
|
+
|
|
150
|
+
# Compute layout
|
|
151
|
+
layout = compute_layout(
|
|
152
|
+
graph,
|
|
153
|
+
algorithm=self.layout_algorithm,
|
|
154
|
+
horizontal_spacing=self.horizontal_spacing,
|
|
155
|
+
vertical_spacing=self.vertical_spacing,
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
# Render to PNG
|
|
159
|
+
return render_to_png(graph, layout, output_path, **png_kwargs)
|
|
160
|
+
|
|
161
|
+
def save_txt(self, input_text: str, output_path: str = "diagram.txt") -> str:
|
|
162
|
+
"""
|
|
163
|
+
Generate a flowchart and save it as an ASCII text file.
|
|
164
|
+
|
|
165
|
+
Args:
|
|
166
|
+
input_text: Multi-line string with connections (e.g., "A -> B")
|
|
167
|
+
output_path: Path to save the text file
|
|
168
|
+
|
|
169
|
+
Returns:
|
|
170
|
+
Path to the saved text file
|
|
171
|
+
"""
|
|
172
|
+
# Generate ASCII flowchart
|
|
173
|
+
flowchart = self.generate(input_text)
|
|
174
|
+
|
|
175
|
+
# Write to file
|
|
176
|
+
with open(output_path, "w", encoding="utf-8") as f:
|
|
177
|
+
f.write(flowchart)
|
|
178
|
+
|
|
179
|
+
return output_path
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def generate_flowchart(input_text: str, **kwargs) -> str:
|
|
183
|
+
"""
|
|
184
|
+
Convenience function to generate a flowchart.
|
|
185
|
+
|
|
186
|
+
Args:
|
|
187
|
+
input_text: Multi-line string with connections
|
|
188
|
+
**kwargs: Additional parameters for FlowchartGenerator
|
|
189
|
+
|
|
190
|
+
Returns:
|
|
191
|
+
ASCII string representation of the flowchart
|
|
192
|
+
"""
|
|
193
|
+
generator = FlowchartGenerator(**kwargs)
|
|
194
|
+
return generator.generate(input_text)
|
retroflow/graph.py
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Graph module for flowchart generator.
|
|
3
|
+
|
|
4
|
+
Provides graph data structure and analysis algorithms.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from collections import defaultdict, deque
|
|
8
|
+
from typing import List, Tuple
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class Graph:
|
|
12
|
+
"""Directed graph structure for flowchart representation."""
|
|
13
|
+
|
|
14
|
+
def __init__(self):
|
|
15
|
+
self.nodes = set()
|
|
16
|
+
self.edges = [] # List of (source, target) tuples
|
|
17
|
+
self.adjacency = defaultdict(list) # source -> [targets]
|
|
18
|
+
self.reverse_adjacency = defaultdict(list) # target -> [sources]
|
|
19
|
+
|
|
20
|
+
def add_edge(self, source: str, target: str):
|
|
21
|
+
"""Add a directed edge from source to target."""
|
|
22
|
+
self.nodes.add(source)
|
|
23
|
+
self.nodes.add(target)
|
|
24
|
+
self.edges.append((source, target))
|
|
25
|
+
self.adjacency[source].append(target)
|
|
26
|
+
self.reverse_adjacency[target].append(source)
|
|
27
|
+
|
|
28
|
+
def get_nodes(self) -> List[str]:
|
|
29
|
+
"""Return list of all nodes."""
|
|
30
|
+
return list(self.nodes)
|
|
31
|
+
|
|
32
|
+
def get_edges(self) -> List[Tuple[str, str]]:
|
|
33
|
+
"""Return list of all edges."""
|
|
34
|
+
return self.edges
|
|
35
|
+
|
|
36
|
+
def get_successors(self, node: str) -> List[str]:
|
|
37
|
+
"""Get all nodes that this node points to."""
|
|
38
|
+
return self.adjacency.get(node, [])
|
|
39
|
+
|
|
40
|
+
def get_predecessors(self, node: str) -> List[str]:
|
|
41
|
+
"""Get all nodes that point to this node."""
|
|
42
|
+
return self.reverse_adjacency.get(node, [])
|
|
43
|
+
|
|
44
|
+
def get_roots(self) -> List[str]:
|
|
45
|
+
"""Get nodes with no incoming edges."""
|
|
46
|
+
return [node for node in self.nodes if not self.get_predecessors(node)]
|
|
47
|
+
|
|
48
|
+
def get_leaves(self) -> List[str]:
|
|
49
|
+
"""Get nodes with no outgoing edges."""
|
|
50
|
+
return [node for node in self.nodes if not self.get_successors(node)]
|
|
51
|
+
|
|
52
|
+
def has_cycle(self) -> bool:
|
|
53
|
+
"""Check if graph contains a cycle using DFS."""
|
|
54
|
+
visited = set()
|
|
55
|
+
rec_stack = set()
|
|
56
|
+
|
|
57
|
+
def dfs(node):
|
|
58
|
+
visited.add(node)
|
|
59
|
+
rec_stack.add(node)
|
|
60
|
+
|
|
61
|
+
for neighbor in self.get_successors(node):
|
|
62
|
+
if neighbor not in visited:
|
|
63
|
+
if dfs(neighbor):
|
|
64
|
+
return True
|
|
65
|
+
elif neighbor in rec_stack:
|
|
66
|
+
return True
|
|
67
|
+
|
|
68
|
+
rec_stack.remove(node)
|
|
69
|
+
return False
|
|
70
|
+
|
|
71
|
+
for node in self.nodes:
|
|
72
|
+
if node not in visited:
|
|
73
|
+
if dfs(node):
|
|
74
|
+
return True
|
|
75
|
+
|
|
76
|
+
return False
|
|
77
|
+
|
|
78
|
+
def find_feedback_edges(self) -> List[Tuple[str, str]]:
|
|
79
|
+
"""
|
|
80
|
+
Find edges that need to be reversed to make graph acyclic.
|
|
81
|
+
Uses DFS to find back edges.
|
|
82
|
+
"""
|
|
83
|
+
visited = set()
|
|
84
|
+
rec_stack = set()
|
|
85
|
+
feedback_edges = []
|
|
86
|
+
|
|
87
|
+
def dfs(node):
|
|
88
|
+
visited.add(node)
|
|
89
|
+
rec_stack.add(node)
|
|
90
|
+
|
|
91
|
+
for neighbor in self.get_successors(node):
|
|
92
|
+
if neighbor not in visited:
|
|
93
|
+
dfs(neighbor)
|
|
94
|
+
elif neighbor in rec_stack:
|
|
95
|
+
# Back edge found
|
|
96
|
+
feedback_edges.append((node, neighbor))
|
|
97
|
+
|
|
98
|
+
rec_stack.remove(node)
|
|
99
|
+
|
|
100
|
+
for node in self.nodes:
|
|
101
|
+
if node not in visited:
|
|
102
|
+
dfs(node)
|
|
103
|
+
|
|
104
|
+
return feedback_edges
|
|
105
|
+
|
|
106
|
+
def topological_sort(self) -> List[str]:
|
|
107
|
+
"""
|
|
108
|
+
Return nodes in topological order (if acyclic).
|
|
109
|
+
Uses Kahn's algorithm.
|
|
110
|
+
"""
|
|
111
|
+
in_degree = {node: len(self.get_predecessors(node)) for node in self.nodes}
|
|
112
|
+
queue = deque([node for node in self.nodes if in_degree[node] == 0])
|
|
113
|
+
result = []
|
|
114
|
+
|
|
115
|
+
while queue:
|
|
116
|
+
node = queue.popleft()
|
|
117
|
+
result.append(node)
|
|
118
|
+
|
|
119
|
+
for neighbor in self.get_successors(node):
|
|
120
|
+
in_degree[neighbor] -= 1
|
|
121
|
+
if in_degree[neighbor] == 0:
|
|
122
|
+
queue.append(neighbor)
|
|
123
|
+
|
|
124
|
+
# If not all nodes processed, there's a cycle
|
|
125
|
+
if len(result) != len(self.nodes):
|
|
126
|
+
return sorted(self.nodes) # Fallback to alphabetical
|
|
127
|
+
|
|
128
|
+
return result
|
|
129
|
+
|
|
130
|
+
def get_longest_path_length(self) -> int:
|
|
131
|
+
"""
|
|
132
|
+
Calculate the length of the longest path in the graph.
|
|
133
|
+
Useful for estimating layout height.
|
|
134
|
+
"""
|
|
135
|
+
if not self.nodes:
|
|
136
|
+
return 0
|
|
137
|
+
|
|
138
|
+
# Use dynamic programming with topological sort
|
|
139
|
+
topo_order = self.topological_sort()
|
|
140
|
+
distances = {node: 0 for node in self.nodes}
|
|
141
|
+
|
|
142
|
+
for node in topo_order:
|
|
143
|
+
for successor in self.get_successors(node):
|
|
144
|
+
distances[successor] = max(distances[successor], distances[node] + 1)
|
|
145
|
+
|
|
146
|
+
return max(distances.values()) if distances else 0
|
|
147
|
+
|
|
148
|
+
def get_max_width(self) -> int:
|
|
149
|
+
"""
|
|
150
|
+
Estimate maximum width by counting nodes at each level.
|
|
151
|
+
Useful for estimating layout width.
|
|
152
|
+
"""
|
|
153
|
+
if not self.nodes:
|
|
154
|
+
return 0
|
|
155
|
+
|
|
156
|
+
# Assign levels using BFS
|
|
157
|
+
levels = defaultdict(list)
|
|
158
|
+
visited = set()
|
|
159
|
+
queue = deque([(node, 0) for node in self.get_roots()])
|
|
160
|
+
|
|
161
|
+
if not queue: # No roots means cycle, start from any node
|
|
162
|
+
queue.append((next(iter(self.nodes)), 0))
|
|
163
|
+
|
|
164
|
+
while queue:
|
|
165
|
+
node, level = queue.popleft()
|
|
166
|
+
if node in visited:
|
|
167
|
+
continue
|
|
168
|
+
|
|
169
|
+
visited.add(node)
|
|
170
|
+
levels[level].append(node)
|
|
171
|
+
|
|
172
|
+
for successor in self.get_successors(node):
|
|
173
|
+
if successor not in visited:
|
|
174
|
+
queue.append((successor, level + 1))
|
|
175
|
+
|
|
176
|
+
return max(len(nodes) for nodes in levels.values()) if levels else 1
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def create_graph(connections: List[Tuple[str, str]]) -> Graph:
|
|
180
|
+
"""
|
|
181
|
+
Create a Graph from a list of connections.
|
|
182
|
+
|
|
183
|
+
Args:
|
|
184
|
+
connections: List of (source, target) tuples
|
|
185
|
+
|
|
186
|
+
Returns:
|
|
187
|
+
Graph object
|
|
188
|
+
"""
|
|
189
|
+
graph = Graph()
|
|
190
|
+
for source, target in connections:
|
|
191
|
+
graph.add_edge(source, target)
|
|
192
|
+
return graph
|