python-pptx2 2.20.0__tar.gz → 3.1.0__tar.gz

{python_pptx2-2.20.0 → python_pptx2-3.1.0}/HISTORY.rst

@@ -15,6 +15,148 @@ can sit beside both ``python-pptx`` (``pptx``) and ``power-pptx``
 .. _`scanny/python-pptx`: https://github.com/scanny/python-pptx
 
 
+3.1.0 (2026-09-03)
+++++++++++++++++++
+
+Slide-design layer: the everyday blocks a content slide is made of, a
+set of curated palettes, a one-image visual check, and a design guide
+that leads generated decks toward calm, consistent layouts.
+
+Added
+.....
+
+* ``pptx2.design.blocks`` (re-exported at the package root):
+
+  * ``add_card(slide, bbox, title=, body=, fill=, line=, pad_pt=, ...)``
+    — one flat rounded surface (``shadow.clear()``, real
+    ``corner_radius``, tint *or* hairline outline) with a padded, fitted
+    title and body. ``body`` may be a list, rendered as bullets
+    (``numbered=True`` for a numbered list). Returns ``Card`` with
+    ``card`` / ``title_box`` / ``body_box`` and ``inner`` (the padded
+    content ``BBox``).
+  * ``add_bullets(slide, bbox, items=, size_pt=, numbered=, gap_pt=, ...)``
+    — real ``a:buChar`` / ``a:buAutoNum`` bullets with a hanging indent
+    that scales with the type size, item spacing, and fit-to-box that
+    never drops below ``min_size_pt``. Numbering continues across items.
+  * ``add_picture_fit(slide, image, bbox, mode="contain"|"cover", align=,
+    caption=, ...)`` — places a picture inside a box without distortion,
+    letter-boxed or cropped symmetrically to fill, with an optional
+    caption. Returns ``FittedPicture`` with the occupied ``frame``.
+
+  All three tag their shapes with one ``lint_group``.
+
+* ``pptx2.design.palettes`` (re-exported at the package root):
+  ``Palette`` with named roles (``paper``, ``surface``, ``line``, ``ink``,
+  ``muted``, ``accent``, ``accent_soft``, ``accent_ink``), ``PALETTES``
+  (``slate``, ``linen``, ``forest``, ``plum``, ``ember``, ``navy``,
+  ``graphite``) that pass WCAG AA contrast for their intended pairings,
+  ``palette(name)``, and ``Palette.dark()`` for title / section slides.
+
+* ``pptx2.render.render_contact_sheet(prs, out_path, cols=, thumb_width=,
+  ...)`` and ``Presentation.render_contact_sheet(...)`` — every slide
+  rendered and tiled into a single numbered PNG.
+
+Skill
+.....
+
+* New ``references/slide-design.md``: grid and margins, type scale,
+  one-palette colour, surfaces done well, whitespace, pictures, tables /
+  diagrams / charts, deliberate vs accidental overlaps, a twelve-archetype
+  slide catalog with runnable code, and the visual check.
+* ``SKILL.md`` cheat sheet, house rules and anti-patterns updated for the
+  blocks, palettes and contact sheet; ``design.md`` and ``render.md``
+  cross-reference them.
+
+
+3.0.0 (2026-09-01)
+++++++++++++++++++
+
+Backward-incompatible
+.....................
+
+* ``Presentation.import_slide`` and ``pptx2.compose.import_slide`` now
+  take the paper-pptx validating signature —
+  ``import_slide(source_prs, slide, *, mode, ...)`` returning
+  ``ImportReport``. The previous part-level engine (including its
+  ``merge_master=`` knobs) remains available unchanged at
+  ``pptx2._slide_importer.import_slide``, and the old deck-integration
+  tests exercise it directly.
+
+Merged
+......
+
+* **Ported the paper-pptx agent-first structure editor** (bootstrap
+  commit 700b5f1f from ``paper-instruments/paper-pptx``, a fork of
+  python-pptx 1.0.2). python-pptx2 gains paper-pptx's whole editing,
+  inspection, and safety surface, import-renamed from ``pptx`` to
+  ``pptx2``:
+
+  - ``pptx2.inspect`` — effective values with provenance
+    (``effective_font()``, ``effective_paragraph_format()``,
+    ``effective_shape_format()``), visibility-complete ``inspect_text()``
+    and a deterministic ``inspect_deck()`` manifest.
+  - ``pptx2.edit`` / ``pptx2.diff`` — ``replace_text()`` that preserves
+    untouched run formatting, and ``diff_decks()`` structural diffing.
+  - ``pptx2.compose`` — paper-pptx's validating
+    ``import_slide(dest, source, slide, mode=...)`` / ``append_deck()``
+    returning |ImportReport| (the older part-level engine remains at
+    ``pptx2._slide_importer``); ``Presentation.import_slide`` now takes
+    the paper-pptx signature.
+  - ``pptx2.hf`` (``Presentation.apply_footers()`` / ``Slide.apply_footers()``
+    / ``header_footers`` flags), ``pptx2.rebind``
+    (``Slide.rebind_layout()``), ``pptx2.slideops``,
+    ``pptx2._transaction`` / ``_ownership`` / ``_zipguard`` /
+    ``errors``, the ``paper_pptx_doctor`` CLI, and the full
+    ``tests/paper`` contract suite. (The bootstrap's ``pptx2.scrub``
+    module was removed again by ported commit #14, matching upstream
+    paper-pptx.)
+  - Slide ops: ``Slides.clone/delete/move/reorder`` (``move`` and
+    ``reorder`` merged with the existing python-pptx2 int/Slice APIs),
+    ``SlideShapes.add_copy/delete/move`` and strict ``*_by_name``
+    addressing, ``Table.insert_row/insert_column/delete_row/delete_column``
+    with merge guards, ``Picture.replace_image()``,
+    ``Chart.replace_data_safe()``, ``TextFrame.normalize_autofit()``,
+    ``_Run.effective_font()``, ``_Paragraph.bullet`` (``BulletFormat``),
+    notes-text read/replace that never creates a notes slide, and an
+    atomic, deterministic (epoch-stamped) package ``save()``.
+
+* Follow-up paper-pptx fixes ported in sequence (their commit ids in
+  ours): zipguard keeps only structural checks and drops numeric
+  resource ceilings (#15); the inspect group-depth guard is gone (#19);
+  the bootstrap's ``scrub`` module was removed again (#14);
+  ``effective_paragraph_format`` resolves *inherited* bullets with
+  provenance, and deck diff reports bullet typeface/size changes (#16,
+  #27); ``Presentation.batch()`` validates once per block and
+  ``save()`` refuses inside it, slide-partname allocation and
+  duplicate-partname writes are fixed (#17); packages with leading
+  bytes are refused (#21); ``save()`` accepts every upstream
+  destination (write-only handles, unseekable sinks), writing at the
+  caller's cursor and resolving symlinks for path destinations (#23);
+  untyped ZIP members refuse while unreferenced parts are accepted
+  (#24); ZIP directory entries are accepted (#25); relationship
+  refusals are retyped with remedies (#26); ``patch_save`` treats
+  semantically equivalent OPC registries (other producers' absolute
+  rels, content-type fallbacks) as unchanged (#36); table expansion is
+  composable — ``insert_row/insert_column(copy_format_from=...)`` and
+  ``_Cell.extend_merge()`` (#37); text edits, layout selection,
+  placeholder reconciliation, section selection, and deck-diff
+  alignment all match by stable *identity*, refusing ambiguity instead
+  of guessing (#40–#46, #38 docs).
+
+* The low-level slide-import engine keeps its part-level API at
+  ``pptx2._slide_importer`` with the ``merge_master=`` knobs; the
+  public ``Presentation.import_slide`` /
+  ``pptx2.compose.import_slide`` now take the paper-pptx
+  ``(source_prs, slide, mode=...)`` signature returning
+  ``ImportReport``.
+
+* A zip-timestamp fix that benefits every save: package entries are
+  stamped with the 1980 zip epoch, so saving the same package state
+  twice produces byte-identical files, and the math-namespace
+  enrichment of slide XML only happens when a slide actually carries
+  equation markup (math-free decks round-trip byte-identically).
+
+
 2.20.0 (2026-08-30)
 +++++++++++++++++++
 

{python_pptx2-2.20.0/src/python_pptx2.egg-info → python_pptx2-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-pptx2
-Version: 2.20.0
+Version: 3.1.0
 Summary: Create, read, and update PowerPoint 2007+ (.pptx) files. Fork of power-pptx / python-pptx, published as python-pptx2.
 Author: Matěj Štágl
 Author-email: stagl@wattlescript.org
@@ -34,7 +34,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: Pillow>=3.3.2
+Requires-Dist: Pillow>=10.3.0
 Requires-Dist: XlsxWriter>=0.5.7
 Requires-Dist: lxml>=3.1.0
 Requires-Dist: typing_extensions>=4.9.0

{python_pptx2-2.20.0 → python_pptx2-3.1.0}/features/steps/table.py

@@ -109,9 +109,9 @@ def when_I_assign_origin_cell_eq_table_cell_0_0(context):
     context.origin_cell = context.table_.cell(0, 0)
 
 
-@when("I assign other_cell = table.cell(1, 1)")
-def when_I_assign_other_cell_eq_table_cell_1_1(context):
-    context.other_cell = context.table_.cell(1, 1)
+@when("I assign other_cell = table.cell({row_idx:d}, {col_idx:d})")
+def when_I_assign_other_cell_eq_table_cell(context, row_idx, col_idx):
+    context.other_cell = context.table_.cell(row_idx, col_idx)
 
 
 @when("I assign table.first_col = True")
@@ -154,6 +154,11 @@ def when_I_call_origin_cell_merge_other_cell(context):
     context.origin_cell.merge(context.other_cell)
 
 
+@when("I call origin_cell.extend_merge(other_cell)")
+def when_I_call_origin_cell_extend_merge_other_cell(context):
+    context.origin_cell.extend_merge(context.other_cell)
+
+
 @when("I add a row to the table")
 def when_I_add_a_row_to_the_table(context):
     context.table_.rows.add_row()
@@ -217,18 +222,18 @@ def then_cell_text_eq_value(context, value):
     assert actual == expected, 'cell.text == "%s"' % actual
 
 
-@then("cell.span_height == {int_lit}")
-def then_cell_span_height_eq(context, int_lit):
+@then("{cell_ref}.span_height == {int_lit}")
+def then_cell_span_height_eq(context, cell_ref, int_lit):
     expected = int(int_lit)
-    actual = context.cell.span_height
-    assert actual is expected, "cell.span_height == %s" % actual
+    actual = getattr(context, cell_ref).span_height
+    assert actual == expected, "%s.span_height == %s" % (cell_ref, actual)
 
 
-@then("cell.span_width == {int_lit}")
-def then_cell_span_width_eq(context, int_lit):
+@then("{cell_ref}.span_width == {int_lit}")
+def then_cell_span_width_eq(context, cell_ref, int_lit):
     expected = int(int_lit)
-    actual = context.cell.span_width
-    assert actual is expected, "cell.span_width == %s" % actual
+    actual = getattr(context, cell_ref).span_width
+    assert actual == expected, "%s.span_width == %s" % (cell_ref, actual)
 
 
 @then("cell.vertical_anchor == {value}")

{python_pptx2-2.20.0 → python_pptx2-3.1.0}/features/tbl-cell.feature

@@ -65,6 +65,21 @@ Feature: Table cell proxy objects
       And other_cell.text == ""
 
 
+  Scenario: _Cell.extend_merge()
+    Given a 3x3 Table object with cells a to i as table
+     When I assign origin_cell = table.cell(0, 0)
+      And I assign other_cell = table.cell(1, 1)
+      And I call origin_cell.merge(other_cell)
+      And I assign other_cell = table.cell(2, 2)
+      And I call origin_cell.extend_merge(other_cell)
+     Then origin_cell.is_merge_origin is True
+      And other_cell.is_spanned is True
+      And origin_cell.span_height == 3
+      And origin_cell.span_width == 3
+      And origin_cell.text == "a\nb\nd\ne\nc\nf\ng\nh\ni"
+      And other_cell.text == ""
+
+
   Scenario: Merged cell size
     Given a 2x3 _MergeOriginCell object as cell
      Then cell.span_height == 2

{python_pptx2-2.20.0 → python_pptx2-3.1.0}/pyproject.toml

@@ -29,7 +29,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-    "Pillow>=3.3.2",
+    "Pillow>=10.3.0",
     "XlsxWriter>=0.5.7",
     "lxml>=3.1.0",
     "typing_extensions>=4.9.0",
@@ -175,3 +175,5 @@ pptx2 = [
 # Convenience CLI: `pptx2-skill install` ≈ `python -m pptx2.skill install`.
 pptx2-skill = "pptx2.skill.__main__:main"
 python-pptx2-skill = "pptx2.skill.__main__:main"
+# paper-pptx addition: package doctor CLI.
+paper-pptx-doctor = "paper_pptx_doctor:main"

python_pptx2-3.1.0/src/paper_pptx_doctor/__init__.py

@@ -0,0 +1,135 @@
+"""Verify that the installed ``pptx2`` import belongs to ``python-pptx2``.
+
+Adapted from paper-pptx's distribution doctor: same wheel-integrity
+checks (RECORD hashes for every ``pptx2`` package file), retargeted at
+the ``python-pptx2`` distribution and its ``__version__`` sentinel.
+"""
+
+from __future__ import annotations
+
+import base64
+import csv
+import hashlib
+import hmac
+import importlib
+import sys
+from importlib.metadata import Distribution, PackageNotFoundError, distribution
+from io import StringIO
+from pathlib import Path, PurePosixPath
+from typing import Iterable, Optional, Tuple
+
+
+class DoctorError(RuntimeError):
+    """The installed ``pptx2`` package cannot be trusted as ``python-pptx2``."""
+
+
+_REMEDY = "python -m pip install --force-reinstall python-pptx2"
+
+
+def verify_install() -> str:
+    """Verify distribution ownership, installed bytes, and the version sentinel.
+
+    Returns the installed ``python-pptx2`` version. Raises :class:`DoctorError`
+    without importing ``pptx2`` until its wheel-owned files have been checked.
+    """
+    dist = _installed_distribution("python-pptx2")
+    if dist is None:
+        raise DoctorError("python-pptx2 distribution metadata is missing")
+
+    _verify_pptx_record(dist)
+
+    try:
+        pptx2 = importlib.import_module("pptx2")
+    except Exception as exc:
+        raise DoctorError(f"pptx2 cannot be imported: {exc}") from exc
+
+    sentinel = getattr(pptx2, "__version__", None)
+    if sentinel is None:
+        raise DoctorError("pptx2.__version__ is missing")
+    if sentinel != dist.version:
+        raise DoctorError(
+            "pptx2.__version__ does not match the installed python-pptx2 "
+            f"version ({sentinel!r} != {dist.version!r})"
+        )
+    return dist.version
+
+
+def main() -> int:
+    """Console entry point for ``paper-pptx-doctor``."""
+    try:
+        version = verify_install()
+    except DoctorError as exc:
+        print(f"paper-pptx-doctor: FAIL: {exc}", file=sys.stderr)
+        print(f"Remedy: {_REMEDY}", file=sys.stderr)
+        return 1
+    print(f"paper-pptx-doctor: OK (python-pptx2 {version})")
+    return 0
+
+
+def _installed_distribution(name: str) -> Optional[Distribution]:
+    try:
+        return distribution(name)
+    except PackageNotFoundError:
+        return None
+
+
+def _verify_pptx_record(dist: Distribution) -> None:
+    record = dist.read_text("RECORD")
+    if record is None:
+        raise DoctorError("python-pptx2 RECORD is missing")
+
+    entries = tuple(
+        (relative_path, hash_spec)
+        for relative_path, hash_spec in _pptx_record_entries(record)
+        if hash_spec
+    )
+    if not entries:
+        raise DoctorError("python-pptx2 RECORD has no hashed pptx2 package files")
+
+    for relative_path, hash_spec in entries:
+        path = Path(dist.locate_file(relative_path))
+        if not path.is_file():
+            raise DoctorError(f"python-pptx2 file is missing: {relative_path}")
+        algorithm, expected = _parse_hash(hash_spec, relative_path)
+        actual = _file_digest(path, algorithm)
+        if not hmac.compare_digest(actual, expected):
+            raise DoctorError(f"python-pptx2 file hash mismatch: {relative_path}")
+
+
+def _pptx_record_entries(record: str) -> Iterable[Tuple[PurePosixPath, str]]:
+    for row in csv.reader(StringIO(record)):
+        if len(row) != 3:
+            raise DoctorError("python-pptx2 RECORD contains a malformed row")
+        raw_path, hash_spec, _size = row
+        path = PurePosixPath(raw_path)
+        if not path.parts or path.parts[0] != "pptx2":
+            continue
+        if path.is_absolute() or ".." in path.parts:
+            raise DoctorError(f"python-pptx2 RECORD contains an unsafe path: {raw_path}")
+        yield path, hash_spec
+
+
+def _parse_hash(hash_spec: str, relative_path: PurePosixPath) -> Tuple[str, str]:
+    try:
+        algorithm, expected = hash_spec.split("=", 1)
+        hashlib.new(algorithm)
+    except (TypeError, ValueError):
+        raise DoctorError(
+            f"python-pptx2 RECORD has an invalid hash for {relative_path}"
+        ) from None
+    if not expected:
+        raise DoctorError(
+            f"python-pptx2 RECORD has an invalid hash for {relative_path}"
+        )
+    return algorithm, expected.rstrip("=")
+
+
+def _file_digest(path: Path, algorithm: str) -> str:
+    digest = hashlib.new(algorithm)
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return base64.urlsafe_b64encode(digest.digest()).rstrip(b"=").decode("ascii")
+
+
+__all__ = ["DoctorError", "main", "verify_install"]

python_pptx2-3.1.0/src/paper_pptx_doctor/__main__.py

@@ -0,0 +1,5 @@
+"""Run ``paper-pptx-doctor`` with ``python -m paper_pptx_doctor``."""
+
+from . import main
+
+raise SystemExit(main())

{python_pptx2-2.20.0 → python_pptx2-3.1.0}/src/pptx2/__init__.py

@@ -9,6 +9,14 @@ import pptx2.exc as exceptions
 from pptx2.api import Presentation
 from pptx2.audit import AuditReport, audit
 from pptx2.geometry import BBox
+from pptx2.design.blocks import (
+    Card,
+    FittedPicture,
+    add_bullets,
+    add_card,
+    add_picture_fit,
+)
+from pptx2.design.palettes import PALETTES, Palette, palette
 from pptx2.design.components import (
     ArticleCard,
     Gauge,
@@ -57,7 +65,7 @@ from pptx2.parts.slide import (
 if TYPE_CHECKING:
     from pptx2.opc.package import Part
 
-__version__ = "2.20.0"
+__version__ = "3.1.0"
 
 sys.modules["pptx2.exceptions"] = exceptions
 del sys
@@ -91,6 +99,16 @@ __all__ = [
     "StatusPill",
     "StatStrip",
     "ArticleCard",
+    # Everyday slide blocks (hex-driven; no token setup required).
+    "add_card",
+    "add_bullets",
+    "add_picture_fit",
+    "Card",
+    "FittedPicture",
+    # Curated colour sets.
+    "Palette",
+    "PALETTES",
+    "palette",
 ]
 
 content_type_to_part_class_map: dict[str, type[Part]] = {

python_pptx2-3.1.0/src/pptx2/_ownership.py

@@ -0,0 +1,67 @@
+"""Attachment checks for live shape proxies used by paper-pptx operations."""
+
+from __future__ import annotations
+
+
+def require_shape_attached(shape, *, argument: str = "shape") -> None:
+    """Refuse a shape proxy whose XML is no longer attached to its remembered part."""
+    from pptx2.errors import TargetNotFoundError
+
+    element = getattr(shape, "_element", None)
+    try:
+        part_root = shape.part._element
+    except (AttributeError, ValueError):
+        part_root = None
+    root = element
+    while root is not None and root.getparent() is not None:
+        root = root.getparent()
+    if element is None or part_root is None or root is not part_root:
+        raise TargetNotFoundError(
+            "%s is stale: its shape was removed from the presentation" % argument
+        )
+    require_part_reachable(shape.part, argument=argument)
+
+
+def require_element_attached(element, part, *, argument: str) -> None:
+    """Refuse an element detached from the active root of its remembered part."""
+    from pptx2.errors import TargetNotFoundError
+
+    root = element
+    while root is not None and root.getparent() is not None:
+        root = root.getparent()
+    if root is not getattr(part, "_element", None):
+        raise TargetNotFoundError(
+            "%s is stale: its content was removed from the presentation" % argument
+        )
+    require_part_reachable(part, argument=argument)
+
+
+def require_shape_tree_attached(shapes, *, argument: str = "target shape tree") -> None:
+    """Refuse a shape collection that no longer wraps its part's active tree."""
+    from pptx2.errors import TargetNotFoundError
+
+    spTree = getattr(shapes, "_spTree", None)
+    part = shapes.part
+    require_element_attached(spTree, part, argument=argument)
+    live_spTree = part._element.cSld.spTree
+    if spTree is not live_spTree:
+        raise TargetNotFoundError(
+            "%s is stale: it is no longer the part's active shape tree" % argument
+        )
+
+
+def require_part_reachable(part, *, argument: str) -> None:
+    """Refuse a part proxy no longer reachable from its package root."""
+    from pptx2.errors import TargetNotFoundError, UnsupportedStructureError
+
+    try:
+        reachable = any(candidate is part for candidate in part.package.iter_parts())
+    except (AssertionError, AttributeError, KeyError, TypeError, ValueError) as exc:
+        raise UnsupportedStructureError(
+            "cannot verify %s ownership because the package relationship graph is broken (%s)"
+            % (argument, exc)
+        ) from exc
+    if not reachable:
+        raise TargetNotFoundError(
+            "%s is stale: its package part is no longer in the presentation" % argument
+        )