Merge pull request #9 from MHoroszowski/feature/customxml

feat: customXml support (1.2.0); supersedes #7 and #8

Author: MHoroszowski

.github/workflows/ci.yml

@@ -1,21 +1,47 @@
 name: ci
 
+# Runs on every push to a branch in this repo and on every pull request
+# targeting master. Tags push the same code through publish.yml separately.
+
 on:
-  pull_request:
-    branches: [ master ]
   push:
     branches:
       - master
       - develop
+      - "release/**"
+      - "feature/**"
+      - "ci/**"
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: python -m pip install --upgrade ruff
+      - name: ruff check
+        run: ruff check src tests
+      - name: ruff format check
+        run: ruff format --check src tests
+        continue-on-error: true  # advisory until format pass is run repo-wide
 
-  build:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
     steps:
@@ -26,11 +52,35 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Display Python version
         run: python -c "import sys; print(sys.version)"
-      - name: Install test dependencies
+      - name: Install package and test deps
         run: |
-          pip install .
-          pip install -r requirements-test.txt
-      - name: Test with pytest
-        run: pytest --cov=pptx --cov-report term-missing tests
-      - name: Acceptance tests with behave
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install -r requirements-test.txt
+      - name: Unit + integration tests (pytest)
+        run: pytest --cov=pptx --cov-report=term-missing tests
+      - name: Acceptance tests (behave)
         run: behave --stop
+
+  build-check:
+    name: Build sdist and wheel (smoke)
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Verify metadata renders
+        run: python -m twine check dist/*
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7

.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: publish
+
+# Builds and publishes python-pptx-extended to PyPI using PyPI Trusted
+# Publishing (OIDC). No long-lived API token is stored in repo secrets — the
+# workflow's identity is verified by PyPI against the configured Trusted
+# Publisher (see one-time setup in the PR description).
+#
+# Triggers:
+#   - GitHub Release published (recommended path: cut a release in the GH UI)
+#   - Manual workflow_dispatch (override / re-run)
+#
+# Tag pushes alone do not trigger this; create a Release pointing at the tag.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+      - name: Build distributions
+        run: python -m build
+      - name: Verify metadata renders
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/python-pptx-extended/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

HISTORY.rst

@@ -3,6 +3,42 @@
 Release History
 ---------------
 
+1.2.0 (2026-05-05)
+++++++++++++++++++
+
+Adds first-class support for OOXML customXml — the mechanism Office.js,
+SharePoint, and VSTO add-ins use to embed structured application data in
+``.pptx`` files. See ``docs/user/custom-xml.rst`` for the user guide and
+``docs/dev/analysis/customxml.rst`` for the OOXML analysis.
+
+- feature: ``Presentation.custom_properties`` — Mapping wrapper over
+  ``/docProps/custom.xml`` (Custom Document Properties; visible in
+  PowerPoint's *File → Properties → Advanced* UI). Type-dispatched
+  ``__setitem__`` plus explicit ``set_string`` / ``set_int`` / ``set_float`` /
+  ``set_bool`` / ``set_datetime`` setters when Python type inference does the
+  wrong thing.
+- feature: ``Presentation.custom_xml_parts`` — Sequence wrapper over the
+  package's customXml data parts. ``add(xml, *, name=, datastoreItem_id=,
+  schema_refs=, scope=)`` supports both presentation-scoped (Office.js
+  default) and package-scoped (VSTO / SharePoint) topologies. Lookup via
+  index, partname tail, ``by_guid(...)``, or ``by_name(...)``.
+- feature: ``CustomXmlParts.add_string_blob(name, content, mime_hint=,
+  encoding=)`` — convenience for the common "embed a string verbatim and
+  read it back" case (e.g. round-trip a markdown source document).
+- feature: round-trip safety with files written by other tools — PPTX files
+  containing customXml parts authored by SharePoint, Office.js, or VSTO load
+  and save without losing their content.
+
+1.1.0 (2026-05-01)
+++++++++++++++++++
+
+- Fork of python-pptx 1.0.2 published as ``python-pptx-extended``.
+- feature: full shadow effect API on ``ShadowFormat``
+- feature: bullet and numbered list paragraph formatting
+- feature: per-edge table cell borders
+- feature: ``cap_style`` and ``join_style`` properties on ``LineFormat``
+- feature: line-end shape types
+
 1.0.2 (2024-08-07)
 ++++++++++++++++++