Metadata-Version: 2.4
Name: graph-easy
Version: 0.1.3
Summary: A Python port of Graph::Easy - lay out and render graphs as ASCII art
Author: Tels (original Graph::Easy author)
License: GPL-2.0-or-later
Project-URL: Original, https://github.com/ironcamel/Graph-Easy
Keywords: graph,ascii,diagram,layout,graphviz
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# graph-easy

[![PyPI version](https://img.shields.io/pypi/v/graph-easy.svg)](https://pypi.org/project/graph-easy/)
[![Downloads](https://static.pepy.tech/badge/graph-easy)](https://pepy.tech/project/graph-easy)

A **Python port** of [Graph::Easy](https://github.com/ironcamel/Graph-Easy),
the Perl tool that lays out directed/undirected graphs and renders them as
**ASCII art** (box-and-wire diagrams rendered in the terminal).

This project faithfully translates the original Perl implementation to Python,
in order to provide the same functionality to Python users / as a native Python
library and command-line tool.

## Provenance & License

- Original: **Graph::Easy**, Copyright (C) 2004 - 2008 by **Tels**
  (<http://bloodgate.com/>).
- Upstream repository: <https://github.com/ironcamel/Graph-Easy>
- This port is licensed under the **GNU General Public License, version 2 or
  (at your option) any later version** — the same license as the original
  Graph::Easy, because a port is a derivative work.

See [`LICENSE`](./LICENSE) for the full GPL text.

### Third-party color schemes

This product includes color specifications and designs developed by Cynthia
Brewer (<http://colorbrewer.org/>), used under the
Apache-Style Software License for ColorBrewer Color Schemes v1.1,
© 2002 Cynthia Brewer, Mark Harrower, and The Pennsylvania State University.
See the header of the original `Graph::Easy::Attributes` for the full notice.

## Status

Actively-developed port. Currently implemented:

- **DSL parser**: `[ label ]`/bare nodes, `-->` `<--` `<-->` `--` arrows,
  labelled edges (`-- label -->` and `-- { label: x; } -->`), multiline
  labels (`\n`), node attribute blocks (`{ shape: diamond; }`), groups
  (`( name [ A ] --> [ B ] )`), comments
- **Layout engine**: longest-path layering with barycenter reordering and
  orthogonal edge routing — chains, branches, merges, layer-spanning edges,
  back edges (cycles) and self-loops all render without clobbering boxes
  (long edges are routed through detour rows); independent components
  stack as separate diagrams
- **Edge line styles**: `--` solid, `..` dotted, `==` double, `~~` wave,
  `##` bold, `.-`/`..-` dot-dash
- **Edge labels** float next to the line (truncated to fit); `label-pos`
  can place them above (default) or below; `--autolabel` tags unlabelled
  edges as `source -> target`
- **Two output charsets**: Unicode box-drawing by default, plain ASCII via
  `--ascii`
- **Colours**: `fill`/`color`, `border-color`, and a ColourBrewer palette
  via `color: <n>; scheme: <name>`; accepts named colours, `#RGB`/`#RRGGBB`
  true-colour, or a palette index
- **Node shapes**: `normal`/`box`, `rounded`/`ellipse`/`circle`/`oval`,
  `diamond`, `hexagon`
- **Edge arrows**: `arrow-style: plain|open|line` (ASCII heads) vs filled
- **Text style**: `text-style: bold|italic|underline|strike`
- **Graphviz export**: `--dot` emits DOT; `--format svg|png` uses `dot`

Limitations: labels clip to free space beside an edge; very dense graphs may
need manual attribute tuning. The heavier layout engine
(`Graph::Easy::Layout` grid solver) is a follow-up milestone.

## Usage

```console
$ printf '[ Bonn ] --> [ Berlin ] --> [ Hamburg ]\n' | graph-easy
┌──────┐     ┌────────┐     ┌─────────┐
│ Bonn │────▶│ Berlin │────▶│ Hamburg │
└──────┘     └────────┘     └─────────┘
```

Colours from `fill`/`color` attributes render **only on a TTY** by default
(`--color on` to force, `--no-color` to disable).

```console
# plain-ASCII output
$ printf '[ A ] ..> [ B ]\n' | graph-easy --ascii
+---+     +---+
| A |....>| B |
+---+     +---+
```

## Development

```console
$ python -m venv .venv && source .venv/bin/activate
$ pip install -e '.[dev]'
$ ruff check .
$ mypy src
$ pytest
```

## Acknowledgments

Thanks to Tels and the Graph::Easy contributors whose careful layout and
rendering work this port builds upon.
