python-pptx2 2.13.0__py3-none-any.whl

pptx2/chart/datalabel.py

@@ -0,0 +1,406 @@
+"""Data label-related objects."""
+
+from __future__ import annotations
+
+from pptx2.oxml.ns import qn
+from pptx2.text.text import Font, TextFrame
+from pptx2.util import Pt, lazyproperty
+
+
+class DataLabels(object):
+    """Provides access to properties of data labels for a plot or a series.
+
+    This is not a collection and does not provide access to individual data
+    labels. Access to individual labels is via the |Point| object. The
+    properties this object provides control formatting of *all* the data
+    labels in its scope.
+    """
+
+    def __init__(self, dLbls):
+        super(DataLabels, self).__init__()
+        self._element = dLbls
+
+    @lazyproperty
+    def font(self):
+        """
+        The |Font| object that provides access to the text properties for
+        these data labels, such as bold, italic, etc.
+        """
+        defRPr = self._element.defRPr
+        font = Font(defRPr)
+        return font
+
+    @property
+    def number_format(self):
+        """
+        Read/write string specifying the format for the numbers on this set
+        of data labels. Returns 'General' if no number format has been set.
+        Note that this format string has no effect on rendered data labels
+        when :meth:`number_format_is_linked` is |True|. Assigning a format
+        string to this property automatically sets
+        :meth:`number_format_is_linked` to |False|.
+        """
+        numFmt = self._element.numFmt
+        if numFmt is None:
+            return "General"
+        return numFmt.formatCode
+
+    @number_format.setter
+    def number_format(self, value):
+        self._element.get_or_add_numFmt().formatCode = value
+        self.number_format_is_linked = False
+
+    @property
+    def number_format_is_linked(self):
+        """
+        Read/write boolean specifying whether number formatting should be
+        taken from the source spreadsheet rather than the value of
+        :meth:`number_format`.
+        """
+        numFmt = self._element.numFmt
+        if numFmt is None:
+            return True
+        souceLinked = numFmt.sourceLinked
+        if souceLinked is None:
+            return True
+        return numFmt.sourceLinked
+
+    @number_format_is_linked.setter
+    def number_format_is_linked(self, value):
+        numFmt = self._element.get_or_add_numFmt()
+        # `formatCode` is schema-required on <c:numFmt>; default it whenever it's
+        # absent (newly created or a pre-existing element that lacks it) so the
+        # linked flag can't be toggled into an invalid, PowerPoint-rejected
+        # element.  An existing explicit value is preserved.
+        if numFmt.get("formatCode") is None:
+            numFmt.formatCode = "General"
+        numFmt.sourceLinked = value
+
+    @property
+    def position(self):
+        """
+        Read/write :ref:`XlDataLabelPosition` enumeration value specifying
+        the position of the data labels with respect to their data point, or
+        |None| if no position is specified. Assigning |None| causes
+        PowerPoint to choose the default position, which varies by chart
+        type.
+        """
+        dLblPos = self._element.dLblPos
+        if dLblPos is None:
+            return None
+        return dLblPos.val
+
+    @position.setter
+    def position(self, value):
+        if value is None:
+            self._element._remove_dLblPos()
+            return
+        self._element.get_or_add_dLblPos().val = value
+
+    @property
+    def show_category_name(self):
+        """Read/write. True when name of category should appear in label."""
+        return self._element.get_or_add_showCatName().val
+
+    @show_category_name.setter
+    def show_category_name(self, value):
+        self._element.get_or_add_showCatName().val = bool(value)
+
+    @property
+    def show_legend_key(self):
+        """Read/write. True when data label displays legend-color swatch."""
+        return self._element.get_or_add_showLegendKey().val
+
+    @show_legend_key.setter
+    def show_legend_key(self, value):
+        self._element.get_or_add_showLegendKey().val = bool(value)
+
+    @property
+    def show_percentage(self):
+        """Read/write. True when data label displays percentage.
+
+        This option is not operative on all chart types. Percentage appears
+        on polar charts such as pie and donut.
+        """
+        return self._element.get_or_add_showPercent().val
+
+    @show_percentage.setter
+    def show_percentage(self, value):
+        self._element.get_or_add_showPercent().val = bool(value)
+
+    @property
+    def show_series_name(self):
+        """Read/write. True when data label displays series name."""
+        return self._element.get_or_add_showSerName().val
+
+    @show_series_name.setter
+    def show_series_name(self, value):
+        self._element.get_or_add_showSerName().val = bool(value)
+
+    @property
+    def show_value(self):
+        """Read/write. True when label displays numeric value of datapoint."""
+        return self._element.get_or_add_showVal().val
+
+    @show_value.setter
+    def show_value(self, value):
+        self._element.get_or_add_showVal().val = bool(value)
+
+    @property
+    def collision_strategy(self):
+        """Write-only — read is unsupported.
+
+        Strategies for handling overlapping data labels on
+        bar / column charts. Native PowerPoint doesn't reposition
+        labels at all, so this is a small set of heuristics that
+        nudge the typography and bar geometry into a less-collidey
+        layout. For genuine collision avoidance (re-laying out
+        labels around their bars), reach for ``add_plotly_figure``
+        — Plotly's chart engine handles this natively.
+
+        Assignable values:
+
+        * ``"auto"`` — apply a sensible default for the chart shape:
+          shrink data-label font to 8 pt, and on bar / column plots
+          with five or more categories *and* multiple series,
+          reduce ``gapWidth`` to 60 (thicker bars, more room
+          between labels). No-op on plots that don't carry
+          ``gapWidth``.
+        * ``"shrink"`` — only shrink the font (8 pt). Doesn't
+          touch bar geometry.
+        * ``"compact"`` — drop font to 8 pt *and* set
+          ``gapWidth=60``, regardless of category count. Use when
+          you've eyeballed the chart and want explicit thickening.
+
+        Read-only access raises ``AttributeError`` because the
+        property doesn't have a single canonical value to return —
+        the underlying state is split across font size and the
+        plot's ``gapWidth`` attribute.
+        """
+        raise AttributeError(
+            "data_labels.collision_strategy is write-only; read "
+            "data_labels.font.size and the plot's gap_width directly."
+        )
+
+    @collision_strategy.setter
+    def collision_strategy(self, value):
+        if value not in ("auto", "shrink", "compact"):
+            raise ValueError(
+                "collision_strategy must be 'auto', 'shrink', or 'compact'; "
+                f"got {value!r}"
+            )
+
+        # Step 1 — typography. Always shrink labels.
+        self.font.size = Pt(8)
+
+        # Step 2 — bar geometry. Walk up to the plot element to read
+        # series / category counts and write gapWidth. Only meaningful
+        # on bar / column charts (which carry ``c:gapWidth``); other
+        # plot types silently skip this step.
+        plot_elm = self._element.getparent()
+        if plot_elm is None:
+            return
+        gap_tag = qn("c:gapWidth")
+        if plot_elm.find(gap_tag) is None and plot_elm.tag not in (
+            qn("c:barChart"),
+            qn("c:bar3DChart"),
+        ):
+            # Not a gap-width-bearing plot; typography update is enough.
+            return
+
+        if value == "shrink":
+            return
+
+        if value == "compact":
+            self._set_or_add_gap_width(plot_elm, 60)
+            return
+
+        # value == "auto" — apply only when the heuristic warrants
+        # (≥5 categories AND multi-series).
+        ser_count = len(plot_elm.findall(qn("c:ser")))
+        cat_count = self._first_series_category_count(plot_elm)
+        if ser_count >= 2 and cat_count >= 5:
+            self._set_or_add_gap_width(plot_elm, 60)
+
+    @staticmethod
+    def _set_or_add_gap_width(plot_elm, val):
+        """Set ``<c:gapWidth val="..."/>`` on *plot_elm* (replacing if present)."""
+        gap_tag = qn("c:gapWidth")
+        existing = plot_elm.find(gap_tag)
+        if existing is not None:
+            existing.set("val", str(int(val)))
+            return
+        # CT_BarChart/CT_Bar3DChart are strict sequences: gapWidth must
+        # precede overlap/serLines/axId/extLst (a bare append lands after
+        # axId, which PowerPoint rejects with the repair prompt).
+        gw = plot_elm.makeelement(gap_tag, {"val": str(int(val))})
+        successor_tags = ("c:overlap", "c:gapDepth", "c:shape", "c:serLines", "c:axId", "c:extLst")
+        for successor_tag in successor_tags:
+            successor = plot_elm.find(qn(successor_tag))
+            if successor is not None:
+                successor.addprevious(gw)
+                return
+        plot_elm.append(gw)
+
+    @staticmethod
+    def _first_series_category_count(plot_elm):
+        """Count category points on the first series, or 0 if unreadable."""
+        ser = plot_elm.find(qn("c:ser"))
+        if ser is None:
+            return 0
+        cat = ser.find(qn("c:cat"))
+        if cat is None:
+            return 0
+        # Categories live as ``c:strRef/c:strCache/c:pt`` or
+        # ``c:numRef/c:numCache/c:pt``; both lead to ``c:pt`` in the
+        # rendered cache.
+        pts = cat.findall(f".//{qn('c:pt')}")
+        return len(pts)
+
+
+class DataLabel(object):
+    """
+    The data label associated with an individual data point.
+    """
+
+    def __init__(self, ser, idx):
+        super(DataLabel, self).__init__()
+        self._ser = self._element = ser
+        self._idx = idx
+
+    @lazyproperty
+    def font(self):
+        """The |Font| object providing text formatting for this data label.
+
+        This font object is used to customize the appearance of automatically
+        inserted text, such as the data point value. The font applies to the
+        entire data label. More granular control of the appearance of custom
+        data label text is controlled by a font object on runs in the text
+        frame.
+        """
+        txPr = self._get_or_add_txPr()
+        text_frame = TextFrame(txPr, self)
+        paragraph = text_frame.paragraphs[0]
+        return paragraph.font
+
+    @property
+    def has_text_frame(self):
+        """
+        Return |True| if this data label has a text frame (implying it has
+        custom data label text), and |False| otherwise. Assigning |True|
+        causes a text frame to be added if not already present. Assigning
+        |False| causes any existing text frame to be removed along with any
+        text contained in the text frame.
+        """
+        dLbl = self._dLbl
+        if dLbl is None:
+            return False
+        if dLbl.xpath("c:tx/c:rich"):
+            return True
+        return False
+
+    @has_text_frame.setter
+    def has_text_frame(self, value):
+        if bool(value) is True:
+            self._get_or_add_tx_rich()
+        else:
+            self._remove_tx_rich()
+
+    @property
+    def position(self):
+        """
+        Read/write :ref:`XlDataLabelPosition` member specifying the position
+        of this data label with respect to its data point, or |None| if no
+        position is specified. Assigning |None| causes PowerPoint to choose
+        the default position, which varies by chart type.
+        """
+        dLbl = self._dLbl
+        if dLbl is None:
+            return None
+        dLblPos = dLbl.dLblPos
+        if dLblPos is None:
+            return None
+        return dLblPos.val
+
+    @position.setter
+    def position(self, value):
+        if value is None:
+            dLbl = self._dLbl
+            if dLbl is None:
+                return
+            dLbl._remove_dLblPos()
+            return
+        dLbl = self._get_or_add_dLbl()
+        dLbl.get_or_add_dLblPos().val = value
+
+    @property
+    def text_frame(self):
+        """
+        |TextFrame| instance for this data label, containing the text of the
+        data label and providing access to its text formatting properties.
+        """
+        rich = self._get_or_add_rich()
+        return TextFrame(rich, self)
+
+    @property
+    def _dLbl(self):
+        """
+        Return the |CT_DLbl| instance referring specifically to this
+        individual data label (having the same index value), or |None| if not
+        present.
+        """
+        return self._ser.get_dLbl(self._idx)
+
+    def _get_or_add_dLbl(self):
+        """
+        The ``CT_DLbl`` instance referring specifically to this individual
+        data label, newly created if not yet present in the XML.
+        """
+        return self._ser.get_or_add_dLbl(self._idx)
+
+    def _get_or_add_rich(self):
+        """
+        Return the `c:rich` element representing the text frame for this data
+        label, newly created with its ancestors if not present.
+        """
+        dLbl = self._get_or_add_dLbl()
+
+        # having a c:spPr or c:txPr when a c:tx is present causes the "can't
+        # save" bug on bubble charts. Remove c:spPr and c:txPr when present.
+        dLbl._remove_spPr()
+        dLbl._remove_txPr()
+
+        return dLbl.get_or_add_rich()
+
+    def _get_or_add_tx_rich(self):
+        """
+        Return the `c:tx` element for this data label, with its `c:rich`
+        child and descendants, newly created if not yet present.
+        """
+        dLbl = self._get_or_add_dLbl()
+
+        # having a c:spPr or c:txPr when a c:tx is present causes the "can't
+        # save" bug on bubble charts. Remove c:spPr and c:txPr when present.
+        dLbl._remove_spPr()
+        dLbl._remove_txPr()
+
+        return dLbl.get_or_add_tx_rich()
+
+    def _get_or_add_txPr(self):
+        """Return the `c:txPr` element for this data label.
+
+        The `c:txPr` element and its parent `c:dLbl` element are created if
+        not yet present.
+        """
+        dLbl = self._get_or_add_dLbl()
+        return dLbl.get_or_add_txPr()
+
+    def _remove_tx_rich(self):
+        """
+        Remove any `c:tx/c:rich` child of the `c:dLbl` element for this data
+        label. Do nothing if that element is not present.
+        """
+        dLbl = self._dLbl
+        if dLbl is None:
+            return
+        dLbl.remove_tx_rich()

pptx2/chart/legend.py

@@ -0,0 +1,86 @@
+"""Legend of a chart."""
+
+from __future__ import annotations
+
+from pptx2.enum.chart import XL_LEGEND_POSITION
+from pptx2.text.text import Font
+from pptx2.util import lazyproperty
+
+
+class Legend(object):
+    """
+    Represents the legend in a chart. A chart can have at most one legend.
+    """
+
+    def __init__(self, legend_elm):
+        super(Legend, self).__init__()
+        self._element = legend_elm
+
+    @lazyproperty
+    def font(self):
+        """
+        The |Font| object that provides access to the text properties for
+        this legend, such as bold, italic, etc.
+        """
+        defRPr = self._element.defRPr
+        font = Font(defRPr)
+        return font
+
+    @property
+    def horz_offset(self):
+        """
+        Adjustment of the x position of the legend from its default.
+        Expressed as a float between -1.0 and 1.0 representing a fraction of
+        the chart width. Negative values move the legend left, positive
+        values move it to the right. |None| if no setting is specified.
+        """
+        return self._element.horz_offset
+
+    @horz_offset.setter
+    def horz_offset(self, value):
+        self._element.horz_offset = value
+
+    @property
+    def include_in_layout(self):
+        """|True| if legend should be located inside plot area.
+
+        Read/write boolean specifying whether legend should be placed inside
+        the plot area. In many cases this will cause it to be superimposed on
+        the chart itself. Assigning |None| to this property causes any
+        `c:overlay` element to be removed, which is interpreted the same as
+        |True|. This use case should rarely be required and assigning
+        a boolean value is recommended.
+        """
+        overlay = self._element.overlay
+        if overlay is None:
+            return True
+        return overlay.val
+
+    @include_in_layout.setter
+    def include_in_layout(self, value):
+        if value is None:
+            self._element._remove_overlay()
+            return
+        self._element.get_or_add_overlay().val = bool(value)
+
+    @property
+    def position(self):
+        """
+        Read/write :ref:`XlLegendPosition` enumeration value specifying the
+        general region of the chart in which to place the legend.
+        """
+        legendPos = self._element.legendPos
+        if legendPos is None:
+            return XL_LEGEND_POSITION.RIGHT
+        return legendPos.val
+
+    @position.setter
+    def position(self, position):
+        # Write the ``val`` attribute directly rather than going through
+        # ``CT_LegendPos.val``: the latter is an ``OptionalAttribute`` whose
+        # setter *strips* the attribute when the assigned value matches the
+        # OOXML default (``"r"``).  PowerPoint's strict parser rejects the
+        # resulting bare ``<c:legendPos/>`` element and "repairs" the chart
+        # by deleting it on open, so always emit the attribute explicitly.
+        legendPos = self._element.get_or_add_legendPos()
+        legendPos.set("val", XL_LEGEND_POSITION.to_xml(position))

pptx2/chart/marker.py

@@ -0,0 +1,70 @@
+"""Marker-related objects.
+
+Only the line-type charts Line, XY, and Radar have markers.
+"""
+
+from __future__ import annotations
+
+from pptx2.dml.chtfmt import ChartFormat
+from pptx2.shared import ElementProxy
+from pptx2.util import lazyproperty
+
+
+class Marker(ElementProxy):
+    """
+    Represents a data point marker, such as a diamond or circle, on
+    a line-type chart.
+    """
+
+    @lazyproperty
+    def format(self):
+        """
+        The |ChartFormat| instance for this marker, providing access to shape
+        properties such as fill and line.
+        """
+        marker = self._element.get_or_add_marker()
+        return ChartFormat(marker)
+
+    @property
+    def size(self):
+        """
+        An integer between 2 and 72 inclusive indicating the size of this
+        marker in points. A value of |None| indicates no explicit value is
+        set and the size is inherited from a higher-level setting or the
+        PowerPoint default (which may be 9). Assigning |None| removes any
+        explicitly assigned size, causing this value to be inherited.
+        """
+        marker = self._element.marker
+        if marker is None:
+            return None
+        return marker.size_val
+
+    @size.setter
+    def size(self, value):
+        marker = self._element.get_or_add_marker()
+        marker._remove_size()
+        if value is None:
+            return
+        size = marker._add_size()
+        size.val = value
+
+    @property
+    def style(self):
+        """
+        A member of the :ref:`XlMarkerStyle` enumeration indicating the shape
+        of this marker. Returns |None| if no explicit style has been set,
+        which corresponds to the "Automatic" option in the PowerPoint UI.
+        """
+        marker = self._element.marker
+        if marker is None:
+            return None
+        return marker.symbol_val
+
+    @style.setter
+    def style(self, value):
+        marker = self._element.get_or_add_marker()
+        marker._remove_symbol()
+        if value is None:
+            return
+        symbol = marker._add_symbol()
+        symbol.val = value

pptx2/chart/palettes.py

@@ -0,0 +1,129 @@
+"""Named chart color palettes, applied independently of `chart_style`.
+
+The PowerPoint `chart_style` integer (1-48) bundles a fill palette together with
+font, axis, and gridline tweaks. Users who want to recolor only the series — for
+example to match a brand palette — without inheriting the rest of the style end
+up either fighting the chart_style enum or hand-painting each series. This module
+exposes a small set of curated palettes plus a tiny resolver that
+`Chart.apply_palette` uses to translate a name or sequence into concrete
+``RGBColor`` values.
+
+Adding a palette here is intentionally lightweight: drop a new entry in
+``CHART_PALETTES`` and it becomes addressable by name from ``apply_palette``.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Sequence, Union
+
+from pptx2.dml.color import RGBColor
+
+ColorLike = Union[RGBColor, str, Sequence[int]]
+"""Anything ``_to_rgb`` knows how to turn into an `RGBColor`."""
+
+
+CHART_PALETTES: dict[str, tuple[str, ...]] = {
+    # Saturated, contemporary brand palette — pairs well with the "Modern"
+    # design-token starter pack.
+    "modern": (
+        "#2D3142",
+        "#4F5D75",
+        "#EF8354",
+        "#BFC0C0",
+        "#FFFFFF",
+        "#057DCD",
+    ),
+    # Conservative, presentation-friendly palette — close to PowerPoint's
+    # default Office accents but a touch desaturated for print.
+    "classic": (
+        "#1F4E79",
+        "#2E75B6",
+        "#9DC3E6",
+        "#C00000",
+        "#7F6000",
+        "#548235",
+    ),
+    # Higher-contrast editorial palette — useful for narrative decks where
+    # one series should clearly dominate.
+    "editorial": (
+        "#0B132B",
+        "#1C2541",
+        "#3A506B",
+        "#5BC0BE",
+        "#6FFFE9",
+        "#FF6B6B",
+    ),
+    # Vibrant categorical palette — eight colors so 5+ series stay readable.
+    "vibrant": (
+        "#E63946",
+        "#F1A208",
+        "#2A9D8F",
+        "#264653",
+        "#7209B7",
+        "#3A86FF",
+        "#FB5607",
+        "#06D6A0",
+    ),
+    # Monochrome blue ramp — ordered, useful when categories have a natural
+    # progression (light-to-dark).
+    "monochrome_blue": (
+        "#CFE2F3",
+        "#9FC5E8",
+        "#6FA8DC",
+        "#3D85C6",
+        "#0B5394",
+        "#073763",
+    ),
+    # Monochrome warm ramp.
+    "monochrome_warm": (
+        "#FFF4E6",
+        "#FFD8A8",
+        "#FFA94D",
+        "#FF922B",
+        "#E8590C",
+        "#A5450A",
+    ),
+}
+
+
+def palette_names() -> tuple[str, ...]:
+    """Return the names of the built-in palettes, in declaration order."""
+    return tuple(CHART_PALETTES.keys())
+
+
+def resolve_palette(palette: Union[str, Iterable[ColorLike]]) -> tuple[RGBColor, ...]:
+    """Return a tuple of `RGBColor` values for a palette name or sequence.
+
+    `palette` is either:
+
+    * A string naming a built-in palette (see :func:`palette_names`), or
+    * An iterable of color-likes — `RGBColor`, hex strings (with or without
+      leading ``'#'``), or 3-tuples of ints in ``0-255``.
+
+    Raises ``ValueError`` if `palette` is an unknown name or resolves to an
+    empty sequence (which would make :meth:`Chart.apply_palette` a no-op and
+    silently mask user error).
+    """
+    if isinstance(palette, str):
+        try:
+            colors = CHART_PALETTES[palette]
+        except KeyError:
+            raise ValueError(
+                "unknown palette %r; choose from %r" % (palette, palette_names())
+            )
+        return tuple(RGBColor.from_hex(c) for c in colors)
+
+    resolved = tuple(_to_rgb(c) for c in palette)
+    if not resolved:
+        raise ValueError("palette must contain at least one color")
+    return resolved
+
+
+def _to_rgb(color: ColorLike) -> RGBColor:
+    if isinstance(color, RGBColor):
+        return color
+    if isinstance(color, str):
+        return RGBColor.from_hex(color)
+    # Treat any other sequence as an (r, g, b) triple.
+    r, g, b = color
+    return RGBColor(r, g, b)