pptxfill 0.2.5__tar.gz

pptxfill-0.2.5/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+/console.py
+.ipynb_checkpoints
+/example/output.pptx
+
+/docs/_build

pptxfill-0.2.5/.gitlab-ci.yml

@@ -0,0 +1,38 @@
+variables:
+  # GitLab CI creates a separate mountpoint for the build directory,
+  # so we need to copy instead of using hard links.
+  UV_VERSION: "0.9.22"
+  PYTHON_VERSION: "3.12"
+  BASE_LAYER: bookworm-slim
+  UV_LINK_MODE: copy
+  UV_CACHE_DIR: .uv-cache
+
+publish:
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v/
+  cache:
+    - key:
+        files:
+          - uv.lock
+      paths:
+        - $UV_CACHE_DIR
+  script:
+    - uv build
+    - uv publish --token "$UV_PUBLISH_TOKEN"
+    - uv cache prune --ci
+
+docs:
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v/
+  cache:
+    - key:
+        files:
+          - uv.lock
+      paths:
+        - $UV_CACHE_DIR
+  script:
+    - uv run --group dev sphinx-build docs public
+    - uv cache prune --ci
+  pages: true

pptxfill-0.2.5/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.5.28
+    hooks:
+      - id: uv-lock
+  # Apply version tag whenever version changes in pyproject.toml
+  - repo: https://gitlab.com/snorkysnark/pyproject-auto-tag
+    rev: v0.3.0
+    hooks:
+      - id: pyproject-auto-tag
+
+default_install_hook_types: [pre-commit, post-commit]

pptxfill-0.2.5/.python-version

@@ -0,0 +1 @@
+3.13

pptxfill-0.2.5/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,22 @@
+# 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/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pptxfill-0.2.5/docs/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+
+sys.path.append(".")
+
+project = "pptxfill"
+copyright = "2026, snorkysnark"
+author = "snorkysnark"
+release = "0.2.5"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]
+
+napoleon_google_docstring = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pptx": ("https://python-pptx.readthedocs.io/en/latest/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+}
+autodoc_typehints = "both"

pptxfill-0.2.5/docs/examples.rst

@@ -0,0 +1,159 @@
+Examples
+========
+
+.. |br| raw:: html
+
+   <br />
+
+Loading your template
+---------------------
+
+Since this library doesn't use Slide Layouts, your template is just a regular presentation. |br|
+The template used in these examples: `template.pptx <https://gitlab.com/csml-tools/pptxfill/-/blob/main/example/template.pptx?ref_type=heads>`_
+
+Ref: :func:`pptxfill.load_template`
+
+.. code-block:: python
+
+   from pptxfill import load_template
+
+   template = load_template("template.pptx")
+
+Text formatting
+---------------
+
+Apply string formatting to all text blocks on Slide 0. |br|
+Python's `string formatting rules <https://www.w3schools.com/python/python_string_formatting.asp>`_ apply, including format specifiers for numbers.
+
+Ref: :func:`pptxfill.format_text_on_slide`
+
+.. code-block:: python
+
+   from pptxfill import format_text_on_slide
+
+   format_text_on_slide(
+       template.slides[0],
+       name="Example University",
+       publications=2932,
+       fwci=7.3658,
+   )
+
+.. image:: img/example_text_1.png
+
+.. image:: img/example_text_2.png
+
+Images
+------
+
+First, open the `Selection Pane <https://support.microsoft.com/en-us/powerpoint/use-the-selection-pane-to-manage-objects-in-documents>`_
+in PowerPoint (``Alt + F10``) and give your placeholder a unique name.
+
+.. image:: img/selection-pane.png
+
+Then it can be replaced by the target image.
+
+Set ``full_width=True`` or ``full_height=True`` to stretch the image to the placeholder's width and height
+
+Ref: :func:`pptxfill.replace_image_by_name`
+
+.. code-block:: python
+
+   from pptxfill import replace_image_by_name
+
+   replace_image_by_name(template.slides[0], "logo", "logo.png")
+
+Tables
+------
+
+Fill a PowerPoint table with the contents of a pandas DataFrame. |br|
+Example data: `data.csv <https://gitlab.com/csml-tools/pptxfill/-/blob/main/example/data.csv?ref_type=heads>`_
+
+Ref: :func:`pptxfill.fill_table_by_name`
+
+.. code-block:: python
+
+   import pandas as pd
+   from pptxfill import fill_table_by_name
+
+   data = pd.read_csv("data.csv")
+   fill_table_by_name(template.slides[0], "table", data)
+
+Since by default ``skip_header=True``, the first row would not be filled.
+
+The folliwing row must contain string templates, where data would be inserted
+using :meth:`str.format` with a single argument: ``string.format(value)``)
+
+.. image:: img/example_table_1.png
+
+.. image:: img/example_table_2.png
+
+This function *does not* automatically expand the table,
+so the data will be cut off where the table ends
+
+Repeating slides
+----------------
+
+Sometimes you may wish to duplicate the slide of the original presentation.
+
+Since this would modify :attr:`template.slides <pptx.presentation.Presentation.slides>`,
+you can make a copy of it to still be able to refere to slides by their original indices:
+
+.. code-block:: python
+
+   template_slides = list(template.slides)
+
+Let's make Slide #2 repeat 5 times:
+
+Ref: :func:`pptxfill.multiply_slide`
+
+.. code-block:: python
+
+   from pptxfill import multiply_slide
+
+   repeating_slides = multiply_slide(template.slides, template_slides[1], 5)
+   for i, slide in enumerate(repeating_slides):
+       format_text_on_slide(slide, slide_num=i + 1)
+
+Split table into multiple slides
+--------------------------------
+
+If you wish to show the entire DataFrame's content, you can split it into multiple slides:
+
+.. code-block:: python
+
+    from pptxfill import find_shape_by_name
+    from pptx.shapes.graphfrm import GraphicFrame
+
+    table = find_shape_by_name(template_slides[1], "table", GraphicFrame).table
+
+    # Since by default skip_header=True, the first row is not filled with data
+    table_size = len(table.rows) - 1
+    table_slides = multiply_slide(
+        template.slides,
+        template_slides[1],
+        math.ceil(len(data) / table_size)
+    )
+
+    for i, slide in enumerate(table_slides):
+        format_text_on_slide(slide, slide_num=i + 1)
+        fill_table_by_name(
+            slide,
+            "table",
+            data.iloc[i * table_size : (i + 1) * table_size],
+            rownum=True,
+        )
+
+Here, we are using ``rownum=True`` to display the row index in the first column.
+
+.. image:: img/example_multi_table_1.png
+
+.. image:: img/example_multi_table_2.png
+
+.. image:: img/example_multi_table_3.png
+
+Exporting
+---------
+
+.. code-block:: python
+
+   template.save("result.pptx")

pptxfill-0.2.5/docs/index.rst

@@ -0,0 +1,35 @@
+.. pptxfill documentation master file, created by
+   sphinx-quickstart on Mon Aug 24 14:38:25 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+pptxfill documentation
+========================
+
+**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.
+
+Installation
+------------
+
+.. code-block::
+
+   uv add pptxfill --index https://gitlab.com/api/v4/groups/101754947/-/packages/pypi/simple
+
+or
+
+.. code-block::
+
+   pip install --index-url https://gitlab.com/api/v4/groups/101754947/-/packages/pypi/simple pptxfill
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   examples
+   reference

pptxfill-0.2.5/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

pptxfill-0.2.5/docs/reference.rst

@@ -0,0 +1,46 @@
+API Reference
+=============
+
+Template
+--------
+
+.. autofunction:: pptxfill.load_template
+
+Shape Tree
+----------
+
+.. autofunction:: pptxfill.walk_shapes
+
+.. autofunction:: pptxfill.find_shape_by_name
+
+
+Slide Manipulation
+------------------
+
+.. autofunction:: pptxfill.copy_slide_content
+
+.. autofunction:: pptxfill.insert_slide
+
+.. autofunction:: pptxfill.delete_slide
+
+.. autofunction:: pptxfill.multiply_slide
+
+Text
+----
+
+.. autofunction:: pptxfill.format_text_on_slide
+
+Images
+------
+
+.. autofunction:: pptxfill.replace_image
+
+.. autofunction:: pptxfill.replace_image_by_name
+
+Tables
+------
+
+.. autofunction:: pptxfill.fill_table
+
+.. autofunction:: pptxfill.fill_table_by_name
+

pptxfill-0.2.5/example/data.csv

@@ -0,0 +1,51 @@
+name,cost,percentage
+logistics,1783,27.418243245046312
+league,3737,3.3290774158836633
+spectrograph,2635,50.07984744768956
+noodle,3245,30.434240332249495
+budget,2841,61.96213623361662
+chili,2201,37.97385252086871
+wonderful,4939,74.8964289076211
+tempo,4828,45.28791637745536
+knowledge,4512,68.6937978433078
+legend,2315,90.10919179049583
+needy,1588,73.43247827182032
+divide,4765,63.63810285920232
+reliability,3871,32.03240986723951
+interlay,3475,33.249377311697096
+bowling,2585,22.03289180796749
+animated,4967,93.45380236016199
+fur,2768,37.45503608654145
+spread,1234,83.06500436711761
+horst,1755,9.120487683357359
+meeting,3808,52.405902077128474
+spree,1309,66.72493850677978
+cloudy,4214,97.41879061022084
+frenzy,4007,63.620655039985586
+fog,4919,21.67586948741935
+macro,3208,23.05521140069565
+hearing,3821,1.306688325996963
+settler,2208,15.73287084523165
+underpants,1044,39.204788529376664
+starboard,2712,84.98825725278499
+former,4858,26.053151850542566
+monopoly,3870,48.57777263757497
+rag,1255,23.219516416486996
+wake,3207,18.642743704938557
+elevation,1990,89.36114451631306
+colonization,1320,84.41680453820814
+nice,4346,10.194224035576793
+king,3682,99.506334861964
+pulley,1309,11.529774855044206
+edge,4319,59.955557737761865
+cinema,3713,88.72685001257503
+motorboat,1525,96.67543307972387
+steward,4690,67.82904861043019
+helmet,3917,54.24036679578976
+gambling,2594,2.016212327948097
+rainstorm,3893,1.1354635256942913
+algorithm,4883,70.74882506429151
+restructuring,4050,60.716841589077
+washtub,3875,2.8019898207405136
+chivalrous,1580,75.18100874664756
+flashy,3755,16.009085621452137

pptxfill-0.2.5/example/examply.py

@@ -0,0 +1,46 @@
+import math
+
+import pandas as pd
+from pptx.shapes.graphfrm import GraphicFrame
+
+from pptxfill import (
+    fill_table_by_name,
+    find_shape_by_name,
+    format_text_on_slide,
+    load_template,
+    multiply_slide,
+    replace_image_by_name,
+)
+
+template = load_template("template.pptx")
+template_slides = list(template.slides)
+
+format_text_on_slide(
+    template_slides[0],
+    name="Example University",
+    publications=2932,
+    fwci=7.3658,
+)
+
+replace_image_by_name(template_slides[0], "logo", "logo.png")
+
+data = pd.read_csv("data.csv")
+fill_table_by_name(template_slides[0], "table", data)
+
+table = find_shape_by_name(template_slides[1], "table", GraphicFrame).table
+# Since by default skip_header=True, the first row is not filled with data
+table_size = len(table.rows) - 1
+table_slides = multiply_slide(
+    template.slides, template_slides[1], math.ceil(len(data) / table_size)
+)
+
+for i, slide in enumerate(table_slides):
+    format_text_on_slide(slide, slide_num=i + 1)
+    fill_table_by_name(
+        slide,
+        "table",
+        data.iloc[i * table_size : (i + 1) * table_size],
+        rownum=True,
+    )
+
+template.save("result.pptx")

pptxfill-0.2.5/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-0.2.5/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
+    )