quickthumb 0.3.1__tar.gz → 0.4.0__tar.gz

{quickthumb-0.3.1 → quickthumb-0.4.0}/.github/workflows/docs.yml

@@ -4,6 +4,10 @@ on:
   push:
     tags:
       - "v*.*.*"
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
   workflow_dispatch:
 
 permissions:

{quickthumb-0.3.1 → quickthumb-0.4.0}/DESIGN.md

@@ -9,7 +9,7 @@ It is intended to be the reliable reference for writing QuickThumb code, generat
 - Layers render in call order: first added is the backmost layer.
 - All layer builder methods mutate the canvas and return `self`.
 - Most canvases can round-trip through JSON with `to_json()` and `from_json()`.
-- Custom callback layers are intentionally excluded from JSON serialization.
+- Named custom callback layers can round-trip through JSON via a registry. Unnamed custom layers cannot be serialized.
 
 ## Public Imports
 
@@ -58,6 +58,9 @@ canvas.outline(...)
 canvas.shape(...)
 canvas.image(...)
 canvas.custom(fn)
+canvas.custom(fn, name="...", kwargs={...})
+Canvas.register_layer_fn(name, fn)
+Canvas.unregister_layer_fn(name)
 ```
 
 ### Export Methods
@@ -294,13 +297,40 @@ def add_badge(image):
 canvas = Canvas(512, 512).custom(add_badge)
 ```
 
+Named custom layers can be serialized to JSON by registering the function in a global registry:
+
+```python
+from PIL import ImageDraw
+from quickthumb import Canvas
+
+def draw_bar(image, *, color: str = "#000000", height: int = 40) -> None:
+    ImageDraw.Draw(image).rectangle((0, 0, image.width, height), fill=color)
+
+Canvas.register_layer_fn("draw_bar", draw_bar)
+
+canvas = Canvas(512, 512).custom(draw_bar, name="draw_bar", kwargs={"color": "#E74C3C", "height": 60})
+
+json_str = canvas.to_json()
+# {"type": "custom", "name": "draw_bar", "kwargs": {"color": "#E74C3C", "height": 60}}
+
+recreated = Canvas.from_json(json_str)  # register_layer_fn must be called first
+```
+
+Parameters:
+
+- `fn`: required callable; receives a `PIL.Image.Image` as the first argument
+- `name`: optional string; required for JSON serialization
+- `kwargs`: optional dict of keyword arguments forwarded to `fn` at render time; must be JSON-serializable when `name` is set
+
 Rules:
 
 - `fn` must be callable.
-- The callback receives a `PIL.Image.Image`.
+- The callback receives a `PIL.Image.Image` as the first positional argument, followed by any `kwargs`.
 - The callback may mutate and return the same image, return a new image of the same size, or return `None`.
 - Exceptions from the callback are wrapped as `RenderingError`.
-- Custom layers cannot be serialized to JSON.
+- Unnamed custom layers (`name=None`) cannot be serialized to JSON.
+- `Canvas.register_layer_fn(name, fn)` must be called before `Canvas.from_json()` for any canvas containing a custom layer with that name.
+- `Canvas.unregister_layer_fn(name)` removes a name from the registry.
 
 ## Helpers, Enums, and Effects
 
@@ -478,7 +508,8 @@ Serialization notes:
 - Enum-like fields serialize to strings.
 - Positions serialize as JSON arrays.
 - `align` serializes to a single string such as `"center"` or `"top-left"`.
-- `canvas.custom(...)` layers are not serializable.
+- Named custom layers serialize as `{"type": "custom", "name": "...", "kwargs": {...}}`.
+- Unnamed custom layers are not serializable.
 
 ## Validation Rules and Gotchas
 
@@ -517,8 +548,10 @@ Serialization notes:
 ### JSON
 
 - `Canvas.from_json()` expects a JSON string.
-- `Canvas.to_json()` raises `ValidationError` when the canvas contains custom layers.
-- Round-trip JSON works for supported layer types and effects only.
+- `Canvas.to_json()` raises `ValidationError` when the canvas contains unnamed custom layers.
+- Named custom layers round-trip through JSON; `Canvas.register_layer_fn(name, fn)` must be called before `Canvas.from_json()`.
+- `Canvas.from_json()` raises `ValidationError` if a custom layer name is not in the registry.
+- Round-trip JSON works for all built-in layer types, effects, and named custom layers.
 
 ## End-to-End Example
 

{quickthumb-0.3.1 → quickthumb-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickthumb
-Version: 0.3.1
+Version: 0.4.0
 Summary: Programmatic thumbnail and social image generation with layered Python and JSON APIs
 Project-URL: Homepage, https://github.com/sjquant/quickthumb
 Project-URL: Repository, https://github.com/sjquant/quickthumb
@@ -244,7 +244,7 @@ serialized = canvas.to_json()
 Notes:
 
 - JSON uses top-level `width`, `height`, and `layers`
-- Custom layers added with `canvas.custom(fn)` are not JSON-serializable
+- Named custom layers added with `canvas.custom(fn, name="...", kwargs={...})` are JSON-serializable via the registry; unnamed custom layers are not
 - Enum-like values such as `blend_mode`, `fit`, and `align` can be passed as strings
 
 ## AI-Friendly Workflows
@@ -305,7 +305,7 @@ os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
 | Image effects | Stroke, shadow, glow, filter effects, border radius, background removal |
 | Shapes | Rectangle and ellipse primitives with stroke/shadow/glow support |
 | Export | PNG, JPEG, WebP, file output, base64, data URLs |
-| Serialization | `to_json()` / `from_json()` for built-in layer types |
+| Serialization | `to_json()` / `from_json()` for built-in layer types and named custom layers |
 
 ## Real Example Scripts
 
@@ -320,7 +320,7 @@ See the shipped examples in [`examples/README.md`](examples/README.md):
 - `weight` and `bold=True` are mutually exclusive on text layers and `TextPart`
 - `auto_scale=True` requires `max_width`
 - `position` percentage values must be strings like `"50%"`
-- `canvas.custom(fn)` runs during render order and cannot be serialized to JSON
+- `canvas.custom(fn)` without a `name` runs during render order but cannot be serialized to JSON; pass `name=` and register the function with `Canvas.register_layer_fn()` to enable serialization
 
 ## Development
 

{quickthumb-0.3.1 → quickthumb-0.4.0}/README.md

@@ -213,7 +213,7 @@ serialized = canvas.to_json()
 Notes:
 
 - JSON uses top-level `width`, `height`, and `layers`
-- Custom layers added with `canvas.custom(fn)` are not JSON-serializable
+- Named custom layers added with `canvas.custom(fn, name="...", kwargs={...})` are JSON-serializable via the registry; unnamed custom layers are not
 - Enum-like values such as `blend_mode`, `fit`, and `align` can be passed as strings
 
 ## AI-Friendly Workflows
@@ -274,7 +274,7 @@ os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
 | Image effects | Stroke, shadow, glow, filter effects, border radius, background removal |
 | Shapes | Rectangle and ellipse primitives with stroke/shadow/glow support |
 | Export | PNG, JPEG, WebP, file output, base64, data URLs |
-| Serialization | `to_json()` / `from_json()` for built-in layer types |
+| Serialization | `to_json()` / `from_json()` for built-in layer types and named custom layers |
 
 ## Real Example Scripts
 
@@ -289,7 +289,7 @@ See the shipped examples in [`examples/README.md`](examples/README.md):
 - `weight` and `bold=True` are mutually exclusive on text layers and `TextPart`
 - `auto_scale=True` requires `max_width`
 - `position` percentage values must be strings like `"50%"`
-- `canvas.custom(fn)` runs during render order and cannot be serialized to JSON
+- `canvas.custom(fn)` without a `name` runs during render order but cannot be serialized to JSON; pass `name=` and register the function with `Canvas.register_layer_fn()` to enable serialization
 
 ## Development
 

{quickthumb-0.3.1 → quickthumb-0.4.0}/examples/shorts_cover_agent.json

@@ -80,10 +80,11 @@
       "font": "Roboto",
       "size": 36,
       "color": "#FFFFFF",
-      "position": ["23.4%", "10.4%"],
-      "align": "center",
+      "position": ["23.4%", "10.9%"],
+      "align": ["center", "middle"],
       "weight": 900,
       "letter_spacing": 2,
+      "rotation": -3,
       "effects": [
         {
           "type": "shadow",

{quickthumb-0.3.1 → quickthumb-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickthumb"
-version = "0.3.1"
+version = "0.4.0"
 description = "Programmatic thumbnail and social image generation with layered Python and JSON APIs"
 authors = [{name = "Seonu Jang"}]
 license = {text = "MIT"}

{quickthumb-0.3.1 → quickthumb-0.4.0}/quickthumb/canvas.py

@@ -4,7 +4,7 @@ import math
 import os
 import warnings
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from io import BytesIO
 from typing import Literal, TypedDict, cast
 from urllib.request import urlopen
@@ -20,7 +20,6 @@ from quickthumb.models import (
     BackgroundEffect,
     BackgroundLayer,
     BlendMode,
-    CanvasModel,
     Filter,
     FitMode,
     Glow,
@@ -73,13 +72,25 @@ class TextPartMetadata(TypedDict):
 
 @dataclass
 class CustomLayer:
-    fn: Callable[[Image.Image], Image.Image | None]
+    fn: Callable[..., Image.Image | None]
+    name: str | None = None
+    kwargs: dict = field(default_factory=dict)
 
 
 RenderableLayer = LayerType | CustomLayer
 
 
 class Canvas:
+    _custom_layer_registry: dict[str, Callable[..., Image.Image | None]] = {}
+
+    @classmethod
+    def register_layer_fn(cls, name: str, fn: Callable[..., Image.Image | None]) -> None:
+        cls._custom_layer_registry[name] = fn
+
+    @classmethod
+    def unregister_layer_fn(cls, name: str) -> None:
+        cls._custom_layer_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")
@@ -260,12 +271,17 @@ class Canvas:
         self._layers.append(layer)
         return self
 
-    def custom(self, fn: Callable[[Image.Image], Image.Image | None]) -> Self:
+    def custom(
+        self,
+        fn: Callable[..., Image.Image | None],
+        name: str | None = None,
+        kwargs: dict | None = None,
+    ) -> Self:
         """Add a custom callback layer that can draw directly onto the canvas image."""
         if not callable(fn):
             raise ValidationError("fn must be callable")
 
-        self._layers.append(CustomLayer(fn=fn))
+        self._layers.append(CustomLayer(fn=fn, name=name, kwargs=kwargs or {}))
         return self
 
     def render(
@@ -279,21 +295,57 @@ class Canvas:
         self._save_to_file(image, output_path, quality, format=format)
 
     def to_json(self) -> str:
-        if any(isinstance(layer, CustomLayer) for layer in self._layers):
-            raise ValidationError("Custom layers cannot be serialized to JSON")
+        import json as _json
 
-        return CanvasModel(
-            width=self.width, height=self.height, layers=cast(list[LayerType], self._layers)
-        ).model_dump_json()
+        layers_json = []
+        for layer in self._layers:
+            if isinstance(layer, CustomLayer):
+                if layer.name is None:
+                    raise ValidationError("Custom layers cannot be serialized to JSON")
+                try:
+                    _json.dumps(layer.kwargs)
+                except (TypeError, ValueError) as e:
+                    raise ValidationError(
+                        f"Custom layer '{layer.name}' has kwargs that are not JSON-serializable:"
+                        f" {e}"
+                    ) from e
+                layers_json.append({"type": "custom", "name": layer.name, "kwargs": layer.kwargs})
+            else:
+                layers_json.append(_json.loads(layer.model_dump_json()))
+
+        return _json.dumps({"width": self.width, "height": self.height, "layers": layers_json})
 
     @classmethod
     def from_json(cls, data: str) -> Self:
-        canvas_model = CanvasModel.model_validate_json(data)
-        return cls(
-            width=canvas_model.width,
-            height=canvas_model.height,
-            layers=cast(list[RenderableLayer], canvas_model.layers),
-        )
+        import json as _json
+
+        from pydantic import TypeAdapter
+
+        from quickthumb.models import CanvasModel, LayerType
+
+        raw = _json.loads(data)
+        layers_raw = raw.get("layers", [])
+
+        if not isinstance(layers_raw, list):
+            CanvasModel.model_validate_json(data)  # raises ValidationError with good message
+
+        layer_adapter: TypeAdapter[LayerType] = TypeAdapter(LayerType)
+        renderable_layers: list[RenderableLayer] = []
+        for layer_dict in layers_raw:
+            if isinstance(layer_dict, dict) and layer_dict.get("type") == "custom":
+                name = layer_dict.get("name")
+                fn = cls._custom_layer_registry.get(name)
+                if fn is None:
+                    raise ValidationError(
+                        f"Custom layer '{name}' is not registered. "
+                        f"Call Canvas.register_layer_fn('{name}', fn) before deserializing."
+                    )
+                kwargs = layer_dict.get("kwargs") or {}
+                renderable_layers.append(CustomLayer(fn=fn, name=name, kwargs=kwargs))
+            else:
+                renderable_layers.append(layer_adapter.validate_python(layer_dict))
+
+        return cls(width=raw["width"], height=raw["height"], layers=renderable_layers)
 
     def to_base64(self, format: FileFormat = "PNG", quality: int | None = None) -> str:
         import base64
@@ -345,7 +397,7 @@ class Canvas:
 
     def _render_custom_layer(self, image: Image.Image, layer: CustomLayer):
         try:
-            result = layer.fn(image)
+            result = layer.fn(image, **layer.kwargs)
         except Exception as e:
             raise RenderingError(f"Custom layer callback failed: {e}") from e
 
@@ -593,21 +645,28 @@ class Canvas:
 
         fill_color = self._parse_color(layer.color)
 
-        # Draw shape on a temp image (shape-sized) so rotation/opacity work cleanly
-        shape_img = Image.new("RGBA", (layer.width, layer.height), (0, 0, 0, 0))
-        draw = ImageDraw.Draw(shape_img)
-        bbox = [0, 0, layer.width - 1, layer.height - 1]
+        # Draw at 4x and keep at 4x through rotation so both curved edges and
+        # rotation edges are anti-aliased when downscaled with LANCZOS.
+        scale = 4
+        shape_w, shape_h = layer.width * scale, layer.height * scale
+        shape_big = Image.new("RGBA", (shape_w, shape_h), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(shape_big)
+        bbox = [0, 0, shape_w - 1, shape_h - 1]
 
         if layer.shape == "rectangle":
-            draw.rounded_rectangle(bbox, radius=layer.border_radius, fill=fill_color)
+            draw.rounded_rectangle(bbox, radius=layer.border_radius * scale, fill=fill_color)
         else:  # ellipse
             draw.ellipse(bbox, fill=fill_color)
 
         if layer.rotation != 0:
-            shape_img = shape_img.rotate(
+            shape_big = shape_big.rotate(
                 -layer.rotation, expand=True, resample=Image.Resampling.BICUBIC
             )
 
+        final_w = round(shape_big.width / scale)
+        final_h = round(shape_big.height / scale)
+        shape_img = shape_big.resize((final_w, final_h), Image.Resampling.LANCZOS)
+
         if layer.opacity < 1.0:
             shape_img = self._apply_opacity(shape_img, layer.opacity)
 
@@ -646,7 +705,13 @@ class Canvas:
             img = self._apply_border_radius(img, layer.border_radius)
 
         if layer.rotation != 0:
-            img = img.rotate(-layer.rotation, expand=True, resample=Image.Resampling.BICUBIC)
+            scale = 4
+            large = img.resize((img.width * scale, img.height * scale), Image.Resampling.LANCZOS)
+            large = large.rotate(-layer.rotation, expand=True, resample=Image.Resampling.BICUBIC)
+            img = large.resize(
+                (round(large.width / scale), round(large.height / scale)),
+                Image.Resampling.LANCZOS,
+            )
 
         if layer.opacity < 1.0:
             img = self._apply_opacity(img, layer.opacity)
@@ -775,12 +840,18 @@ class Canvas:
             canvas.alpha_composite(patch, (dst_x, dst_y))
 
     def _apply_border_radius(self, img: Image.Image, radius: int) -> Image.Image:
-        """Clip image to a rounded rectangle mask."""
+        """Clip image to a rounded rectangle mask with anti-aliased corners via supersampling."""
         w, h = img.size
-        mask = Image.new("L", (w, h), 0)
-        draw = ImageDraw.Draw(mask)
-        draw.rounded_rectangle([0, 0, w - 1, h - 1], radius=radius, fill=255)
+        scale = 4
+        mask_big = Image.new("L", (w * scale, h * scale), 0)
+        draw = ImageDraw.Draw(mask_big)
+        draw.rounded_rectangle(
+            [0, 0, w * scale - 1, h * scale - 1], radius=radius * scale, fill=255
+        )
+        mask = mask_big.resize((w, h), Image.Resampling.LANCZOS)
         result = img.copy()
+        if result.mode != "RGBA":
+            result = result.convert("RGBA")
         result.putalpha(mask)
         return result
 
@@ -2039,23 +2110,24 @@ class Canvas:
         bg_width = content_width + pad_left + pad_right
         bg_height = content_height + pad_top + pad_bottom
 
-        # Create background layer and apply color with opacity
-        bg_layer = Image.new("RGBA", (bg_width, bg_height), (0, 0, 0, 0))
-        bg_draw = ImageDraw.Draw(bg_layer)
         bg_color = self._apply_opacity_to_color(
             self._parse_color(background.color), background.opacity
         )
 
-        # Draw background shape (rounded rectangle or normal rectangle)
-        # Use (bg_width - 1, bg_height - 1) so arcs are not clipped at image boundary
+        # Draw background shape; supersample rounded corners for anti-aliased edges.
         if background.border_radius > 0:
-            self._draw_rounded_rectangle(
-                bg_draw,
-                [(0, 0), (bg_width - 1, bg_height - 1)],
-                background.border_radius,
+            scale = 4
+            bg_big = Image.new("RGBA", (bg_width * scale, bg_height * scale), (0, 0, 0, 0))
+            bg_draw_big = ImageDraw.Draw(bg_big)
+            bg_draw_big.rounded_rectangle(
+                [0, 0, bg_width * scale - 1, bg_height * scale - 1],
+                radius=background.border_radius * scale,
                 fill=bg_color,
             )
+            bg_layer = bg_big.resize((bg_width, bg_height), Image.Resampling.LANCZOS)
         else:
+            bg_layer = Image.new("RGBA", (bg_width, bg_height), (0, 0, 0, 0))
+            bg_draw = ImageDraw.Draw(bg_layer)
             bg_draw.rectangle([(0, 0), (bg_width - 1, bg_height - 1)], fill=bg_color)
 
         paste_x = content_left - pad_left
@@ -2086,18 +2158,6 @@ class Canvas:
         else:  # len(padding) == 4
             return cast(tuple[int, int, int, int], padding)
 
-    def _draw_rounded_rectangle(
-        self,
-        draw: ImageDraw.ImageDraw,
-        coords: list[tuple[int, int]],
-        radius: int,
-        fill: tuple[int, ...] | None = None,
-    ):
-        """Draw a rounded rectangle on the given draw context."""
-        x0, y0 = coords[0]
-        x1, y1 = coords[1]
-        draw.rounded_rectangle([x0, y0, x1, y1], radius=radius, fill=fill)
-
     def _load_font(self, layer: TextLayer) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
         return self._load_font_variant(
             layer.font,