✨ Add Template System (Canvas.from_template + built-in templates) (#1)

Author: sjquant

quickthumb/canvas.py

@@ -83,6 +83,9 @@ class CustomLayer:
 
 class Canvas:
     _custom_layer_registry: dict[str, Callable[..., Image.Image | None]] = {}
+    _template_registry: dict[str, str] = {}
+
+    _BUILTIN_TEMPLATES_DIR = os.path.join(os.path.dirname(__file__), "templates")
 
     @classmethod
     def register_layer_fn(cls, name: str, fn: Callable[..., Image.Image | None]) -> None:
@@ -92,6 +95,14 @@ def register_layer_fn(cls, name: str, fn: Callable[..., Image.Image | None]) ->
     def unregister_layer_fn(cls, name: str) -> None:
         cls._custom_layer_registry.pop(name, None)
 
+    @classmethod
+    def register_template(cls, name: str, path: str) -> None:
+        cls._template_registry[name] = path
+
+    @classmethod
+    def unregister_template(cls, name: str) -> None:
+        cls._template_registry.pop(name, None)
+
     def __init__(self, width: int, height: int, layers: list[RenderableLayer] | None = None):
         if width <= 0:
             raise ValidationError("width must be > 0")
@@ -352,6 +363,49 @@ def from_json(cls, data: str) -> Self:
 
         return cls(width=raw["width"], height=raw["height"], layers=renderable_layers)
 
+    @classmethod
+    def _read_template_file(cls, path: str) -> str:
+        try:
+            with open(path) as f:
+                return f.read()
+        except OSError as e:
+            raise ValidationError(f"Cannot read template file '{path}': {e}") from e
+
+    @classmethod
+    def _resolve_template_string(cls, spec_or_path: str) -> str:
+        if spec_or_path.lstrip().startswith("{"):
+            return spec_or_path
+        if spec_or_path in cls._template_registry:
+            return cls._read_template_file(cls._template_registry[spec_or_path])
+        builtin_path = os.path.join(cls._BUILTIN_TEMPLATES_DIR, f"{spec_or_path}.json")
+        if os.path.exists(builtin_path):
+            return cls._read_template_file(builtin_path)
+        if os.path.exists(spec_or_path):
+            return cls._read_template_file(spec_or_path)
+        raise ValidationError(
+            f"Template '{spec_or_path}' is not a registered template name, "
+            f"built-in template name, or valid file path."
+        )
+
+    @classmethod
+    def from_template(cls, spec_or_path: str, variables: dict[str, str] | None = None) -> Self:
+        import json as _json
+        import re
+
+        variables = variables or {}
+        raw_spec = cls._resolve_template_string(spec_or_path)
+
+        def substitute(match: re.Match) -> str:
+            key = match.group(1) or match.group(2)
+            if key not in variables:
+                raise ValidationError(
+                    f"Template placeholder '${key}' has no matching variable. "
+                    f"Provide variables={{'{key}': ...}} to Canvas.from_template()."
+                )
+            return _json.dumps(variables[key])[1:-1]
+
+        return cls.from_json(re.sub(r"\$\{(\w+)\}|\$(\w+)", substitute, raw_spec))
+
     def to_base64(self, format: FileFormat = "PNG", quality: int | None = None) -> str:
         import base64
 

quickthumb/templates/instagram-square.json

@@ -0,0 +1,18 @@
+{
+  "width": 1080,
+  "height": 1080,
+  "layers": [
+    {
+      "type": "background",
+      "color": "#111827"
+    },
+    {
+      "type": "text",
+      "content": "$title",
+      "size": 88,
+      "color": "#FFFFFF",
+      "position": ["50%", "50%"],
+      "align": ["center", "middle"]
+    }
+  ]
+}

quickthumb/templates/og-image.json

@@ -0,0 +1,18 @@
+{
+  "width": 1200,
+  "height": 630,
+  "layers": [
+    {
+      "type": "background",
+      "color": "#111827"
+    },
+    {
+      "type": "text",
+      "content": "$title",
+      "size": 72,
+      "color": "#FFFFFF",
+      "position": ["50%", "50%"],
+      "align": ["center", "middle"]
+    }
+  ]
+}

quickthumb/templates/twitter-card.json

@@ -0,0 +1,18 @@
+{
+  "width": 1200,
+  "height": 600,
+  "layers": [
+    {
+      "type": "background",
+      "color": "#111827"
+    },
+    {
+      "type": "text",
+      "content": "$title",
+      "size": 72,
+      "color": "#FFFFFF",
+      "position": ["50%", "50%"],
+      "align": ["center", "middle"]
+    }
+  ]
+}

quickthumb/templates/youtube-16x9.json

@@ -0,0 +1,18 @@
+{
+  "width": 1280,
+  "height": 720,
+  "layers": [
+    {
+      "type": "background",
+      "color": "#111827"
+    },
+    {
+      "type": "text",
+      "content": "$title",
+      "size": 88,
+      "color": "#FFFFFF",
+      "position": ["8%", "50%"],
+      "align": ["left", "middle"]
+    }
+  ]
+}

specs/TASKS.md

@@ -24,10 +24,10 @@
 
 #### Template System
 
-- [TODO] Implement `Canvas.from_template(spec_or_path, variables={})` with `$var` / `${var}` string substitution
-- [TODO] Raise `ValidationError` on unresolved placeholders before JSON parsing
-- [TODO] Add `Canvas.register_template(name, path)` and `Canvas.unregister_template(name)` registry
-- [TODO] Create `quickthumb/templates/` directory with starter templates: `youtube-16x9`, `instagram-square`, `twitter-card`, `og-image`
+- [DONE] Implement `Canvas.from_template(spec_or_path, variables={})` with `$var` / `${var}` string substitution
+- [DONE] Raise `ValidationError` on unresolved placeholders before JSON parsing
+- [DONE] Add `Canvas.register_template(name, path)` and `Canvas.unregister_template(name)` registry
+- [DONE] Create `quickthumb/templates/` directory with starter templates: `youtube-16x9`, `instagram-square`, `twitter-card`, `og-image`
 
 #### Gradient / Image-Filled Text (Knockout Text)