python-pptx2 2.13.0__py3-none-any.whl

pptx2/api.py

@@ -0,0 +1,49 @@
+"""Directly exposed API classes, Presentation for now.
+
+Provides some syntactic sugar for interacting with the pptx2.presentation.Package graph and also
+provides some insulation so not so many classes in the other modules need to be named as internal
+(leading underscore).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import IO, TYPE_CHECKING
+
+from pptx2.opc.constants import CONTENT_TYPE as CT
+from pptx2.package import Package
+
+if TYPE_CHECKING:
+    from pptx2 import presentation
+    from pptx2.parts.presentation import PresentationPart
+
+
+def Presentation(pptx: str | IO[bytes] | None = None) -> presentation.Presentation:
+    """
+    Return a |Presentation| object loaded from *pptx*, where *pptx* can be
+    either a path to a ``.pptx`` file (a string) or a file-like object. If
+    *pptx* is missing or ``None``, the built-in default presentation
+    "template" is loaded.
+    """
+    if pptx is None:
+        pptx = _default_pptx_path()
+
+    presentation_part = Package.open(pptx).main_document_part
+
+    if not _is_pptx_package(presentation_part):
+        tmpl = "file '%s' is not a PowerPoint file, content type is '%s'"
+        raise ValueError(tmpl % (pptx, presentation_part.content_type))
+
+    return presentation_part.presentation
+
+
+def _default_pptx_path() -> str:
+    """Return the path to the built-in default .pptx package."""
+    _thisdir = os.path.split(__file__)[0]
+    return os.path.join(_thisdir, "templates", "default.pptx")
+
+
+def _is_pptx_package(prs_part: PresentationPart):
+    """Return |True| if *prs_part* is a valid main document part, |False| otherwise."""
+    valid_content_types = (CT.PML_PRESENTATION_MAIN, CT.PML_PRES_MACRO_MAIN)
+    return prs_part.content_type in valid_content_types

pptx2/audit.py

@@ -0,0 +1,258 @@
+"""One-call deck audit — combines lint, picture sanity, and empty-slide checks.
+
+For agents producing a deck end-to-end the question is "did I do a
+good job?".  :func:`audit` returns a small structured report so the
+agent can include a "what I shipped" summary in its reply to the user
+without crawling every slide manually::
+
+    from pptx2 import audit
+
+    report = audit(prs)
+    print(report.markdown())
+
+The report contains:
+
+* ``lint_issues`` — every :class:`~pptx2.lint.LintIssue` aggregated
+  across slides, each annotated with the slide index it came from.
+* ``broken_pictures`` — pictures whose dimensions are zero or whose
+  embedded image part appears corrupt.
+* ``empty_slides`` — slide indexes whose only shapes are background
+  decoration (full-bleed rects, layout placeholders).
+* ``font_warnings`` — fonts referenced by shapes that aren't typically
+  pre-installed on Windows / macOS / Linux (raises false positives;
+  treat as advisory).
+* ``size_warnings`` — pictures larger than ``size_warn_bytes`` (default
+  2 MB) — flagged so callers can choose to compress.
+
+The audit is read-only — it never mutates the deck.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pptx2.api import Presentation
+    from pptx2.lint import LintIssue
+
+
+__all__ = ["AuditReport", "audit"]
+
+
+# Fonts that ship with stock Windows / macOS / Office installs.  Used as
+# a (very conservative) safe-list for the font_warnings probe.
+_COMMON_FONTS = frozenset(
+    name.lower()
+    for name in (
+        "Arial", "Calibri", "Helvetica", "Times New Roman", "Cambria",
+        "Verdana", "Tahoma", "Georgia", "Courier New", "Consolas",
+        "Segoe UI", "Trebuchet MS", "Garamond", "Impact", "Comic Sans MS",
+        "Lucida Console", "Palatino", "Palatino Linotype", "Symbol",
+        "Wingdings", "Wingdings 2", "Wingdings 3", "Webdings",
+        "Inter", "Roboto", "Open Sans", "Lato", "Noto Sans",
+    )
+)
+
+
+@dataclass
+class AuditReport:
+    """Structured summary returned by :func:`audit`."""
+
+    lint_issues: list[tuple[int, "LintIssue"]] = field(default_factory=list)
+    broken_pictures: list[tuple[int, Any]] = field(default_factory=list)
+    empty_slides: list[int] = field(default_factory=list)
+    font_warnings: list[tuple[int, str]] = field(default_factory=list)
+    size_warnings: list[tuple[int, str, int]] = field(default_factory=list)
+    total_slides: int = 0
+
+    @property
+    def has_errors(self) -> bool:
+        from pptx2.lint import LintSeverity
+
+        return any(
+            issue.severity == LintSeverity.ERROR
+            for _idx, issue in self.lint_issues
+        )
+
+    def markdown(self) -> str:
+        """Render the report as a markdown string suitable for chat replies."""
+        lines = [f"# Audit report — {self.total_slides} slide(s)"]
+        if not (
+            self.lint_issues
+            or self.broken_pictures
+            or self.empty_slides
+            or self.font_warnings
+            or self.size_warnings
+        ):
+            lines.append("")
+            lines.append("**No issues found.**")
+            return "\n".join(lines)
+
+        if self.lint_issues:
+            lines.append("")
+            lines.append(f"## Lint ({len(self.lint_issues)})")
+            for idx, issue in self.lint_issues:
+                lines.append(f"- slide {idx}: {issue}")
+        if self.broken_pictures:
+            lines.append("")
+            lines.append(f"## Broken pictures ({len(self.broken_pictures)})")
+            for idx, shape in self.broken_pictures:
+                lines.append(f"- slide {idx}: `{shape.name}` is zero-sized or missing image data")
+        if self.empty_slides:
+            lines.append("")
+            lines.append("## Empty slides")
+            for idx in self.empty_slides:
+                lines.append(f"- slide {idx}: no content-bearing shapes")
+        if self.font_warnings:
+            lines.append("")
+            lines.append(f"## Font warnings ({len(self.font_warnings)})")
+            seen = set()
+            for idx, font in self.font_warnings:
+                key = (idx, font)
+                if key in seen:
+                    continue
+                seen.add(key)
+                lines.append(f"- slide {idx}: uses `{font}` (not in the common safe-list)")
+        if self.size_warnings:
+            lines.append("")
+            lines.append(f"## Large pictures ({len(self.size_warnings)})")
+            for idx, name, size_bytes in self.size_warnings:
+                lines.append(
+                    f"- slide {idx}: `{name}` is {size_bytes / 1_000_000:.1f} MB"
+                )
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dict of the whole audit.
+
+        This is the machine-readable counterpart to :meth:`markdown` — built
+        for the agent loop that generates a deck, audits it, and feeds the
+        result back to a model (or a CI gate) to decide what to fix. Every
+        lint issue is expanded via :meth:`~pptx2.lint.LintIssue.to_dict`,
+        and slide-relative shape references are reduced to names::
+
+            report = audit(prs)
+            if report.to_dict()["has_errors"]:
+                ...
+
+        Top-level keys: ``total_slides``, ``has_errors``, ``lint_issues``,
+        ``broken_pictures``, ``empty_slides``, ``font_warnings``,
+        ``size_warnings``.
+        """
+        return {
+            "total_slides": self.total_slides,
+            "has_errors": self.has_errors,
+            "lint_issues": [
+                {"slide": idx, **issue.to_dict()} for idx, issue in self.lint_issues
+            ],
+            "broken_pictures": [
+                {"slide": idx, "shape": shape.name} for idx, shape in self.broken_pictures
+            ],
+            "empty_slides": list(self.empty_slides),
+            "font_warnings": [
+                {"slide": idx, "font": font} for idx, font in self.font_warnings
+            ],
+            "size_warnings": [
+                {"slide": idx, "shape": name, "bytes": size_bytes}
+                for idx, name, size_bytes in self.size_warnings
+            ],
+        }
+
+    def to_json(self, *, indent: int | None = 2) -> str:
+        """Return :meth:`to_dict` serialized as a JSON string."""
+        import json
+
+        return json.dumps(self.to_dict(), indent=indent)
+
+    def __str__(self) -> str:
+        return self.markdown()
+
+
+def audit(
+    prs: "Presentation",
+    *,
+    size_warn_bytes: int = 2_000_000,
+    check_fonts: bool = True,
+) -> AuditReport:
+    """Walk the deck and return an :class:`AuditReport` summary.
+
+    Read-only — never mutates the presentation.  Each slide is linted
+    in passing-defaults mode; per-slide overrides should be supplied
+    via the slide-level ``slide.lint(...)`` API directly.
+    """
+    from pptx2.shapes.picture import Picture
+
+    report = AuditReport()
+    slides = list(prs.slides)
+    report.total_slides = len(slides)
+
+    # Read slide dimensions once for the full-bleed-background heuristic.
+    slide_w = int(prs.slide_width) if prs.slide_width else 0
+    slide_h = int(prs.slide_height) if prs.slide_height else 0
+    bleed_w = slide_w * 0.95
+    bleed_h = slide_h * 0.95
+
+    for idx, slide in enumerate(slides):
+        # Lint each slide and prefix with the index.
+        for issue in slide.lint().issues:
+            report.lint_issues.append((idx, issue))
+
+        content_shapes = 0
+        for shape in slide.shapes:
+            # Skip layout placeholders that are entirely inherited.
+            if (
+                shape.is_placeholder
+                and getattr(shape, "has_text_frame", False)
+                and not shape.text_frame.text.strip()
+            ):
+                continue
+            # Skip full-bleed background rectangles — they're decoration,
+            # not content, so a slide that only contains them should be
+            # flagged as empty (matches the documented contract for
+            # ``empty_slides``).
+            try:
+                sw = int(shape.width)
+                sh = int(shape.height)
+            except Exception:
+                sw = sh = 0
+            if (
+                bleed_w > 0
+                and bleed_h > 0
+                and sw >= bleed_w
+                and sh >= bleed_h
+            ):
+                has_text = (
+                    getattr(shape, "has_text_frame", False)
+                    and shape.text_frame.text.strip()
+                )
+                if not has_text:
+                    continue
+            content_shapes += 1
+
+            # Picture sanity.
+            if isinstance(shape, Picture):
+                if int(shape.width) <= 0 or int(shape.height) <= 0:
+                    report.broken_pictures.append((idx, shape))
+                # Picture size warning via the underlying image part.
+                try:
+                    img = shape.image  # type: ignore[attr-defined]
+                    size_bytes = len(img.blob)
+                    if size_bytes > size_warn_bytes:
+                        report.size_warnings.append((idx, shape.name, size_bytes))
+                except Exception:
+                    pass
+
+            # Font warning sweep.
+            if check_fonts and getattr(shape, "has_text_frame", False):
+                tf = shape.text_frame
+                for para in tf.paragraphs:
+                    for run in para.runs:
+                        name = run.font.name
+                        if name and name.lower() not in _COMMON_FONTS:
+                            report.font_warnings.append((idx, name))
+
+        if content_shapes == 0:
+            report.empty_slides.append(idx)
+
+    return report

pptx2/chart/analytics.py

@@ -0,0 +1,381 @@
+"""Series-level analytics: trendlines and error bars.
+
+These objects wrap the ``<c:trendline>`` and ``<c:errBars>`` children of a
+``<c:ser>`` element and expose an Excel-like authoring API on chart series.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pptx2.enum.chart import (
+    XL_ERROR_BAR_INCLUDE,
+    XL_ERROR_BAR_TYPE,
+    XL_TRENDLINE_TYPE,
+)
+from pptx2.oxml import parse_xml
+from pptx2.oxml.ns import nsdecls
+
+# -- map of the short-name strings accepted at the API boundary to the
+# -- corresponding enum member, so callers can pass e.g. "linear" or
+# -- "movingAvg" without importing the enum.
+_TRENDLINE_ALIASES = {
+    "linear": XL_TRENDLINE_TYPE.LINEAR,
+    "exp": XL_TRENDLINE_TYPE.EXPONENTIAL,
+    "exponential": XL_TRENDLINE_TYPE.EXPONENTIAL,
+    "log": XL_TRENDLINE_TYPE.LOGARITHMIC,
+    "logarithmic": XL_TRENDLINE_TYPE.LOGARITHMIC,
+    "movingavg": XL_TRENDLINE_TYPE.MOVING_AVERAGE,
+    "moving_average": XL_TRENDLINE_TYPE.MOVING_AVERAGE,
+    "poly": XL_TRENDLINE_TYPE.POLYNOMIAL,
+    "polynomial": XL_TRENDLINE_TYPE.POLYNOMIAL,
+    "power": XL_TRENDLINE_TYPE.POWER,
+}
+
+_ERR_DIRECTION_ALIASES = {
+    "both": XL_ERROR_BAR_TYPE.BOTH,
+    "plus": XL_ERROR_BAR_TYPE.PLUS,
+    "minus": XL_ERROR_BAR_TYPE.MINUS,
+}
+
+
+def _resolve_trendline_type(kind):
+    """Return the `XL_TRENDLINE_TYPE` member for *kind*.
+
+    *kind* may already be an enum member, or one of the short-name strings
+    such as ``"linear"`` / ``"movingAvg"`` / ``"poly"``.
+    """
+    if isinstance(kind, XL_TRENDLINE_TYPE):
+        return kind
+    try:
+        return _TRENDLINE_ALIASES[str(kind).lower()]
+    except KeyError:
+        raise ValueError(
+            "trendline kind must be one of %r or an XL_TRENDLINE_TYPE member; got %r"
+            % (sorted(set(_TRENDLINE_ALIASES)), kind)
+        )
+
+
+def _resolve_err_direction(direction):
+    """Return the `XL_ERROR_BAR_TYPE` member for *direction*."""
+    if isinstance(direction, XL_ERROR_BAR_TYPE):
+        return direction
+    try:
+        return _ERR_DIRECTION_ALIASES[str(direction).lower()]
+    except KeyError:
+        raise ValueError(
+            "error-bar direction must be 'both', 'plus', or 'minus' (or an "
+            "XL_ERROR_BAR_TYPE member); got %r" % (direction,)
+        )
+
+
+class Trendline(object):
+    """A single ``<c:trendline>`` fitted to a chart series."""
+
+    def __init__(self, trendline):
+        self._element = trendline
+        self._trendline = trendline
+
+    @property
+    def trendline_type(self):
+        """Member of :ref:`XL_TRENDLINE_TYPE` for this trendline's curve."""
+        return self._trendline.trendlineType.val
+
+    @property
+    def show_equation(self):
+        """Read/write bool: whether the fitted equation is displayed."""
+        dispEq = self._trendline.dispEq
+        if dispEq is None:
+            return False
+        return bool(dispEq.val)
+
+    @show_equation.setter
+    def show_equation(self, value):
+        if bool(value):
+            self._trendline.get_or_add_dispEq().val = True
+        else:
+            self._trendline._remove_dispEq()
+
+    @property
+    def show_r_squared(self):
+        """Read/write bool: whether the R-squared value is displayed."""
+        dispRSqr = self._trendline.dispRSqr
+        if dispRSqr is None:
+            return False
+        return bool(dispRSqr.val)
+
+    @show_r_squared.setter
+    def show_r_squared(self, value):
+        if bool(value):
+            self._trendline.get_or_add_dispRSqr().val = True
+        else:
+            self._trendline._remove_dispRSqr()
+
+    @property
+    def name(self):
+        """Read/write str: the legend label for this trendline, or |None|."""
+        name = self._trendline.name
+        if name is None:
+            return None
+        return name.text
+
+    @name.setter
+    def name(self, value):
+        if value is None:
+            self._trendline._remove_name()
+            return
+        self._trendline.get_or_add_name().text = str(value)
+
+    @property
+    def order(self):
+        """Read/write int: polynomial order (2-6), or |None| if unset."""
+        order = self._trendline.order
+        if order is None:
+            return None
+        return order.val
+
+    @order.setter
+    def order(self, value):
+        if value is None:
+            self._trendline._remove_order()
+            return
+        order = int(value)
+        if not 2 <= order <= 6:
+            raise ValueError(
+                "polynomial trendline order must be in the range 2-6 "
+                "(ST_Order); got %r" % (value,)
+            )
+        self._trendline.get_or_add_order().val = order
+
+    @property
+    def period(self):
+        """Read/write int: moving-average period (>=2), or |None| if unset."""
+        period = self._trendline.period
+        if period is None:
+            return None
+        return period.val
+
+    @period.setter
+    def period(self, value):
+        if value is None:
+            self._trendline._remove_period()
+            return
+        period = int(value)
+        if period < 2:
+            raise ValueError(
+                "moving-average trendline period must be 2 or greater "
+                "(ST_Period); got %r" % (value,)
+            )
+        self._trendline.get_or_add_period().val = period
+
+    @property
+    def forward(self):
+        """Read/write float: forward projection in periods, or |None|."""
+        forward = self._trendline.forward
+        if forward is None:
+            return None
+        return forward.val
+
+    @forward.setter
+    def forward(self, value):
+        if value is None:
+            self._trendline._remove_forward()
+            return
+        self._trendline.get_or_add_forward().val = float(value)
+
+    @property
+    def backward(self):
+        """Read/write float: backward projection in periods, or |None|."""
+        backward = self._trendline.backward
+        if backward is None:
+            return None
+        return backward.val
+
+    @backward.setter
+    def backward(self, value):
+        if value is None:
+            self._trendline._remove_backward()
+            return
+        self._trendline.get_or_add_backward().val = float(value)
+
+
+class Trendlines(Sequence):
+    """The collection of ``<c:trendline>`` elements for a series.
+
+    Supports ``len()``, iteration, indexed access, and ``.add(...)``.
+    """
+
+    def __init__(self, ser):
+        self._element = ser
+        self._ser = ser
+
+    def __getitem__(self, index):
+        trendlines = self._ser.trendline_lst
+        if isinstance(index, slice):
+            return [Trendline(t) for t in trendlines[index]]
+        return Trendline(trendlines[index])
+
+    def __len__(self):
+        return len(self._ser.trendline_lst)
+
+    def add(
+        self,
+        kind=XL_TRENDLINE_TYPE.LINEAR,
+        *,
+        show_equation=False,
+        show_r_squared=False,
+        name=None,
+        order=None,
+        period=None,
+        forward=None,
+        backward=None,
+    ):
+        """Add and return a new |Trendline| of the given *kind*.
+
+        *kind* accepts an :class:`XL_TRENDLINE_TYPE` member or a short-name
+        string (``"linear"``, ``"exp"``, ``"log"``, ``"movingAvg"``,
+        ``"poly"``, ``"power"``). *order* applies to polynomial trendlines,
+        *period* to moving-average trendlines. *forward* / *backward* project
+        the curve that many periods past the data.
+        """
+        trendline_type = _resolve_trendline_type(kind)
+        trendline = self._ser._add_trendline()
+        # -- write the `val` attribute explicitly (even for the schema default
+        # -- "linear") so the emitted XML matches Excel/PowerPoint output and
+        # -- is unambiguous to readers.
+        trendline.trendlineType.set("val", trendline_type.xml_value)
+
+        proxy = Trendline(trendline)
+        if name is not None:
+            proxy.name = name
+        if order is not None:
+            proxy.order = order
+        if period is not None:
+            proxy.period = period
+        if forward is not None:
+            proxy.forward = forward
+        if backward is not None:
+            proxy.backward = backward
+        # -- dispRSqr / dispEq come late in the schema, set after order/period
+        if show_r_squared:
+            proxy.show_r_squared = True
+        if show_equation:
+            proxy.show_equation = True
+        return proxy
+
+
+class ErrorBars(object):
+    """The ``<c:errBars>`` element for a series, with Excel-style constructors.
+
+    The collection is materialised lazily — the underlying ``<c:errBars>``
+    element is only created when one of the constructor methods (``fixed``,
+    ``percentage``, ``standard_deviation``, ``standard_error``, ``custom``) is
+    called. Calling a constructor a second time replaces the prior settings.
+    """
+
+    def __init__(self, ser):
+        self._element = ser
+        self._ser = ser
+
+    @property
+    def exists(self):
+        """True if an ``<c:errBars>`` element is present on this series."""
+        return self._ser.errBars is not None
+
+    @property
+    def error_bar_type(self):
+        """The :ref:`XL_ERROR_BAR_TYPE` direction, or |None| if no error bars."""
+        errBars = self._ser.errBars
+        if errBars is None or errBars.errBarType is None:
+            return None
+        return errBars.errBarType.val
+
+    @property
+    def include_type(self):
+        """The :ref:`XL_ERROR_BAR_INCLUDE` value-type, or |None|."""
+        errBars = self._ser.errBars
+        if errBars is None or errBars.errValType is None:
+            return None
+        return errBars.errValType.val
+
+    @property
+    def value(self):
+        """The numeric error amount (fixed/percentage/stdDev), or |None|."""
+        errBars = self._ser.errBars
+        if errBars is None or errBars.val is None:
+            return None
+        return float(errBars.val.get("val"))
+
+    def remove(self):
+        """Remove any error bars present on this series."""
+        self._ser._remove_errBars()
+
+    # -- Excel-mirroring constructors -----------------------------------
+
+    def fixed(self, value, *, direction="both"):
+        """Set fixed-value error bars of magnitude *value*."""
+        return self._configure(XL_ERROR_BAR_INCLUDE.FIXED_VALUE, direction, value=value)
+
+    def percentage(self, pct, *, direction="both"):
+        """Set percentage error bars of *pct* percent of each value."""
+        return self._configure(XL_ERROR_BAR_INCLUDE.PERCENTAGE, direction, value=pct)
+
+    def standard_deviation(self, n=1, *, direction="both"):
+        """Set error bars of *n* standard deviations."""
+        return self._configure(XL_ERROR_BAR_INCLUDE.STANDARD_DEVIATION, direction, value=n)
+
+    def standard_error(self, *, direction="both"):
+        """Set standard-error error bars (no numeric amount)."""
+        return self._configure(XL_ERROR_BAR_INCLUDE.STANDARD_ERROR, direction, value=None)
+
+    def custom(self, plus, minus, *, direction="both"):
+        """Set custom error bars from per-point *plus* / *minus* sequences.
+
+        *plus* and *minus* are sequences of floats, one per data point.
+        """
+        errBars = self._reset_errBars(direction)
+        errBars.get_or_add_errValType().set("val", XL_ERROR_BAR_INCLUDE.CUSTOM.xml_value)
+        errBars.append(self._num_data_source("c:plus", plus))
+        errBars.append(self._num_data_source("c:minus", minus))
+        return self
+
+    # -- internals ------------------------------------------------------
+
+    def _configure(self, include_type, direction, *, value):
+        errBars = self._reset_errBars(direction)
+        errBars.get_or_add_errValType().set("val", include_type.xml_value)
+        if value is not None:
+            val = parse_xml('<c:val %s val="%s"/>' % (nsdecls("c"), float(value)))
+            errBars.append(val)
+        return self
+
+    def _reset_errBars(self, direction):
+        """Return a fresh ``<c:errBars>`` element with *direction* applied.
+
+        Any pre-existing error bars are removed first so repeated constructor
+        calls don't accumulate stale ``plus`` / ``minus`` / ``val`` children.
+        """
+        self._ser._remove_errBars()
+        errBars = self._ser.get_or_add_errBars()
+        errBars.get_or_add_errBarType().set("val", _resolve_err_direction(direction).xml_value)
+        return errBars
+
+    @staticmethod
+    def _num_data_source(tag, values):
+        """Return a ``<c:plus>`` or ``<c:minus>`` numeric-literal data source."""
+        seq = list(values)
+        pts = "".join(
+            '<c:pt idx="%d"><c:v>%s</c:v></c:pt>' % (i, float(v))
+            for i, v in enumerate(seq)
+            if v is not None
+        )
+        xml = (
+            "<%s %s>"
+            "<c:numLit>"
+            "<c:formatCode>General</c:formatCode>"
+            '<c:ptCount val="%d"/>'
+            "%s"
+            "</c:numLit>"
+            "</%s>"
+        ) % (tag, nsdecls("c"), len(seq), pts, tag)
+        return parse_xml(xml)