decksmith 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

decksmith/card_builder.py

@@ -4,8 +4,12 @@ which is used to create card images based on a JSON specification.
 """
 
 import operator
+from pathlib import Path
+from typing import Dict, Any, Tuple, List
+
 import pandas as pd
 from PIL import Image, ImageDraw, ImageFont
+
 from .utils import get_wrapped_text, apply_anchor
 from .validate import validate_card, transform_card
 
@@ -14,29 +18,30 @@ class CardBuilder:
     """
     A class to build a card image based on a JSON specification.
     Attributes:
-        spec (dict): The JSON specification for the card.
-        card (Image): The PIL Image object representing the card.
-        draw (ImageDraw): The PIL ImageDraw object for drawing on the card.
+        spec (Dict[str, Any]): The JSON specification for the card.
+        card (Image.Image): The PIL Image object representing the card.
+        draw (ImageDraw.ImageDraw): The PIL ImageDraw object for drawing on the card.
+        element_positions (Dict[str, Tuple[int, int, int, int]]):
+            A dictionary mapping element IDs to their bounding boxes.
     """
 
-    def __init__(self, spec: dict):
+    def __init__(self, spec: Dict[str, Any]):
         """
-        Initializes the CardBuilder with a JSON specification file.
+        Initializes the CardBuilder with a JSON specification.
         Args:
-            spec_path (str): Path to the JSON specification file.
+            spec (Dict[str, Any]): The JSON specification for the card.
         """
         self.spec = spec
         width = self.spec.get("width", 250)
         height = self.spec.get("height", 350)
         bg_color = tuple(self.spec.get("background_color", (255, 255, 255, 0)))
-        self.card = Image.new("RGBA", (width, height), bg_color)
-        self.draw = ImageDraw.Draw(self.card, "RGBA")
-        self.element_positions = {}
-        # Store position if id is provided
+        self.card: Image.Image = Image.new("RGBA", (width, height), bg_color)
+        self.draw: ImageDraw.ImageDraw = ImageDraw.Draw(self.card, "RGBA")
+        self.element_positions: Dict[str, Tuple[int, int, int, int]] = {}
         if "id" in spec:
             self.element_positions[self.spec["id"]] = (0, 0, width, height)
 
-    def _calculate_absolute_position(self, element: dict) -> tuple:
+    def _calculate_absolute_position(self, element: Dict[str, Any]) -> Tuple[int, int]:
         """
         Calculates the absolute position of an element,
         resolving relative positioning.
@@ -62,13 +67,11 @@ class CardBuilder:
         offset = tuple(element.get("position", [0, 0]))
         return tuple(map(operator.add, anchor_point, offset))
 
-    def _draw_text(self, element: dict):
+    def _draw_text(self, element: Dict[str, Any]):
         """
         Draws text on the card based on the provided element dictionary.
         Args:
-            element (dict): A dictionary containing text properties such as
-                            'text', 'font_path', 'font_size', 'position',
-                            'color', and 'width'.
+            element (Dict[str, Any]): A dictionary containing text properties.
         """
         assert element.pop("type") == "text", "Element type must be 'text'"
 
@@ -160,12 +163,100 @@ class CardBuilder:
             )
             self.element_positions[element["id"]] = bbox
 
-    def _draw_image(self, element):
+    def _apply_image_filters(
+        self, img: Image.Image, filters: Dict[str, Any]
+    ) -> Image.Image:
+        for filter_name, filter_value in filters.items():
+            filter_method_name = f"_filter_{filter_name}"
+            filter_method = getattr(self, filter_method_name, self._filter_unsupported)
+            img = filter_method(img, filter_value)
+        return img
+
+    def _filter_unsupported(self, img: Image.Image, _: Any) -> Image.Image:
+        return img
+
+    def _filter_crop(self, img: Image.Image, crop_values: List[int]) -> Image.Image:
+        return img.crop(crop_values)
+
+    def _filter_crop_top(self, img: Image.Image, value: int) -> Image.Image:
+        if value < 0:
+            img = img.convert("RGBA")
+            new_img = Image.new("RGBA", (img.width, img.height - value), (0, 0, 0, 0))
+            new_img.paste(img, (0, -value))
+            return new_img
+        return img.crop((0, value, img.width, img.height))
+
+    def _filter_crop_bottom(self, img: Image.Image, value: int) -> Image.Image:
+        if value < 0:
+            img = img.convert("RGBA")
+            new_img = Image.new("RGBA", (img.width, img.height - value), (0, 0, 0, 0))
+            new_img.paste(img, (0, 0))
+            return new_img
+        return img.crop((0, 0, img.width, img.height - value))
+
+    def _filter_crop_left(self, img: Image.Image, value: int) -> Image.Image:
+        if value < 0:
+            img = img.convert("RGBA")
+            new_img = Image.new("RGBA", (img.width - value, img.height), (0, 0, 0, 0))
+            new_img.paste(img, (-value, 0))
+            return new_img
+        return img.crop((value, 0, img.width, img.height))
+
+    def _filter_crop_right(self, img: Image.Image, value: int) -> Image.Image:
+        if value < 0:
+            img = img.convert("RGBA")
+            new_img = Image.new("RGBA", (img.width - value, img.height), (0, 0, 0, 0))
+            new_img.paste(img, (0, 0))
+            return new_img
+        return img.crop((0, 0, img.width - value, img.height))
+
+    def _filter_crop_box(self, img: Image.Image, box: List[int]) -> Image.Image:
+        img = img.convert("RGBA")
+        x, y, w, h = box
+        new_img = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+        src_x1 = max(0, x)
+        src_y1 = max(0, y)
+        src_x2 = min(img.width, x + w)
+        src_y2 = min(img.height, y + h)
+        if src_x1 < src_x2 and src_y1 < src_y2:
+            src_w = src_x2 - src_x1
+            src_h = src_y2 - src_y1
+            src_img = img.crop((src_x1, src_y1, src_x1 + src_w, src_y1 + src_h))
+            dst_x = src_x1 - x
+            dst_y = src_y1 - y
+            new_img.paste(src_img, (dst_x, dst_y))
+        return new_img
+
+    def _filter_resize(self, img: Image.Image, size: Tuple[int, int]) -> Image.Image:
+        new_width, new_height = size
+        if new_width is None and new_height is None:
+            return img
+        if new_width is None or new_height is None:
+            original_width, original_height = img.size
+            aspect_ratio = original_width / float(original_height)
+            if new_width is None:
+                new_width = int(new_height * aspect_ratio)
+            else:
+                new_height = int(new_width / aspect_ratio)
+        return img.resize((new_width, new_height))
+
+    def _filter_rotate(self, img: Image.Image, angle: float) -> Image.Image:
+        return img.rotate(angle, expand=True)
+
+    def _filter_flip(self, img: Image.Image, direction: str) -> Image.Image:
+        if direction == "horizontal":
+            # pylint: disable=E1101
+            return img.transpose(Image.FLIP_LEFT_RIGHT)
+        if direction == "vertical":
+            # pylint: disable=E1101
+            return img.transpose(Image.FLIP_TOP_BOTTOM)
+        return img
+
+    def _draw_image(self, element: Dict[str, Any]):
         """
         Draws an image on the card based on the provided element dictionary.
         Args:
-            element (dict): A dictionary containing image properties such as
-                            'path', 'filters', and 'position'.
+            element (Dict[str, Any]): A dictionary containing image properties.
         """
         # Ensure the element type is 'image'
         assert element.pop("type") == "image", "Element type must be 'image'"
@@ -174,98 +265,7 @@ class CardBuilder:
         path = element["path"]
         img = Image.open(path)
 
-        # Apply filters if specified
-        if "filters" in element:
-            for filter_name, filter_value in element["filters"].items():
-                if filter_name == "crop_top":
-                    if filter_value < 0:
-                        img = img.convert("RGBA")
-                        new_img = Image.new(
-                            "RGBA",
-                            (img.width, img.height - filter_value),
-                            (0, 0, 0, 0),
-                        )
-                        new_img.paste(img, (0, -filter_value))
-                        img = new_img
-                    else:
-                        img = img.crop((0, filter_value, img.width, img.height))
-                elif filter_name == "crop_bottom":
-                    if filter_value < 0:
-                        img = img.convert("RGBA")
-                        new_img = Image.new(
-                            "RGBA",
-                            (img.width, img.height - filter_value),
-                            (0, 0, 0, 0),
-                        )
-                        new_img.paste(img, (0, 0))
-                        img = new_img
-                    else:
-                        img = img.crop((0, 0, img.width, img.height - filter_value))
-                elif filter_name == "crop_left":
-                    if filter_value < 0:
-                        img = img.convert("RGBA")
-                        new_img = Image.new(
-                            "RGBA",
-                            (img.width - filter_value, img.height),
-                            (0, 0, 0, 0),
-                        )
-                        new_img.paste(img, (-filter_value, 0))
-                        img = new_img
-                    else:
-                        img = img.crop((filter_value, 0, img.width, img.height))
-                elif filter_name == "crop_right":
-                    if filter_value < 0:
-                        img = img.convert("RGBA")
-                        new_img = Image.new(
-                            "RGBA",
-                            (img.width - filter_value, img.height),
-                            (0, 0, 0, 0),
-                        )
-                        new_img.paste(img, (0, 0))
-                        img = new_img
-                    else:
-                        img = img.crop((0, 0, img.width - filter_value, img.height))
-                elif filter_name == "crop_box":
-                    img = img.convert("RGBA")
-                    x, y, w, h = filter_value
-                    new_img = Image.new("RGBA", (w, h), (0, 0, 0, 0))
-                    src_x1 = max(0, x)
-                    src_y1 = max(0, y)
-                    src_x2 = min(img.width, x + w)
-                    src_y2 = min(img.height, y + h)
-                    if src_x1 < src_x2 and src_y1 < src_y2:
-                        src_w = src_x2 - src_x1
-                        src_h = src_y2 - src_y1
-                        src_img = img.crop(
-                            (src_x1, src_y1, src_x1 + src_w, src_y1 + src_h)
-                        )
-                        dst_x = src_x1 - x
-                        dst_y = src_y1 - y
-                        new_img.paste(src_img, (dst_x, dst_y))
-                    img = new_img
-                elif filter_name == "resize":
-                    new_width, new_height = filter_value
-                    if new_width is None and new_height is None:
-                        continue
-                    if new_width is None or new_height is None:
-                        original_width, original_height = img.size
-                        aspect_ratio = original_width / float(original_height)
-                        if new_width is None:
-                            new_width = int(new_height * aspect_ratio)
-                        else:  # new_height is None
-                            new_height = int(new_width / aspect_ratio)
-                    img = img.resize((new_width, new_height))
-                elif filter_name == "rotate":
-                    img = img.rotate(filter_value, expand=True)
-                elif filter_name == "flip":
-                    if filter_value == "horizontal":
-                        # pylint: disable=E1101
-                        img = img.transpose(Image.FLIP_LEFT_RIGHT)
-                    elif filter_value == "vertical":
-                        # pylint: disable=E1101
-                        img = img.transpose(Image.FLIP_TOP_BOTTOM)
-                else:
-                    raise ValueError(f"Unknown filter: {filter_name}")
+        img = self._apply_image_filters(img, element.get("filters", {}))
 
         # Convert position to a tuple
         position = tuple(element.get("position", [0, 0]))
@@ -291,15 +291,11 @@ class CardBuilder:
                 position[1] + img.height,
             )
 
-    def _draw_shape_circle(self, element):
+    def _draw_shape_circle(self, element: Dict[str, Any]):
         """
         Draws a circle on the card based on the provided element dictionary.
         Args:
-            element (dict): A dictionary containing circle properties such as
-                            'position', 'radius', 'color', 'outline', 'width', and 'anchor'.
-
-        Raises:
-            AssertionError: If the element type is not 'circle'.
+            element (Dict[str, Any]): A dictionary containing circle properties.
         """
         assert element.pop("type") == "circle", "Element type must be 'circle'"
 
@@ -344,16 +340,11 @@ class CardBuilder:
                 absolute_pos[1] + size[1],
             )
 
-    def _draw_shape_ellipse(self, element):
+    def _draw_shape_ellipse(self, element: Dict[str, Any]):
         """
         Draws an ellipse on the card based on the provided element dictionary.
-
         Args:
-            element (dict): A dictionary containing ellipse properties such as
-                            'position', 'size', 'color', 'outline', 'width', and 'anchor'.
-
-        Raises:
-            AssertionError: If the element type is not 'ellipse'.
+            element (Dict[str, Any]): A dictionary containing ellipse properties.
         """
         assert element.pop("type") == "ellipse", "Element type must be 'ellipse'"
 
@@ -398,14 +389,11 @@ class CardBuilder:
         if "id" in element:
             self.element_positions[element["id"]] = bounding_box
 
-    def _draw_shape_polygon(self, element):
+    def _draw_shape_polygon(self, element: Dict[str, Any]):
         """
         Draws a polygon on the card based on the provided element dictionary.
         Args:
-            element (dict): A dictionary containing polygon properties such as
-                            'position', 'points', 'color', 'outline', 'width', and 'anchor'.
-        Raises:
-            AssertionError: If the element type is not 'polygon'.
+            element (Dict[str, Any]): A dictionary containing polygon properties.
         """
         assert element.pop("type") == "polygon", "Element type must be 'polygon'"
 
@@ -462,17 +450,11 @@ class CardBuilder:
                 max_y + offset[1],
             )
 
-    def _draw_shape_regular_polygon(self, element):
+    def _draw_shape_regular_polygon(self, element: Dict[str, Any]):
         """
         Draws a regular polygon on the card based on the provided element dictionary.
-
         Args:
-            element (dict): A dictionary containing regular polygon properties such as
-                            'position', 'radius', 'sides', 'rotation', 'color', 'outline',
-                            'width', and 'anchor'.
-
-        Raises:
-            AssertionError: If the element type is not 'regular-polygon'.
+            element (Dict[str, Any]): A dictionary containing regular polygon properties.
         """
         assert (
             element.pop("type") == "regular-polygon"
@@ -520,16 +502,11 @@ class CardBuilder:
                 absolute_pos[1] + size[1],
             )
 
-    def _draw_shape_rectangle(self, element):
+    def _draw_shape_rectangle(self, element: Dict[str, Any]):
         """
         Draws a rectangle on the card based on the provided element dictionary.
-
         Args:
-            element (dict): A dictionary containing rectangle properties such as
-                            'size', 'color', 'outline_color', 'width', 'radius',
-                            'corners', 'position', and 'anchor'.
-        Raises:
-            AssertionError: If the element type is not 'rectangle'.
+            element (Dict[str, Any]): A dictionary containing rectangle properties.
         """
         assert element.pop("type") == "rectangle", "Element type must be 'rectangle'"
 
@@ -582,30 +559,29 @@ class CardBuilder:
         if "id" in element:
             self.element_positions[element["id"]] = bounding_box
 
-    def build(self, output_path):
+    def build(self, output_path: Path):
         """
         Builds the card image by drawing all elements specified in the JSON.
         Args:
-            output_path (str): The path where the card image will be saved.
+            output_path (Path): The path where the card image will be saved.
         """
         self.spec = transform_card(self.spec)
         validate_card(self.spec)
 
-        for el in self.spec.get("elements", []):
-            el_type = el.get("type")
-            if el_type == "text":
-                self._draw_text(el)
-            elif el_type == "image":
-                self._draw_image(el)
-            elif el_type == "circle":
-                self._draw_shape_circle(el)
-            elif el_type == "ellipse":
-                self._draw_shape_ellipse(el)
-            elif el_type == "polygon":
-                self._draw_shape_polygon(el)
-            elif el_type == "regular-polygon":
-                self._draw_shape_regular_polygon(el)
-            elif el_type == "rectangle":
-                self._draw_shape_rectangle(el)
+        draw_methods = {
+            "text": self._draw_text,
+            "image": self._draw_image,
+            "circle": self._draw_shape_circle,
+            "ellipse": self._draw_shape_ellipse,
+            "polygon": self._draw_shape_polygon,
+            "regular-polygon": self._draw_shape_regular_polygon,
+            "rectangle": self._draw_shape_rectangle,
+        }
+
+        for element in self.spec.get("elements", []):
+            element_type = element.get("type")
+            if draw_method := draw_methods.get(element_type):
+                draw_method(element)
+
         self.card.save(output_path)
         print(f"(✔) Card saved to {output_path}")

decksmith/deck_builder.py

@@ -7,8 +7,10 @@ and a CSV file.
 import concurrent.futures
 import json
 from pathlib import Path
+from typing import Union, List, Dict, Any
 
 import pandas as pd
+from pandas import Series
 
 from .card_builder import CardBuilder
 
@@ -17,23 +19,23 @@ class DeckBuilder:
     """
     A class to build a deck of cards based on a JSON specification and a CSV file.
     Attributes:
-        spec_path (str): Path to the JSON specification file.
-        csv_path (str): Path to the CSV file containing card data.
+        spec_path (Path): Path to the JSON specification file.
+        csv_path (Union[Path, None]): Path to the CSV file containing card data.
         cards (list): List of CardBuilder instances for each card in the deck.
     """
 
-    def __init__(self, spec_path: str, csv_path: str = None):
+    def __init__(self, spec_path: Path, csv_path: Union[Path, None] = None):
         """
         Initializes the DeckBuilder with a JSON specification file and a CSV file.
         Args:
-            spec_path (str): Path to the JSON specification file.
-            csv_path (str): Path to the CSV file containing card data.
+            spec_path (Path): Path to the JSON specification file.
+            csv_path (Union[Path, None]): Path to the CSV file containing card data.
         """
         self.spec_path = spec_path
         self.csv_path = csv_path
-        self.cards = []
+        self.cards: List[CardBuilder] = []
 
-    def _replace_macros(self, row: dict) -> dict:
+    def _replace_macros(self, row: Dict[str, Any]) -> Dict[str, Any]:
         """
         Replaces %colname% macros in the card specification with values from the row.
         Works recursively for nested structures.
@@ -43,7 +45,7 @@ class DeckBuilder:
             dict: The updated card specification with macros replaced.
         """
 
-        def replace_in_value(value):
+        def replace_in_value(value: Any) -> Any:
             if isinstance(value, str):
                 stripped_value = value.strip()
                 # First, check for an exact macro match to preserve type
@@ -68,24 +70,29 @@ class DeckBuilder:
             spec = json.load(f)
         return replace_in_value(spec)
 
-    def build_deck(self, output_path: str):
+    def build_deck(self, output_path: Path):
         """
         Builds the deck of cards by reading the CSV file and creating CardBuilder instances.
         """
-        if not self.csv_path:
+        if not self.csv_path or not self.csv_path.exists():
             with open(self.spec_path, "r", encoding="utf-8") as f:
                 spec = json.load(f)
             card_builder = CardBuilder(spec)
-            card_builder.build(Path(output_path) / "card_1.png")
+            card_builder.build(output_path / "card_1.png")
             return
 
         df = pd.read_csv(self.csv_path, encoding="utf-8", sep=";", header=0)
 
-        def build_card(row_tuple):
+        def build_card(row_tuple: tuple[int, Series]):
+            """
+            Builds a single card from a row of the CSV file.
+            Args:
+                row_tuple (tuple[int, Series]): A tuple containing the row index and the row data.
+            """
             idx, row = row_tuple
             spec = self._replace_macros(row.to_dict())
             card_builder = CardBuilder(spec)
-            card_builder.build(Path(output_path) / f"card_{idx + 1}.png")
+            card_builder.build(output_path / f"card_{idx + 1}.png")
 
         with concurrent.futures.ThreadPoolExecutor() as executor:
             list(executor.map(build_card, df.iterrows()))

decksmith/export.py

@@ -14,29 +14,19 @@ from reportlab.pdfgen import canvas
 class PdfExporter:
     """
     A class to export images from a folder to a PDF file.
-
-    Attributes:
-        image_folder (Path): The folder containing the images to be exported.
-        image_paths (List[str]): A list of paths to the images to be exported.
-        output_path (str): The path to the output PDF file.
-        page_size (Tuple[float, float]): The size of the PDF pages.
-        image_width (float): The width of the images in mm.
-        image_height (float): The height of the images in mm.
-        gap (float): The gap between images in pixels.
-        margins (Tuple[float, float]): The horizontal and vertical margins of the pages.
     """
 
     def __init__(
         self,
-        image_folder: str,
-        output_path: str,
+        image_folder: Path,
+        output_path: Path,
         page_size_str: str = "A4",
         image_width: float = 63,
         image_height: float = 88,
         gap: float = 0,
         margins: Tuple[float, float] = (2, 2),
     ):
-        self.image_folder = Path(image_folder)
+        self.image_folder = image_folder
         self.image_paths = self._get_image_paths()
         self.output_path = output_path
         self.page_size = self._get_page_size(page_size_str)
@@ -44,9 +34,9 @@ class PdfExporter:
         self.image_height = image_height * mm
         self.gap = gap * mm
         self.margins = (margins[0] * mm, margins[1] * mm)
-        self.pdf = canvas.Canvas(self.output_path, pagesize=self.page_size)
+        self.pdf = canvas.Canvas(str(self.output_path), pagesize=self.page_size)
 
-    def _get_image_paths(self) -> List[str]:
+    def _get_image_paths(self) -> List[Path]:
         """
         Scans the image folder and returns a list of image paths.
 
@@ -54,11 +44,13 @@ class PdfExporter:
             List[str]: A sorted list of image paths.
         """
         image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
-        image_paths = []
-        for file_path in self.image_folder.iterdir():
-            if file_path.suffix.lower() in image_extensions:
-                image_paths.append(str(file_path))
-        return sorted(image_paths)
+        return sorted(
+            [
+                p
+                for p in self.image_folder.iterdir()
+                if p.suffix.lower() in image_extensions
+            ]
+        )
 
     def _get_page_size(self, page_size_str: str) -> Tuple[float, float]:
         """
@@ -118,8 +110,7 @@ class PdfExporter:
             cols, rows, rotated = self._calculate_layout(page_width, page_height)
 
             if cols == 0 or rows == 0:
-                logging.error("The images are too large to fit on the page.")
-                return
+                raise ValueError("The images are too large to fit on the page.")
 
             img_w, img_h = (
                 (self.image_width, self.image_height)
@@ -134,7 +125,7 @@ class PdfExporter:
 
             images_on_page = 0
             for image_path in self.image_paths:
-                if images_on_page == cols * rows:
+                if images_on_page > 0 and images_on_page % (cols * rows) == 0:
                     self.pdf.showPage()
                     images_on_page = 0
 
@@ -146,7 +137,7 @@ class PdfExporter:
 
                 if not rotated:
                     self.pdf.drawImage(
-                        image_path,
+                        str(image_path),
                         x,
                         y,
                         width=img_w,
@@ -160,7 +151,7 @@ class PdfExporter:
                     self.pdf.translate(center_x, center_y)
                     self.pdf.rotate(90)
                     self.pdf.drawImage(
-                        image_path,
+                        str(image_path),
                         -img_h / 2,
                         -img_w / 2,
                         width=img_h,

decksmith/main.py

@@ -2,10 +2,9 @@
 This module provides a command-line tool for building decks of cards.
 """
 
-import os
 import shutil
 from importlib import resources
-
+from pathlib import Path
 import traceback
 
 import click
@@ -21,7 +20,7 @@ def cli():
 @cli.command()
 def init():
     """Initializes a new project by creating deck.json and deck.csv."""
-    if os.path.exists("deck.json") or os.path.exists("deck.csv"):
+    if Path("deck.json").exists() or Path("deck.csv").exists():
         click.echo("(!) Project already initialized.")
         return
 
@@ -33,57 +32,90 @@ def init():
     click.echo("(✔) Initialized new project from templates.")
 
 
-@cli.command()
+@cli.command(context_settings={"show_default": True})
 @click.option("--output", default="output", help="The output directory for the deck.")
 @click.option(
     "--spec", default="deck.json", help="The path to the deck specification file."
 )
 @click.option("--data", default="deck.csv", help="The path to the data file.")
-def build(output, spec, data):
+@click.pass_context
+def build(ctx, output, spec, data):
     """Builds the deck of cards."""
-    if not os.path.exists(output):
-        os.makedirs(output)
+    output_path = Path(output)
+    output_path.mkdir(exist_ok=True)
+
+    click.echo(f"(i) Building deck in {output_path}...")
 
-    click.echo(f"(i) Building deck in {output}...")
     try:
-        builder = DeckBuilder(spec, data)
-        builder.build_deck(output)
+        spec_path = Path(spec)
+        if not spec_path.exists():
+            raise FileNotFoundError(f"Spec file not found: {spec_path}")
+
+        csv_path = Path(data)
+        if not csv_path.exists():
+            source = ctx.get_parameter_source("data")
+            if source.name == "DEFAULT":
+                click.echo(
+                    f"(i) Building a single card deck because '{csv_path}' was not found"
+                )
+                csv_path = None
+            else:
+                raise FileNotFoundError(f"Data file not found: {csv_path}")
+
+        builder = DeckBuilder(spec_path, csv_path)
+        builder.build_deck(output_path)
+    except FileNotFoundError as exc:
+        click.echo(f"(x) {exc}")
+        ctx.exit(1)
     # pylint: disable=W0718
     except Exception as exc:
-        with open("log.txt", "w", encoding="utf-8") as log:
+        with open("log.txt", "a", encoding="utf-8") as log:
             log.write(traceback.format_exc())
         # print(f"{traceback.format_exc()}", end="\n")
         print(f"(x) Error building deck '{data}' from spec '{spec}':")
         print(" " * 4 + f"{exc}")
-        return
+        ctx.exit(1)
 
     click.echo("(✔) Deck built successfully.")
 
 
-@cli.command()
+@cli.command(context_settings={"show_default": True})
 @click.argument("image_folder")
-@click.option("--output", default="output.pdf", help="The output PDF file path.")
-@click.option("--page-size", default="A4", help="The page size (e.g., A4).")
 @click.option(
-    "--width", type=float, default=63.5, help="The width of the images in mm."
+    "--output", default="output.pdf", help="The path for the output PDF file."
+)
+@click.option(
+    "--page-size", default="A4", help="The page size for the PDF (e.g., A4, Letter)."
 )
 @click.option(
-    "--height", type=float, default=88.9, help="The height of the images in mm."
+    "--width", type=float, default=63.5, help="The width for each image in millimeters."
+)
+@click.option(
+    "--height",
+    type=float,
+    default=88.9,
+    help="The height for each image in millimeters.",
+)
+@click.option(
+    "--gap", type=float, default=0, help="The gap between images in millimeters."
 )
-@click.option("--gap", type=float, default=0, help="The gap between images in pixels.")
 @click.option(
     "--margins",
     type=float,
     nargs=2,
     default=[2, 2],
-    help="The horizontal and vertical margins in mm.",
+    help="The horizontal and vertical page margins in millimeters.",
 )
 def export(image_folder, output, page_size, width, height, gap, margins):
     """Exports images from a folder to a PDF file."""
     try:
+        image_folder_path = Path(image_folder)
+        if not image_folder_path.exists():
+            raise FileNotFoundError(f"Image folder not found: {image_folder_path}")
+
         exporter = PdfExporter(
-            image_folder=image_folder,
-            output_path=output,
+            image_folder=image_folder_path,
+            output_path=Path(output),
             page_size_str=page_size,
             image_width=width,
             image_height=height,
@@ -92,9 +124,11 @@ def export(image_folder, output, page_size, width, height, gap, margins):
         )
         exporter.export()
         click.echo(f"(✔) Successfully exported PDF to {output}")
+    except FileNotFoundError as exc:
+        click.echo(f"(x) {exc}")
     # pylint: disable=W0718
     except Exception as exc:
-        with open("log.txt", "w", encoding="utf-8") as log:
+        with open("log.txt", "a", encoding="utf-8") as log:
             log.write(traceback.format_exc())
         print(f"(x) Error exporting images to '{output}':")
         print(" " * 4 + f"{exc}")

decksmith/utils.py

@@ -2,12 +2,15 @@
 This module provides utility functions for text wrapping and positioning.
 """
 
+from typing import Tuple
+
 from PIL import ImageFont
 
 
-def get_wrapped_text(text: str, font: ImageFont.ImageFont, line_length: int):
+def get_wrapped_text(text: str, font: ImageFont.ImageFont, line_length: int) -> str:
     """
-    Wraps text to fit within a specified line length using the given font.
+    Wraps text to fit within a specified line length using the given font,
+    preserving existing newlines.
     Args:
         text (str): The text to wrap.
         font (ImageFont.ImageFont): The font to use for measuring text length.
@@ -16,68 +19,51 @@ def get_wrapped_text(text: str, font: ImageFont.ImageFont, line_length: int):
     Returns:
         str: The wrapped text with newlines inserted where necessary.
     """
-    lines = [""]
-    for word in text.split():
-        line = f"{lines[-1]} {word}".strip()
-        if font.getlength(line) <= line_length:
-            lines[-1] = line
-        else:
-            lines.append(word)
-    return "\n".join(lines)
+    wrapped_lines = []
+    for line in text.split("\n"):
+        lines = [""]
+        for word in line.split():
+            line_to_check = f"{lines[-1]} {word}".strip()
+            if font.getlength(line_to_check) <= line_length:
+                lines[-1] = line_to_check
+            else:
+                lines.append(word)
+        wrapped_lines.extend(lines)
+    return "\n".join(wrapped_lines)
 
 
-def apply_anchor(size: tuple, anchor: str):
+def apply_anchor(size: Tuple[int, ...], anchor: str) -> Tuple[int, int]:
     """
     Applies an anchor to a size tuple to determine the position of an element.
     Args:
-        size (tuple): A tuple representing the size (width, height).
-        anchor (str): The anchor position, e.g., "center", "top-left",
-                      "top-right", "bottom-left", "bottom-right".
+        size (Tuple[int, ...]): A tuple representing the size (width, height)
+            or a bounding box (x1, y1, x2, y2).
+        anchor (str): The anchor position, e.g., "center", "top-left".
     Returns:
-        tuple: A tuple representing the position (x, y) based on the anchor.
+        Tuple[int, int]: A tuple representing the position (x, y) based on the anchor.
     """
     if len(size) == 2:
-        x, y = size
-        if anchor == "top-left":
-            return (0, 0)
-        if anchor == "top-center":
-            return (x // 2, 0)
-        if anchor == "top-right":
-            return (x, 0)
-        if anchor == "middle-left":
-            return (0, y // 2)
-        if anchor == "center":
-            return (x // 2, y // 2)
-        if anchor == "middle-right":
-            return (x, y // 2)
-        if anchor == "bottom-left":
-            return (0, y)
-        if anchor == "bottom-center":
-            return (x // 2, y)
-        if anchor == "bottom-right":
-            return (x, y)
-        raise ValueError(f"Unknown anchor: {anchor}")
-    if len(size) == 4:
-        x1, y1, x2, y2 = size
-        width = x2 - x1
-        height = y2 - y1
-        if anchor == "top-left":
-            return (x1, y1)
-        if anchor == "top-center":
-            return (x1 + width // 2, y1)
-        if anchor == "top-right":
-            return (x2, y1)
-        if anchor == "middle-left":
-            return (x1, y1 + height // 2)
-        if anchor == "center":
-            return (x1 + width // 2, y1 + height // 2)
-        if anchor == "middle-right":
-            return (x2, y1 + height // 2)
-        if anchor == "bottom-left":
-            return (x1, y2)
-        if anchor == "bottom-center":
-            return (x1 + width // 2, y2)
-        if anchor == "bottom-right":
-            return (x2, y2)
+        w, h = size
+        x, y = 0, 0
+    elif len(size) == 4:
+        x, y, x2, y2 = size
+        w, h = x2 - x, y2 - y
+    else:
+        raise ValueError("Size must be a tuple of 2 or 4 integers.")
+
+    anchor_points = {
+        "top-left": (x, y),
+        "top-center": (x + w // 2, y),
+        "top-right": (x + w, y),
+        "middle-left": (x, y + h // 2),
+        "center": (x + w // 2, y + h // 2),
+        "middle-right": (x + w, y + h // 2),
+        "bottom-left": (x, y + h),
+        "bottom-center": (x + w // 2, y + h),
+        "bottom-right": (x + w, y + h),
+    }
+
+    if anchor not in anchor_points:
         raise ValueError(f"Unknown anchor: {anchor}")
-    return None
+
+    return anchor_points[anchor]

decksmith/validate.py

@@ -1,11 +1,13 @@
 """
-Python module for validating a dictionar
+This module provides functions for validating and transforming card specifications.
 """
 
+from typing import Dict, Any
+
 import pandas as pd
 from jval import validate
 
-ELEMENT_SPEC = {
+ELEMENT_SPEC: Dict[str, Any] = {
     "?*id": "<?str>",
     "*type": "<?str>",
     "?*position": ["<?float>"],
@@ -13,7 +15,7 @@ ELEMENT_SPEC = {
     "?*anchor": "<?str>",
 }
 
-SPECS_FOR_TYPE = {
+SPECS_FOR_TYPE: Dict[str, Dict[str, Any]] = {
     "text": {
         "*text": "<?str>",
         "?*color": ["<?int>"],
@@ -75,7 +77,7 @@ SPECS_FOR_TYPE = {
     },
 }
 
-CARD_SPEC = {
+CARD_SPEC: Dict[str, Any] = {
     "?*id": "<?str>",
     "*width": "<?int>",
     "*height": "<?int>",
@@ -84,7 +86,7 @@ CARD_SPEC = {
 }
 
 
-def validate_element(element, element_type):
+def validate_element(element: Dict[str, Any], element_type: str):
     """
     Validates an element of a card against a spec, raising an exception
     if it does not meet the spec.
@@ -96,12 +98,12 @@ def validate_element(element, element_type):
     validate(element, spec)
 
 
-def validate_card(card):
+def validate_card(card: Dict[str, Any]):
     """
     Validates a card against a spec, raising an exception
     if it does not meet the spec.
     Args:
-        card (dict): The card.
+        card (Dict[str, Any]): The card.
     """
     # print(f"DEBUG:\n{card=}")
     validate(card, CARD_SPEC)
@@ -110,15 +112,15 @@ def validate_card(card):
         validate_element(element, element["type"])
 
 
-def transform_card(card):
+def transform_card(card: Dict[str, Any]) -> Dict[str, Any]:
     """
     Perform certain automatic type casts on the card and its
     elements. For example, cast the "text" property of elements
     of type "text" to str, to support painting numbers as text.
     Args:
-        card (dict): The card.
+        card (Dict[str, Any]): The card.
     Return:
-        dict: The transformed card with all automatic casts applied.
+        Dict[str, Any]: The transformed card with all automatic casts applied.
     """
     for element in card.get("elements", []):
         if element.get("type") == "text" and "text" in element:

{decksmith-0.1.9.dist-info → decksmith-0.1.11.dist-info}/METADATA

@@ -1,13 +1,15 @@
 Metadata-Version: 2.3
 Name: decksmith
-Version: 0.1.9
+Version: 0.1.11
 Summary: A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck.
 License: GPL-2.0-only
 Author: Julio Cabria
 Author-email: juliocabria@tutanota.com
-Requires-Python: >=3.13
+Requires-Python: >=3.11
 Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: dev
 Requires-Dist: click

decksmith-0.1.11.dist-info/RECORD

@@ -0,0 +1,13 @@
+decksmith/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+decksmith/card_builder.py,sha256=rDj2uFaA22XVXYInod4d9ljEk1OBeXh_ES0WdLcmrcs,23935
+decksmith/deck_builder.py,sha256=WoaY2A0RDrYNvWZtBckcsR5MKHOXdCpNHaI2J5JZlKU,3835
+decksmith/export.py,sha256=55TaK1fSL0EvtKCoAvUx-47ljNOL5zPeFJguDqL4BVU,5631
+decksmith/main.py,sha256=upBSH8yCOiwCPjW-zf9QpqPTO-RIIaAuEACkWhUTgEw,4542
+decksmith/templates/deck.csv,sha256=pNJebNxoDIfM8m0-aj05YrANHih1BTKOMry1kspIpPI,462
+decksmith/templates/deck.json,sha256=BTTnmaFP5AkbbC_B7uMF6R4bOM7JizW6EATcsjjJrT4,695
+decksmith/utils.py,sha256=vwRrzQEjpZq4x0GJLgJc7TqrC9LLJJqcHAsz1ar-vVs,2301
+decksmith/validate.py,sha256=zA3ygyzOpx3ai6AhkSw611Qik3syZvR5ZmI_w3Pj_No,3813
+decksmith-0.1.11.dist-info/entry_points.txt,sha256=-usRztjj2gnfmPubb8nFYHD22drzThAmSfM6geWI98Y,48
+decksmith-0.1.11.dist-info/METADATA,sha256=L5sn3x0uhVFGYvvQMtRLMmiRY9bfevuQvOLxWhGoSL8,2522
+decksmith-0.1.11.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+decksmith-0.1.11.dist-info/RECORD,,

decksmith-0.1.9.dist-info/RECORD

@@ -1,13 +0,0 @@
-decksmith/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-decksmith/card_builder.py,sha256=oXD6XvtbNaUW-WF47v6y7GjIyg_g2giu4SEEEqq8D_c,25521
-decksmith/deck_builder.py,sha256=8YK4ds51-z9f-BUyQ8jyh15BY9f16UQBYFI6Z87yFfU,3415
-decksmith/export.py,sha256=aMMoGdBDQ-Gr4QJ_ziiV3F673kEyXzM0phVq14uDDJg,6225
-decksmith/main.py,sha256=AzDq1aXziQmYz2IWdWSoBFskUeAXfOmcfYnIQUNIYp0,3357
-decksmith/templates/deck.csv,sha256=pNJebNxoDIfM8m0-aj05YrANHih1BTKOMry1kspIpPI,462
-decksmith/templates/deck.json,sha256=BTTnmaFP5AkbbC_B7uMF6R4bOM7JizW6EATcsjjJrT4,695
-decksmith/utils.py,sha256=XKSapVB1_zZvYcl3LgZcHAob4Pk5HUT9AnlAQBAdeTs,2833
-decksmith/validate.py,sha256=uqnNs8n6IeYfZcRrQKOaZzTMZM6gGP3MS_HPyWJ9vrQ,3578
-decksmith-0.1.9.dist-info/entry_points.txt,sha256=-usRztjj2gnfmPubb8nFYHD22drzThAmSfM6geWI98Y,48
-decksmith-0.1.9.dist-info/METADATA,sha256=Uq5NLeafcSXqufooG6g8GTcihnyPsci0VCB-kGWkbrs,2419
-decksmith-0.1.9.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-decksmith-0.1.9.dist-info/RECORD,,