python-pptx2 2.13.0__py3-none-any.whl

pptx2/__init__.py

@@ -0,0 +1,152 @@
+"""Initialization module for python-pptx2 package."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import pptx2.exc as exceptions
+from pptx2.api import Presentation
+from pptx2.audit import AuditReport, audit
+from pptx2.geometry import BBox
+from pptx2.design.components import (
+    ArticleCard,
+    Gauge,
+    KpiCard,
+    ProgressBar,
+    StatStrip,
+    StatusPill,
+    add_article_card,
+    add_gauge,
+    add_kpi_card,
+    add_progress_bar,
+    add_stat_strip,
+    add_status_pill,
+)
+from pptx2.design.figures import (
+    FigureBackendUnavailable,
+    add_html_figure,
+    add_matplotlib_figure,
+    add_plotly_figure,
+    add_svg_figure,
+)
+from pptx2.math import MathBackendUnavailable
+from pptx2.opc.constants import CONTENT_TYPE as CT
+from pptx2.opc.package import PartFactory
+from pptx2.parts.chart import ChartPart
+from pptx2.parts.coreprops import CorePropertiesPart
+from pptx2.parts.diagram import (
+    DiagramColorsPart,
+    DiagramDataPart,
+    DiagramLayoutPart,
+    DiagramStylePart,
+)
+from pptx2.parts.image import ImagePart
+from pptx2.parts.media import MediaPart
+from pptx2.parts.presentation import PresentationPart
+from pptx2.parts.slide import (
+    NotesMasterPart,
+    NotesSlidePart,
+    SlideLayoutPart,
+    SlideMasterPart,
+    SlidePart,
+    ThemePart,
+)
+
+if TYPE_CHECKING:
+    from pptx2.opc.package import Part
+
+__version__ = "2.13.0"
+
+sys.modules["pptx2.exceptions"] = exceptions
+del sys
+
+__all__ = [
+    "Presentation",
+    # First-class rectangular region value object (immutable, splattable
+    # into add_shape / add_textbox / add_picture).
+    "BBox",
+    # One-call deck audit (lint + picture + empty-slide + font + size).
+    "audit",
+    "AuditReport",
+    # Figure adapters — embed Plotly / Matplotlib / SVG / HTML output as
+    # slide pictures. Third-party deps are imported lazily on first call.
+    "add_plotly_figure",
+    "add_matplotlib_figure",
+    "add_svg_figure",
+    "add_html_figure",
+    "FigureBackendUnavailable",
+    "MathBackendUnavailable",
+    # Shape-level building blocks built on the design tokens.
+    "add_kpi_card",
+    "add_progress_bar",
+    "add_gauge",
+    "add_status_pill",
+    "add_stat_strip",
+    "add_article_card",
+    "KpiCard",
+    "ProgressBar",
+    "Gauge",
+    "StatusPill",
+    "StatStrip",
+    "ArticleCard",
+]
+
+content_type_to_part_class_map: dict[str, type[Part]] = {
+    CT.PML_PRESENTATION_MAIN: PresentationPart,
+    CT.PML_PRES_MACRO_MAIN: PresentationPart,
+    CT.PML_TEMPLATE_MAIN: PresentationPart,
+    CT.PML_SLIDESHOW_MAIN: PresentationPart,
+    CT.OPC_CORE_PROPERTIES: CorePropertiesPart,
+    CT.PML_NOTES_MASTER: NotesMasterPart,
+    CT.PML_NOTES_SLIDE: NotesSlidePart,
+    CT.PML_SLIDE: SlidePart,
+    CT.PML_SLIDE_LAYOUT: SlideLayoutPart,
+    CT.PML_SLIDE_MASTER: SlideMasterPart,
+    CT.OFC_THEME: ThemePart,
+    CT.DML_CHART: ChartPart,
+    CT.DML_DIAGRAM_DATA: DiagramDataPart,
+    CT.DML_DIAGRAM_LAYOUT: DiagramLayoutPart,
+    CT.DML_DIAGRAM_STYLE: DiagramStylePart,
+    CT.DML_DIAGRAM_COLORS: DiagramColorsPart,
+    CT.BMP: ImagePart,
+    CT.GIF: ImagePart,
+    CT.JPEG: ImagePart,
+    CT.MS_PHOTO: ImagePart,
+    CT.PNG: ImagePart,
+    CT.TIFF: ImagePart,
+    CT.X_EMF: ImagePart,
+    CT.X_WMF: ImagePart,
+    CT.ASF: MediaPart,
+    CT.AVI: MediaPart,
+    CT.MOV: MediaPart,
+    CT.MP4: MediaPart,
+    CT.MPG: MediaPart,
+    CT.MS_VIDEO: MediaPart,
+    CT.SWF: MediaPart,
+    CT.VIDEO: MediaPart,
+    CT.WMV: MediaPart,
+    CT.X_MS_VIDEO: MediaPart,
+    # -- accommodate "image/jpg" as an alias for "image/jpeg" --
+    "image/jpg": ImagePart,
+}
+
+PartFactory.part_type_for.update(content_type_to_part_class_map)
+
+del (
+    ChartPart,
+    CorePropertiesPart,
+    DiagramColorsPart,
+    DiagramDataPart,
+    DiagramLayoutPart,
+    DiagramStylePart,
+    ImagePart,
+    MediaPart,
+    SlidePart,
+    SlideLayoutPart,
+    SlideMasterPart,
+    ThemePart,
+    PresentationPart,
+    CT,
+    PartFactory,
+)

pptx2/_color.py

@@ -0,0 +1,75 @@
+"""Internal canonical colour-coercion helper.
+
+Most public colour-accepting setters in python-pptx2 historically accepted
+exactly one shape (``RGBColor`` for ``shape.fill.fore_color.rgb``, hex
+strings for ``linear_gradient``, mixed for ``chart.apply_palette``).  The
+asymmetry was a category-of-bug for both human and LLM authoring.
+
+:func:`coerce_color` accepts every shape any documented surface in the
+library has accepted historically, so a public setter that routes a
+caller-supplied colour through this helper "just works" with hex
+strings, ``RGBColor`` instances, and 3-tuples.
+
+Supported inputs
+~~~~~~~~~~~~~~~~
+
+* :class:`~pptx2.dml.color.RGBColor` — returned as-is.
+* ``str`` — 6-digit hex, with or without leading ``"#"``.  3-digit
+  shorthand (``"#FFF"``) is **not** accepted; write the full form.
+* 3-tuple / 3-list of ``int`` in ``[0, 255]`` — positional R, G, B.
+
+Anything else raises :class:`TypeError` with a message that points to
+this helper, so callers see one consistent error regardless of which
+public setter they hit.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pptx2.dml.color import RGBColor
+
+ColorLike = "RGBColor | str | tuple[int, int, int] | list[int]"
+
+
+def coerce_color(value: Any) -> RGBColor:
+    """Coerce *value* to an :class:`RGBColor`.
+
+    See module docstring for the accepted shapes.
+    """
+    if isinstance(value, RGBColor):
+        return value
+    if isinstance(value, str):
+        s = value.lstrip("#")
+        if len(s) != 6:
+            raise ValueError(
+                "color hex string must be 6 digits "
+                "(e.g. '#3C2F80' or '3C2F80'); got %r" % value
+            )
+        try:
+            return RGBColor.from_hex(s)
+        except ValueError as exc:
+            raise ValueError("invalid color hex string %r: %s" % (value, exc)) from exc
+    if isinstance(value, (tuple, list)) and len(value) == 3:
+        # Reject floats, numeric strings, and bools rather than
+        # silently coercing via ``int()`` — the documented contract is
+        # "3-tuple of int", and the previous ``RGBColor(*value)`` path
+        # rejected non-int inputs too.  ``bool`` is a subclass of
+        # ``int`` in Python, so guard explicitly so ``(True, False,
+        # True)`` doesn't silently resolve to ``RGBColor(1, 0, 1)``.
+        for c in value:
+            if not isinstance(c, int) or isinstance(c, bool):
+                raise TypeError(
+                    "color 3-tuple must contain ints in [0, 255]; got %r"
+                    % (value,)
+                )
+        return RGBColor(value[0], value[1], value[2])
+    raise TypeError(
+        "expected a color-like value (RGBColor, '#RRGGBB' hex string, "
+        "or 3-tuple of ints); got %r" % (value,)
+    )
+
+
+# Re-export under the historical underscore name as well so
+# ``from pptx2._color import _coerce`` works.
+_coerce = coerce_color