retroflow 0.8.2__py3-none-any.whl

retroflow-0.8.2.dist-info/METADATA

@@ -0,0 +1,445 @@
+Metadata-Version: 2.4
+Name: retroflow
+Version: 0.8.2
+Summary: Generate beautiful ASCII and PNG flowcharts from simple text descriptions
+Project-URL: Homepage, https://github.com/ronikobrosly/retroflow
+Project-URL: Repository, https://github.com/ronikobrosly/retroflow
+Project-URL: Issues, https://github.com/ronikobrosly/retroflow/issues
+Author-email: Roni Kobrosly <roni.kobrosly@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ascii,cli,diagram,flowchart,graph,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: General
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: networkx>=3.0.0
+Requires-Dist: pillow>=9.0.0
+Description-Content-Type: text/markdown
+
+# RetroFlow
+
+```
+ ___________________________________________________________
+|                                                           |
+|   _____      _             ______ _                       |
+|  |  __ \    | |           |  ____| |                      |
+|  | |__) |___| |_ _ __ ___ | |__  | | _____      __        |
+|  |  _  // _ \ __| '__/ _ \|  __| | |/ _ \ \ /\ / /        |
+|  | | \ \  __/ |_| | | (_) | |    | | (_) \ V  V /         |
+|  |_|  \_\___|\__|_|  \___/|_|    |_|\___/ \_/\_/          |
+|                                                           |
+|            [ Beautiful ASCII Flowcharts ]                 |
+|___________________________________________________________|
+               ||                           ||
+```
+
+A Python library for generating beautiful ASCII and PNG flowcharts from simple text descriptions.
+
+[![PyPI version](https://badge.fury.io/py/retroflow.svg)](https://badge.fury.io/py/retroflow)
+[![Python Versions](https://img.shields.io/pypi/pyversions/retroflow.svg)](https://pypi.org/project/retroflow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/ronikobrosly/retroflow/branch/main/graph/badge.svg)](https://codecov.io/gh/ronikobrosly/retroflow)
+
+
+## Overview 
+
+This is a project to help engineers, researchers, project managers, and others create beautiful, retro-looking ASCII flow diagrams. ASCII diagrams are pretty, and harken back to the mid-20th century technical documentation. They also have real advantages:
+
+1) They work wonderfully in the age of agentic AI, which can easily read and parse these small representations.
+2) ASCII diagrams can live inline with: PRs, Markdown files, Slack threads, etc.
+3) ASCII diagrams optimize for thinking speed, not presentation quality. It encourages iteration and deletion instead of premature refinement.
+4) Minimalist diagrams reduce visual noise (although they do still look retro and pretty)
+5) They're tool agnostic and can be rendered anywhere
+
+
+```
+                                       ╔════════╗
+                                       ║  Mesh  ║
+                                       ╚════════╝
+
+
+
+
+ ┌──────────────────────────────────────────────────────────────────────────────────────┐
+ │                                                                                      │
+ │                                                                                      │
+ │                                                 ┌────────────────────────────────────┐
+ │                                                 │                                    │
+ │                                                 │                                    │
+ │                        ┌────────────────────────┼───────────┐                        │
+ │                        │                        │           │                        │
+ │                        │                        │           │                        │
+ │┌───────────────────────┼───────────┐            │           │                        │
+ ││                       │           │            │           │                        │
+ ││                       │           │            │           │                        │
+ ││                       │           │            │           │                        │
+ ▼▼                       ▼           │            ▼           │                        │
+┌──────────┐             ┌──────────┐ │           ┌──────────┐ │           ┌──────────┐ │
+│          ┤────────────►│          ┤─┘           │          ┤─┘           │          ┤─┘
+│  Node A  ┤──────┐      │  Node B  ┤────────────►│  Node C  ┤──────┌─────►│  Node D  │░
+│          │░     │      │          │░            │          │░     │      │          │░
+└──────────┘░     │      └──────────┘░            └──────────┘░     │      └──────────┘░
+ ░░░░░░░░░░░░     │       ░░░░░░░░░░░░             ░░░░░░░░░░░░     │       ░░░░░░░░░░░░
+                  │                                                 │
+                  │                                                 │
+                  │                                                 │
+                  └─────────────────────────────────────────────────┘
+```
+
+
+<p align="center">
+<img src="/imgs/README_example.png" align="middle"/>
+</p>
+
+
+<p align="center">
+<img src="/imgs/README_example2.png" align="middle"/>
+</p>
+
+
+## Installation
+
+```bash
+pip install retroflow
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add retroflow
+```
+
+## Quick Start
+
+```python
+from retroflow import FlowchartGenerator
+
+# Create a generator
+generator = FlowchartGenerator()
+
+# Define your flowchart using simple arrow syntax
+flowchart = generator.generate("""
+    Start -> Process
+    Process -> Decision
+    Decision -> End
+""")
+
+print(flowchart)
+```
+
+## Features
+
+- **Simple syntax**: Define flowcharts using intuitive `A -> B` arrow notation
+- **ASCII output**: Generate text-based flowcharts for terminals and documentation
+- **PNG export**: Save high-resolution PNG images with customizable fonts
+- **Intelligent layout**: Automatic node positioning using NetworkX with barycenter heuristic
+- **Smart edge routing**: Edges automatically route around intermediate boxes to avoid visual overlap
+- **Cycle detection**: Handles cyclic graphs gracefully with back-edge routing
+- **Customizable**: Adjust text width, box sizes, spacing, shadows, and fonts
+- **Unicode box-drawing**: Beautiful boxes with optional shadow effects
+- **Title banners**: Optional double-line bordered titles with automatic word wrapping
+- **Horizontal flow**: Left-to-right layout mode for compact linear diagrams
+
+## Usage
+
+### Basic Generation
+
+```python
+from retroflow import FlowchartGenerator
+
+generator = FlowchartGenerator()
+
+# Simple linear flow
+result = generator.generate("""
+    A -> B
+    B -> C
+    C -> D
+""")
+print(result)
+```
+
+### Branching Flows
+
+```python
+# Branching and merging
+result = generator.generate("""
+    Start -> Validate
+    Validate -> Process
+    Validate -> Error
+    Process -> End
+    Error -> End
+""")
+print(result)
+```
+
+### Cyclic Flows
+
+```python
+# Loops and cycles are supported
+result = generator.generate("""
+    Init -> Check
+    Check -> Process
+    Process -> Check
+    Check -> Done
+""")
+print(result)
+```
+
+### Export to Text File
+
+```python
+generator = FlowchartGenerator()
+
+generator.save_txt("""
+    A -> B
+    B -> C
+""", "flowchart.txt")
+```
+
+### Export to PNG
+
+Save your flowchart as a high-resolution PNG image:
+
+```python
+generator = FlowchartGenerator()
+
+generator.save_png("""
+    A -> B
+    B -> C
+""", "flowchart.png")
+```
+
+Customize the PNG output with various options:
+
+```python
+generator.save_png(
+    "A -> B\nB -> C",
+    "flowchart.png",
+    font_size=24,           # Base font size in points (default: 16)
+    bg_color="#1a1a2e",     # Background color (default: "#FFFFFF")
+    fg_color="#00ff00",     # Text color (default: "#000000")
+    padding=40,             # Padding around diagram in pixels (default: 20)
+    scale=2,                # Resolution multiplier for crisp output (default: 2)
+)
+```
+
+The `scale` parameter controls the output resolution. With the default `scale=2`, images render at 2x resolution for crisp display on high-DPI/retina screens. Use `scale=1` for smaller file sizes, or `scale=3` for even sharper output.
+
+## Configuration
+
+### FlowchartGenerator Options
+
+```python
+generator = FlowchartGenerator(
+    max_text_width=22,      # Max width for text inside boxes before wrapping (default: 22)
+    min_box_width=10,       # Minimum box width (default: 10)
+    horizontal_spacing=12,  # Space between boxes horizontally (default: 12)
+    vertical_spacing=6,     # Space between boxes vertically (default: 6)
+    shadow=True,            # Whether to draw box shadows (default: True)
+    font="Cascadia Code",   # Font for PNG output (default: None, uses system font)
+    title="My Diagram",     # Optional title banner with double-line border (default: None)
+    direction="TB",         # Flow direction: "TB" (top-to-bottom) or "LR" (left-to-right)
+)
+```
+
+### Font Configuration
+
+You can specify a font for PNG output either at initialization or per-call:
+
+```python
+# Set font for all PNG exports from this generator
+generator = FlowchartGenerator(font="Cascadia Code")
+generator.save_png("A -> B", "flowchart.png")
+
+# Or override the font for a specific export
+generator.save_png("A -> B", "flowchart.png", font="Monaco")
+```
+
+Common monospace fonts that work well:
+- **Windows**: `Cascadia Code`, `Consolas`, `Courier New`
+- **macOS**: `Monaco`, `Menlo`, `SF Mono`
+- **Linux**: `DejaVu Sans Mono`, `Ubuntu Mono`, `Liberation Mono`
+
+If the specified font isn't found, RetroFlow automatically falls back to available system fonts.
+
+### Title Banner
+
+Add a title banner with a double-line border above your flowchart:
+
+```python
+generator = FlowchartGenerator(title="CI/CD Pipeline")
+result = generator.generate("""
+    Build -> Test
+    Test -> Deploy
+""")
+```
+
+Output:
+```
+╔══════════════════╗
+║  CI/CD Pipeline  ║
+╚══════════════════╝
+
+    ┌─────────┐
+    │  Build  │░
+    └────┬────┘░
+     ░░░░│░░░░░░
+         │
+         ▼
+    ┌─────────┐
+    │  Test   │░
+    └────┬────┘░
+     ░░░░│░░░░░░
+         │
+         ▼
+    ┌──────────┐
+    │  Deploy  │░
+    └──────────┘░
+     ░░░░░░░░░░░░
+```
+
+**Title Wrapping**: Long titles automatically wrap at word boundaries (approximately every 15 characters) to keep the title box compact:
+
+```python
+generator = FlowchartGenerator(title="My Very Long Project Title Here")
+```
+
+```
+╔═════════════════╗
+║  My Very Long   ║
+║  Project Title  ║
+║      Here       ║
+╚═════════════════╝
+```
+
+You can also override the title per-call:
+```python
+generator.generate("A -> B", title="Override Title")
+```
+
+### Horizontal Flow Mode
+
+Use `direction="LR"` for left-to-right layouts instead of top-to-bottom:
+
+```python
+generator = FlowchartGenerator(direction="LR")
+result = generator.generate("""
+    Start -> Process
+    Process -> End
+""")
+```
+
+This produces a horizontal flowchart where nodes flow from left to right, which can be more compact for linear processes.
+
+## Input Format
+
+The input format uses a simple arrow syntax:
+
+```
+# Comments start with #
+NodeA -> NodeB
+NodeB -> NodeC
+
+# Node names can contain spaces
+User Login -> Validate Credentials
+Validate Credentials -> Access Granted
+```
+
+### Rules
+
+- Each line defines one connection: `Source -> Target`
+- Node names are trimmed of whitespace
+- Empty lines are ignored
+- Lines starting with `#` are comments
+- Node names can contain spaces
+
+## API Reference
+
+### FlowchartGenerator
+
+The main class for generating flowcharts.
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `generate(input_text)` | Generate ASCII flowchart string |
+| `save_txt(input_text, filename)` | Save flowchart to a text file |
+| `save_png(input_text, filename, ...)` | Save flowchart as a PNG image |
+
+### Convenience Functions
+
+```python
+from retroflow import parse_flowchart
+
+# Parse without rendering
+connections = parse_flowchart("A -> B\nB -> C")
+# Returns: [('A', 'B'), ('B', 'C')]
+```
+
+### Lower-Level API
+
+For advanced use cases, you can access the individual components:
+
+```python
+from retroflow import (
+    Parser,
+    SugiyamaLayout,  # Alias for NetworkXLayout
+    Canvas,
+    BoxRenderer,
+)
+
+# Parse input
+parser = Parser()
+connections = parser.parse("A -> B\nB -> C")
+
+# Compute layout
+layout_engine = SugiyamaLayout()
+layout_result = layout_engine.layout(connections)
+
+# Access layout information
+for node_name, node_layout in layout_result.nodes.items():
+    print(f"{node_name}: layer={node_layout.layer}, position={node_layout.position}")
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/ronikobrosly/retroflow.git
+cd retroflow
+uv sync --dev
+```
+
+### Run Tests
+
+```bash
+uv run pytest
+```
+
+### Run Linting
+
+```bash
+uvx ruff check .
+uvx ruff format --check .
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are 100% welcome! Please feel free to submit a PR.

retroflow-0.8.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+retroflow/__init__.py,sha256=nLV_7Dy6m2oW4U17JRcTtETPg2G4rbv6FhN-A3k-dS4,1050
+retroflow/generator.py,sha256=q4G2xqHmaDU3AuECARlz0dGSjd4nwAmWtJa-BzeeN5w,73036
+retroflow/layout.py,sha256=C0vuhnGSaW46uie4lcu1RrSB3ccXErLBhSONWk5jzAU,7336
+retroflow/parser.py,sha256=Z5_QJexjdh6-Wge-pxqqYEYoMdeKRwsjL64ueN_MhRY,2600
+retroflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+retroflow/renderer.py,sha256=n47KaQIsvgg9Pr3016-6pRhNVbuv_lz5p0YSYLX5yFs,16211
+retroflow/router.py,sha256=ledYdbJcID2UmLOMnLP_1aOpVxAfZLHTWRyYc9pkc5c,10878
+retroflow-0.8.2.dist-info/METADATA,sha256=bSdABVBgL9F1Cp5LXm4FUmelGKi6dPLQOSle3eWYjys,14931
+retroflow-0.8.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+retroflow-0.8.2.dist-info/licenses/LICENSE,sha256=pxkJvysic-mY3ELfi-ts2445liyatgXLCbZig1vnhZA,1070
+retroflow-0.8.2.dist-info/RECORD,,

retroflow-0.8.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

retroflow-0.8.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roni Kobrosly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.