-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Joshua Bettigole edited this page Apr 12, 2026
·
2 revisions
Welcome to the documentation for ascii-network-diagram! This provides in-depth guidance for using the package, including advanced usage, customization, and integration tips.
ascii-network-diagram is a Python package for generating clear, readable ASCII art network diagrams directly in your terminal or text output. It is ideal for documentation, CLI tools, and environments where graphical diagrams are not practical.
Install from PyPI:
pip install ascii-network-diagramImport the main function:
from ascii_network_diagram import star_diagramDraws a star topology ASCII diagram for 2–12 nodes.
Parameters:
-
nodes(list of dict): Each node is a dictionary with at least:-
label(str): Node label (e.g., "Router, eth0") -
vlan(int or str): VLAN or identifier -
connection(str): Connection label (e.g., "CIR-100")
-
-
title(str, optional): Title to display above the diagram.
Returns:
Prints the diagram to stdout.
from ascii_network_diagram import star_diagram
nodes = [
{"label": "Router, eth0"},
{"label": "Switch, port1"},
]
star_diagram(nodes)┌──────────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ ────▶ │ Router, eth0 │ ◀═════════▶ │ Switch, port1 │ ◀──── │
│ └────────────────┘ └────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
star_diagram(nodes, title="2 Node Star Diagram")┌──────────────────────────────────────────────────────────────────┐
│ │
│ 2 Node Star Diagram │
│ │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ ────▶ │ Router, eth0 │ ◀═════════▶ │ Switch, port1 │ ◀──── │
│ └────────────────┘ └────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
nodes = [
{"label": "RouterA, Port1", "vlan": 500, "connection": "CIR-500"},
{"label": "RouterB, Port2", "vlan": 500, "connection": "CIR-500"},
{"label": "RouterC, Port3", "vlan": 500, "connection": "CIR-500"},
{"label": "RouterD, Port4", "vlan": 500, "connection": "CIR-500"},
{"label": "RouterE, Port5", "vlan": 500, "connection": "CIR-500"},
]
star_diagram(nodes, title="5 Node Star Diagram")┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ 5 Node Star Diagram │
│ │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ CIR-500 │
│ ╷ │
│ ╵ │
│ (vlan 500) │
│ ╷ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ RouterE, Port5 │ │
│ └────────────────┘ │
│ ▲ │
│ ║ │
│ ║ │
│ ┌────────────────┐ ║ ┌────────────────┐ │
│ CIR-500 ──── (vlan 500) ────▶ │ RouterA, Port1 │ ◀════╦═════════╩══════════╦════▶ │ RouterD, Port4 │ ◀──── (vlan 500) ──── CIR-500 │
│ └────────────────┘ ║ ║ └────────────────┘ │
│ ║ ║ │
│ ║ ║ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ RouterB, Port2 │ │ RouterC, Port3 │ │
│ └────────────────┘ └────────────────┘ │
│ ▲ ▲ │
│ │ │ │
│ ╵ ╵ │
│ (vlan 500) (vlan 500) │
│ ╷ ╷ │
│ ╵ ╵ │
│ CIR-500 CIR-500 │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
- If you call
star_diagramwith fewer than 2 or more than 12 nodes, it raises aValueError:ValueError: Not implemented: Only 2-12 nodes supported in this style
- Use descriptive labels for each node for clarity.
- Keep connection labels concise to avoid diagram overflow.
- For large diagrams, consider adjusting your terminal width.
- Integrate with CLI tools by capturing stdout.
- Use in scripts to generate diagrams for network automation reports.
See the CONTRIBUTING guide for how to contribute new features, report bugs, or suggest improvements.
MIT License. See LICENSE for details.