Asciidag

0.2.0 · active · verified Thu Apr 16

Asciidag is a Python library that draws Directed Acyclic Graphs (DAGs) as ASCII art, mimicking the output style of `git log --graph`. It is a direct, mechanical port of Git's log graphing code, currently at version 0.2.0. The project is explicitly stated as 'alpha quality' and subject to breaking API changes, with the last release in October 2020.

Common errors

```
ImportError: cannot import name 'Graph' from 'asciidag'
```
cause Attempting to import `Graph` or `Node` directly from the top-level `asciidag` package.

fix The `Graph` and `Node` classes are located in submodules. Use `from asciidag.graph import Graph` and `from asciidag.node import Node` instead.
```
Unexpected ASCII graph output or layout issues when providing complex DAG structures.
```
cause While asciidag aims to replicate Git's graph, its 'alpha quality' and direct port nature might lead to edge cases or less-than-optimal layouts for graphs significantly different from typical Git histories.

fix Simplify the input DAG structure if possible. Review the `examples/demo.py` for typical usage patterns. If issues persist, consider reporting them on the GitHub issue tracker, providing a minimal reproducible example.

Warnings

breaking The library is explicitly labeled as 'alpha quality' and its API is 'subject to breaking API changes' at any time. Users should expect instability in future minor or patch releases, as there is no strong commitment to backward compatibility in the 0.x.x series.
Fix: Pin your dependency to a specific patch version (e.g., `asciidag==0.2.0`) and review the GitHub repository for any changes before upgrading.
gotcha The codebase is a 'direct port of the Git log graphing code' and is described as 'not Pythonic'. This means the internal structure and coding conventions might not align with typical Python practices, potentially making it harder to debug or extend.
Fix: Be aware that the code style may be unusual. When contributing or debugging, refer to the original Git log graphing logic for context if Pythonic patterns are not immediately apparent.

Install

pip install -U asciidag Install latest version

Imports

Graph
```
from asciidag.graph import Graph
```
The core Graph object is imported from the 'asciidag.graph' submodule.
Node
```
from asciidag.node import Node
```
Node objects, representing elements in the DAG, are imported from 'asciidag.node'.

Quickstart

This quickstart demonstrates how to create a `Graph` object, define `Node`s with parent-child relationships, and then render the DAG to the console using `graph.show_nodes(tips)`.

from asciidag.graph import Graph
from asciidag.node import Node

graph = Graph()

# Define nodes and their relationships (parents)
root = Node('root')
grandpa = Node('grandpa', parents=[root])
tips = [
    Node('child', parents=[
        Node('mom', parents=[
            Node('grandma', parents=[
                Node('greatgrandma', parents=[]),
            ]),
            grandpa,
        ]),
        Node('dad', parents=[
            Node('bill', parents=[
                Node('martin'),
                Node('james'),
                Node('paul'),
                Node('jon'),
            ])
        ]),
        Node('stepdad', parents=[grandpa]),
    ]),
    Node('foo', [Node('bar')]),
]

# Display the graph
graph.show_nodes(tips)

view raw JSON →