infrasketch 2.1.0__tar.gz → 2.2.0__tar.gz

{infrasketch-2.1.0/src/infrasketch.egg-info → infrasketch-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infrasketch
-Version: 2.1.0
+Version: 2.2.0
 Summary: Draw Azure and AWS architecture diagrams as SVG with official resource icons. No Graphviz.
 Author: infrasketch
 License-Expression: MIT AND LicenseRef-Microsoft-Azure-Architecture-Icons AND LicenseRef-AWS-Architecture-Icons
@@ -98,7 +98,9 @@ with Diagram("Web, API, and Redis", "platform.svg", subtitle="Production · West
 ```
 
 `direction="TB"` flows top to bottom. `spacing` is `"compact"`, `"regular"`,
-or `"relaxed"`. Pass `autosave=False` when you want the SVG string yourself:
+or `"relaxed"`. `align` is `"top"` or `"center"`. `as_of` prints a date in
+the footer beside the icon credit. Pass `autosave=False` when you want the
+SVG string yourself:
 
 ```python
 with Diagram("Orders", autosave=False) as diagram:
@@ -156,6 +158,8 @@ Inside a boundary, connected resources flow in the diagram direction.
 Resources at the same step stack, which is what you want for a cache beside
 its database. `arrange="row"` forces a single row, `arrange="column"` a
 single column, and `arrange="grid"` with `columns=3` a grid.
+`folded=True` draws the boundary closed, with a count of the resources
+inside. Connectors from outside land on that box. The default is open.
 
 ## Finding an icon
 

{infrasketch-2.1.0 → infrasketch-2.2.0}/README.md

@@ -79,7 +79,9 @@ with Diagram("Web, API, and Redis", "platform.svg", subtitle="Production · West
 ```
 
 `direction="TB"` flows top to bottom. `spacing` is `"compact"`, `"regular"`,
-or `"relaxed"`. Pass `autosave=False` when you want the SVG string yourself:
+or `"relaxed"`. `align` is `"top"` or `"center"`. `as_of` prints a date in
+the footer beside the icon credit. Pass `autosave=False` when you want the
+SVG string yourself:
 
 ```python
 with Diagram("Orders", autosave=False) as diagram:
@@ -137,6 +139,8 @@ Inside a boundary, connected resources flow in the diagram direction.
 Resources at the same step stack, which is what you want for a cache beside
 its database. `arrange="row"` forces a single row, `arrange="column"` a
 single column, and `arrange="grid"` with `columns=3` a grid.
+`folded=True` draws the boundary closed, with a count of the resources
+inside. Connectors from outside land on that box. The default is open.
 
 ## Finding an icon
 

{infrasketch-2.1.0 → infrasketch-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "infrasketch"
-version = "2.1.0"
+version = "2.2.0"
 description = "Draw Azure and AWS architecture diagrams as SVG with official resource icons. No Graphviz."
 readme = "README.md"
 requires-python = ">=3.10"

{infrasketch-2.1.0 → infrasketch-2.2.0}/src/infrasketch/layout.py

@@ -39,6 +39,9 @@ def layout_diagram(diagram: Diagram) -> None:
 
 
 def layout_scope(scope: Diagram | Group) -> None:
+    if isinstance(scope, Group) and scope.folded:
+        _layout_folded(scope)
+        return
     for child in scope.children:
         if isinstance(child, Group):
             layout_scope(child)
@@ -64,6 +67,14 @@ def layout_scope(scope: Diagram | Group) -> None:
         scope.content_y = 0.0
 
 
+def _layout_folded(group: Group) -> None:
+    count = sum(1 for _ in group.walk())
+    group.fold_caption = "1 resource" if count == 1 else f"{count} resources"
+    group.content_w = max(132.0, text_width(group.fold_caption, 11.0) + 28.0, text_width(group.label, 13.5) + 36.0)
+    group.content_h = 28.0
+    apply_chrome(group)
+
+
 def measure_node(node: Node) -> None:
     node.label_lines = wrap(node.label, LABEL_SIZE, TEXT_MAX)[:3]
     node.caption_lines = wrap(node.caption, CAPTION_SIZE, TEXT_MAX)[:2] if node.caption else []

{infrasketch-2.1.0 → infrasketch-2.2.0}/src/infrasketch/model.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass, field
+from datetime import date
 from typing import Iterator
 
 _stack: list[Scope] = []
@@ -353,6 +354,7 @@ class Group(Endpoint):
         region: str | None = None,
         public: bool | None = None,
         note: str | None = None,
+        folded: bool = False,
     ) -> None:
         super().__init__()
         self.label = label
@@ -360,6 +362,10 @@ class Group(Endpoint):
         self.region = _text(region, "region")
         self.public = _check_public(public)
         self.note = _text(note, "note")
+        if not isinstance(folded, bool):
+            raise DiagramError("folded must be true or false")
+        self.folded = folded
+        self.fold_caption = ""
         self.kind = kind or self.__class__.kind
         self.direction = _check_direction(direction) if direction else None
         self.arrange = arrange
@@ -385,6 +391,16 @@ class Group(Endpoint):
         _stack.pop()
 
 
+def inside_folded(element: Endpoint) -> bool:
+    """True when a folded boundary hides this resource."""
+    parent = element.parent
+    while isinstance(parent, Group):
+        if parent.folded:
+            return True
+        parent = parent.parent
+    return False
+
+
 class Diagram(Scope):
     """An architecture diagram. Use it as a context manager.
 
@@ -402,10 +418,12 @@ class Diagram(Scope):
         spacing: str = "regular",
         align: str = "top",
         autosave: bool = True,
+        as_of: str | date | None = None,
     ) -> None:
         super().__init__()
         self.title = title
         self.subtitle = subtitle or ""
+        self.as_of = _as_of(as_of)
         self.path = path or _slug(title) + ".svg"
         self.direction = _check_direction(direction)
         if spacing not in {"compact", "regular", "relaxed"}:
@@ -466,6 +484,16 @@ def _check_direction(direction: str) -> str:
     return value
 
 
+def _as_of(value: str | date | None) -> str:
+    if value is None or value == "":
+        return ""
+    if isinstance(value, date):
+        return f"{value.day} {value.strftime('%b %Y')}"
+    if not isinstance(value, str):
+        raise DiagramError("as_of must be text or a date")
+    return value.strip()
+
+
 def _text(value: str | None, name: str) -> str:
     if value is None:
         return ""

{infrasketch-2.1.0 → infrasketch-2.2.0}/src/infrasketch/render.py

@@ -6,7 +6,7 @@ from xml.sax.saxutils import escape
 
 from infrasketch.icons import embed_icon
 from infrasketch.layout import LABEL_LEADING, LABEL_SIZE, layout_diagram, text_width
-from infrasketch.model import Connection, Diagram, Group, Node
+from infrasketch.model import Connection, Diagram, Group, Node, inside_folded
 from infrasketch.route import route_diagram
 from infrasketch.theme import BOUNDARIES, CANVAS, EDGE, FONT_ATTR, FOOTER, INK, LINE, MUTED, PAGE_X
 
@@ -33,6 +33,8 @@ def render_svg(diagram: Diagram) -> str:
     layout_diagram(diagram)
     route_diagram(diagram)
     note = footnote(diagram)
+    if diagram.as_of:
+        note = f"{note} · as of {diagram.as_of}"
     width, height = _canvas_size(diagram, note)
     ids = _Ids()
     link_ns = ""
@@ -53,6 +55,8 @@ def render_svg(diagram: Diagram) -> str:
     for color in colors:
         parts.append(_marker(color))
     for group in _groups(diagram):
+        if inside_folded(group):
+            continue
         clip = ids.next("clip")
         group.clip_id = clip
         parts.append(
@@ -61,12 +65,18 @@ def render_svg(diagram: Diagram) -> str:
         )
     parts.append("</defs>")
     for group in _groups(diagram):
+        if inside_folded(group):
+            continue
         parts.append(_group_body(group))
     for edge in diagram.edges:
         parts.append(_edge_path(edge))
     for group in _groups(diagram):
+        if inside_folded(group):
+            continue
         parts.append(_group_header(group, ids))
     for node in _nodes(diagram):
+        if inside_folded(node):
+            continue
         parts.append(_node(node, ids))
     parts.append(_edge_labels(diagram))
     parts.append(_legend(diagram))
@@ -128,6 +138,13 @@ def _group_body(group: Group) -> str:
     dash = f' stroke-dasharray="{style["dash"]}"' if style["dash"] else ""
     x, y, w, h = group.abs_x, group.abs_y, group.w, group.h
     radius = style["radius"]
+    caption = ""
+    if group.folded and group.fold_caption:
+        caption = (
+            f'<text x="{x + w / 2:.1f}" y="{y + group.header_h + (h - group.header_h) / 2 + 4:.1f}" '
+            f'text-anchor="middle" fill="{MUTED}" font-family="{FONT_ATTR}" font-size="11">'
+            f"{escape(group.fold_caption)}</text>"
+        )
     return (
         f'<g clip-path="url(#{group.clip_id})">'
         f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" fill="{style["fill"]}"/>'
@@ -137,6 +154,7 @@ def _group_body(group: Group) -> str:
         f'fill="none" stroke="{style["stroke"]}" stroke-width="{style["stroke_width"]}"{dash}/>'
         f'<line x1="{x + 1:.1f}" y1="{y + group.header_h:.1f}" x2="{x + w - 1:.1f}" y2="{y + group.header_h:.1f}" '
         f'stroke="{LINE}" stroke-width="1"/>'
+        f"{caption}"
     )
 
 
@@ -317,7 +335,7 @@ def _legend_entries(diagram: Diagram) -> list[tuple[int, str]]:
     seen: set[tuple[int, str]] = set()
     entries = []
     for edge in diagram.edges:
-        if edge.number is None:
+        if edge.number is None or len(edge.points) < 2:
             continue
         item = (edge.number, edge.label)
         if item in seen:

{infrasketch-2.1.0 → infrasketch-2.2.0}/src/infrasketch/route.py

@@ -46,14 +46,44 @@ class Rect:
 def route_diagram(diagram: Diagram) -> None:
     obstacles: list[tuple[Endpoint | None, Rect]] = []
     for element in _nodes(diagram):
+        if _inside_folded(element):
+            continue
         obstacles.append((element, _node_obstacle(element)))
     for element in diagram.walk():
-        if isinstance(element, Group):
+        if not isinstance(element, Group) or _inside_folded(element):
+            continue
+        if element.folded:
+            obstacles.append((element, _node_obstacle(element)))
+        else:
             # Titles stay clear. The padding under a title is a lane for connectors.
             obstacles.append((None, _header_obstacle(element)))
     _assign_lanes(diagram.edges)
     for edge in diagram.edges:
-        edge.points = _route(edge, obstacles)
+        source, target = _shown(edge.source), _shown(edge.target)
+        if source is target:
+            edge.points = [] if source is not edge.source else _loop(source)
+            continue
+        edge.points = _route(edge, obstacles, source, target)
+
+
+def _shown(element: Endpoint) -> Endpoint:
+    """A folded boundary stands in for the resources it hides."""
+    shown = element
+    parent = element.parent
+    while isinstance(parent, Group):
+        if parent.folded:
+            shown = parent
+        parent = parent.parent
+    return shown
+
+
+def _inside_folded(element: Endpoint) -> bool:
+    parent = element.parent
+    while isinstance(parent, Group):
+        if parent.folded:
+            return True
+        parent = parent.parent
+    return False
 
 
 def _nodes(diagram: Diagram):
@@ -103,10 +133,11 @@ def _ports(source: Endpoint, target: Endpoint) -> tuple[tuple[float, float], tup
 def _assign_lanes(edges: list[Connection]) -> None:
     buckets: dict[tuple, list[Connection]] = defaultdict(list)
     for edge in edges:
-        if edge.source is edge.target:
+        source, target = _shown(edge.source), _shown(edge.target)
+        if source is target:
             edge.lane = 0.0
             continue
-        start, end, orient = _ports(edge.source, edge.target)
+        start, end, orient = _ports(source, target)
         if orient == "h":
             key = ("h", round(start[1] / 34), round(end[1] / 34), int(end[0] >= start[0]))
         else:
@@ -118,15 +149,21 @@ def _assign_lanes(edges: list[Connection]) -> None:
             edge.lane = (index - (count - 1) / 2.0) * 18.0
 
 
-def _route(edge: Connection, obstacles: list[tuple[Endpoint, Rect]]) -> list[tuple[float, float]]:
-    source, target = edge.source, edge.target
+def _route(
+    edge: Connection,
+    obstacles: list[tuple[Endpoint, Rect]],
+    source: Endpoint | None = None,
+    target: Endpoint | None = None,
+) -> list[tuple[float, float]]:
+    source = source or edge.source
+    target = target or edge.target
     if source is target:
         return _loop(source)
     start, end, orient = _ports(source, target)
     blocked = [rect for element, rect in obstacles if element is not source and element is not target]
-    if isinstance(target, Group):
+    if isinstance(target, Group) and not target.folded:
         blocked = [rect for element, rect in obstacles if element is not source]
-    if isinstance(source, Group):
+    if isinstance(source, Group) and not source.folded:
         blocked = [rect for element, rect in obstacles if element is not target]
     if orient == "h":
         return _route_horizontal(start, end, edge.lane, blocked)

{infrasketch-2.1.0 → infrasketch-2.2.0/src/infrasketch.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infrasketch
-Version: 2.1.0
+Version: 2.2.0
 Summary: Draw Azure and AWS architecture diagrams as SVG with official resource icons. No Graphviz.
 Author: infrasketch
 License-Expression: MIT AND LicenseRef-Microsoft-Azure-Architecture-Icons AND LicenseRef-AWS-Architecture-Icons
@@ -98,7 +98,9 @@ with Diagram("Web, API, and Redis", "platform.svg", subtitle="Production · West
 ```
 
 `direction="TB"` flows top to bottom. `spacing` is `"compact"`, `"regular"`,
-or `"relaxed"`. Pass `autosave=False` when you want the SVG string yourself:
+or `"relaxed"`. `align` is `"top"` or `"center"`. `as_of` prints a date in
+the footer beside the icon credit. Pass `autosave=False` when you want the
+SVG string yourself:
 
 ```python
 with Diagram("Orders", autosave=False) as diagram:
@@ -156,6 +158,8 @@ Inside a boundary, connected resources flow in the diagram direction.
 Resources at the same step stack, which is what you want for a cache beside
 its database. `arrange="row"` forces a single row, `arrange="column"` a
 single column, and `arrange="grid"` with `columns=3` a grid.
+`folded=True` draws the boundary closed, with a count of the resources
+inside. Connectors from outside land on that box. The default is open.
 
 ## Finding an icon