decksmith 0.1.14__tar.gz → 0.9.1__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: decksmith
-Version: 0.1.14
-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,29 +43,64 @@ 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 quickly.
+- 📖 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)
 
 ## Getting started
 
-- First, install DeckSmith by running `pip install decksmith`.
+### Installation
+
+- To begin, install DeckSmith by running:
+
+  ```bash
+  pip install decksmith
+  ```
+
+- To launch the GUI, run:
+
+  ```bash
+  decksmith --gui
+  ```
+
+### Creating a project
+
+- Run the following command to start from sample `deck.yaml` and `deck.csv` files:
+
+  ```text
+  decksmith init
+  ```
+
+  - `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.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.yaml` file as `%column_name%`.
 
-- Then, run `decksmith init` to start from sample `deck.json` and `deck.csv` files.
+### Building the deck
 
-- The `deck.json` file defines the layout for the cards in the deck, while the `deck.csv` file holds the data for each card.
+- When you are ready to generate the deck images, run:
 
-  - You can find a complete list of all the available elements you can use in the [documentation](https://github.com/Julynx/decksmith/blob/main/docs/DOCS.md).
+  ```text
+  decksmith build
+  ```
 
-  - Any column from the CSV can be referenced anywhere in the JSON as `%column_name%`.
+- After building a deck, you can export it to PDF by running:
 
-- Finally, run `decksmith build` when you are ready to generate the deck images, and export them to PDF using the `decksmith export` command.
+  ```text
+  decksmith export
+  ```
 
 ## Documentation
 

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.14 → decksmith-0.9.1}/decksmith/export.py

@@ -2,7 +2,6 @@
 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
 
@@ -10,6 +9,8 @@ from reportlab.lib.pagesizes import A4
 from reportlab.lib.units import mm
 from reportlab.pdfgen import canvas
 
+from decksmith.logger import logger
+
 
 class PdfExporter:
     """
@@ -46,9 +47,9 @@ class PdfExporter:
         image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
         return sorted(
             [
-                p
-                for p in self.image_folder.iterdir()
-                if p.suffix.lower() in image_extensions
+                image_path
+                for image_path in self.image_folder.iterdir()
+                if image_path.suffix.lower() in image_extensions
             ]
         )
 
@@ -82,17 +83,18 @@ class PdfExporter:
         best_layout = (0, 0, False)
 
         for rotated in [False, True]:
-            img_w, img_h = (
+            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) / (img_w + self.gap)
+                (page_width - 2 * self.margins[0] + self.gap) / (image_width + self.gap)
             )
             rows = int(
-                (page_height - 2 * self.margins[1] + self.gap) / (img_h + self.gap)
+                (page_height - 2 * self.margins[1] + self.gap)
+                / (image_height + self.gap)
             )
 
             if cols * rows > best_fit:
@@ -112,16 +114,16 @@ class PdfExporter:
             if cols == 0 or rows == 0:
                 raise ValueError("The images are too large to fit on the page.")
 
-            img_w, img_h = (
+            image_width, image_height = (
                 (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
+            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:
@@ -132,37 +134,37 @@ class PdfExporter:
                 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)
+                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),
-                        x,
-                        y,
-                        width=img_w,
-                        height=img_h,
+                        position_horizontal,
+                        position_vertical,
+                        width=image_width,
+                        height=image_height,
                         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)
+                    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),
-                        -img_h / 2,
-                        -img_w / 2,
-                        width=img_h,
-                        height=img_w,
+                        -image_height / 2,
+                        -image_width / 2,
+                        width=image_height,
+                        height=image_width,
                         preserveAspectRatio=True,
                     )
                     self.pdf.restoreState()
                 images_on_page += 1
 
             self.pdf.save()
-            logging.info("Successfully exported PDF to %s", self.output_path)
+            logger.info("Successfully exported PDF to %s", self.output_path)
         except Exception as e:
-            logging.error("An error occurred during PDF export: %s", e)
+            logger.error("An error occurred during PDF export: %s", e)
             raise