python-pptx2 2.13.0__py3-none-any.whl

pptx2/chart/quick_layouts.py

@@ -0,0 +1,325 @@
+"""Named chart "quick layouts" mirroring PowerPoint's gallery.
+
+PowerPoint's *Chart Design → Quick Layout* gallery exposes 10-11 named
+layout presets that toggle title / legend / axis-title / gridline
+visibility in opinionated combinations.  Replicating *every* layout from
+the gallery requires a couple of features we don't yet model (data
+labels positioned inside bars, "best fit" pie labels), so this module
+ships the subset that maps cleanly onto the existing high-level API:
+title, legend (with position), axis titles, and gridlines.
+
+Public surface::
+
+    from pptx2.chart.quick_layouts import (
+        apply_quick_layout, layout_names, QUICK_LAYOUTS,
+    )
+
+    chart.apply_quick_layout("title_legend_right")     # convenience method on Chart
+    apply_quick_layout(chart, "title_legend_right")    # functional form
+
+A layout spec is a plain dict with any of the keys below.  Missing keys
+mean "don't touch this property" so two layouts can be composed by
+calling ``apply_quick_layout`` twice.
+
+==============================  ==========================================
+``has_title``                   bool — toggle the chart title.
+``title_text``                  str  — set chart title text (forces ``has_title=True``).
+``has_legend``                  bool — toggle the legend.
+``legend_position``             ``XL_LEGEND_POSITION`` member *or* its
+                                lowercase string name (``"right"``, ``"left"``,
+                                ``"top"``, ``"bottom"``, ``"corner"``).
+``legend_in_layout``            bool — whether the legend overlaps the plot area.
+``has_category_axis_title``     bool — toggle the category-axis title.
+``category_axis_title_text``    str  — set category-axis title text.
+``has_value_axis_title``        bool — toggle the value-axis title.
+``value_axis_title_text``       str  — set value-axis title text.
+``has_major_gridlines``         bool — value-axis major gridlines.
+``has_minor_gridlines``         bool — value-axis minor gridlines.
+==============================  ==========================================
+
+Charts without a category axis (e.g. pie charts) silently skip the
+category-axis keys; same for value-axis keys on charts without a value
+axis.  This matches how PowerPoint's gallery degrades.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from pptx2.enum.chart import XL_LEGEND_POSITION
+
+QUICK_LAYOUTS: dict[str, dict[str, Any]] = {
+    # --- Layouts 1-3 from the gallery: title + variations on legend slot --
+    "title_legend_right": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.RIGHT,
+        "legend_in_layout": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    "title_legend_bottom": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.BOTTOM,
+        "legend_in_layout": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    "title_legend_top": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.TOP,
+        "legend_in_layout": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    "title_legend_left": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.LEFT,
+        "legend_in_layout": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    "title_no_legend": {
+        "has_title": True,
+        "has_legend": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    "no_title_no_legend": {
+        "has_title": False,
+        "has_legend": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    # --- Layouts with axis titles -----------------------------------------
+    "title_axes_legend_right": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.RIGHT,
+        "legend_in_layout": False,
+        "has_category_axis_title": True,
+        "has_value_axis_title": True,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    "title_axes_legend_bottom": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.BOTTOM,
+        "legend_in_layout": False,
+        "has_category_axis_title": True,
+        "has_value_axis_title": True,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": False,
+    },
+    # --- Minimal / dense -------------------------------------------------
+    "minimal": {
+        "has_title": False,
+        "has_legend": False,
+        "has_major_gridlines": False,
+        "has_minor_gridlines": False,
+    },
+    "dense": {
+        "has_title": True,
+        "has_legend": True,
+        "legend_position": XL_LEGEND_POSITION.RIGHT,
+        "legend_in_layout": False,
+        "has_major_gridlines": True,
+        "has_minor_gridlines": True,
+    },
+}
+
+
+def layout_names() -> tuple[str, ...]:
+    """Return the names of the built-in quick layouts, in declaration order."""
+    return tuple(QUICK_LAYOUTS.keys())
+
+
+def apply_quick_layout(chart, layout, **overrides) -> None:
+    """Apply a quick-layout preset to `chart`.
+
+    `layout` is either the name of a built-in preset (see
+    :func:`layout_names`) or a dict in the spec format described in the
+    module docstring.  Missing spec keys are left untouched on the chart,
+    so layouts can be composed.  Charts that lack a category or value
+    axis silently skip the corresponding axis keys.
+
+    Any keyword arguments are merged on top of the resolved layout — they
+    override the preset where they collide.  This is the pattern for
+    "use this preset, but with this title"::
+
+        apply_quick_layout(chart, "title_legend_right", title_text="Q4 ARR")
+        apply_quick_layout(
+            chart, "title_axes_legend_bottom",
+            value_axis_title_text="Revenue (£m)",
+            has_major_gridlines=False,
+        )
+
+    Unknown override keys raise :class:`TypeError`.
+    """
+    spec = _resolve_layout(layout)
+    if overrides:
+        unknown = set(overrides) - _VALID_SPEC_KEYS
+        if unknown:
+            raise TypeError(
+                "unknown quick-layout override(s): %s; valid keys: %s"
+                % (sorted(unknown), sorted(_VALID_SPEC_KEYS))
+            )
+        spec.update(overrides)
+    _apply_title(chart, spec)
+    _apply_legend(chart, spec)
+    _apply_category_axis(chart, spec)
+    _apply_value_axis(chart, spec)
+
+
+_VALID_SPEC_KEYS = frozenset(
+    {
+        "has_title",
+        "title_text",
+        "has_legend",
+        "legend_position",
+        "legend_in_layout",
+        "has_category_axis_title",
+        "category_axis_title_text",
+        "has_value_axis_title",
+        "value_axis_title_text",
+        "has_major_gridlines",
+        "has_minor_gridlines",
+    }
+)
+
+
+def _resolve_layout(layout) -> dict[str, Any]:
+    if isinstance(layout, Mapping):
+        return dict(layout)
+    if isinstance(layout, str):
+        try:
+            return dict(QUICK_LAYOUTS[layout])
+        except KeyError:
+            raise ValueError(
+                "unknown quick layout %r; choose from %r" % (layout, layout_names())
+            )
+    raise TypeError(
+        "layout must be a name or spec mapping, got %s" % type(layout).__name__
+    )
+
+
+def _apply_title(chart, spec: Mapping[str, Any]) -> None:
+    title_text = spec.get("title_text")
+    if title_text is not None:
+        chart.has_title = True
+        chart.chart_title.text_frame.text = title_text
+    elif "has_title" in spec:
+        chart.has_title = bool(spec["has_title"])
+
+
+_LEGEND_POSITION_NAMES = {
+    "right": XL_LEGEND_POSITION.RIGHT,
+    "left": XL_LEGEND_POSITION.LEFT,
+    "top": XL_LEGEND_POSITION.TOP,
+    "bottom": XL_LEGEND_POSITION.BOTTOM,
+    "corner": XL_LEGEND_POSITION.CORNER,
+}
+
+
+def _coerce_legend_position(value: Any) -> XL_LEGEND_POSITION:
+    """Accept an :class:`XL_LEGEND_POSITION` member, int value, or lowercase name.
+
+    The reference docs were inconsistent about which form was canonical
+    (``"bottom"`` in prose, ``XL_LEGEND_POSITION.BOTTOM`` in code).
+    Accept both at the boundary, plus the historical integer form
+    (``-4107`` etc.) that ``Legend.position`` already supported via
+    ``XL_LEGEND_POSITION.to_xml``, so config-driven layouts that
+    serialised enum values as ints keep working.  Unknown strings or
+    out-of-range integers raise :class:`ValueError`.
+    """
+    if isinstance(value, XL_LEGEND_POSITION):
+        return value
+    if isinstance(value, str):
+        try:
+            return _LEGEND_POSITION_NAMES[value.lower()]
+        except KeyError:
+            raise ValueError(
+                "legend_position string must be one of %s; got %r"
+                % (sorted(_LEGEND_POSITION_NAMES), value)
+            ) from None
+    # ``bool`` is a subclass of ``int`` — guard explicitly so
+    # ``legend_position=True`` doesn't silently resolve to whichever
+    # member happens to have value 1.
+    if isinstance(value, int) and not isinstance(value, bool):
+        try:
+            return XL_LEGEND_POSITION(value)
+        except ValueError:
+            raise ValueError(
+                "legend_position int %r is not a valid XL_LEGEND_POSITION "
+                "value" % value
+            ) from None
+    raise TypeError(
+        "legend_position must be an XL_LEGEND_POSITION member, int value, "
+        "or string name (one of %s); got %r"
+        % (sorted(_LEGEND_POSITION_NAMES), value)
+    )
+
+
+def _apply_legend(chart, spec: Mapping[str, Any]) -> None:
+    if "has_legend" in spec:
+        chart.has_legend = bool(spec["has_legend"])
+
+    if not chart.has_legend:
+        # Don't touch position/in_layout when the legend is off — those
+        # writes would silently re-add a legend element.
+        return
+
+    legend = chart.legend
+    if "legend_position" in spec:
+        legend.position = _coerce_legend_position(spec["legend_position"])
+    if "legend_in_layout" in spec:
+        legend.include_in_layout = bool(spec["legend_in_layout"])
+
+
+def _apply_category_axis(chart, spec: Mapping[str, Any]) -> None:
+    cat_keys = (
+        "has_category_axis_title",
+        "category_axis_title_text",
+    )
+    if not any(k in spec for k in cat_keys):
+        return
+    try:
+        axis = chart.category_axis
+    except (ValueError, NotImplementedError):
+        # Pie/doughnut charts have no category axis — nothing to do.
+        return
+    title_text = spec.get("category_axis_title_text")
+    if title_text is not None:
+        axis.has_title = True
+        axis.axis_title.text_frame.text = title_text
+    elif "has_category_axis_title" in spec:
+        axis.has_title = bool(spec["has_category_axis_title"])
+
+
+def _apply_value_axis(chart, spec: Mapping[str, Any]) -> None:
+    val_keys = (
+        "has_value_axis_title",
+        "value_axis_title_text",
+        "has_major_gridlines",
+        "has_minor_gridlines",
+    )
+    if not any(k in spec for k in val_keys):
+        return
+    try:
+        axis = chart.value_axis
+    except (ValueError, NotImplementedError):
+        return
+    title_text = spec.get("value_axis_title_text")
+    if title_text is not None:
+        axis.has_title = True
+        axis.axis_title.text_frame.text = title_text
+    elif "has_value_axis_title" in spec:
+        axis.has_title = bool(spec["has_value_axis_title"])
+    if "has_major_gridlines" in spec:
+        axis.has_major_gridlines = bool(spec["has_major_gridlines"])
+    if "has_minor_gridlines" in spec:
+        axis.has_minor_gridlines = bool(spec["has_minor_gridlines"])

pptx2/chart/series.py

@@ -0,0 +1,334 @@
+"""Series-related objects."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pptx2.chart.analytics import ErrorBars, Trendlines
+from pptx2.chart.datalabel import DataLabels
+from pptx2.chart.marker import Marker
+from pptx2.chart.point import BubblePoints, CategoryPoints, XyPoints
+from pptx2.dml.chtfmt import ChartFormat
+from pptx2.oxml.ns import qn
+from pptx2.util import lazyproperty
+
+
+class _BaseSeries(object):
+    """
+    Base class for |BarSeries| and other series classes.
+    """
+
+    def __init__(self, ser):
+        super(_BaseSeries, self).__init__()
+        self._element = ser
+        self._ser = ser
+
+    @lazyproperty
+    def format(self):
+        """
+        The |ChartFormat| instance for this series, providing access to shape
+        properties such as fill and line.
+        """
+        return ChartFormat(self._ser)
+
+    @property
+    def index(self):
+        """
+        The zero-based integer index of this series as reported in its
+        `c:ser/c:idx` element.
+        """
+        return self._element.idx.val
+
+    @property
+    def name(self):
+        """
+        The string label given to this series, appears as the title of the
+        column for this series in the Excel worksheet. It also appears as the
+        label for this series in the legend.
+        """
+        names = self._element.xpath("./c:tx//c:pt/c:v/text()")
+        name = names[0] if names else ""
+        return name
+
+
+class _BaseCategorySeries(_BaseSeries):
+    """Base class for |BarSeries| and other category chart series classes."""
+
+    @lazyproperty
+    def data_labels(self):
+        """|DataLabels| object controlling data labels for this series."""
+        return DataLabels(self._ser.get_or_add_dLbls())
+
+    @lazyproperty
+    def points(self):
+        """
+        The |CategoryPoints| object providing access to individual data
+        points in this series.
+        """
+        return CategoryPoints(self._ser)
+
+    @property
+    def values(self):
+        """
+        Read-only. A sequence containing the float values for this series, in
+        the order they appear on the chart.
+        """
+
+        def iter_values():
+            val = self._element.val
+            if val is None:
+                return
+            for idx in range(val.ptCount_val):
+                yield val.pt_v(idx)
+
+        return tuple(iter_values())
+
+
+class _MarkerMixin(object):
+    """
+    Mixin class providing `.marker` property for line-type chart series. The
+    line-type charts are Line, XY, and Radar.
+    """
+
+    @lazyproperty
+    def marker(self):
+        """
+        The |Marker| instance for this series, providing access to data point
+        marker properties such as fill and line. Setting these properties
+        determines the appearance of markers for all points in this series
+        that are not overridden by settings at the point level.
+        """
+        return Marker(self._ser)
+
+
+class _AnalyticsMixin(object):
+    """Mixin adding ``trendlines`` and ``error_bars`` to a series.
+
+    Only mixed into the series types whose schema complexType permits
+    ``<c:trendline>`` / ``<c:errBars>`` children (bar, line, scatter, area,
+    bubble). Pie and radar series do not allow them.
+    """
+
+    @lazyproperty
+    def trendlines(self):
+        """The |Trendlines| collection for this series.
+
+        Supports ``len()``, iteration, indexed access, and
+        ``.add(kind, ...)`` to fit a new analytical trendline.
+        """
+        return Trendlines(self._ser)
+
+    @lazyproperty
+    def error_bars(self):
+        """The |ErrorBars| object for this series.
+
+        Provides Excel-style constructors: ``fixed(value)``,
+        ``percentage(pct)``, ``standard_deviation(n)``, ``standard_error()``,
+        and ``custom(plus, minus)``.
+        """
+        return ErrorBars(self._ser)
+
+    @property
+    def axis_group(self):
+        """Read/write ``"primary"`` or ``"secondary"`` axis group.
+
+        A series shares the value axis of the plot (chart group) it belongs
+        to. Assigning ``"secondary"`` moves this series' whole plot onto a
+        secondary value axis, creating that axis (and a hidden secondary
+        category axis it crosses) if necessary. The newly-allocated axis ids
+        stay within the signed-int32 range so PowerPoint never flags the file
+        for repair. Assigning ``"primary"`` is only valid while the series is
+        already on the primary axis (moving back is unsupported).
+        """
+        plotArea = self._ser.xpath("ancestor::c:plotArea")[0]
+        secondary = plotArea.secondary_value_axis
+        if secondary is None:
+            return "primary"
+        secondary_id = secondary.xpath("c:axId")[0].get("val")
+        xChart = self._ser.getparent()
+        ax_ids = {a.get("val") for a in xChart.xpath("c:axId")}
+        return "secondary" if secondary_id in ax_ids else "primary"
+
+    @axis_group.setter
+    def axis_group(self, value):
+        if value not in ("primary", "secondary"):
+            raise ValueError("axis_group must be 'primary' or 'secondary', got %r" % (value,))
+        if value == "primary":
+            if self.axis_group == "secondary":
+                raise ValueError("moving a series back to the primary axis group is not supported")
+            return
+        if self.axis_group == "secondary":
+            return
+        plotArea = self._ser.xpath("ancestor::c:plotArea")[0]
+        secondary = plotArea.secondary_value_axis
+        if secondary is None:
+            # Move THIS series' plot (not just the front-most one) onto the new
+            # secondary axis — critical for combo charts with multiple plots.
+            plotArea.add_secondary_value_axis(self._ser.getparent())
+            return
+        # -- a secondary axis already exists; re-point this series' plot onto
+        # -- the secondary axis ids.
+        val2_id = secondary.xpath("c:axId")[0].get("val")
+        cross2_id = secondary.xpath("c:crossAx")[0].get("val")
+        ax_ids = self._ser.getparent().xpath("c:axId")
+        if len(ax_ids) >= 2:
+            ax_ids[0].set("val", str(cross2_id))
+            ax_ids[1].set("val", str(val2_id))
+
+
+class AreaSeries(_BaseCategorySeries, _AnalyticsMixin):
+    """
+    A data point series belonging to an area plot.
+    """
+
+
+class BarSeries(_BaseCategorySeries, _AnalyticsMixin):
+    """A data point series belonging to a bar plot."""
+
+    @property
+    def invert_if_negative(self):
+        """
+        |True| if a point having a value less than zero should appear with a
+        fill different than those with a positive value. |False| if the fill
+        should be the same regardless of the bar's value. When |True|, a bar
+        with a solid fill appears with white fill; in a bar with gradient
+        fill, the direction of the gradient is reversed, e.g. dark -> light
+        instead of light -> dark. The term "invert" here should be understood
+        to mean "invert the *direction* of the *fill gradient*".
+        """
+        invertIfNegative = self._element.invertIfNegative
+        if invertIfNegative is None:
+            return True
+        return invertIfNegative.val
+
+    @invert_if_negative.setter
+    def invert_if_negative(self, value):
+        invertIfNegative = self._element.get_or_add_invertIfNegative()
+        invertIfNegative.val = value
+
+
+class LineSeries(_BaseCategorySeries, _MarkerMixin, _AnalyticsMixin):
+    """
+    A data point series belonging to a line plot.
+    """
+
+    @property
+    def smooth(self):
+        """
+        Read/write boolean specifying whether to use curve smoothing to
+        form the line connecting the data points in this series into
+        a continuous curve. If |False|, a series of straight line segments
+        are used to connect the points.
+        """
+        smooth = self._element.smooth
+        if smooth is None:
+            return True
+        return smooth.val
+
+    @smooth.setter
+    def smooth(self, value):
+        self._element.get_or_add_smooth().val = value
+
+
+class PieSeries(_BaseCategorySeries):
+    """
+    A data point series belonging to a pie plot.
+    """
+
+
+class RadarSeries(_BaseCategorySeries, _MarkerMixin):
+    """
+    A data point series belonging to a radar plot.
+    """
+
+
+class XySeries(_BaseSeries, _MarkerMixin, _AnalyticsMixin):
+    """
+    A data point series belonging to an XY (scatter) plot.
+    """
+
+    def iter_values(self):
+        """
+        Generate each float Y value in this series, in the order they appear
+        on the chart. A value of `None` represents a missing Y value
+        (corresponding to a blank Excel cell).
+        """
+        yVal = self._element.yVal
+        if yVal is None:
+            return
+
+        for idx in range(yVal.ptCount_val):
+            yield yVal.pt_v(idx)
+
+    @lazyproperty
+    def points(self):
+        """
+        The |XyPoints| object providing access to individual data points in
+        this series.
+        """
+        return XyPoints(self._ser)
+
+    @property
+    def values(self):
+        """
+        Read-only. A sequence containing the float values for this series, in
+        the order they appear on the chart.
+        """
+        return tuple(self.iter_values())
+
+
+class BubbleSeries(XySeries):
+    """
+    A data point series belonging to a bubble plot.
+    """
+
+    @lazyproperty
+    def points(self):
+        """
+        The |BubblePoints| object providing access to individual data point
+        objects used to discover and adjust the formatting and data labels of
+        a data point.
+        """
+        return BubblePoints(self._ser)
+
+
+class SeriesCollection(Sequence):
+    """
+    A sequence of |Series| objects.
+    """
+
+    def __init__(self, parent_elm):
+        # *parent_elm* can be either a c:plotArea or xChart element
+        super(SeriesCollection, self).__init__()
+        self._element = parent_elm
+
+    def __getitem__(self, index):
+        ser = self._element.sers[index]
+        return _SeriesFactory(ser)
+
+    def __len__(self):
+        return len(self._element.sers)
+
+
+def _SeriesFactory(ser):
+    """
+    Return an instance of the appropriate subclass of _BaseSeries based on the
+    xChart element *ser* appears in.
+    """
+    xChart_tag = ser.getparent().tag
+
+    try:
+        SeriesCls = {
+            qn("c:areaChart"): AreaSeries,
+            qn("c:barChart"): BarSeries,
+            qn("c:bubbleChart"): BubbleSeries,
+            qn("c:doughnutChart"): PieSeries,
+            qn("c:lineChart"): LineSeries,
+            qn("c:pieChart"): PieSeries,
+            qn("c:radarChart"): RadarSeries,
+            qn("c:scatterChart"): XySeries,
+        }[xChart_tag]
+    except KeyError:
+        raise NotImplementedError("series class for %s not yet implemented" % xChart_tag)
+
+    return SeriesCls(ser)