pptxizza 0.1.0__tar.gz

pptxizza-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: pptxizza
+Version: 0.1.0
+Summary: A streamlined, LLM-friendly pip package for creating and editing pptx files from templates.
+Author: Kameron
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: lxml>=4.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# pptxizza
+
+A streamlined, LLM-friendly pip package for creating and editing `.pptx` files dynamically. `pptxizza` uses direct XML manipulation under the hood (via `lxml`) to fill text, replace images, and update charts and tables within existing PowerPoint templates quickly and efficiently, featuring a highly-granular Object-Oriented API for direct shape manipulation!
+
+## Features
+
+- **Object-Oriented Integrity**: Native interaction with shapes (`Shape`, `Rect`, `Circle`) and charts (`BarChart`, `PieChart`, etc.).
+- **Programmatic Shape Insertion**: Generate and structure exact geometry auto-shapes or vector pictures dynamically from code.
+- **Text Replacement**: Replace `{{mustache}}` template variables anywhere on a slide, or target specific named shapes.
+- **Image Replacement**: Easily swap out placeholder images with `.png`, `.jpg`, or `.svg` files while preserving position and styling.
+- **Chart & Table Data Binding**: Update the underlying data of native PowerPoint charts (`BarChart`, `PieChart`, `LineChart`) directly via their class objects.
+
+## Installation
+
+As this package is under development, you can use it locally by ensuring the package is in your `sys.path` or installing it in editable mode:
+
+```bash
+pip install -e .
+```
+
+Dependencies:
+- `lxml`
+
+## Quick Start (Templating)
+
+The most robust way to use `pptxizza` is to create a template (`template.pptx`) with some named placeholders or `{{mustache_keys}}`, then parse it:
+
+```python
+from pptxizza import Presentation
+
+def main():
+    pres = Presentation("template.pptx")
+    slide = pres.slides[0]
+
+    # Fill the slide with dynamic content mapped to shape names
+    slide.fill({
+        "{{title}}": "Quarterly Business Review",  # Global mustache text replacement
+        "SubtitleShape": "Q3 2026 Results",         # Named shape text replacement
+        "LogoPlaceholder": "company_logo.svg"       # Named picture shape replacement (injects SVG!)
+    })
+
+    pres.save("output.pptx")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Creating a Presentation from Scratch
+
+If you just need a blank presentation without an existing template, you can initialize `Presentation` with no arguments.
+
+```python
+from pptxizza import Presentation
+
+def main():
+    # Calling Presentation() without an argument loads a default blank template
+    pres = Presentation()
+    
+    # You can now add slides or insert shapes programmatically
+    # ...
+    
+    pres.save("new_presentation.pptx")
+
+if __name__ == "__main__":
+    main()
+```
+
+## The Object-Oriented API (`pptxizza.shapes`)
+
+`pptxizza` maps OpenXML structures directly into typed Python objects, allowing for programmatic instantiation and highly specific template discovery.
+
+### 1. Generating & Inserting Shapes Programmatically
+
+Instead of relying solely on existing templates, you can import granular geometric components from `pptxizza.shapes` to build slides from scratch!
+
+```python
+from pptxizza.shapes import Shape, Rect, Circle, Picture, Table
+from pptxizza import Inches
+
+slide = pres.slides[0]
+
+# Create a primitive Rect shape with text
+my_rect = Rect(text="Action Item", x=Inches(1), y=Inches(1), cx=Inches(3), cy=Inches(1))
+
+# Create an Oval/Circle
+my_circle = Circle(text="1", x=Inches(5), y=Inches(1), cx=Inches(1), cy=Inches(1))
+
+# Create a Table (3 rows, 3 columns)
+my_table = Table(rows=3, cols=3, x=Inches(1), y=Inches(3), cx=Inches(6), cy=Inches(1.5))
+
+# Create an SVG Vector graphic dynamically
+my_ufo = Picture(image_path="ufo.svg", x=Inches(3), y=Inches(5), cx=Inches(2), cy=Inches(2))
+
+# Insert the objects natively. Background relation mapping is handled automatically!
+slide.insert_shape(my_rect)
+slide.insert_shape(my_circle)
+slide.insert_shape(my_table)
+slide.insert_shape(my_ufo)
+```
+
+_Note_: `x`, `y`, `cx`, and `cy` are tracked in English Metric Units (EMUs). All shapes also expose `x_inches`, `y_inches`, `width_inches`, and `height_inches` for easier visual math.
+
+### 2. Inspecting and Manipulating Dynamic Shapes
+
+`pptxizza` intelligently probes into the ZIP packages under the hood to detect exactly what's sitting on a template slide. When examining `slide.shapes`, generic graphic frames are dynamically resolved into explicit subclasses like `BarChart`, `PieChart`, or `LineChart`.
+
+```python
+for shape in slide.shapes:
+    print(f"Discovered: {type(shape).__name__} named '{shape.shape_name}'")
+    
+    # You can access common underlying properties easily!
+    shape.x_inches += 1.5  # shift everything right by 1.5 inches
+```
+
+### 3. Updating Chart Data via Shape Objects
+
+When `slide.shapes` returns a chart class (e.g. `BarChart`, `PieChart`), you can call `.replace_data()` directly onto the object to overwrite its internal points caches.
+
+```python
+from pptxizza.shapes import BarChart
+
+for shape in slide.shapes:
+    if isinstance(shape, BarChart) and shape.shape_name == "SalesChart":
+        categories = ["Jan", "Feb", "Mar"]
+        data = {
+            0: [150, 200, 250],        # Update series 0 by its index
+            "Europe": [120, 180, 210]  # Update series by string name matching
+        }
+        
+        # Inject seamlessly into the cache!
+        shape.replace_data(data, categories)
+```
+
+### 4. Manipulating Tables
+
+`Table` objects allow for granular cell access and styling using presets.
+
+```python
+from pptxizza.shapes import Table
+
+for shape in slide.shapes:
+    if isinstance(shape, Table):
+        # Access cells by (row, col)
+        shape.cell(0, 0).text = "Header 1"
+        
+        # Helper to set first row names
+        shape.set_column_names(["ID", "Name", "Status"])
+        
+        # Add new rows or columns
+        new_row = shape.add_row()
+        new_row.cells[0].text = "001"
+        
+        # Apply visual presets
+        shape.apply_preset("Medium Style 2 - Accent 1")
+```
+
+### 5. Styling and Rich Text
+
+Most shapes support direct styling of fill and font properties. You can also use the `Text` and `Run` objects for rich text formatting.
+
+```python
+from pptxizza import RGBColor, HexColor, ThemeColor, Pt, Text
+
+# Solid Fill
+shape.fill.solid(HexColor("#4287f5"))
+
+# Font Styling
+shape.font.size = Pt(24)
+shape.font.bold = True
+shape.font.color = RGBColor(255, 255, 255)
+
+# Rich Text with Runs
+t = Text()
+t.add_run("Normal text, ")
+t.add_run("BOLD AND RED", bold=True, color=HexColor("FF0000"))
+t.add_run(" and ", italic=True)
+t.add_run("LARGE BLUE", size=Pt(40), color=ThemeColor("accent1"))
+
+shape.text = t
+```
+
+## Advanced Native Image Support (SVG)
+
+Native PowerPoint doesn't typically embed pure SVGs comfortably via older XML specifications. `pptxizza` utilizes modern Microsoft Open XML extension nodes natively mapping `a:svgBlip` relations to automatically parse, embed, and inject SVGs interchangeably with PNGs and JPGs!

pptxizza-0.1.0/README.md

@@ -0,0 +1,184 @@
+# pptxizza
+
+A streamlined, LLM-friendly pip package for creating and editing `.pptx` files dynamically. `pptxizza` uses direct XML manipulation under the hood (via `lxml`) to fill text, replace images, and update charts and tables within existing PowerPoint templates quickly and efficiently, featuring a highly-granular Object-Oriented API for direct shape manipulation!
+
+## Features
+
+- **Object-Oriented Integrity**: Native interaction with shapes (`Shape`, `Rect`, `Circle`) and charts (`BarChart`, `PieChart`, etc.).
+- **Programmatic Shape Insertion**: Generate and structure exact geometry auto-shapes or vector pictures dynamically from code.
+- **Text Replacement**: Replace `{{mustache}}` template variables anywhere on a slide, or target specific named shapes.
+- **Image Replacement**: Easily swap out placeholder images with `.png`, `.jpg`, or `.svg` files while preserving position and styling.
+- **Chart & Table Data Binding**: Update the underlying data of native PowerPoint charts (`BarChart`, `PieChart`, `LineChart`) directly via their class objects.
+
+## Installation
+
+As this package is under development, you can use it locally by ensuring the package is in your `sys.path` or installing it in editable mode:
+
+```bash
+pip install -e .
+```
+
+Dependencies:
+- `lxml`
+
+## Quick Start (Templating)
+
+The most robust way to use `pptxizza` is to create a template (`template.pptx`) with some named placeholders or `{{mustache_keys}}`, then parse it:
+
+```python
+from pptxizza import Presentation
+
+def main():
+    pres = Presentation("template.pptx")
+    slide = pres.slides[0]
+
+    # Fill the slide with dynamic content mapped to shape names
+    slide.fill({
+        "{{title}}": "Quarterly Business Review",  # Global mustache text replacement
+        "SubtitleShape": "Q3 2026 Results",         # Named shape text replacement
+        "LogoPlaceholder": "company_logo.svg"       # Named picture shape replacement (injects SVG!)
+    })
+
+    pres.save("output.pptx")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Creating a Presentation from Scratch
+
+If you just need a blank presentation without an existing template, you can initialize `Presentation` with no arguments.
+
+```python
+from pptxizza import Presentation
+
+def main():
+    # Calling Presentation() without an argument loads a default blank template
+    pres = Presentation()
+    
+    # You can now add slides or insert shapes programmatically
+    # ...
+    
+    pres.save("new_presentation.pptx")
+
+if __name__ == "__main__":
+    main()
+```
+
+## The Object-Oriented API (`pptxizza.shapes`)
+
+`pptxizza` maps OpenXML structures directly into typed Python objects, allowing for programmatic instantiation and highly specific template discovery.
+
+### 1. Generating & Inserting Shapes Programmatically
+
+Instead of relying solely on existing templates, you can import granular geometric components from `pptxizza.shapes` to build slides from scratch!
+
+```python
+from pptxizza.shapes import Shape, Rect, Circle, Picture, Table
+from pptxizza import Inches
+
+slide = pres.slides[0]
+
+# Create a primitive Rect shape with text
+my_rect = Rect(text="Action Item", x=Inches(1), y=Inches(1), cx=Inches(3), cy=Inches(1))
+
+# Create an Oval/Circle
+my_circle = Circle(text="1", x=Inches(5), y=Inches(1), cx=Inches(1), cy=Inches(1))
+
+# Create a Table (3 rows, 3 columns)
+my_table = Table(rows=3, cols=3, x=Inches(1), y=Inches(3), cx=Inches(6), cy=Inches(1.5))
+
+# Create an SVG Vector graphic dynamically
+my_ufo = Picture(image_path="ufo.svg", x=Inches(3), y=Inches(5), cx=Inches(2), cy=Inches(2))
+
+# Insert the objects natively. Background relation mapping is handled automatically!
+slide.insert_shape(my_rect)
+slide.insert_shape(my_circle)
+slide.insert_shape(my_table)
+slide.insert_shape(my_ufo)
+```
+
+_Note_: `x`, `y`, `cx`, and `cy` are tracked in English Metric Units (EMUs). All shapes also expose `x_inches`, `y_inches`, `width_inches`, and `height_inches` for easier visual math.
+
+### 2. Inspecting and Manipulating Dynamic Shapes
+
+`pptxizza` intelligently probes into the ZIP packages under the hood to detect exactly what's sitting on a template slide. When examining `slide.shapes`, generic graphic frames are dynamically resolved into explicit subclasses like `BarChart`, `PieChart`, or `LineChart`.
+
+```python
+for shape in slide.shapes:
+    print(f"Discovered: {type(shape).__name__} named '{shape.shape_name}'")
+    
+    # You can access common underlying properties easily!
+    shape.x_inches += 1.5  # shift everything right by 1.5 inches
+```
+
+### 3. Updating Chart Data via Shape Objects
+
+When `slide.shapes` returns a chart class (e.g. `BarChart`, `PieChart`), you can call `.replace_data()` directly onto the object to overwrite its internal points caches.
+
+```python
+from pptxizza.shapes import BarChart
+
+for shape in slide.shapes:
+    if isinstance(shape, BarChart) and shape.shape_name == "SalesChart":
+        categories = ["Jan", "Feb", "Mar"]
+        data = {
+            0: [150, 200, 250],        # Update series 0 by its index
+            "Europe": [120, 180, 210]  # Update series by string name matching
+        }
+        
+        # Inject seamlessly into the cache!
+        shape.replace_data(data, categories)
+```
+
+### 4. Manipulating Tables
+
+`Table` objects allow for granular cell access and styling using presets.
+
+```python
+from pptxizza.shapes import Table
+
+for shape in slide.shapes:
+    if isinstance(shape, Table):
+        # Access cells by (row, col)
+        shape.cell(0, 0).text = "Header 1"
+        
+        # Helper to set first row names
+        shape.set_column_names(["ID", "Name", "Status"])
+        
+        # Add new rows or columns
+        new_row = shape.add_row()
+        new_row.cells[0].text = "001"
+        
+        # Apply visual presets
+        shape.apply_preset("Medium Style 2 - Accent 1")
+```
+
+### 5. Styling and Rich Text
+
+Most shapes support direct styling of fill and font properties. You can also use the `Text` and `Run` objects for rich text formatting.
+
+```python
+from pptxizza import RGBColor, HexColor, ThemeColor, Pt, Text
+
+# Solid Fill
+shape.fill.solid(HexColor("#4287f5"))
+
+# Font Styling
+shape.font.size = Pt(24)
+shape.font.bold = True
+shape.font.color = RGBColor(255, 255, 255)
+
+# Rich Text with Runs
+t = Text()
+t.add_run("Normal text, ")
+t.add_run("BOLD AND RED", bold=True, color=HexColor("FF0000"))
+t.add_run(" and ", italic=True)
+t.add_run("LARGE BLUE", size=Pt(40), color=ThemeColor("accent1"))
+
+shape.text = t
+```
+
+## Advanced Native Image Support (SVG)
+
+Native PowerPoint doesn't typically embed pure SVGs comfortably via older XML specifications. `pptxizza` utilizes modern Microsoft Open XML extension nodes natively mapping `a:svgBlip` relations to automatically parse, embed, and inject SVGs interchangeably with PNGs and JPGs!

pptxizza-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pptxizza"
+version = "0.1.0"
+authors = [
+  { name="Kameron" },
+]
+description = "A streamlined, LLM-friendly pip package for creating and editing pptx files from templates."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "lxml>=4.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pptxizza = ["templates/*.pptx"]

pptxizza-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pptxizza-0.1.0/src/pptxizza/__init__.py

@@ -0,0 +1,12 @@
+from .presentation import Presentation
+from .util import Length, Inches, Cm, Pt, Emu
+from .colors import Color, RGBColor, HexColor, ThemeColor
+from .text import Text, Run
+from .shapes.table import Table
+
+__all__ = [
+    "Presentation",
+    "Length", "Inches", "Cm", "Pt", "Emu",
+    "Color", "RGBColor", "HexColor", "ThemeColor",
+    "Text", "Run", "Table"
+]

pptxizza-0.1.0/src/pptxizza/charts.py

@@ -0,0 +1,95 @@
+from typing import Dict, List, Any, Optional, Union
+from .xml_utils import etree, xpath, qname
+
+def replace_chart_data(slide: Any, shape_name: str, data: Dict[Union[int, str], List[Any]], categories: List[str]) -> None:
+    """
+    Replaces the underlying data cache bindings inside an existing chart shape.
+    
+    Args:
+        slide (Slide): The origin slide wrapper instance resolving the chart relational context.
+        shape_name (str): The logical embedded drawingML name attribute for the chart.
+        data (Dict[Union[int, str], List[Any]]): A dictionary mapping Series index integers or string headers to lists of arbitrary values.
+        categories (List[str]): Overriding axis category label names (e.g. Month headers / "Q1", "Q2").
+        
+    Raises:
+        ValueError: If the shape wasn't found, isn't a chart, or lacks valid XML relationship dependencies.
+    """
+    cnvprs = xpath(slide._xml, f"//p:cNvPr[@name='{shape_name}']")
+    if not cnvprs:
+        raise ValueError(f"Chart shape '{shape_name}' not found on slide.")
+    
+    parent = cnvprs[0].getparent()
+    if parent is None:
+        raise ValueError("Invalid shape hierarchy")
+    graphicFrame = parent.getparent()
+    if graphicFrame is None:
+        raise ValueError("Invalid shape hierarchy")
+        
+    chart_ref = xpath(graphicFrame, ".//c:chart")
+    if not chart_ref:
+        raise ValueError(f"Shape '{shape_name}' is not a chart.")
+        
+    rId = chart_ref[0].get(qname("r", "id"))
+    
+    slide_rels = slide._package.get_rels(slide.part_name)
+    rel = slide_rels.rels.get(rId)
+    if not rel:
+        raise ValueError(f"Relationship {rId} for chart not found.")
+        
+    target = rel['Target']
+    if target.startswith("../"):
+        target = target[3:]
+    chart_part_name = f"ppt/{target}"
+    
+    chart_xml = slide._package.get_xml_part(chart_part_name)
+    if chart_xml is None:
+        raise ValueError(f"Chart part {chart_part_name} not found in package.")
+        
+    series_nodes = xpath(chart_xml, "//c:ser")
+    for idx, ser in enumerate(series_nodes):
+        ser_vals = data.get(idx) or data.get(str(idx))
+        if ser_vals is None:
+            tx_node = xpath(ser, "c:tx//c:v")
+            if tx_node and tx_node[0].text in data:
+                ser_vals = data[tx_node[0].text]
+                
+        if ser_vals is None:
+            continue
+            
+        cat_caches = xpath(ser, "c:cat//c:strCache")
+        if not cat_caches:
+            cat_caches = xpath(ser, "c:cat//c:numCache")
+            
+        if cat_caches:
+            _update_cache(cat_caches[0], categories)
+            
+        val_caches = xpath(ser, "c:val//c:numCache")
+        if val_caches:
+            _update_cache(val_caches[0], ser_vals)
+            
+    slide._package.set_xml_part(chart_part_name, chart_xml)
+
+
+def _update_cache(cache_node: etree._Element, items: List[Any]) -> None:
+    """
+    Overwrites the `ptCount` size cache and constructs identical `pt` mapping points internally.
+    
+    Args:
+        cache_node (etree._Element): The internal c:strCache or c:numCache DOM node target wrapper.
+        items (List[Any]): Array of primitive values to serialize into the point cache elements.
+    """
+    ptCount = xpath(cache_node, "c:ptCount")
+    if not ptCount:
+        ptCount_elem = etree.SubElement(cache_node, qname("c", "ptCount"))
+    else:
+        ptCount_elem = ptCount[0]
+    ptCount_elem.set("val", str(len(items)))
+    
+    for pt in xpath(cache_node, "c:pt"):
+        cache_node.remove(pt)
+        
+    for i, item in enumerate(items):
+        pt_elem = etree.SubElement(cache_node, qname("c", "pt"))
+        pt_elem.set("idx", str(i))
+        v_elem = etree.SubElement(pt_elem, qname("c", "v"))
+        v_elem.text = str(item)

pptxizza-0.1.0/src/pptxizza/colors.py

@@ -0,0 +1,55 @@
+from lxml import etree
+from .xml_utils import qname
+
+class Color:
+    """
+    Base class for shape and text colors in pptxizza.
+    Subclasses must implement _get_color_node.
+    """
+    def _get_color_node(self) -> etree._Element:
+        raise NotImplementedError("Subclasses must implement _get_color_node")
+
+
+class RGBColor(Color):
+    """
+    Represents an RGB color constructed from integer red, green, and blue values (0-255).
+    """
+    def __init__(self, r: int, g: int, b: int) -> None:
+        self.r = r
+        self.g = g
+        self.b = b
+
+    def _get_color_node(self) -> etree._Element:
+        node = etree.Element(qname("a", "srgbClr"))
+        # Render hex format without the #
+        hex_val = f"{self.r:02X}{self.g:02X}{self.b:02X}"
+        node.set("val", hex_val)
+        return node
+
+
+class HexColor(Color):
+    """
+    Represents a color constructed from a standard hexadecimal string (e.g. '#FF0000' or 'FF0000').
+    """
+    def __init__(self, hex_str: str) -> None:
+        if hex_str.startswith("#"):
+            hex_str = hex_str[1:]
+        self.hex_str = hex_str.upper()
+
+    def _get_color_node(self) -> etree._Element:
+        node = etree.Element(qname("a", "srgbClr"))
+        node.set("val", self.hex_str)
+        return node
+
+
+class ThemeColor(Color):
+    """
+    Represents a color tied to the presentation's theme scheme (e.g., 'accent1', 'tx1', 'bg1').
+    """
+    def __init__(self, theme_val: str) -> None:
+        self.theme_val = theme_val
+
+    def _get_color_node(self) -> etree._Element:
+        node = etree.Element(qname("a", "schemeClr"))
+        node.set("val", self.theme_val)
+        return node