diagr 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. diagr-0.1.0/LICENSE +21 -0
  2. diagr-0.1.0/PKG-INFO +225 -0
  3. diagr-0.1.0/README.md +199 -0
  4. diagr-0.1.0/pyproject.toml +78 -0
  5. diagr-0.1.0/pyproject.toml.orig +55 -0
  6. diagr-0.1.0/src/diagr/__init__.py +13 -0
  7. diagr-0.1.0/src/diagr/__main__.py +3 -0
  8. diagr-0.1.0/src/diagr/build.py +117 -0
  9. diagr-0.1.0/src/diagr/cli.py +348 -0
  10. diagr-0.1.0/src/diagr/components.py +151 -0
  11. diagr-0.1.0/src/diagr/effects.py +386 -0
  12. diagr-0.1.0/src/diagr/fields.py +396 -0
  13. diagr-0.1.0/src/diagr/icons.py +249 -0
  14. diagr-0.1.0/src/diagr/iconsets/core/icons.yml +43 -0
  15. diagr-0.1.0/src/diagr/layout/__init__.py +0 -0
  16. diagr-0.1.0/src/diagr/layout/auto.py +557 -0
  17. diagr-0.1.0/src/diagr/layout/engine.py +367 -0
  18. diagr-0.1.0/src/diagr/layout/flow.py +227 -0
  19. diagr-0.1.0/src/diagr/layout/geometry.py +230 -0
  20. diagr-0.1.0/src/diagr/layout/metrics.py +35 -0
  21. diagr-0.1.0/src/diagr/layout/route.py +714 -0
  22. diagr-0.1.0/src/diagr/layout/text.py +25 -0
  23. diagr-0.1.0/src/diagr/live.py +76 -0
  24. diagr-0.1.0/src/diagr/markdown.py +87 -0
  25. diagr-0.1.0/src/diagr/migrations/__init__.py +40 -0
  26. diagr-0.1.0/src/diagr/model.py +261 -0
  27. diagr-0.1.0/src/diagr/parse.py +326 -0
  28. diagr-0.1.0/src/diagr/py.typed +0 -0
  29. diagr-0.1.0/src/diagr/render/assets/__init__.py +12 -0
  30. diagr-0.1.0/src/diagr/render/assets/contrast.js +22 -0
  31. diagr-0.1.0/src/diagr/render/assets/debug.js +8 -0
  32. diagr-0.1.0/src/diagr/render/assets/fold.js +12 -0
  33. diagr-0.1.0/src/diagr/render/assets/live.js +26 -0
  34. diagr-0.1.0/src/diagr/render/assets/page.css +115 -0
  35. diagr-0.1.0/src/diagr/render/assets/player.js +231 -0
  36. diagr-0.1.0/src/diagr/render/assets/theme-boot.js +12 -0
  37. diagr-0.1.0/src/diagr/render/assets/theme.js +6 -0
  38. diagr-0.1.0/src/diagr/render/assets/zoom.js +118 -0
  39. diagr-0.1.0/src/diagr/render/debug.py +61 -0
  40. diagr-0.1.0/src/diagr/render/html.py +222 -0
  41. diagr-0.1.0/src/diagr/render/scene.py +801 -0
  42. diagr-0.1.0/src/diagr/render/svg.py +154 -0
  43. diagr-0.1.0/src/diagr/scenario.py +269 -0
  44. diagr-0.1.0/src/diagr/source.py +118 -0
  45. diagr-0.1.0/src/diagr/starter.yml +30 -0
  46. diagr-0.1.0/src/diagr/syntax.py +493 -0
  47. diagr-0.1.0/src/diagr/theme.py +232 -0
  48. diagr-0.1.0/src/diagr/themes/contrast.yml +55 -0
  49. diagr-0.1.0/src/diagr/themes/default.yml +89 -0
  50. diagr-0.1.0/src/diagr/unparse.py +200 -0
  51. diagr-0.1.0/src/diagr/validate.py +341 -0
  52. diagr-0.1.0/src/diagr/views.py +118 -0
diagr-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AnasImloul
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
diagr-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,225 @@
1
+ Metadata-Version: 2.4
2
+ Name: diagr
3
+ Version: 0.1.0
4
+ Summary: Declarative diagrams in YAML: static SVG in light and dark, and a self-contained interactive HTML page.
5
+ Keywords: diagram,svg,yaml,architecture,documentation
6
+ Author: AnasImloul
7
+ Author-email: AnasImloul <anas.imloul27@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Documentation
17
+ Classifier: Topic :: Multimedia :: Graphics
18
+ Classifier: Typing :: Typed
19
+ Requires-Dist: pyyaml>=6.0
20
+ Requires-Python: >=3.12
21
+ Project-URL: Homepage, https://anasimloul.github.io/diagr/
22
+ Project-URL: Documentation, https://anasimloul.github.io/diagr/
23
+ Project-URL: Repository, https://github.com/AnasImloul/diagr
24
+ Project-URL: Issues, https://github.com/AnasImloul/diagr/issues
25
+ Description-Content-Type: text/markdown
26
+
27
+ # diagr
28
+
29
+ Diagrams from a YAML file that you can read and also play. One file gives you a static SVG for light mode and one
30
+ for dark mode, for READMEs, docs and slides, and a single HTML page where the diagram plays a scenario step by step:
31
+ edges draw as a request moves along them, nodes turn active, done or failed, and text changes as the story goes.
32
+
33
+ <picture>
34
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-dark.svg">
35
+ <img alt="A web app posts an order to the API, which queues it for workers that write it to the orders database." src="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-light.svg">
36
+ </picture>
37
+
38
+ - **Static first.** The SVGs are laid out on a grid, automatically or with the cells you pin, with rounded
39
+ orthogonal edges, label pills and tinted groups. Icons are inlined and colours are baked in, so the files work
40
+ anywhere an image does.
41
+ - **Interactive on top.** The HTML page has a scenario player: run, play and pause, step forward and back, scrub,
42
+ change the speed. A diagram can have several scenarios, each with its own trigger button. Each frame's state is
43
+ worked out from the frame number, so stepping back or scrubbing shows exactly what playing would.
44
+ - **One HTML file.** Inline SVG, CSS and JavaScript. No CDN, no framework, nothing to load at runtime.
45
+ - **Checks that point at the line.** `diagr check` reports problems as `file:line:col`, suggests the id you probably
46
+ meant, and warns about what you would otherwise only spot in the picture, such as an edge running through a node.
47
+ - **Domain-neutral.** Nothing in the format assumes pipelines or a vendor. Vendor icons go in a folder next to the
48
+ diagram.
49
+
50
+ ## Install
51
+
52
+ diagr needs Python 3.12 or later.
53
+
54
+ ```sh
55
+ uv tool install diagr
56
+ # or
57
+ pip install diagr
58
+ ```
59
+
60
+ ## Quick start
61
+
62
+ ```sh
63
+ diagr init my-flow.yml # writes a starter diagram, and never overwrites a file
64
+ diagr build my-flow.yml --svg --html -o dist # dist/my-flow-light.svg, dist/my-flow-dark.svg, dist/my-flow.html
65
+ ```
66
+
67
+ Open `dist/my-flow.html` and press **Place order** to play the scenario. While you edit,
68
+ `diagr watch my-flow.yml --html -o dist --serve` rebuilds on every save and serves the output at `http://127.0.0.1:8001/`,
69
+ where open pages reload and keep their place in the scenario.
70
+
71
+ The starter is a short order flow:
72
+
73
+ ```yaml
74
+ version: 1
75
+ id: my-flow
76
+ title: Order processing
77
+ grid: {col: 200, row: 170}
78
+
79
+ groups:
80
+ front:
81
+ title: Frontend
82
+ tone: blue
83
+ nodes:
84
+ web: {at: [0, 0], icon: browser, title: Web app}
85
+ back:
86
+ title: Backend
87
+ sub: one region
88
+ tone: teal
89
+ nodes:
90
+ api: {at: [1, 0], icon: function, title: API, sub: validates}
91
+ queue: {at: [2, 0], icon: queue, title: Order queue}
92
+ db: {at: [3, 0], icon: database, title: Orders}
93
+
94
+ edges:
95
+ web -> api -> queue -> db: [POST /orders, enqueue, write]
96
+
97
+ scenarios:
98
+ order:
99
+ trigger: {at: web, label: Place order}
100
+ steps:
101
+ - {title: Submit, at: web, do: [flow web -> api]}
102
+ - {title: Queue, at: api, do: [flow api 400ms -> queue]}
103
+ - {title: Store, at: db, do: [flow queue -> db 300ms done]}
104
+ ```
105
+
106
+ Groups hold nodes, each edge key can make several edges (`web -> api -> queue -> db` makes three, one label each),
107
+ and each step of a scenario says what happens: `flow web -> api` makes `web` active, draws its edge to `api`, then
108
+ marks `web` done.
109
+
110
+ To show a diagram in a README, use both SVGs so the image follows the reader's theme:
111
+
112
+ ```html
113
+ <picture>
114
+ <source media="(prefers-color-scheme: dark)" srcset="my-flow-dark.svg">
115
+ <img alt="Order processing" src="my-flow-light.svg">
116
+ </picture>
117
+ ```
118
+
119
+ ## What a diagram can hold
120
+
121
+ - **Groups and nodes**, nested as deep as you like, with titles, sub lines, icons, tooltips, progress cells and
122
+ stacked copies. Pin any of them to grid cells, or leave out `at` and diagr places them for you.
123
+ - **Edges**, written as chains (`a -> b -> c`), fans (`(a b) -> c`), dashed links (`a --> b`) and pairs that run
124
+ both ways (`a <-> b`), with labels, ports and routes of your own when you want them.
125
+ - **Rows and columns** that arrange a box's contents like CSS flexbox, as an alternative to grid cells.
126
+ - **Components**: a block of groups, nodes and edges defined once and used as named instances, with text
127
+ parameters.
128
+ - **Scenarios**: steps whose effects activate, finish or fail nodes, draw edges, fill cells, change text, show and
129
+ hide parts, and run side by side or on repeat.
130
+ - **Views**: parts of one diagram built as their own images and page, including dynamic views that number a
131
+ scenario's edges by step.
132
+ - **Themes and icons**: a default and a high-contrast theme, brand themes that change only what they need, 40 core
133
+ icons, and folders of your own.
134
+
135
+ ## Documentation
136
+
137
+ - [Diagram format](https://anasimloul.github.io/diagr/format/): everything a diagram file can say, with examples
138
+ - [Themes and icons](https://anasimloul.github.io/diagr/themes-and-icons/)
139
+ - [Docs and CI](https://anasimloul.github.io/diagr/integrations/): ```` ```diagr ```` blocks in MkDocs, and a GitHub Actions workflow that keeps
140
+ committed SVGs in step with their diagrams
141
+ - [How diagr compares](https://anasimloul.github.io/diagr/comparison/) with D2, Mermaid, Structurizr, LikeC4, Ilograph and IcePanel, and when
142
+ another tool fits better
143
+ - [Examples](https://anasimloul.github.io/diagr/examples/), with their source in [`examples/`](https://github.com/AnasImloul/diagr/tree/main/examples):
144
+ - `order-flow`: the example above, looping, with a dead-letter queue
145
+ - `cloud-architecture`: pull-based workers, retries, and a captions path running alongside the job
146
+ - `multi-region`: nested groups, a component used twice and three scenarios
147
+ - `data-platform`: a three-instance component, three levels of nesting, a merge junction and four scenarios
148
+ - `event-driven`: no positions at all, so every node is placed automatically
149
+
150
+ ## CLI
151
+
152
+ | Command | What it does |
153
+ |---|---|
154
+ | `diagr init [FILE] [--id ID]` | Write a starter diagram (default `diagram.yml`); never overwrites |
155
+ | `diagr build FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--debug] [--transparent]` | Write the files you ask for, at least one, for each diagram and each of its views: `--light` and `--dark` the static SVGs, `--svg` both, `--html` the page with the player; `--debug` adds the grid and route overlay to the page (G toggles it); `--transparent` leaves the background out of the SVGs |
156
+ | `diagr watch FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--interval S] [--debug] [--transparent] [--serve] [--port P]` | Rebuild the files you ask for, as `build` does, when the diagram, its icon folders or its theme file change; `--serve` also serves the output, and open pages reload on each rebuild |
157
+ | `diagr check FILE... [--theme T] [--strict] [--format json]` | Validate; problems are printed as `file:line:col`, or as JSON on stdout; `--strict` fails on warnings too |
158
+ | `diagr expand FILE [-o OUT]` | Print the diagram with its components written out as plain groups, nodes and edges and every position pinned; the output builds to the same files |
159
+ | `diagr icons [FILE]` | List the core icons, plus the icon folders of `FILE` if given |
160
+ | `diagr schema [-o FILE]` | Print the JSON Schema |
161
+ | `diagr --version` | Print the installed version |
162
+
163
+ `--theme` on the command line is resolved against the current folder; `theme:` in a diagram against the diagram's
164
+ folder.
165
+
166
+ For autocomplete in editors that support it, put `# yaml-language-server: $schema=<path>/diagr.schema.json` at the
167
+ top of a diagram, pointing at [`schema/diagr.schema.json`](https://github.com/AnasImloul/diagr/blob/main/schema/diagr.schema.json) or at the file
168
+ `diagr schema -o` writes.
169
+
170
+ ## Player keys
171
+
172
+ The keys work once the diagram or the player has focus: click the diagram, or Tab to it. The rest of the page keeps
173
+ its keys, so Space and the arrows still scroll it.
174
+
175
+ | Key | Does |
176
+ |---|---|
177
+ | Space | Play or pause |
178
+ | Left, Right | Previous or next step; with Shift, one frame |
179
+ | Home, End | Back to the start, or to the end |
180
+ | `+`, `-`, `0` | Zoom in, zoom out, fit the whole diagram |
181
+ | `F` | Full screen |
182
+ | `C` | High contrast, remembered like the light or dark choice |
183
+
184
+ Ctrl or ⌘ with the scroll wheel, or a pinch, zooms around the pointer, and you can drag to pan once zoomed in.
185
+ Clicking a step in the list jumps to it, and with several scenarios the buttons above the progress bar switch between
186
+ them. A scenario with `loop: true` plays on its own and replays until you pause it.
187
+
188
+ ## Development
189
+
190
+ ```sh
191
+ uv sync
192
+ uv run ruff check .
193
+ uv run ruff format --check . # or: uv run ruff format .
194
+ uv run pyright
195
+ uv run python -m unittest discover -s tests -t .
196
+ ```
197
+
198
+ `tests/golden/` holds the expected output of every example. After a change that is meant to alter the output, run
199
+ `DIAGR_UPDATE_GOLDEN=1 uv run python -m unittest tests.test_examples` and review the diff. After changing the format,
200
+ regenerate the schema with `uv run diagr schema -o schema/diagr.schema.json`; a test fails if it is out of date. One
201
+ test runs the player's state code with Node and is skipped when `node` is not installed.
202
+ `.github/workflows/ci.yml` runs all of this on every push and pull request.
203
+
204
+ The docs site is built with MkDocs Material, with the examples built from `examples/` each time:
205
+
206
+ ```sh
207
+ uv sync --group docs
208
+ uv run mkdocs serve # live preview
209
+ uv run mkdocs build --strict # writes site/
210
+ ```
211
+
212
+ `.github/workflows/docs.yml` builds it on every push to `main`, and deploys it to GitHub Pages once the repository is
213
+ public.
214
+
215
+ | Path | What |
216
+ |---|---|
217
+ | `src/diagr/` | The package: parser, validator, layout, scenario compiler, renderers, themes, core icons |
218
+ | `examples/` | Example diagrams |
219
+ | `schema/` | Generated JSON Schema |
220
+ | `tests/` | Unit tests and golden files for the examples |
221
+ | `tools/measure_text.py` | Regenerates the text width table from installed fonts (needs Chrome) |
222
+
223
+ ## License
224
+
225
+ MIT, see [LICENSE](https://github.com/AnasImloul/diagr/blob/main/LICENSE).
diagr-0.1.0/README.md ADDED
@@ -0,0 +1,199 @@
1
+ # diagr
2
+
3
+ Diagrams from a YAML file that you can read and also play. One file gives you a static SVG for light mode and one
4
+ for dark mode, for READMEs, docs and slides, and a single HTML page where the diagram plays a scenario step by step:
5
+ edges draw as a request moves along them, nodes turn active, done or failed, and text changes as the story goes.
6
+
7
+ <picture>
8
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-dark.svg">
9
+ <img alt="A web app posts an order to the API, which queues it for workers that write it to the orders database." src="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-light.svg">
10
+ </picture>
11
+
12
+ - **Static first.** The SVGs are laid out on a grid, automatically or with the cells you pin, with rounded
13
+ orthogonal edges, label pills and tinted groups. Icons are inlined and colours are baked in, so the files work
14
+ anywhere an image does.
15
+ - **Interactive on top.** The HTML page has a scenario player: run, play and pause, step forward and back, scrub,
16
+ change the speed. A diagram can have several scenarios, each with its own trigger button. Each frame's state is
17
+ worked out from the frame number, so stepping back or scrubbing shows exactly what playing would.
18
+ - **One HTML file.** Inline SVG, CSS and JavaScript. No CDN, no framework, nothing to load at runtime.
19
+ - **Checks that point at the line.** `diagr check` reports problems as `file:line:col`, suggests the id you probably
20
+ meant, and warns about what you would otherwise only spot in the picture, such as an edge running through a node.
21
+ - **Domain-neutral.** Nothing in the format assumes pipelines or a vendor. Vendor icons go in a folder next to the
22
+ diagram.
23
+
24
+ ## Install
25
+
26
+ diagr needs Python 3.12 or later.
27
+
28
+ ```sh
29
+ uv tool install diagr
30
+ # or
31
+ pip install diagr
32
+ ```
33
+
34
+ ## Quick start
35
+
36
+ ```sh
37
+ diagr init my-flow.yml # writes a starter diagram, and never overwrites a file
38
+ diagr build my-flow.yml --svg --html -o dist # dist/my-flow-light.svg, dist/my-flow-dark.svg, dist/my-flow.html
39
+ ```
40
+
41
+ Open `dist/my-flow.html` and press **Place order** to play the scenario. While you edit,
42
+ `diagr watch my-flow.yml --html -o dist --serve` rebuilds on every save and serves the output at `http://127.0.0.1:8001/`,
43
+ where open pages reload and keep their place in the scenario.
44
+
45
+ The starter is a short order flow:
46
+
47
+ ```yaml
48
+ version: 1
49
+ id: my-flow
50
+ title: Order processing
51
+ grid: {col: 200, row: 170}
52
+
53
+ groups:
54
+ front:
55
+ title: Frontend
56
+ tone: blue
57
+ nodes:
58
+ web: {at: [0, 0], icon: browser, title: Web app}
59
+ back:
60
+ title: Backend
61
+ sub: one region
62
+ tone: teal
63
+ nodes:
64
+ api: {at: [1, 0], icon: function, title: API, sub: validates}
65
+ queue: {at: [2, 0], icon: queue, title: Order queue}
66
+ db: {at: [3, 0], icon: database, title: Orders}
67
+
68
+ edges:
69
+ web -> api -> queue -> db: [POST /orders, enqueue, write]
70
+
71
+ scenarios:
72
+ order:
73
+ trigger: {at: web, label: Place order}
74
+ steps:
75
+ - {title: Submit, at: web, do: [flow web -> api]}
76
+ - {title: Queue, at: api, do: [flow api 400ms -> queue]}
77
+ - {title: Store, at: db, do: [flow queue -> db 300ms done]}
78
+ ```
79
+
80
+ Groups hold nodes, each edge key can make several edges (`web -> api -> queue -> db` makes three, one label each),
81
+ and each step of a scenario says what happens: `flow web -> api` makes `web` active, draws its edge to `api`, then
82
+ marks `web` done.
83
+
84
+ To show a diagram in a README, use both SVGs so the image follows the reader's theme:
85
+
86
+ ```html
87
+ <picture>
88
+ <source media="(prefers-color-scheme: dark)" srcset="my-flow-dark.svg">
89
+ <img alt="Order processing" src="my-flow-light.svg">
90
+ </picture>
91
+ ```
92
+
93
+ ## What a diagram can hold
94
+
95
+ - **Groups and nodes**, nested as deep as you like, with titles, sub lines, icons, tooltips, progress cells and
96
+ stacked copies. Pin any of them to grid cells, or leave out `at` and diagr places them for you.
97
+ - **Edges**, written as chains (`a -> b -> c`), fans (`(a b) -> c`), dashed links (`a --> b`) and pairs that run
98
+ both ways (`a <-> b`), with labels, ports and routes of your own when you want them.
99
+ - **Rows and columns** that arrange a box's contents like CSS flexbox, as an alternative to grid cells.
100
+ - **Components**: a block of groups, nodes and edges defined once and used as named instances, with text
101
+ parameters.
102
+ - **Scenarios**: steps whose effects activate, finish or fail nodes, draw edges, fill cells, change text, show and
103
+ hide parts, and run side by side or on repeat.
104
+ - **Views**: parts of one diagram built as their own images and page, including dynamic views that number a
105
+ scenario's edges by step.
106
+ - **Themes and icons**: a default and a high-contrast theme, brand themes that change only what they need, 40 core
107
+ icons, and folders of your own.
108
+
109
+ ## Documentation
110
+
111
+ - [Diagram format](https://anasimloul.github.io/diagr/format/): everything a diagram file can say, with examples
112
+ - [Themes and icons](https://anasimloul.github.io/diagr/themes-and-icons/)
113
+ - [Docs and CI](https://anasimloul.github.io/diagr/integrations/): ```` ```diagr ```` blocks in MkDocs, and a GitHub Actions workflow that keeps
114
+ committed SVGs in step with their diagrams
115
+ - [How diagr compares](https://anasimloul.github.io/diagr/comparison/) with D2, Mermaid, Structurizr, LikeC4, Ilograph and IcePanel, and when
116
+ another tool fits better
117
+ - [Examples](https://anasimloul.github.io/diagr/examples/), with their source in [`examples/`](https://github.com/AnasImloul/diagr/tree/main/examples):
118
+ - `order-flow`: the example above, looping, with a dead-letter queue
119
+ - `cloud-architecture`: pull-based workers, retries, and a captions path running alongside the job
120
+ - `multi-region`: nested groups, a component used twice and three scenarios
121
+ - `data-platform`: a three-instance component, three levels of nesting, a merge junction and four scenarios
122
+ - `event-driven`: no positions at all, so every node is placed automatically
123
+
124
+ ## CLI
125
+
126
+ | Command | What it does |
127
+ |---|---|
128
+ | `diagr init [FILE] [--id ID]` | Write a starter diagram (default `diagram.yml`); never overwrites |
129
+ | `diagr build FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--debug] [--transparent]` | Write the files you ask for, at least one, for each diagram and each of its views: `--light` and `--dark` the static SVGs, `--svg` both, `--html` the page with the player; `--debug` adds the grid and route overlay to the page (G toggles it); `--transparent` leaves the background out of the SVGs |
130
+ | `diagr watch FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--interval S] [--debug] [--transparent] [--serve] [--port P]` | Rebuild the files you ask for, as `build` does, when the diagram, its icon folders or its theme file change; `--serve` also serves the output, and open pages reload on each rebuild |
131
+ | `diagr check FILE... [--theme T] [--strict] [--format json]` | Validate; problems are printed as `file:line:col`, or as JSON on stdout; `--strict` fails on warnings too |
132
+ | `diagr expand FILE [-o OUT]` | Print the diagram with its components written out as plain groups, nodes and edges and every position pinned; the output builds to the same files |
133
+ | `diagr icons [FILE]` | List the core icons, plus the icon folders of `FILE` if given |
134
+ | `diagr schema [-o FILE]` | Print the JSON Schema |
135
+ | `diagr --version` | Print the installed version |
136
+
137
+ `--theme` on the command line is resolved against the current folder; `theme:` in a diagram against the diagram's
138
+ folder.
139
+
140
+ For autocomplete in editors that support it, put `# yaml-language-server: $schema=<path>/diagr.schema.json` at the
141
+ top of a diagram, pointing at [`schema/diagr.schema.json`](https://github.com/AnasImloul/diagr/blob/main/schema/diagr.schema.json) or at the file
142
+ `diagr schema -o` writes.
143
+
144
+ ## Player keys
145
+
146
+ The keys work once the diagram or the player has focus: click the diagram, or Tab to it. The rest of the page keeps
147
+ its keys, so Space and the arrows still scroll it.
148
+
149
+ | Key | Does |
150
+ |---|---|
151
+ | Space | Play or pause |
152
+ | Left, Right | Previous or next step; with Shift, one frame |
153
+ | Home, End | Back to the start, or to the end |
154
+ | `+`, `-`, `0` | Zoom in, zoom out, fit the whole diagram |
155
+ | `F` | Full screen |
156
+ | `C` | High contrast, remembered like the light or dark choice |
157
+
158
+ Ctrl or ⌘ with the scroll wheel, or a pinch, zooms around the pointer, and you can drag to pan once zoomed in.
159
+ Clicking a step in the list jumps to it, and with several scenarios the buttons above the progress bar switch between
160
+ them. A scenario with `loop: true` plays on its own and replays until you pause it.
161
+
162
+ ## Development
163
+
164
+ ```sh
165
+ uv sync
166
+ uv run ruff check .
167
+ uv run ruff format --check . # or: uv run ruff format .
168
+ uv run pyright
169
+ uv run python -m unittest discover -s tests -t .
170
+ ```
171
+
172
+ `tests/golden/` holds the expected output of every example. After a change that is meant to alter the output, run
173
+ `DIAGR_UPDATE_GOLDEN=1 uv run python -m unittest tests.test_examples` and review the diff. After changing the format,
174
+ regenerate the schema with `uv run diagr schema -o schema/diagr.schema.json`; a test fails if it is out of date. One
175
+ test runs the player's state code with Node and is skipped when `node` is not installed.
176
+ `.github/workflows/ci.yml` runs all of this on every push and pull request.
177
+
178
+ The docs site is built with MkDocs Material, with the examples built from `examples/` each time:
179
+
180
+ ```sh
181
+ uv sync --group docs
182
+ uv run mkdocs serve # live preview
183
+ uv run mkdocs build --strict # writes site/
184
+ ```
185
+
186
+ `.github/workflows/docs.yml` builds it on every push to `main`, and deploys it to GitHub Pages once the repository is
187
+ public.
188
+
189
+ | Path | What |
190
+ |---|---|
191
+ | `src/diagr/` | The package: parser, validator, layout, scenario compiler, renderers, themes, core icons |
192
+ | `examples/` | Example diagrams |
193
+ | `schema/` | Generated JSON Schema |
194
+ | `tests/` | Unit tests and golden files for the examples |
195
+ | `tools/measure_text.py` | Regenerates the text width table from installed fonts (needs Chrome) |
196
+
197
+ ## License
198
+
199
+ MIT, see [LICENSE](https://github.com/AnasImloul/diagr/blob/main/LICENSE).
@@ -0,0 +1,78 @@
1
+ [project]
2
+ name = "diagr"
3
+ version = "0.1.0"
4
+ description = "Declarative diagrams in YAML: static SVG in light and dark, and a self-contained interactive HTML page."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ dependencies = ["pyyaml>=6.0"]
10
+ keywords = [
11
+ "diagram",
12
+ "svg",
13
+ "yaml",
14
+ "architecture",
15
+ "documentation",
16
+ ]
17
+ classifiers = [
18
+ "Development Status :: 3 - Alpha",
19
+ "Environment :: Console",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Programming Language :: Python :: 3.14",
24
+ "Topic :: Documentation",
25
+ "Topic :: Multimedia :: Graphics",
26
+ "Typing :: Typed",
27
+ ]
28
+
29
+ [[project.authors]]
30
+ name = "AnasImloul"
31
+ email = "anas.imloul27@gmail.com"
32
+
33
+ [project.urls]
34
+ Homepage = "https://anasimloul.github.io/diagr/"
35
+ Documentation = "https://anasimloul.github.io/diagr/"
36
+ Repository = "https://github.com/AnasImloul/diagr"
37
+ Issues = "https://github.com/AnasImloul/diagr/issues"
38
+
39
+ [project.scripts]
40
+ diagr = "diagr.cli:main"
41
+
42
+ [dependency-groups]
43
+ dev = [
44
+ "ruff",
45
+ "pyright",
46
+ ]
47
+ docs = ["mkdocs-material"]
48
+
49
+ [build-system]
50
+ requires = ["uv_build>=0.12,<0.13"]
51
+ build-backend = "uv_build"
52
+
53
+ [tool.ruff]
54
+ line-length = 120
55
+ target-version = "py312"
56
+
57
+ [tool.ruff.format]
58
+ exclude = ["src/diagr/layout/metrics.py"]
59
+
60
+ [tool.ruff.lint]
61
+ select = [
62
+ "E",
63
+ "F",
64
+ "W",
65
+ "I",
66
+ "B",
67
+ "UP",
68
+ ]
69
+
70
+ [tool.pyright]
71
+ include = [
72
+ "src",
73
+ "tools",
74
+ "tests",
75
+ ]
76
+ pythonVersion = "3.12"
77
+ venvPath = "."
78
+ venv = ".venv"
@@ -0,0 +1,55 @@
1
+ [project]
2
+ name = "diagr"
3
+ version = "0.1.0"
4
+ description = "Declarative diagrams in YAML: static SVG in light and dark, and a self-contained interactive HTML page."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "AnasImloul", email = "anas.imloul27@gmail.com" }]
9
+ requires-python = ">=3.12"
10
+ dependencies = ["pyyaml>=6.0"]
11
+ keywords = ["diagram", "svg", "yaml", "architecture", "documentation"]
12
+ classifiers = [
13
+ "Development Status :: 3 - Alpha",
14
+ "Environment :: Console",
15
+ "Programming Language :: Python :: 3",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Programming Language :: Python :: 3.14",
19
+ "Topic :: Documentation",
20
+ "Topic :: Multimedia :: Graphics",
21
+ "Typing :: Typed",
22
+ ]
23
+
24
+ [project.urls]
25
+ Homepage = "https://anasimloul.github.io/diagr/"
26
+ Documentation = "https://anasimloul.github.io/diagr/"
27
+ Repository = "https://github.com/AnasImloul/diagr"
28
+ Issues = "https://github.com/AnasImloul/diagr/issues"
29
+
30
+ [project.scripts]
31
+ diagr = "diagr.cli:main"
32
+
33
+ [dependency-groups]
34
+ dev = ["ruff", "pyright"]
35
+ docs = ["mkdocs-material"]
36
+
37
+ [build-system]
38
+ requires = ["uv_build>=0.12,<0.13"]
39
+ build-backend = "uv_build"
40
+
41
+ [tool.ruff]
42
+ line-length = 120
43
+ target-version = "py312"
44
+
45
+ [tool.ruff.format]
46
+ exclude = ["src/diagr/layout/metrics.py"]
47
+
48
+ [tool.ruff.lint]
49
+ select = ["E", "F", "W", "I", "B", "UP"]
50
+
51
+ [tool.pyright]
52
+ include = ["src", "tools", "tests"]
53
+ pythonVersion = "3.12"
54
+ venvPath = "."
55
+ venv = ".venv"
@@ -0,0 +1,13 @@
1
+ from importlib.metadata import PackageNotFoundError, version
2
+
3
+ from .build import Prepared, build_files, prepare
4
+ from .model import Diagram
5
+ from .parse import load_file
6
+ from .source import DiagramError, Problem
7
+ from .syntax import json_schema
8
+
9
+ __all__ = ["Diagram", "DiagramError", "Prepared", "Problem", "build_files", "json_schema", "load_file", "prepare"]
10
+ try:
11
+ __version__ = version("diagr")
12
+ except PackageNotFoundError:
13
+ __version__ = "0+unknown"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())