Metadata-Version: 2.4
Name: drawn-cli
Version: 0.1.0
Summary: A minimalistic CLI tool for diagrams-as-code
Author-email: Parthiv R Menon <parthivrmenon@gmail.com>
Maintainer-email: Parthiv R Menon <parthivrmenon@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/parthivrmenon/drawn
Project-URL: Repository, https://github.com/parthivrmenon/drawn
Project-URL: Issues, https://github.com/parthivrmenon/drawn/issues
Project-URL: Documentation, https://github.com/parthivrmenon/drawn#readme
Keywords: diagrams,graphviz,cli,visualization,architecture
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Documentation
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: graphviz
Dynamic: license-file

# Drawn

**Drawn** is a really **minimalistic** and **lightweight** CLI tool for **diagrams-as-code** – It helps users generate beautiful system diagrams using a super simple notation.

## Example

From this simple code:
```
Sun --> Evaporation
Evaporation -(condensation)-> Clouds
Clouds -(precipitation)-> Rain
Rain --> Rivers
Rivers --> Oceans
Oceans -(evaporation)-> Evaporation

```
To this diagram:

<img src="./docs/water_cycle.svg" alt="Water Cycle Diagram" width="300"/>

## Table of Contents:
- [Features](#features)
- [Philosophy](#philosophy)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Testing](#testing)
- [Advanced Configuration](#advanced-configuration)

## Features

- **Simple arrow syntax** - `A --> B --> C`
- **Multi-line support** - Handle complex flows
- **Branching flows** - One node to multiple destinations  
- **Professional output** - High-quality SVG/PNG via Graphviz
- **Fast rendering** - Instant feedback
- **Test coverage** - Reliable and maintainable
- **Inline configuration** - Simple directives using % prefix

## Philosophy

- **Simple over complex** - Minimal syntax that anyone can learn
- **Fast feedback** - From idea to diagram in 30 seconds
- **Git-friendly** - Text-based diagrams that version well
- **Opinionated** - Simple and consistent styling
- **Advanced configuration** - Customise every aspect of the diagram if required.


## Quick Start

### Installation

#### Prerequisites
Drawn requires [Graphviz](https://graphviz.org/download/) to be installed on your system:

```bash
# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

# Windows
# Download and install from: https://graphviz.org/download/
```

#### Install from PyPI (Recommended)
```bash
# Install the latest stable version
pip install drawn-cli

# Create your first diagram
echo "API --> Server --> DB" > flow.drawn
drawn flow.drawn
```

#### Install from Source
```bash
# Clone the repo
git clone git@github.com:parthivrmenon/drawn.git
cd drawn

# Install the package
pip install .
```

#### Development Installation
```bash
# Clone the repo for development
git clone git@github.com:parthivrmenon/drawn.git
cd drawn

# Install dependencies (optional, for full package install)
pip install -e .

# Or run directly without installation
python drawn/cli.py flow.drawn
```

### Usage

```bash
# Basic usage
echo "API --> Server --> DB" > flow.drawn
drawn flow.drawn
```

## Configuration

You can configure your diagrams using simple directives with a `%` prefix:

### Basic Configuration

```
% output_file: filename      # Output filename (default: flow)
% output_format: svg|png|pdf # Output format (default: svg)
% comment: My Diagram        # Title for the diagram (default: Flow)
```

For advanced configuration options, see [Advanced Configuration](#advanced-configuration).

### Themes

Drawn supports three built-in themes that control the visual styling of your diagrams:

```
% theme: light    # Black on white (default)
% theme: dark     # White on black  
% theme: matrix   # Bright green terminal aesthetic
```

#### Examples
<div align="center">
<table>
  <tr>
    <td align="center"><b>Light Theme</b><br/>Clean, professional diagrams</td>
    <td align="center"><b>Dark Theme</b><br/>High contrast on dark background</td>
    <td align="center"><b>Matrix Theme</b><br/>Terminal-style hacker aesthetic</td>
  </tr>
  <tr>
    <td><img src="./docs/light.svg" alt="Light Theme"/></td>
    <td><img src="./docs/dark.svg" alt="Dark Theme"/></td>
    <td><img src="./docs/matrix.svg" alt="Matrix Theme"/></td>
  </tr>
</table>
</div>

**Available Themes:**
- `light` - Black text on white background (default)
- `dark` - White text on black background
- `matrix` - Bright green text on black background with terminal styling

## Testing

{{ ... }}
# Run all tests
python -m pytest tests/

# Run tests with verbose output
python -m pytest tests/ -v

## Advanced Configuration

### Graph Attributes

```
% graph_bgcolor: transparent  # Background color (default: transparent)
% graph_dpi: 300             # Resolution in DPI (default: 300)
% graph_rankdir: TB          # Direction: TB (top-bottom), LR (left-right) (default: TB)
% graph_splines: ortho       # Line style: ortho, curved, etc. (default: ortho)
% graph_pad: 0.2             # Padding around the graph (default: 0.2)
% graph_nodesep: 1           # Horizontal separation between nodes (default: 1)
% graph_ranksep: 0.8         # Vertical separation between nodes (default: 0.8)
```

### Node Attributes

```
% node_fontname: Courier     # Font for node labels (default: Courier)
% node_fontsize: 12          # Font size for node labels (default: 12)
% node_fontcolor: white      # Font color for node labels (default: white)
% node_shape: box            # Node shape: box, circle, ellipse, etc. (default: box)
% node_style: filled         # Node style: filled, dashed, etc. (default: filled)
% node_fillcolor: transparent # Fill color for nodes (default: transparent)
% node_color: white          # Border color for nodes (default: white)
% node_margin: 0.15,0.1      # Margin inside nodes (default: 0.15,0.1)
```

### Edge Attributes

```
% edge_fontname: Courier     # Font for edge labels (default: Courier)
% edge_fontsize: 12          # Font size for edge labels (default: 12)
% edge_fontcolor: white      # Font color for edge labels (default: white)
% edge_color: white          # Edge line color (default: white)
% edge_arrowhead: normal     # Arrow style: normal, vee, dot, etc. (default: normal)
% edge_penwidth: 0.8         # Edge line thickness (default: 0.8)
```

### Auto-Shapes

Drawn automatically selects appropriate node shapes based on node names to improve diagram readability:

```
% auto_shapes: true     # Enable automatic shape selection (default: true)
% auto_shapes: false    # Disable automatic shape selection
```

**Shape Mappings:**
- **Databases** (`db`, `database`, `sql`, `postgres`, `mysql`) → `cylinder`
- **Caches** (`cache`, `redis`, `memcached`) → `box3d`
- **Queues** (`queue`, `kafka`, `rabbitmq`) → `parallelogram`
- **Storage** (`storage`, `bucket`, `s3`) → `folder`
- **Components** (`api`, `service`, `server`) → `component`
- **Users** (`user`, `customer`) → `ellipse`
- **Default** (all others) → `box`
