Metadata-Version: 2.4
Name: graph-easy
Version: 0.0.9
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

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** (faithful to upstream `Parser::_edge_style`):
  `--` solid, `..` dotted, `==` double, `~~` wave, `##` bold, `.-`/`..-` dot-dash
- **Edge labels** float in the box-free region next to the line (truncated
  to fit)
- **Two output charsets**: Unicode box-drawing by default
  (`┌──┐ ──▶ ══ ║ ·`), plain ASCII via `--ascii`
- **Colours**: `fill`/`color` attributes map to ANSI codes (on by default,
  `--no-color` / `--color auto` to control)

Limitations: labels are clipped to the free space beside an edge; very dense
graphs may need manual attribute tuning. The heavier automatic 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 are **on by default**; use
`--no-color` to disable, or `--color auto` to enable only on a TTY.

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