decksmith 0.1.15__tar.gz → 0.9.1__tar.gz

{decksmith-0.1.15 → decksmith-0.9.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: decksmith
-Version: 0.1.15
-Summary: A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck.
+Version: 0.9.1
+Summary: A command-line application to dynamically generate decks of cards from a YAML specification and a CSV data file, inspired by nandeck.
 License-Expression: GPL-2.0-only
 Author: Julio Cabria
 Author-email: juliocabria@tutanota.com
@@ -13,27 +13,26 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: dev
 Requires-Dist: click
+Requires-Dist: crossfiledialog (>=1.1.0)
+Requires-Dist: flask (>=3.1.2)
 Requires-Dist: jval (==1.0.6)
 Requires-Dist: pandas
 Requires-Dist: pillow (>=11.3.0)
-Requires-Dist: poetry ; extra == "dev"
+Requires-Dist: platformdirs (>=4.5.1)
 Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: pywin32 (>=311) ; sys_platform == "win32"
 Requires-Dist: reportlab (>=4.4.3)
-Project-URL: Homepage, https://github.com/Julynx/decksmith
+Requires-Dist: ruamel-yaml (>=0.19.1)
+Requires-Dist: waitress (>=3.0.2)
 Description-Content-Type: text/markdown
 
 # DeckSmith
 
-*A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck.*
+*A powerful application to dynamically generate decks of cards from a YAML specification and a CSV data file.*
 
 <br>
 <p align="center">
-  <img width="600" src="https://raw.githubusercontent.com/Julynx/decksmith/refs/heads/main/docs/assets/decksmith.png">
-</p>
-
-<br>
-<p align="center">
-  <img width="600" src="https://raw.githubusercontent.com/Julynx/decksmith/refs/heads/main/docs/assets/banner.png">
+  <img src="https://raw.githubusercontent.com/Julynx/decksmith/refs/heads/main/docs/assets/screenshot.png" width='100%'>
 </p>
 
 <br>
@@ -44,12 +43,13 @@ DeckSmith is ideal for automating the creation of all kinds of decks, including
 
 - ✨ Consistent layout and formatting across all cards. Define once, edit anytime, generate as many cards as you need.
 - 🍳 Pure python, with easy installation via pip.
+- 🖥️ User-friendly GUI for easy project management and generation.
 - ⚡ Highly performant card generation using parallel processing.
 - 📖 Intuitive syntax and extensive [documentation](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md) with examples to help you get started.
 - 🧰 Tons of powerful features such as:
   - [Start from a sample project and edit it instead of starting from scratch](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#creating-a-project)
   - [Extensive support for images](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#images), [text](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#text), [and all kinds of different shapes](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#shapes)
-  - [Link any field to a column in the CSV file](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#basic-example-with-deckcsv)
+  - [Link any field to a column in the CSV file](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#example-with-deckcsv)
   - [Position elements absolutely or relative to other elements, using anchors to simplify placement](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#positioning)
   - [Powerful image transformations using filters like crop, resize, rotate, or flip](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#images)
   - [Export your deck as images or as a PDF for printing](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md#building-the-deck)
@@ -64,23 +64,29 @@ DeckSmith is ideal for automating the creation of all kinds of decks, including
   pip install decksmith
   ```
 
+- To launch the GUI, run:
+
+  ```bash
+  decksmith --gui
+  ```
+
 ### Creating a project
 
-- Run the following command to start from sample `deck.json` and `deck.csv` files:
+- Run the following command to start from sample `deck.yaml` and `deck.csv` files:
 
   ```text
   decksmith init
   ```
 
-  - `deck.json` defines the layout for the cards in the deck.
+  - `deck.yaml` defines the layout for the cards in the deck.
   - `deck.csv` holds the data for each card, like the content of the text fields and the image paths.
 
 ### Defining the layout
 
-- Edit `deck.json` to include all the elements you want on your cards.
+- Edit `deck.yaml` to include all the elements you want on your cards.
   You can find a complete list of all the available elements and their properties in the [documentation](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md).
 
-- You can reference any column from `deck.csv` in the `deck.json` file as `%column_name%`.
+- You can reference any column from `deck.csv` in the `deck.yaml` file as `%column_name%`.
 
 ### Building the deck
 

decksmith-0.9.1/decksmith/card_builder.py

@@ -0,0 +1,140 @@
+"""
+This module contains the CardBuilder class,
+which is used to create card images based on a YAML specification.
+"""
+
+import operator
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from PIL import Image, ImageDraw
+
+from decksmith.logger import logger
+from decksmith.renderers.image import ImageRenderer
+from decksmith.renderers.shapes import ShapeRenderer
+from decksmith.renderers.text import TextRenderer
+from decksmith.utils import apply_anchor
+from decksmith.validate import transform_card, validate_card
+
+
+class CardBuilder:
+    """
+    A class to build a card image based on a YAML specification.
+    Attributes:
+        spec (Dict[str, Any]): The YAML 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[str, Any], base_path: Optional[Path] = None):
+        """
+        Initializes the CardBuilder with a YAML specification.
+        Args:
+            spec (Dict[str, Any]): The YAML specification for the card.
+            base_path (Optional[Path]): The base path for resolving relative file paths.
+        """
+        self.spec = spec
+        self.base_path = base_path
+        width = self.spec.get("width", 250)
+        height = self.spec.get("height", 350)
+        background_color = tuple(self.spec.get("background_color", (255, 255, 255, 0)))
+        self.card: Image.Image = Image.new("RGBA", (width, height), background_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)
+
+        self.text_renderer = TextRenderer(base_path)
+        self.image_renderer = ImageRenderer(base_path)
+        self.shape_renderer = ShapeRenderer()
+
+    def _calculate_absolute_position(self, element: Dict[str, Any]) -> Tuple[int, int]:
+        """
+        Calculates the absolute position of an element,
+        resolving relative positioning.
+        Args:
+            element (dict): The element dictionary.
+        Returns:
+            tuple: The absolute (x, y) position of the element.
+        """
+        # If the element has no 'relative_to', return its position directly
+        if "relative_to" not in element:
+            return tuple(element.get("position", [0, 0]))
+
+        # If the element has 'relative_to', resolve based on the reference element and anchor
+        relative_identifier, anchor = element["relative_to"]
+        if relative_identifier not in self.element_positions:
+            raise ValueError(
+                f"Element with id '{relative_identifier}' not found for relative positioning."
+            )
+
+        parent_bbox = self.element_positions[relative_identifier]
+        anchor_point = apply_anchor(parent_bbox, anchor)
+
+        offset = tuple(element.get("position", [0, 0]))
+        return tuple(map(operator.add, anchor_point, offset))
+
+    def _store_element_position(
+        self, element_identifier: str, bbox: Tuple[int, int, int, int]
+    ):
+        """Stores the bounding box of an element."""
+        self.element_positions[element_identifier] = bbox
+
+    def render(self) -> Image.Image:
+        """
+        Renders the card image by drawing all elements specified in the YAML.
+        Returns:
+            Image.Image: The rendered card image.
+        """
+        self.spec = transform_card(self.spec)
+        validate_card(self.spec)
+
+        for element in self.spec.get("elements", []):
+            element_type = element.get("type")
+            try:
+                if element_type == "text":
+                    self.text_renderer.render(
+                        self.draw,
+                        element,
+                        self._calculate_absolute_position,
+                        self._store_element_position,
+                    )
+                elif element_type == "image":
+                    self.image_renderer.render(
+                        self.card,
+                        element,
+                        self._calculate_absolute_position,
+                        self._store_element_position,
+                    )
+                elif element_type in [
+                    "circle",
+                    "ellipse",
+                    "polygon",
+                    "regular-polygon",
+                    "rectangle",
+                ]:
+                    self.card = self.shape_renderer.render(
+                        self.card,
+                        element,
+                        self._calculate_absolute_position,
+                        self._store_element_position,
+                    )
+                    # Re-create draw object because shape renderer might have composited a new image
+                    self.draw = ImageDraw.Draw(self.card, "RGBA")
+            except Exception as e:
+                logger.error("Error drawing element %s: %s", element_type, e)
+                # Continue drawing other elements
+
+        return self.card
+
+    def build(self, output_path: Path):
+        """
+        Builds the card image and saves it to the specified path.
+        Args:
+            output_path (Path): The path where the card image will be saved.
+        """
+        card = self.render()
+        card.save(output_path)
+        logger.info("(✔) Card saved to %s", output_path)

decksmith-0.9.1/decksmith/deck_builder.py

@@ -0,0 +1,85 @@
+"""
+This module contains the DeckBuilder class,
+which is used to create a deck of cards based on a YAML specification
+and a CSV file.
+"""
+
+import concurrent.futures
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+from pandas import Series
+from ruamel.yaml import YAML
+
+from decksmith.card_builder import CardBuilder
+from decksmith.logger import logger
+from decksmith.macro import MacroResolver
+
+
+class DeckBuilder:
+    """
+    A class to build a deck of cards based on a YAML specification and a CSV file.
+    Attributes:
+        spec_path (Path): Path to the YAML 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: Path, csv_path: Optional[Path] = None):
+        """
+        Initializes the DeckBuilder with a YAML specification file and a CSV file.
+        Args:
+            spec_path (Path): Path to the YAML 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: List[CardBuilder] = []
+        self._spec_cache: Optional[Dict[str, Any]] = None
+
+    @property
+    def spec(self) -> Dict[str, Any]:
+        """Loads and caches the spec file."""
+        if self._spec_cache is None:
+            yaml = YAML()
+            with open(self.spec_path, "r", encoding="utf-8") as spec_file:
+                self._spec_cache = yaml.load(spec_file)
+        return self._spec_cache
+
+    def build_deck(self, output_path: Path):
+        """
+        Builds the deck of cards by reading the CSV file and creating CardBuilder instances.
+        """
+        base_path = self.spec_path.parent if self.spec_path else None
+
+        if not self.csv_path or not self.csv_path.exists():
+            logger.info("No CSV file found. Building single card from spec.")
+            card_builder = CardBuilder(self.spec, base_path=base_path)
+            card_builder.build(output_path / "card_1.png")
+            return
+
+        try:
+            dataframe = pd.read_csv(self.csv_path, encoding="utf-8", sep=";", header=0)
+        except Exception as e:
+            logger.error("Error reading CSV file: %s", e)
+            return
+
+        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
+            try:
+                # We need a deep copy of the spec for each card to avoid side effects
+                # But resolve_macros creates a new structure, so it should be fine
+                spec = MacroResolver.resolve(self.spec, row.to_dict())
+                card_builder = CardBuilder(spec, base_path=base_path)
+                card_builder.build(output_path / f"card_{idx + 1}.png")
+            except Exception as e:
+                logger.error("Error building card %s: %s", idx + 1, e)
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            list(executor.map(build_card, dataframe.iterrows()))

{decksmith-0.1.15 → decksmith-0.9.1}/decksmith/export.py

@@ -1,168 +1,170 @@
-"""
-This module provides the functionality to export images from a folder to a PDF file.
-"""
-
-import logging
-from pathlib import Path
-from typing import List, Tuple
-
-from reportlab.lib.pagesizes import A4
-from reportlab.lib.units import mm
-from reportlab.pdfgen import canvas
-
-
-class PdfExporter:
-    """
-    A class to export images from a folder to a PDF file.
-    """
-
-    def __init__(
-        self,
-        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 = image_folder
-        self.image_paths = self._get_image_paths()
-        self.output_path = output_path
-        self.page_size = self._get_page_size(page_size_str)
-        self.image_width = image_width * mm
-        self.image_height = image_height * mm
-        self.gap = gap * mm
-        self.margins = (margins[0] * mm, margins[1] * mm)
-        self.pdf = canvas.Canvas(str(self.output_path), pagesize=self.page_size)
-
-    def _get_image_paths(self) -> List[Path]:
-        """
-        Scans the image folder and returns a list of image paths.
-
-        Returns:
-            List[str]: A sorted list of image paths.
-        """
-        image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
-        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]:
-        """
-        Returns the page size from a string.
-
-        Args:
-            page_size_str (str): The string representing the page size.
-
-        Returns:
-            Tuple[float, float]: The page size in points.
-        """
-        if page_size_str.lower() == "a4":
-            return A4
-        # Add other page sizes here if needed
-        return A4
-
-    def _calculate_layout(self, page_width: float, page_height: float):
-        """
-        Calculates the optimal layout for the images on the page.
-
-        Args:
-            page_width (float): The width of the page.
-            page_height (float): The height of the page.
-
-        Returns:
-            Tuple[int, int, bool]: The number of columns, rows, and if the layout is rotated.
-        """
-        best_fit = 0
-        best_layout = (0, 0, False)
-
-        for rotated in [False, True]:
-            img_w, img_h = (
-                (self.image_width, self.image_height)
-                if not rotated
-                else (self.image_height, self.image_width)
-            )
-
-            cols = int(
-                (page_width - 2 * self.margins[0] + self.gap) / (img_w + self.gap)
-            )
-            rows = int(
-                (page_height - 2 * self.margins[1] + self.gap) / (img_h + self.gap)
-            )
-
-            if cols * rows > best_fit:
-                best_fit = cols * rows
-                best_layout = (cols, rows, rotated)
-
-        return best_layout
-
-    def export(self):
-        """
-        Exports the images to a PDF file.
-        """
-        try:
-            page_width, page_height = self.page_size
-            cols, rows, rotated = self._calculate_layout(page_width, page_height)
-
-            if cols == 0 or rows == 0:
-                raise ValueError("The images are too large to fit on the page.")
-
-            img_w, img_h = (
-                (self.image_width, self.image_height)
-                if not rotated
-                else (self.image_height, self.image_width)
-            )
-
-            total_width = cols * img_w + (cols - 1) * self.gap
-            total_height = rows * img_h + (rows - 1) * self.gap
-            start_x = (page_width - total_width) / 2
-            start_y = (page_height - total_height) / 2
-
-            images_on_page = 0
-            for image_path in self.image_paths:
-                if images_on_page > 0 and images_on_page % (cols * rows) == 0:
-                    self.pdf.showPage()
-                    images_on_page = 0
-
-                row = images_on_page // cols
-                col = images_on_page % cols
-
-                x = start_x + col * (img_w + self.gap)
-                y = start_y + row * (img_h + self.gap)
-
-                if not rotated:
-                    self.pdf.drawImage(
-                        str(image_path),
-                        x,
-                        y,
-                        width=img_w,
-                        height=img_h,
-                        preserveAspectRatio=True,
-                    )
-                else:
-                    self.pdf.saveState()
-                    center_x = x + img_w / 2
-                    center_y = y + img_h / 2
-                    self.pdf.translate(center_x, center_y)
-                    self.pdf.rotate(90)
-                    self.pdf.drawImage(
-                        str(image_path),
-                        -img_h / 2,
-                        -img_w / 2,
-                        width=img_h,
-                        height=img_w,
-                        preserveAspectRatio=True,
-                    )
-                    self.pdf.restoreState()
-                images_on_page += 1
-
-            self.pdf.save()
-            logging.info("Successfully exported PDF to %s", self.output_path)
-        except Exception as e:
-            logging.error("An error occurred during PDF export: %s", e)
-            raise
+"""
+This module provides the functionality to export images from a folder to a PDF file.
+"""
+
+from pathlib import Path
+from typing import List, Tuple
+
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import mm
+from reportlab.pdfgen import canvas
+
+from decksmith.logger import logger
+
+
+class PdfExporter:
+    """
+    A class to export images from a folder to a PDF file.
+    """
+
+    def __init__(
+        self,
+        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 = image_folder
+        self.image_paths = self._get_image_paths()
+        self.output_path = output_path
+        self.page_size = self._get_page_size(page_size_str)
+        self.image_width = image_width * mm
+        self.image_height = image_height * mm
+        self.gap = gap * mm
+        self.margins = (margins[0] * mm, margins[1] * mm)
+        self.pdf = canvas.Canvas(str(self.output_path), pagesize=self.page_size)
+
+    def _get_image_paths(self) -> List[Path]:
+        """
+        Scans the image folder and returns a list of image paths.
+
+        Returns:
+            List[str]: A sorted list of image paths.
+        """
+        image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+        return sorted(
+            [
+                image_path
+                for image_path in self.image_folder.iterdir()
+                if image_path.suffix.lower() in image_extensions
+            ]
+        )
+
+    def _get_page_size(self, page_size_str: str) -> Tuple[float, float]:
+        """
+        Returns the page size from a string.
+
+        Args:
+            page_size_str (str): The string representing the page size.
+
+        Returns:
+            Tuple[float, float]: The page size in points.
+        """
+        if page_size_str.lower() == "a4":
+            return A4
+        # Add other page sizes here if needed
+        return A4
+
+    def _calculate_layout(self, page_width: float, page_height: float):
+        """
+        Calculates the optimal layout for the images on the page.
+
+        Args:
+            page_width (float): The width of the page.
+            page_height (float): The height of the page.
+
+        Returns:
+            Tuple[int, int, bool]: The number of columns, rows, and if the layout is rotated.
+        """
+        best_fit = 0
+        best_layout = (0, 0, False)
+
+        for rotated in [False, True]:
+            image_width, image_height = (
+                (self.image_width, self.image_height)
+                if not rotated
+                else (self.image_height, self.image_width)
+            )
+
+            cols = int(
+                (page_width - 2 * self.margins[0] + self.gap) / (image_width + self.gap)
+            )
+            rows = int(
+                (page_height - 2 * self.margins[1] + self.gap)
+                / (image_height + self.gap)
+            )
+
+            if cols * rows > best_fit:
+                best_fit = cols * rows
+                best_layout = (cols, rows, rotated)
+
+        return best_layout
+
+    def export(self):
+        """
+        Exports the images to a PDF file.
+        """
+        try:
+            page_width, page_height = self.page_size
+            cols, rows, rotated = self._calculate_layout(page_width, page_height)
+
+            if cols == 0 or rows == 0:
+                raise ValueError("The images are too large to fit on the page.")
+
+            image_width, image_height = (
+                (self.image_width, self.image_height)
+                if not rotated
+                else (self.image_height, self.image_width)
+            )
+
+            total_width = cols * image_width + (cols - 1) * self.gap
+            total_height = rows * image_height + (rows - 1) * self.gap
+            start_horizontal = (page_width - total_width) / 2
+            start_vertical = (page_height - total_height) / 2
+
+            images_on_page = 0
+            for image_path in self.image_paths:
+                if images_on_page > 0 and images_on_page % (cols * rows) == 0:
+                    self.pdf.showPage()
+                    images_on_page = 0
+
+                row = images_on_page // cols
+                col = images_on_page % cols
+
+                position_horizontal = start_horizontal + col * (image_width + self.gap)
+                position_vertical = start_vertical + row * (image_height + self.gap)
+
+                if not rotated:
+                    self.pdf.drawImage(
+                        str(image_path),
+                        position_horizontal,
+                        position_vertical,
+                        width=image_width,
+                        height=image_height,
+                        preserveAspectRatio=True,
+                    )
+                else:
+                    self.pdf.saveState()
+                    center_horizontal = position_horizontal + image_width / 2
+                    center_vertical = position_vertical + image_height / 2
+                    self.pdf.translate(center_horizontal, center_vertical)
+                    self.pdf.rotate(90)
+                    self.pdf.drawImage(
+                        str(image_path),
+                        -image_height / 2,
+                        -image_width / 2,
+                        width=image_height,
+                        height=image_width,
+                        preserveAspectRatio=True,
+                    )
+                    self.pdf.restoreState()
+                images_on_page += 1
+
+            self.pdf.save()
+            logger.info("Successfully exported PDF to %s", self.output_path)
+        except Exception as e:
+            logger.error("An error occurred during PDF export: %s", e)
+            raise