infrasketch 2.0.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infrasketch
-Version: 2.0.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:
@@ -120,10 +122,26 @@ diagram.save("orders.svg")
 | `a >> Https() >> b` | Azure-blue HTTPS |
 | `a >> Async("enqueue") >> b` | Dashed queue or event |
 | `a >> Private() >> b` | Dashed Private Link |
+| `a >> Https("Open the store", 1) >> b` | Numbered step. The sentence is listed under the drawing |
 
 `style` is `"solid"`, `"dashed"`, or `"dotted"`. `color` is a hex color such
 as `"#0078D4"`.
 
+A resource can carry the design decision and a link. The SKU, region, and
+exposure are a second caption. `note` is the line under that. `href` makes the
+icon a link. The same fields, except `href`, work on a group:
+
+```python
+api = AppService(
+    "Orders API",
+    sku="P1v3",
+    region="West Europe",
+    public=False,
+    note="Private endpoint only",
+    href="https://learn.microsoft.com/azure/app-service/overview",
+)
+```
+
 ## Boundaries
 
 | Group | Use it for |
@@ -140,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
 
@@ -192,6 +212,8 @@ to use your own artwork. Azure icons are never recoloured or stretched.
 | `examples/aws_orders.py` | CloudFront, API Gateway, Lambda, DynamoDB, and S3 in a VPC |
 | `examples/aws_eks.py` | EKS, a registry, ElastiCache, and RDS |
 | `examples/aws_events.py` | API Gateway, Lambda, SQS, DynamoDB, and S3 |
+| `examples/azure_decisions.py` | SKU, exposure, notes, numbered steps, and links |
+| `examples/aws_decisions.py` | The same decisions on an AWS drawing |
 
 ![Web, API, and Redis](examples/out/azure-web-api.svg)
 

{infrasketch-2.0.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:
@@ -101,10 +103,26 @@ diagram.save("orders.svg")
 | `a >> Https() >> b` | Azure-blue HTTPS |
 | `a >> Async("enqueue") >> b` | Dashed queue or event |
 | `a >> Private() >> b` | Dashed Private Link |
+| `a >> Https("Open the store", 1) >> b` | Numbered step. The sentence is listed under the drawing |
 
 `style` is `"solid"`, `"dashed"`, or `"dotted"`. `color` is a hex color such
 as `"#0078D4"`.
 
+A resource can carry the design decision and a link. The SKU, region, and
+exposure are a second caption. `note` is the line under that. `href` makes the
+icon a link. The same fields, except `href`, work on a group:
+
+```python
+api = AppService(
+    "Orders API",
+    sku="P1v3",
+    region="West Europe",
+    public=False,
+    note="Private endpoint only",
+    href="https://learn.microsoft.com/azure/app-service/overview",
+)
+```
+
 ## Boundaries
 
 | Group | Use it for |
@@ -121,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
 
@@ -173,6 +193,8 @@ to use your own artwork. Azure icons are never recoloured or stretched.
 | `examples/aws_orders.py` | CloudFront, API Gateway, Lambda, DynamoDB, and S3 in a VPC |
 | `examples/aws_eks.py` | EKS, a registry, ElastiCache, and RDS |
 | `examples/aws_events.py` | API Gateway, Lambda, SQS, DynamoDB, and S3 |
+| `examples/azure_decisions.py` | SKU, exposure, notes, numbered steps, and links |
+| `examples/aws_decisions.py` | The same decisions on an AWS drawing |
 
 ![Web, API, and Redis](examples/out/azure-web-api.svg)
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "infrasketch"
-version = "2.0.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.0.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,16 +67,32 @@ 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 []
+    node.detail_lines = wrap(node.facts(), CAPTION_SIZE, TEXT_MAX)[:2]
+    node.note_lines = wrap(node.note, CAPTION_SIZE, TEXT_MAX)[:2]
     widths = [text_width(line, LABEL_SIZE) for line in node.label_lines]
     widths += [text_width(line, CAPTION_SIZE) for line in node.caption_lines]
+    widths += [text_width(line, CAPTION_SIZE) for line in node.detail_lines]
+    widths += [text_width(line, CAPTION_SIZE) for line in node.note_lines]
     text_w = max(widths) if widths else 0.0
     node.w = max(ICON + 20.0, text_w + 12.0)
     text_h = len(node.label_lines) * LABEL_LEADING
     if node.caption_lines:
         text_h += 3.0 + len(node.caption_lines) * CAPTION_LEADING
+    if node.detail_lines:
+        text_h += len(node.detail_lines) * CAPTION_LEADING
+    if node.note_lines:
+        text_h += 2.0 + len(node.note_lines) * CAPTION_LEADING
     node.h = ICON + ICON_TEXT_GAP + text_h
     node.icon_box = ((node.w - ICON) / 2.0, 0.0, ICON, ICON)
 
@@ -81,7 +100,7 @@ def measure_node(node: Node) -> None:
 def apply_chrome(group: Group) -> None:
     style = BOUNDARIES[group.kind]
     spacing = SPACING[group.diagram.spacing]
-    header = measure_header(group.label, style)
+    header = measure_header(group.label, style, detail=group.facts(), note=group.note)
     group.header = header
     group.header_h = header["height"]
     pad = spacing["pad"]
@@ -93,18 +112,32 @@ def apply_chrome(group: Group) -> None:
     group.h = group.content_y + group.content_h + pad
 
 
-def measure_header(label: str, style: dict) -> dict:
+def measure_header(label: str, style: dict, detail: str = "", note: str = "") -> dict:
     title_lines = wrap(label, 13.5, 240.0)[:2] or [label]
+    detail_lines = wrap(detail, 11.0, 240.0)[:2] if detail else []
+    note_lines = wrap(note, 11.0, 240.0)[:2] if note else []
     title_w = max(text_width(line, 13.5) for line in title_lines)
+    detail_w = max((text_width(line, 11.0) for line in detail_lines), default=0.0)
+    note_w = max((text_width(line, 11.0) for line in note_lines), default=0.0)
     eyebrow = style["eyebrow"]
     eye_w = text_width(eyebrow, 10.0) * 1.18 if eyebrow else 0.0
     icon_slot = 28.0 if style["icon"] else 0.0
-    width = 16.0 + icon_slot + max(title_w, eye_w) + 18.0
+    width = 16.0 + icon_slot + max(title_w, eye_w, detail_w, note_w) + 18.0
     if eyebrow:
         height = 14.0 + 13.0 + len(title_lines) * 16.0 + 8.0
     else:
         height = 10.0 + len(title_lines) * 18.0 + 10.0
-    return {"height": height, "width": width, "title_lines": title_lines, "eyebrow": eyebrow}
+    extra = (len(detail_lines) + len(note_lines)) * 14.0
+    if extra:
+        height += extra + 2.0
+    return {
+        "height": height,
+        "width": width,
+        "title_lines": title_lines,
+        "eyebrow": eyebrow,
+        "detail_lines": detail_lines,
+        "note_lines": note_lines,
+    }
 
 
 def place_flow(scope: Diagram | Group) -> None:

{infrasketch-2.0.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] = []
@@ -47,6 +48,23 @@ class Endpoint(Scope):
     """Something an arrow can connect to: a resource or a boundary."""
 
     label = ""
+    sku = ""
+    region = ""
+    public: bool | None = None
+    note = ""
+
+    def facts(self) -> str:
+        """SKU, region, and exposure, joined for the second caption."""
+        parts = []
+        if self.sku:
+            parts.append(self.sku)
+        if self.region:
+            parts.append(self.region)
+        if self.public is True:
+            parts.append("Public")
+        elif self.public is False:
+            parts.append("Private")
+        return " · ".join(parts)
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.label!r})"
@@ -75,6 +93,7 @@ class Endpoint(Scope):
                 color=edge.color,
                 style=edge.style or "solid",
                 direction=direction,
+                number=edge.number,
             )
         )
         return other
@@ -145,6 +164,7 @@ class Connection:
     color: str = ""
     style: str = "solid"
     direction: str = "forward"
+    number: int | None = None
     points: list[tuple[float, float]] = field(default_factory=list)
     lane: float = 0.0
 
@@ -155,6 +175,7 @@ class Edge:
     def __init__(
         self,
         label: str = "",
+        number: int | None = None,
         *,
         color: str = "",
         style: str = "solid",
@@ -163,6 +184,7 @@ class Edge:
         node: Endpoint | None = None,
     ) -> None:
         self.label = label or ""
+        self.number = _check_number(number)
         self.color = color or ""
         self.style = style or "solid"
         self.forward = forward
@@ -197,6 +219,7 @@ class Edge:
         for item in other:
             edge = Edge(
                 self.label,
+                self.number,
                 color=self.color,
                 style=self.style,
                 forward=forward or self.forward,
@@ -207,6 +230,8 @@ class Edge:
                 edge.label = item.label or edge.label
                 edge.color = item.color or edge.color
                 edge.style = item.style or edge.style
+                if item.number is not None:
+                    edge.number = item.number
             result.append(edge)
         return result
 
@@ -222,6 +247,8 @@ class Edge:
                 self.color = other.color
             if other.style:
                 self.style = other.style
+            if other.number is not None:
+                self.number = other.number
             return self
         if self.node is not None:
             return self.node.connect(other, self)
@@ -232,27 +259,27 @@ class Edge:
 class Https(Edge):
     """HTTPS connector in Azure blue."""
 
-    def __init__(self, label: str = "HTTPS", **kwargs) -> None:
+    def __init__(self, label: str = "HTTPS", number: int | None = None, **kwargs) -> None:
         kwargs.setdefault("color", "#0078D4")
-        super().__init__(label, **kwargs)
+        super().__init__(label, number, **kwargs)
 
 
 class Async(Edge):
     """Dashed connector for queues, events, and other asynchronous calls."""
 
-    def __init__(self, label: str = "", **kwargs) -> None:
+    def __init__(self, label: str = "", number: int | None = None, **kwargs) -> None:
         kwargs.setdefault("color", "#7C3AED")
         kwargs.setdefault("style", "dashed")
-        super().__init__(label, **kwargs)
+        super().__init__(label, number, **kwargs)
 
 
 class Private(Edge):
     """Dashed green connector for Private Link and private endpoints."""
 
-    def __init__(self, label: str = "", **kwargs) -> None:
+    def __init__(self, label: str = "", number: int | None = None, **kwargs) -> None:
         kwargs.setdefault("color", "#107C41")
         kwargs.setdefault("style", "dashed")
-        super().__init__(label, **kwargs)
+        super().__init__(label, number, **kwargs)
 
 
 class Node(Endpoint):
@@ -267,6 +294,11 @@ class Node(Endpoint):
         *,
         caption: str | bool | None = None,
         icon: str | None = None,
+        sku: str | None = None,
+        region: str | None = None,
+        public: bool | None = None,
+        note: str | None = None,
+        href: str | None = None,
     ) -> None:
         super().__init__()
         parent = _current_parent()
@@ -283,11 +315,18 @@ class Node(Endpoint):
             self.label = service
             self.caption = ""
         self.icon = icon if icon is not None else self.__class__.icon
+        self.sku = _text(sku, "sku")
+        self.region = _text(region, "region")
+        self.public = _check_public(public)
+        self.note = _text(note, "note")
+        self.href = _check_href(href)
         self.diagram = parent.diagram if not isinstance(parent, Diagram) else parent
         self.parent = parent
         parent.children.append(self)
         self.label_lines: list[str] = []
         self.caption_lines: list[str] = []
+        self.detail_lines: list[str] = []
+        self.note_lines: list[str] = []
         self.icon_box = (0.0, 0.0, 0.0, 0.0)
 
     def __init_subclass__(cls, **kwargs) -> None:
@@ -311,9 +350,22 @@ class Group(Endpoint):
         arrange: str | None = None,
         columns: int | None = None,
         align: str | None = None,
+        sku: str | None = None,
+        region: str | None = None,
+        public: bool | None = None,
+        note: str | None = None,
+        folded: bool = False,
     ) -> None:
         super().__init__()
         self.label = label
+        self.sku = _text(sku, "sku")
+        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
@@ -339,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.
 
@@ -356,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"}:
@@ -420,6 +484,48 @@ 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 ""
+    if not isinstance(value, str):
+        raise DiagramError(f"{name} must be text")
+    return value.strip()
+
+
+def _check_public(value: bool | None) -> bool | None:
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        raise DiagramError("public must be true or false")
+    return value
+
+
+def _check_href(value: str | None) -> str:
+    if value is None or value == "":
+        return ""
+    if not isinstance(value, str) or not re.match(r"https?://\S+$", value.strip(), re.IGNORECASE):
+        raise DiagramError("href must be an http or https URL")
+    return value.strip()
+
+
+def _check_number(value: int | None) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise DiagramError("Edge number must be a positive integer")
+    return value
+
+
 def _check_color(color: str) -> None:
     if not color:
         return