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 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