pptxfill 0.2.5__py3-none-any.whl

pptxfill/__init__.py

@@ -0,0 +1,21 @@
+from .loader import load_template
+from .picture import replace_image, replace_image_by_name
+from .slides import copy_slide_content, delete_slide, insert_slide, multiply_slide
+from .table import fill_table, fill_table_by_name
+from .text import format_text_on_slide
+from .walker import find_shape_by_name, walk_shapes
+
+__all__ = [
+    "load_template",
+    "replace_image",
+    "replace_image_by_name",
+    "copy_slide_content",
+    "delete_slide",
+    "insert_slide",
+    "multiply_slide",
+    "fill_table",
+    "fill_table_by_name",
+    "format_text_on_slide",
+    "walk_shapes",
+    "find_shape_by_name",
+]

pptxfill/eq.py

@@ -0,0 +1,66 @@
+from typing import Callable, Optional, cast
+
+from lxml.etree import Element, QName
+from lxml.etree import tostring as lxml_tostring
+from pptx.oxml.action import CT_Hyperlink
+from pptx.oxml.text import CT_TextCharacterProperties, CT_TextFont
+
+
+def optional_eq[T](v1: Optional[T], v2: Optional[T], eq: Callable[[T, T], bool]):
+    if v1 is None or v2 is None:
+        return (v1 is None) == (v2 is None)
+
+    return eq(v1, v2)
+
+
+def get_fill_properties(rpr: CT_TextCharacterProperties):
+    """rPr.eg_fillProperties doesn't cover all fill-related tags, so using a custom method"""
+    return next(
+        filter(
+            lambda el: not isinstance(el.tag, bytearray)
+            and QName(el.tag).localname
+            in {
+                "noFill",
+                "solidFill",
+                "gradFill",
+                "blipFill",
+                "pattFill",
+                "grpFill",
+                "effectLst",
+                "effectDag",
+                "highlight",
+                "uLnTx",
+                "uLn",
+                "uFillTx",
+                "uFill",
+            },
+            cast(Element, rpr),
+        ),
+        None,
+    )
+
+
+def elements_eq(el1: Element, el2: Element):
+    return lxml_tostring(el1) == lxml_tostring(el2)
+
+
+def text_font_eq(t1: CT_TextFont, t2: CT_TextFont):
+    return t1.typeface == t2.typeface
+
+
+def hyperlink_eq(h1: CT_Hyperlink, h2: CT_Hyperlink):
+    return h1.rId == h2.rId and h1.action == h2.action
+
+
+def text_character_properties_eq(
+    rpr1: CT_TextCharacterProperties, rpr2: CT_TextCharacterProperties
+):
+    return (
+        optional_eq(get_fill_properties(rpr1), get_fill_properties(rpr2), elements_eq)
+        and optional_eq(rpr1.latin, rpr2.latin, text_font_eq)
+        and optional_eq(rpr1.hlinkClick, rpr2.hlinkClick, hyperlink_eq)
+        and rpr1.sz == rpr2.sz
+        and rpr1.b == rpr2.b
+        and rpr1.i == rpr2.i
+        and rpr1.u == rpr2.u
+    )

pptxfill/loader.py

@@ -0,0 +1,57 @@
+from typing import IO
+
+from lxml.etree import Element
+from pptx import Presentation as new_presentation
+from pptx.oxml.text import CT_RegularTextRun
+from pptx.shapes.autoshape import Shape
+
+from .eq import optional_eq, text_character_properties_eq
+from .walker import walk_shapes
+
+
+def merge_spans_with_similar_style(parent: Element):
+    children = list(parent)
+
+    merged = [children[0]]
+    for i in range(1, len(children)):
+        last_part = merged[-1]
+        next_part = children[i]
+
+        if (
+            isinstance(last_part, CT_RegularTextRun)
+            and isinstance(next_part, CT_RegularTextRun)
+            and optional_eq(last_part.rPr, next_part.rPr, text_character_properties_eq)
+        ):
+            last_part.text += next_part.text
+        else:
+            merged.append(next_part)
+
+    parent.clear()
+    parent.extend(merged)
+
+
+def load_template(pptx: str | IO[bytes]):
+    """Loads a presentation similarly to :func:`pptx.Presentation`,
+
+    fixing split tags such as:
+
+    .. code-block:: xml
+
+        <a:r>
+            <a:t>{uni_full</a:t>
+        </a:r>
+        <a:r>
+            <a:t>_name}</a:t>
+        </a:r>
+
+    to make future formatting easier
+    """
+
+    template = new_presentation(pptx)
+
+    for slide in template.slides:
+        for shape in walk_shapes(slide, Shape):
+            for paragraph in shape.text_frame.paragraphs:
+                merge_spans_with_similar_style(paragraph._element)
+
+    return template

pptxfill/picture.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+from typing import IO, cast
+
+from lxml.etree import Element
+from pptx.shapes.base import BaseShape
+from pptx.shapes.picture import Picture
+from pptx.slide import Slide
+
+from .walker import find_shape_by_name
+
+
+def replace_image(
+    slide: Slide,
+    old_pic: BaseShape,
+    image: Path | str | IO[bytes],
+    full_width: bool = True,
+    full_height: bool = True,
+) -> Picture:
+    """Replace contents of a :class:`Picture <pptx.shapes.picture.Picture>` shape
+
+    Args:
+        slide: target slide
+        old_pic: shape to replace
+        image: new image file
+        full_width: stretch to original shape's width
+        full_height: stretch to original shape's height
+    """
+
+    if isinstance(image, Path):
+        image = str(image)
+
+    new_pic = slide.shapes.add_picture(
+        image,
+        left=old_pic.left,
+        top=old_pic.top,
+        width=old_pic.width if full_width else None,
+        height=old_pic.height if full_height else None,
+    )
+
+    old_pic_element = cast(Element, old_pic._element)
+    old_pic_element.addnext(new_pic._element)
+    parent = old_pic_element.getparent()
+    if parent is not None:
+        parent.remove(old_pic_element)
+
+    new_pic.name = old_pic.name
+    return new_pic
+
+
+def replace_image_by_name(
+    slide: Slide,
+    name: str,
+    image: Path | str | IO[bytes],
+    full_width: bool = True,
+    full_height: bool = True,
+):
+    """Shorthand for :func:`pptxfill.find_shape_by_name` + :func:`pptxfill.replace_image`
+
+    Args:
+        slide: target slide
+        name: target shape name
+        image: new image file
+        full_width: stretch to original shape's width
+        full_height: stretch to original shape's height
+    """
+
+    return replace_image(
+        slide,
+        find_shape_by_name(slide, name),
+        image,
+        full_width=full_width,
+        full_height=full_height,
+    )

pptxfill/slides.py

@@ -0,0 +1,93 @@
+import io
+from copy import deepcopy
+
+from pptx.shapes.picture import Picture
+from pptx.slide import Slide, SlideLayout, Slides
+
+
+def insert_slide(slides: Slides, layout: SlideLayout, position: int) -> Slide:
+    """Insert a new slide into the slide list
+
+    Args:
+        slides: the slide list (usually :attr:`pptx.presentation.Presentation.slides`)
+        layout: layout to base the new slide off
+        position: index where the new slide will be inserted
+
+    Returns:
+        the new slide
+    """
+
+    new_slide = slides.add_slide(layout)
+
+    slide_ids = slides._sldIdLst
+    new_id = slide_ids[-1]
+    slide_ids.remove(new_id)
+    slide_ids.insert(position, new_id)
+
+    return new_slide
+
+
+def copy_slide_content(source: Slide, target: Slide):
+    """Copy XML tree and images to the new slide"""
+
+    for shape in target.shapes:
+        target.shapes.element.remove(shape.element)
+
+    for shape in source.shapes:
+        if isinstance(shape, Picture):
+            img = io.BytesIO(shape.image.blob)
+            new_shape = target.shapes.add_picture(
+                img,
+                left=shape.left,
+                top=shape.top,
+                width=shape.width,
+                height=shape.height,
+            )
+            new_shape.name = shape.name
+        else:
+            target.shapes._spTree.insert_element_before(
+                deepcopy(shape.element), "p:extList"
+            )
+
+
+def delete_slide(slides: Slides, index: int):
+    """Delete slide at index
+
+    Args:
+        slides: the slide list (usually :attr:`pptx.presentation.Presentation.slides`)
+        index: target index
+    """
+    slides._sldIdLst.remove(slides._sldIdLst[index])
+
+
+def multiply_slide(slides: Slides, source: Slide, n: int) -> list[Slide]:
+    """Replace a single slide with N copies of itself
+
+    Useful for templating where you need a certain slide to repeat.
+    The new slides will be inserted at the original slide's index
+    and will have the original slides's content copied into them.
+
+    Args:
+        slides: the slide list (usually :attr:`pptx.presentation.Presentation.slides`)
+        source: template slide
+        n: number of new slides
+
+    Returns:
+        list of slides with length N
+    """
+
+    source_index = slides.index(source)
+
+    if n == 0:
+        delete_slide(slides, source_index)
+        return []
+    else:
+        slide_list = [source]
+
+        for _ in range(n - 1):
+            new_slide = insert_slide(slides, source.slide_layout, source_index)
+            copy_slide_content(source, new_slide)
+            slide_list.append(new_slide)
+
+        slide_list.reverse()
+        return slide_list

pptxfill/table.py

@@ -0,0 +1,105 @@
+from copy import deepcopy
+from itertools import islice
+from typing import Any, cast
+
+from lxml.etree import Element
+from pandas import DataFrame
+from pptx.oxml.text import CT_RegularTextRun
+from pptx.shapes.graphfrm import GraphicFrame
+from pptx.slide import Slide
+from pptx.table import Table, _Cell
+
+from .loader import merge_spans_with_similar_style
+from .walker import find_shape_by_name
+
+
+def get_cell_template(cell: _Cell):
+    for paragraph in cell.text_frame.paragraphs:
+        merge_spans_with_similar_style(paragraph._element)
+
+    return list(cast(Element, cell.text_frame._txBody))
+
+
+def set_cell_value(cell: _Cell, template: list[Element], value: Any):
+    text_body = cast(Element, cell.text_frame._txBody)
+    text_body.clear()
+
+    for template_element in template:
+        text_body.append(deepcopy(template_element))
+
+    for paragraph in cell.text_frame.paragraphs:
+        for tag in cast(Element, paragraph._element):
+            if isinstance(tag, CT_RegularTextRun):
+                tag.text = tag.text.format(value)
+
+
+def fill_table(
+    table: Table,
+    data: DataFrame,
+    skip_header: bool = True,
+    rownum: bool = False,
+):
+    """Fill :class:`pptx.table.Table` object with data from a :class:`pandas.DataFrame`
+
+    Does not expand the table, data will be cut off where the table ends.
+
+    In the template, the first row must be filled with format strings, for example:
+
+    .. list-table::
+
+       * - Name
+         - Number
+         - Percent
+       * - {}
+         - {:.2f}
+         - {}%
+
+    Args:
+        table: table in the presentation
+        data: fill with this data
+        skip_header: consider the first row the header, begin filling table from the second row
+        rownum: fill the first column with row numbers, data begins from the second column
+    """
+
+    row_start = 1 if skip_header else 0
+    height = min(len(table.rows) - row_start, len(data))
+
+    template = [
+        get_cell_template(table.cell(row_start, i)) for i in range(len(table.columns))
+    ]
+
+    if rownum:
+        for y, index in enumerate(islice(data.index, height)):
+            set_cell_value(table.cell(row_start + y, 0), template[0], str(index))
+
+    col_start = 1 if rownum else 0
+    width = min(len(table.columns) - col_start, len(data.columns))
+
+    for x, (_, column) in enumerate(islice(data.items(), width)):
+        for y, value in enumerate(islice(column, height)):
+            set_cell_value(
+                table.cell(row_start + y, col_start + x),
+                template[col_start + x],
+                value,
+            )
+
+
+def fill_table_by_name(
+    slide: Slide,
+    name: str,
+    data: DataFrame,
+    skip_header: bool = True,
+    rownum: bool = False,
+):
+    """Shorthand for :func:`pptxfill.find_shape_by_name` + :func:`pptxfill.fill_table`
+
+    Args:
+        slide: target slide
+        name: target shape's name
+        data: fill with this data
+        skip_header: consider the first row the header, begin filling table from the second row
+        rownum: fill the first column with row numbers, data begins from the second column
+    """
+    table = find_shape_by_name(slide, name, GraphicFrame).table
+    fill_table(table, data, skip_header=skip_header, rownum=rownum)
+    return table

pptxfill/text.py

@@ -0,0 +1,23 @@
+from typing import cast
+
+from lxml.etree import Element
+from pptx.oxml.text import CT_RegularTextRun
+from pptx.shapes.autoshape import Shape
+from pptx.slide import Slide
+
+from .walker import walk_shapes
+
+
+def format_text_on_slide(slide: Slide, **format_args):
+    """Walk the slides's shape tree, applying :meth:`str.format` to each text frame
+
+    Args:
+        slide: the target slide
+        *format_args: identical to :meth:`str.format` arguments
+    """
+
+    for shape in walk_shapes(slide, Shape):
+        for paragraph in shape.text_frame.paragraphs:
+            for tag in cast(Element, paragraph._element):
+                if isinstance(tag, CT_RegularTextRun):
+                    tag.text = tag.text.format(**format_args)

pptxfill/walker.py

@@ -0,0 +1,48 @@
+from typing import Iterator
+
+from pptx.shapes.base import BaseShape
+from pptx.shapes.group import GroupShape
+from pptx.shapes.shapetree import _BaseGroupShapes
+from pptx.slide import Slide
+
+
+def walk_group_shapes[T: BaseShape](
+    group: _BaseGroupShapes, t: type[T] = BaseShape
+) -> Iterator[T]:
+    for shape in group:
+        if isinstance(shape, t):
+            yield shape
+
+        if isinstance(shape, GroupShape):
+            yield from walk_group_shapes(shape.shapes, t)
+
+
+def walk_shapes[T: BaseShape](slide: Slide, t: type[T] = BaseShape) -> Iterator[T]:
+    """Walks the shape tree of the slide, visiting each :class:`GroupShape <pptx.shapes.group.GroupShape>` contents
+
+    Args:
+        slide: target slide
+        t: filter by shape type (if omitted, will visit all shapes)
+    """
+
+    yield from walk_group_shapes(slide.shapes, t)
+
+
+def find_shape_by_name[T: BaseShape](
+    slide: Slide, name: str, t: type[T] = BaseShape
+) -> T:
+    """Walk the slide's shape tree and find shape with the given name
+
+    Args:
+        slide: target slide
+        name: target shape name
+        t: target shape's type
+
+    Raises:
+        RuntimeError: If shape wasn't found
+    """
+    for shape in walk_shapes(slide, t):
+        if shape.name == name:
+            return shape
+
+    raise RuntimeError(f"Shape '{name}' of type {t} not found")

pptxfill-0.2.5.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: pptxfill
+Version: 0.2.5
+Summary: Add your description here
+Project-URL: Repository, https://gitlab.com/csml-tools/pptxfill/
+Project-URL: Documentation, https://csml-tools.gitlab.io/pptxfill/
+Requires-Python: >=3.13
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: types-lxml>=2026.1.1
+Description-Content-Type: text/markdown
+
+# pptxfill
+
+**pptxfill** is a templating library for PowerPoint presentations.
+
+Unlike other similar template engines, this one does not rely on Slide Layouts,
+instead using a more flexible system similar to ones used for Word documents,
+where you can substitute variables in text blocks using string formatting,
+replace arbitrary images and fill tables with data.
+
+[Documentation](https://csml-tools.gitlab.io/pptxfill/)
+
+## Installation:
+
+```
+uv add pptxfill
+```
+
+or 
+
+```
+pip install pptxfill
+```

pptxfill-0.2.5.dist-info/RECORD

@@ -0,0 +1,11 @@
+pptxfill/__init__.py,sha256=T-OZylf9hyoqJ9WiKqSEg8ZYYbnrS141uF2spkmWgbU,607
+pptxfill/eq.py,sha256=JlZ1f5tzKpgtrWistRY_8E5MzWLtOt8m5Jrc57CSJ-o,1927
+pptxfill/loader.py,sha256=K7vaBHaJQ6gqtWblmgmE_TG3EgGRqgJGd079TL5KsMo,1462
+pptxfill/picture.py,sha256=-FQMNlczPgw0fP3mvaQknuUdWG7s83ZnMpkAeEjavEA,1886
+pptxfill/slides.py,sha256=bqLtTaQaAmwS0Y8aP2Mz7DgUqMiG77W6bFaRMwmCMoo,2643
+pptxfill/table.py,sha256=KNrAN6t2lL7Zmvu6Q1SnIRpoItpzwOg6yG8UBSvjeGs,3248
+pptxfill/text.py,sha256=5saIUGwm58y2HjeOTHNE0GWcPFkgPCu1Xdp1OvgfjwQ,733
+pptxfill/walker.py,sha256=uXYo7SDXJ4rRaK2sJg0I47bp44AacpdmL9U4ownyOuc,1346
+pptxfill-0.2.5.dist-info/METADATA,sha256=YUqmgQlaxZkC6Q3loD1S7xxS4qnfunVkP8jrhHbCSmc,883
+pptxfill-0.2.5.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pptxfill-0.2.5.dist-info/RECORD,,

pptxfill-0.2.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any