frameplot 0.5.5__tar.gz → 0.5.7__tar.gz

{frameplot-0.5.5/src/frameplot.egg-info → frameplot-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frameplot
-Version: 0.5.5
+Version: 0.5.7
 Summary: Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams.
 Author: Small Turtle 2
 License-Expression: MIT
@@ -147,6 +147,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -161,6 +167,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

{frameplot-0.5.5 → frameplot-0.5.7}/README.md

@@ -118,6 +118,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -132,6 +138,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

{frameplot-0.5.5 → frameplot-0.5.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "frameplot"
-version = "0.5.5"
+version = "0.5.7"
 description = "Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams."
 readme = "README.md"
 requires-python = ">=3.11"

{frameplot-0.5.5 → frameplot-0.5.7}/src/frameplot/api.py

@@ -19,8 +19,12 @@ class Pipeline:
     """Describe and render a pipeline diagram.
 
     The constructor accepts any iterable of nodes, edges, and groups, then
-    normalizes them to tuples for deterministic rendering. Passing `theme=None`
-    uses the default :class:`Theme`.
+    normalizes them to tuples for deterministic rendering. The main graph uses
+    dependency-driven left-to-right auto-layout, so it works best when kept to
+    one abstraction level. If stage flow and internal mechanics are mixed into
+    the same graph, ranks can stretch and routes can become unexpectedly long;
+    move those internals into a :class:`DetailPanel` instead. Passing
+    `theme=None` uses the default :class:`Theme`.
     """
 
     nodes: tuple[Node, ...]