python-pptx2 2.13.0__py3-none-any.whl

pptx2/accessibility.py

@@ -0,0 +1,365 @@
+"""Read-only accessibility audit for a generated deck.
+
+Decks produced programmatically routinely ship without the metadata a
+screen reader needs — pictures with no alt text, slides with no title,
+text whose contrast against its fill falls below WCAG AA.  These slip
+past the layout linter (the deck *looks* fine) but make the result
+unusable for assistive technology.
+
+:func:`audit_accessibility` walks every slide and shape and returns a
+small structured :class:`AccessibilityReport` so an agent that builds a
+deck can answer "is this accessible?" without crawling the slides by
+hand::
+
+    from pptx2 import accessibility
+
+    report = accessibility.audit_accessibility(prs)
+    print(report.markdown())
+    if report.has_errors:
+        ...
+
+The audit is strictly read-only — it never mutates the deck.
+
+Issue codes:
+
+* ``MissingAltText``   — a picture or other meaningful shape carries no
+  ``alt_text`` (``<p:cNvPr descr=...>``).  Pictures are ERROR (a screen
+  reader has nothing to announce); other meaningful shapes are WARNING.
+* ``LowContrast``      — text-on-fill contrast is below WCAG AA (4.5:1),
+  reusing the contrast math from :mod:`pptx2.lint`.
+* ``NoSlideTitle``     — a slide has no (non-empty) title, so it has no
+  landmark for navigation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pptx2.api import Presentation
+    from pptx2.shapes.base import BaseShape
+    from pptx2.slide import Slide
+
+
+__all__ = [
+    "AccessibilitySeverity",
+    "AccessibilityIssue",
+    "AccessibilityReport",
+    "audit_accessibility",
+]
+
+
+class AccessibilitySeverity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class AccessibilityIssue:
+    """A single accessibility problem found on a slide.
+
+    ``slide`` is the zero-based slide index; ``shape`` is the offending
+    shape's name (``None`` for slide-level issues such as a missing
+    title).  ``code`` is one of ``"MissingAltText"``, ``"LowContrast"``,
+    ``"NoSlideTitle"``.
+    """
+
+    slide: int
+    code: str
+    message: str
+    severity: AccessibilitySeverity = AccessibilitySeverity.WARNING
+    shape: str | None = None
+
+    def __str__(self) -> str:
+        where = f"slide {self.slide}"
+        if self.shape is not None:
+            where += f" / {self.shape!r}"
+        return f"[{self.severity.value.upper()}] {self.code} ({where}): {self.message}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dict describing this issue."""
+        payload = asdict(self)
+        payload["severity"] = self.severity.value
+        return payload
+
+
+# Shape types that carry visual meaning and should describe themselves to a
+# screen reader.  Decorative chrome (plain text boxes, which already expose
+# their text, and group containers) is handled separately below.
+_MEANINGFUL_TYPE_NAMES = frozenset(
+    {
+        "PICTURE",
+        "LINKED_PICTURE",
+        "CHART",
+        "TABLE",
+        "DIAGRAM",
+        "IGX_GRAPHIC",
+        "MEDIA",
+        "EMBEDDED_OLE_OBJECT",
+        "LINKED_OLE_OBJECT",
+        "FREEFORM",
+        "WEB_VIDEO",
+    }
+)
+
+# Picture-like types are held to a higher standard: a screen reader has
+# literally nothing to announce for them without alt text, so a missing
+# description is an ERROR rather than a WARNING.
+_PICTURE_TYPE_NAMES = frozenset({"PICTURE", "LINKED_PICTURE", "MEDIA", "WEB_VIDEO"})
+
+
+def _shape_type_name(shape: "BaseShape") -> str | None:
+    """Return the ``MSO_SHAPE_TYPE`` member name for *shape*, or ``None``.
+
+    Some shapes (notably bare group children or proxies that don't
+    implement ``shape_type``) raise on access; treat those as untyped.
+    """
+    try:
+        st = shape.shape_type
+    except Exception:
+        return None
+    return getattr(st, "name", None)
+
+
+def _iter_shapes_recursive(shapes: Any) -> "Any":
+    """Yield every shape, recursing into group members.
+
+    A meaningful image or text run inside a |GroupShape| still needs alt text
+    / adequate contrast, so the audit must look past the group container.
+    ``GroupShape.walk()`` already yields all descendants depth-first, so it is
+    only invoked on top-level groups (recursing on its output would
+    double-count nested groups).
+    """
+    for shape in shapes:
+        yield shape
+        if _shape_type_name(shape) == "GROUP":
+            try:
+                yield from shape.walk()
+            except Exception:
+                pass
+
+
+def _has_text(shape: "BaseShape") -> bool:
+    try:
+        if not getattr(shape, "has_text_frame", False):
+            return False
+        return bool(shape.text_frame.text.strip())  # type: ignore[attr-defined]
+    except Exception:
+        return False
+
+
+def _slide_has_title(slide: "Slide") -> bool:
+    """Return ``True`` when *slide* has a title placeholder with text."""
+    try:
+        title = slide.shapes.title
+    except Exception:
+        title = None
+    if title is None:
+        return False
+    try:
+        return bool(title.text_frame.text.strip())
+    except Exception:
+        # A title placeholder exists; without readable text we still
+        # treat the landmark as present (the placeholder is navigable).
+        return True
+
+
+def _check_alt_text(slide_idx: int, shape: "BaseShape") -> list[AccessibilityIssue]:
+    """Flag meaningful shapes that carry no alt text."""
+    type_name = _shape_type_name(shape)
+    if type_name is None:
+        return []
+    if type_name not in _MEANINGFUL_TYPE_NAMES:
+        return []
+    try:
+        alt = shape.alt_text
+    except Exception:
+        return []
+    if alt.strip():
+        return []
+    # A meaningful shape that also exposes its text content is partially
+    # self-describing; still flag it, but as a warning either way.
+    is_picture = type_name in _PICTURE_TYPE_NAMES
+    severity = AccessibilitySeverity.ERROR if is_picture else AccessibilitySeverity.WARNING
+    kind = "picture" if is_picture else type_name.replace("_", " ").lower()
+    return [
+        AccessibilityIssue(
+            slide=slide_idx,
+            code="MissingAltText",
+            message=f"{kind} has no alt text; set shape.alt_text for screen readers.",
+            severity=severity,
+            shape=shape.name,
+        )
+    ]
+
+
+def _check_contrast(slide_idx: int, shape: "BaseShape", slide: "Slide") -> list[AccessibilityIssue]:
+    """Flag low text/background contrast, reusing lint's contrast math.
+
+    Imports the contrast helpers from :mod:`pptx2.lint` read-only.
+    Skips silently whenever colours can't be resolved (theme colours,
+    gradients, inherited backgrounds) — matching the linter's behaviour.
+    """
+    try:
+        from pptx2.lint import (
+            _CONTRAST_THRESHOLD,
+            _contrast_ratio,
+            _resolve_solid_rgb,
+            _slide_background_rgb,
+        )
+    except Exception:
+        return []
+
+    if not _has_text(shape):
+        return []
+
+    tf = shape.text_frame  # type: ignore[attr-defined]
+    text_rgb = None
+    try:
+        for paragraph in tf.paragraphs:
+            for run in paragraph.runs:
+                try:
+                    rgb = run.font.color.rgb
+                except (AttributeError, ValueError):
+                    rgb = None
+                if rgb is not None:
+                    text_rgb = rgb
+                    break
+            if text_rgb is not None:
+                break
+    except Exception:
+        return []
+    if text_rgb is None:
+        return []
+
+    bg_rgb = None
+    try:
+        bg_rgb = _resolve_solid_rgb(shape.fill)  # type: ignore[attr-defined]
+    except Exception:
+        bg_rgb = None
+    if bg_rgb is None:
+        bg_rgb = _slide_background_rgb(slide)
+    if bg_rgb is None:
+        return []
+
+    ratio = _contrast_ratio(text_rgb, bg_rgb)
+    if ratio >= _CONTRAST_THRESHOLD:
+        return []
+    return [
+        AccessibilityIssue(
+            slide=slide_idx,
+            code="LowContrast",
+            message=(
+                f"text-on-fill contrast {ratio:.2f}:1 is below WCAG AA "
+                f"({_CONTRAST_THRESHOLD:.1f}:1)."
+            ),
+            severity=AccessibilitySeverity.WARNING,
+            shape=shape.name,
+        )
+    ]
+
+
+@dataclass
+class AccessibilityReport:
+    """Structured summary returned by :func:`audit_accessibility`."""
+
+    issues: list[AccessibilityIssue] = field(default_factory=list)
+    total_slides: int = 0
+
+    @property
+    def has_errors(self) -> bool:
+        """True when at least one ERROR-severity issue is present."""
+        return any(i.severity == AccessibilitySeverity.ERROR for i in self.issues)
+
+    def markdown(self) -> str:
+        """Render the report as a markdown string suitable for chat replies."""
+        lines = [f"# Accessibility report — {self.total_slides} slide(s)"]
+        if not self.issues:
+            lines.append("")
+            lines.append("**No accessibility issues found.**")
+            return "\n".join(lines)
+
+        # Group by code so the reader sees "all the missing alt text"
+        # together rather than interleaved per slide.
+        by_code: dict[str, list[AccessibilityIssue]] = {}
+        for issue in self.issues:
+            by_code.setdefault(issue.code, []).append(issue)
+
+        for code in sorted(by_code):
+            bucket = by_code[code]
+            lines.append("")
+            lines.append(f"## {code} ({len(bucket)})")
+            for issue in bucket:
+                where = f"slide {issue.slide}"
+                if issue.shape is not None:
+                    where += f" — `{issue.shape}`"
+                lines.append(f"- {where}: {issue.message}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dict of the whole audit."""
+        return {
+            "total_slides": self.total_slides,
+            "has_errors": self.has_errors,
+            "issues": [issue.to_dict() for issue in self.issues],
+        }
+
+    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_accessibility(
+    prs: "Presentation",
+    *,
+    check_contrast: bool = True,
+) -> AccessibilityReport:
+    """Walk the deck and return an :class:`AccessibilityReport`.
+
+    Read-only — never mutates the presentation.  Flags:
+
+    * pictures and other meaningful shapes missing ``alt_text``;
+    * text whose contrast against its fill/background is below WCAG AA
+      (when ``check_contrast`` is True and the colours are resolvable);
+    * slides with no (non-empty) title placeholder.
+    """
+    report = AccessibilityReport()
+    slides = list(prs.slides)
+    report.total_slides = len(slides)
+
+    for idx, slide in enumerate(slides):
+        if not _slide_has_title(slide):
+            report.issues.append(
+                AccessibilityIssue(
+                    slide=idx,
+                    code="NoSlideTitle",
+                    message=(
+                        "slide has no title; screen-reader users rely on the "
+                        "title as a navigation landmark."
+                    ),
+                    severity=AccessibilitySeverity.WARNING,
+                    shape=None,
+                )
+            )
+
+        for shape in _iter_shapes_recursive(slide.shapes):
+            report.issues.extend(_check_alt_text(idx, shape))
+            if check_contrast:
+                report.issues.extend(_check_contrast(idx, shape, slide))
+
+    # Order: errors first, then warnings, then info — mirrors lint.
+    _order = {
+        AccessibilitySeverity.ERROR: 0,
+        AccessibilitySeverity.WARNING: 1,
+        AccessibilitySeverity.INFO: 2,
+    }
+    report.issues.sort(key=lambda i: (_order.get(i.severity, 3), i.slide))
+    return report

pptx2/action.py

@@ -0,0 +1,270 @@
+"""Objects related to mouse click and hover actions on a shape or text."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from pptx2.enum.action import PP_ACTION
+from pptx2.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx2.shapes import Subshape
+from pptx2.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.oxml.action import CT_Hyperlink
+    from pptx2.oxml.shapes.shared import CT_NonVisualDrawingProps
+    from pptx2.oxml.text import CT_TextCharacterProperties
+    from pptx2.parts.slide import SlidePart
+    from pptx2.shapes.base import BaseShape
+    from pptx2.slide import Slide, Slides
+
+
+class ActionSetting(Subshape):
+    """Properties specifying how a shape or run reacts to mouse actions."""
+
+    # -- The Subshape base class provides access to the Slide Part, which is needed to access
+    # -- relationships, which is where hyperlinks live.
+
+    def __init__(
+        self,
+        xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties,
+        parent: BaseShape,
+        hover: bool = False,
+    ):
+        super(ActionSetting, self).__init__(parent)
+        # xPr is either a cNvPr or rPr element
+        self._element = xPr
+        # _hover determines use of `a:hlinkClick` or `a:hlinkHover`
+        self._hover = hover
+
+    @property
+    def action(self):
+        """Member of :ref:`PpActionType` enumeration, such as `PP_ACTION.HYPERLINK`.
+
+        The returned member indicates the type of action that will result when the
+        specified shape or text is clicked or the mouse pointer is positioned over the
+        shape during a slide show.
+
+        If there is no click-action or the click-action value is not recognized (is not
+        one of the official `MsoPpAction` values) then `PP_ACTION.NONE` is returned.
+        """
+        hlink = self._hlink
+
+        if hlink is None:
+            return PP_ACTION.NONE
+
+        action_verb = hlink.action_verb
+
+        if action_verb == "hlinkshowjump":
+            relative_target = hlink.action_fields["jump"]
+            return {
+                "firstslide": PP_ACTION.FIRST_SLIDE,
+                "lastslide": PP_ACTION.LAST_SLIDE,
+                "lastslideviewed": PP_ACTION.LAST_SLIDE_VIEWED,
+                "nextslide": PP_ACTION.NEXT_SLIDE,
+                "previousslide": PP_ACTION.PREVIOUS_SLIDE,
+                "endshow": PP_ACTION.END_SHOW,
+            }[relative_target]
+
+        return {
+            None: PP_ACTION.HYPERLINK,
+            "hlinksldjump": PP_ACTION.NAMED_SLIDE,
+            "hlinkpres": PP_ACTION.PLAY,
+            "hlinkfile": PP_ACTION.OPEN_FILE,
+            "customshow": PP_ACTION.NAMED_SLIDE_SHOW,
+            "ole": PP_ACTION.OLE_VERB,
+            "macro": PP_ACTION.RUN_MACRO,
+            "program": PP_ACTION.RUN_PROGRAM,
+        }.get(action_verb, PP_ACTION.NONE)
+
+    @lazyproperty
+    def hyperlink(self) -> Hyperlink:
+        """
+        A |Hyperlink| object representing the hyperlink action defined on
+        this click or hover mouse event. A |Hyperlink| object is always
+        returned, even if no hyperlink or other click action is defined.
+        """
+        return Hyperlink(self._element, self._parent, self._hover)
+
+    @property
+    def target_slide(self) -> Slide | None:
+        """
+        A reference to the slide in this presentation that is the target of
+        the slide jump action in this shape. Slide jump actions include
+        `PP_ACTION.FIRST_SLIDE`, `LAST_SLIDE`, `NEXT_SLIDE`,
+        `PREVIOUS_SLIDE`, and `NAMED_SLIDE`. Returns |None| for all other
+        actions. In particular, the `LAST_SLIDE_VIEWED` action and the `PLAY`
+        (start other presentation) actions are not supported.
+
+        A slide object may be assigned to this property, which makes the
+        shape an "internal hyperlink" to the assigened slide::
+
+            slide, target_slide = prs.slides[0], prs.slides[1]
+            shape = slide.shapes[0]
+            shape.target_slide = target_slide
+
+        Assigning |None| removes any slide jump action. Note that this is
+        accomplished by removing any action present (such as a hyperlink),
+        without first checking that it is a slide jump action.
+        """
+        slide_jump_actions = (
+            PP_ACTION.FIRST_SLIDE,
+            PP_ACTION.LAST_SLIDE,
+            PP_ACTION.NEXT_SLIDE,
+            PP_ACTION.PREVIOUS_SLIDE,
+            PP_ACTION.NAMED_SLIDE,
+        )
+
+        if self.action not in slide_jump_actions:
+            return None
+
+        if self.action == PP_ACTION.FIRST_SLIDE:
+            return self._slides[0]
+        elif self.action == PP_ACTION.LAST_SLIDE:
+            return self._slides[-1]
+        elif self.action == PP_ACTION.NEXT_SLIDE:
+            next_slide_idx = self._slide_index + 1
+            if next_slide_idx >= len(self._slides):
+                raise ValueError("no next slide")
+            return self._slides[next_slide_idx]
+        elif self.action == PP_ACTION.PREVIOUS_SLIDE:
+            prev_slide_idx = self._slide_index - 1
+            if prev_slide_idx < 0:
+                raise ValueError("no previous slide")
+            return self._slides[prev_slide_idx]
+        elif self.action == PP_ACTION.NAMED_SLIDE:
+            assert self._hlink is not None
+            rId = self._hlink.rId
+            slide_part = cast("SlidePart", self.part.related_part(rId))
+            return slide_part.slide
+
+    @target_slide.setter
+    def target_slide(self, slide: Slide | None):
+        self._clear_click_action()
+        if slide is None:
+            return
+        hlink = self._element.get_or_add_hlinkClick()
+        hlink.action = "ppaction://hlinksldjump"
+        hlink.rId = self.part.relate_to(slide.part, RT.SLIDE)
+
+    def _clear_click_action(self):
+        """Remove any existing click action."""
+        hlink = self._hlink
+        if hlink is None:
+            return
+        rId = hlink.rId
+        if rId:
+            self.part.drop_rel(rId)
+        self._element.remove(hlink)
+
+    @property
+    def _hlink(self) -> CT_Hyperlink | None:
+        """
+        Reference to the `a:hlinkClick` or `a:hlinkHover` element for this
+        click action. Returns |None| if the element is not present.
+        """
+        if self._hover:
+            assert isinstance(self._element, CT_NonVisualDrawingProps)
+            return self._element.hlinkHover
+        return self._element.hlinkClick
+
+    @lazyproperty
+    def _slide(self):
+        """
+        Reference to the slide containing the shape having this click action.
+        """
+        return self.part.slide
+
+    @lazyproperty
+    def _slide_index(self):
+        """
+        Position in the slide collection of the slide containing the shape
+        having this click action.
+        """
+        return self._slides.index(self._slide)
+
+    @lazyproperty
+    def _slides(self) -> Slides:
+        """
+        Reference to the slide collection for this presentation.
+        """
+        return self.part.package.presentation_part.presentation.slides
+
+
+class Hyperlink(Subshape):
+    """Represents a hyperlink action on a shape or text run."""
+
+    def __init__(
+        self,
+        xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties,
+        parent: BaseShape,
+        hover: bool = False,
+    ):
+        super(Hyperlink, self).__init__(parent)
+        # xPr is either a cNvPr or rPr element
+        self._element = xPr
+        # _hover determines use of `a:hlinkClick` or `a:hlinkHover`
+        self._hover = hover
+
+    @property
+    def address(self) -> str | None:
+        """Read/write. The URL of the hyperlink.
+
+        URL can be on http, https, mailto, or file scheme; others may work. Returns |None| if no
+        hyperlink is defined, including when another action such as `RUN_MACRO` is defined on the
+        object. Assigning |None| removes any action defined on the object, whether it is a hyperlink
+        action or not.
+        """
+        hlink = self._hlink
+
+        # there's no URL if there's no click action
+        if hlink is None:
+            return None
+
+        # a click action without a relationship has no URL
+        rId = hlink.rId
+        if not rId:
+            return None
+
+        return self.part.target_ref(rId)
+
+    @address.setter
+    def address(self, url: str | None):
+        # implements all three of add, change, and remove hyperlink
+        self._remove_hlink()
+
+        if url:
+            rId = self.part.relate_to(url, RT.HYPERLINK, is_external=True)
+            hlink = self._get_or_add_hlink()
+            hlink.rId = rId
+
+    def _get_or_add_hlink(self) -> CT_Hyperlink:
+        """Get the `a:hlinkClick` or `a:hlinkHover` element for the Hyperlink object.
+
+        The actual element depends on the value of `self._hover`. Create the element if not present.
+        """
+        if self._hover:
+            return cast("CT_NonVisualDrawingProps", self._element).get_or_add_hlinkHover()
+        return self._element.get_or_add_hlinkClick()
+
+    @property
+    def _hlink(self) -> CT_Hyperlink | None:
+        """Reference to the `a:hlinkClick` or `h:hlinkHover` element for this click action.
+
+        Returns |None| if the element is not present.
+        """
+        if self._hover:
+            return cast("CT_NonVisualDrawingProps", self._element).hlinkHover
+        return self._element.hlinkClick
+
+    def _remove_hlink(self):
+        """Remove the a:hlinkClick or a:hlinkHover element.
+
+        Also drops any relationship it might have.
+        """
+        hlink = self._hlink
+        if hlink is None:
+            return
+        rId = hlink.rId
+        if rId:
+            self.part.drop_rel(rId)
+        self._element.remove(hlink)