python-pptx2 2.13.0__py3-none-any.whl

pptx2/chart/plot.py

@@ -0,0 +1,462 @@
+"""Plot-related objects.
+
+A plot is known as a chart group in the MS API. A chart can have more than one plot overlayed on
+each other, such as a line plot layered over a bar plot.
+"""
+
+from __future__ import annotations
+
+from pptx2.chart.category import Categories
+from pptx2.chart.datalabel import DataLabels
+from pptx2.chart.series import SeriesCollection
+from pptx2.enum.chart import XL_CHART_TYPE as XL
+from pptx2.oxml.ns import qn
+from pptx2.oxml.simpletypes import ST_BarDir, ST_Grouping
+from pptx2.util import lazyproperty
+
+
+class _BasePlot(object):
+    """
+    A distinct plot that appears in the plot area of a chart. A chart may
+    have more than one plot, in which case they appear as superimposed
+    layers, such as a line plot appearing on top of a bar chart.
+    """
+
+    def __init__(self, xChart, chart):
+        super(_BasePlot, self).__init__()
+        self._element = xChart
+        self._chart = chart
+
+    @lazyproperty
+    def categories(self):
+        """
+        Returns a |category.Categories| sequence object containing
+        a |category.Category| object for each of the category labels
+        associated with this plot. The |category.Category| class derives from
+        ``str``, so the returned value can be treated as a simple sequence of
+        strings for the common case where all you need is the labels in the
+        order they appear on the chart. |category.Categories| provides
+        additional properties for dealing with hierarchical categories when
+        required.
+        """
+        return Categories(self._element)
+
+    @property
+    def chart(self):
+        """
+        The |Chart| object containing this plot.
+        """
+        return self._chart
+
+    @property
+    def data_labels(self):
+        """
+        |DataLabels| instance providing properties and methods on the
+        collection of data labels associated with this plot.
+        """
+        dLbls = self._element.dLbls
+        if dLbls is None:
+            raise ValueError("plot has no data labels, set has_data_labels = True first")
+        return DataLabels(dLbls)
+
+    @property
+    def has_data_labels(self):
+        """
+        Read/write boolean, |True| if the series has data labels. Assigning
+        |True| causes data labels to be added to the plot. Assigning False
+        removes any existing data labels.
+        """
+        return self._element.dLbls is not None
+
+    @has_data_labels.setter
+    def has_data_labels(self, value):
+        """
+        Add, remove, or leave alone the ``<c:dLbls>`` child element depending
+        on current state and assigned *value*. If *value* is |True| and no
+        ``<c:dLbls>`` element is present, a new default element is added with
+        default child elements and settings. When |False|, any existing dLbls
+        element is removed.
+        """
+        if bool(value) is False:
+            self._element._remove_dLbls()
+        else:
+            if self._element.dLbls is None:
+                dLbls = self._element._add_dLbls()
+                dLbls.showVal.val = True
+
+    @lazyproperty
+    def series(self):
+        """
+        A sequence of |Series| objects representing the series in this plot,
+        in the order they appear in the plot.
+        """
+        return SeriesCollection(self._element)
+
+    @property
+    def vary_by_categories(self):
+        """
+        Read/write boolean value specifying whether to use a different color
+        for each of the points in this plot. Only effective when there is
+        a single series; PowerPoint automatically varies color by series when
+        more than one series is present.
+        """
+        varyColors = self._element.varyColors
+        if varyColors is None:
+            return True
+        return varyColors.val
+
+    @vary_by_categories.setter
+    def vary_by_categories(self, value):
+        self._element.get_or_add_varyColors().val = bool(value)
+
+
+class AreaPlot(_BasePlot):
+    """
+    An area plot.
+    """
+
+
+class Area3DPlot(_BasePlot):
+    """
+    A 3-dimensional area plot.
+    """
+
+
+class BarPlot(_BasePlot):
+    """
+    A bar chart-style plot.
+    """
+
+    @property
+    def gap_width(self):
+        """
+        Width of gap between bar(s) of each category, as an integer
+        percentage of the bar width. The default value for a new bar chart is
+        150, representing 150% or 1.5 times the width of a single bar.
+        """
+        gapWidth = self._element.gapWidth
+        if gapWidth is None:
+            return 150
+        return gapWidth.val
+
+    @gap_width.setter
+    def gap_width(self, value):
+        gapWidth = self._element.get_or_add_gapWidth()
+        gapWidth.val = value
+
+    @property
+    def overlap(self):
+        """
+        Read/write int value in range -100..100 specifying a percentage of
+        the bar width by which to overlap adjacent bars in a multi-series bar
+        chart. Default is 0. A setting of -100 creates a gap of a full bar
+        width and a setting of 100 causes all the bars in a category to be
+        superimposed. A stacked bar plot has overlap of 100 by default.
+        """
+        overlap = self._element.overlap
+        if overlap is None:
+            return 0
+        return overlap.val
+
+    @overlap.setter
+    def overlap(self, value):
+        """
+        Set the value of the ``<c:overlap>`` child element to *int_value*,
+        or remove the overlap element if *int_value* is 0.
+        """
+        if value == 0:
+            self._element._remove_overlap()
+            return
+        self._element.get_or_add_overlap().val = value
+
+
+class BubblePlot(_BasePlot):
+    """
+    A bubble chart plot.
+    """
+
+    @property
+    def bubble_scale(self):
+        """
+        An integer between 0 and 300 inclusive indicating the percentage of
+        the default size at which bubbles should be displayed. Assigning
+        |None| produces the same behavior as assigning `100`.
+        """
+        bubbleScale = self._element.bubbleScale
+        if bubbleScale is None:
+            return 100
+        return bubbleScale.val
+
+    @bubble_scale.setter
+    def bubble_scale(self, value):
+        bubbleChart = self._element
+        bubbleChart._remove_bubbleScale()
+        if value is None:
+            return
+        bubbleScale = bubbleChart._add_bubbleScale()
+        bubbleScale.val = value
+
+
+class DoughnutPlot(_BasePlot):
+    """
+    An doughnut plot.
+    """
+
+    @property
+    def hole_size(self):
+        """
+        Read/write int in range 10..90 specifying the size of the doughnut
+        hole as a percentage of the chart radius. The PowerPoint default for a
+        new doughnut chart is 50, which is what this property reports when no
+        explicit ``<c:holeSize>`` element is present.
+        """
+        holeSize = self._element.holeSize
+        if holeSize is None:
+            return 50
+        return holeSize.val
+
+    @hole_size.setter
+    def hole_size(self, value):
+        holeSize = self._element.get_or_add_holeSize()
+        holeSize.val = value
+
+
+class LinePlot(_BasePlot):
+    """
+    A line chart-style plot.
+    """
+
+    @property
+    def smooth(self):
+        """
+        Read/write bool specifying whether the lines in this plot are smoothed
+        (curve-fitted) rather than drawn as straight segments between points.
+        Reading returns |True| only when *every* series in the plot is
+        smoothed. Assigning a value sets the ``<c:smooth>`` element on each
+        line series in the plot.
+        """
+        sers = self._element.sers
+        if not sers:
+            return False
+        for ser in sers:
+            smooth = ser.smooth
+            if smooth is None or not smooth.val:
+                return False
+        return True
+
+    @smooth.setter
+    def smooth(self, value):
+        value = bool(value)
+        for ser in self._element.sers:
+            ser.get_or_add_smooth().val = value
+
+
+class PiePlot(_BasePlot):
+    """
+    A pie chart-style plot.
+    """
+
+
+class RadarPlot(_BasePlot):
+    """
+    A radar-style plot.
+    """
+
+
+class XyPlot(_BasePlot):
+    """
+    An XY (scatter) plot.
+    """
+
+
+def PlotFactory(xChart, chart):
+    """
+    Return an instance of the appropriate subclass of _BasePlot based on the
+    tagname of *xChart*.
+    """
+    try:
+        PlotCls = {
+            qn("c:areaChart"): AreaPlot,
+            qn("c:area3DChart"): Area3DPlot,
+            qn("c:barChart"): BarPlot,
+            qn("c:bubbleChart"): BubblePlot,
+            qn("c:doughnutChart"): DoughnutPlot,
+            qn("c:lineChart"): LinePlot,
+            qn("c:pieChart"): PiePlot,
+            qn("c:radarChart"): RadarPlot,
+            qn("c:scatterChart"): XyPlot,
+        }[xChart.tag]
+    except KeyError:
+        raise ValueError("unsupported plot type %s" % xChart.tag)
+
+    return PlotCls(xChart, chart)
+
+
+class PlotTypeInspector(object):
+    """
+    "One-shot" service object that knows how to identify the type of a plot
+    as a member of the XL_CHART_TYPE enumeration.
+    """
+
+    @classmethod
+    def chart_type(cls, plot):
+        """
+        Return the member of :ref:`XlChartType` that corresponds to the chart
+        type of *plot*.
+        """
+        try:
+            chart_type_method = {
+                "AreaPlot": cls._differentiate_area_chart_type,
+                "Area3DPlot": cls._differentiate_area_3d_chart_type,
+                "BarPlot": cls._differentiate_bar_chart_type,
+                "BubblePlot": cls._differentiate_bubble_chart_type,
+                "DoughnutPlot": cls._differentiate_doughnut_chart_type,
+                "LinePlot": cls._differentiate_line_chart_type,
+                "PiePlot": cls._differentiate_pie_chart_type,
+                "RadarPlot": cls._differentiate_radar_chart_type,
+                "XyPlot": cls._differentiate_xy_chart_type,
+            }[plot.__class__.__name__]
+        except KeyError:
+            raise NotImplementedError(
+                "chart_type() not implemented for %s" % plot.__class__.__name__
+            )
+        return chart_type_method(plot)
+
+    @classmethod
+    def _differentiate_area_3d_chart_type(cls, plot):
+        return {
+            ST_Grouping.STANDARD: XL.THREE_D_AREA,
+            ST_Grouping.STACKED: XL.THREE_D_AREA_STACKED,
+            ST_Grouping.PERCENT_STACKED: XL.THREE_D_AREA_STACKED_100,
+        }[plot._element.grouping_val]
+
+    @classmethod
+    def _differentiate_area_chart_type(cls, plot):
+        return {
+            ST_Grouping.STANDARD: XL.AREA,
+            ST_Grouping.STACKED: XL.AREA_STACKED,
+            ST_Grouping.PERCENT_STACKED: XL.AREA_STACKED_100,
+        }[plot._element.grouping_val]
+
+    @classmethod
+    def _differentiate_bar_chart_type(cls, plot):
+        barChart = plot._element
+        if barChart.barDir.val == ST_BarDir.BAR:
+            return {
+                ST_Grouping.CLUSTERED: XL.BAR_CLUSTERED,
+                ST_Grouping.STACKED: XL.BAR_STACKED,
+                ST_Grouping.PERCENT_STACKED: XL.BAR_STACKED_100,
+            }[barChart.grouping_val]
+        if barChart.barDir.val == ST_BarDir.COL:
+            return {
+                ST_Grouping.CLUSTERED: XL.COLUMN_CLUSTERED,
+                ST_Grouping.STACKED: XL.COLUMN_STACKED,
+                ST_Grouping.PERCENT_STACKED: XL.COLUMN_STACKED_100,
+            }[barChart.grouping_val]
+        raise ValueError("invalid barChart.barDir value '%s'" % barChart.barDir.val)
+
+    @classmethod
+    def _differentiate_bubble_chart_type(cls, plot):
+        def first_bubble3D(bubbleChart):
+            results = bubbleChart.xpath("c:ser/c:bubble3D")
+            return results[0] if results else None
+
+        bubbleChart = plot._element
+        bubble3D = first_bubble3D(bubbleChart)
+
+        if bubble3D is None:
+            return XL.BUBBLE
+        if bubble3D.val:
+            return XL.BUBBLE_THREE_D_EFFECT
+        return XL.BUBBLE
+
+    @classmethod
+    def _differentiate_doughnut_chart_type(cls, plot):
+        doughnutChart = plot._element
+        explosion = doughnutChart.xpath("./c:ser/c:explosion")
+        return XL.DOUGHNUT_EXPLODED if explosion else XL.DOUGHNUT
+
+    @classmethod
+    def _differentiate_line_chart_type(cls, plot):
+        lineChart = plot._element
+
+        def has_line_markers():
+            matches = lineChart.xpath('c:ser/c:marker/c:symbol[@val="none"]')
+            if matches:
+                return False
+            return True
+
+        if has_line_markers():
+            return {
+                ST_Grouping.STANDARD: XL.LINE_MARKERS,
+                ST_Grouping.STACKED: XL.LINE_MARKERS_STACKED,
+                ST_Grouping.PERCENT_STACKED: XL.LINE_MARKERS_STACKED_100,
+            }[plot._element.grouping_val]
+        else:
+            return {
+                ST_Grouping.STANDARD: XL.LINE,
+                ST_Grouping.STACKED: XL.LINE_STACKED,
+                ST_Grouping.PERCENT_STACKED: XL.LINE_STACKED_100,
+            }[plot._element.grouping_val]
+
+    @classmethod
+    def _differentiate_pie_chart_type(cls, plot):
+        pieChart = plot._element
+        explosion = pieChart.xpath("./c:ser/c:explosion")
+        return XL.PIE_EXPLODED if explosion else XL.PIE
+
+    @classmethod
+    def _differentiate_radar_chart_type(cls, plot):
+        radarChart = plot._element
+        radar_style = radarChart.xpath("c:radarStyle")[0].get("val")
+
+        def noMarkers():
+            matches = radarChart.xpath("c:ser/c:marker/c:symbol")
+            if matches and matches[0].get("val") == "none":
+                return True
+            return False
+
+        if radar_style is None:
+            return XL.RADAR
+        if radar_style == "filled":
+            return XL.RADAR_FILLED
+        if noMarkers():
+            return XL.RADAR
+        return XL.RADAR_MARKERS
+
+    @classmethod
+    def _differentiate_xy_chart_type(cls, plot):
+        scatterChart = plot._element
+
+        def noLine():
+            return bool(scatterChart.xpath("c:ser/c:spPr/a:ln/a:noFill"))
+
+        def noMarkers():
+            symbols = scatterChart.xpath("c:ser/c:marker/c:symbol")
+            if symbols and symbols[0].get("val") == "none":
+                return True
+            return False
+
+        scatter_style = scatterChart.xpath("c:scatterStyle")[0].get("val")
+
+        # ``val="marker"`` (markers-only) is the canonical OOXML way to
+        # encode XY_SCATTER and is what the writer now emits. The legacy
+        # ``lineMarker + noLine`` combination is still recognised so
+        # decks saved by earlier releases keep round-tripping. See
+        # IMPROVEMENTS item 5.
+        if scatter_style == "marker":
+            return XL.XY_SCATTER
+
+        if scatter_style == "lineMarker":
+            if noLine():
+                return XL.XY_SCATTER
+            if noMarkers():
+                return XL.XY_SCATTER_LINES_NO_MARKERS
+            return XL.XY_SCATTER_LINES
+
+        if scatter_style == "smoothMarker":
+            if noMarkers():
+                return XL.XY_SCATTER_SMOOTH_NO_MARKERS
+            return XL.XY_SCATTER_SMOOTH
+
+        return XL.XY_SCATTER

pptx2/chart/point.py

@@ -0,0 +1,101 @@
+"""Data point-related objects."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pptx2.chart.datalabel import DataLabel
+from pptx2.chart.marker import Marker
+from pptx2.dml.chtfmt import ChartFormat
+from pptx2.util import lazyproperty
+
+
+class _BasePoints(Sequence):
+    """
+    Sequence providing access to the individual data points in a series.
+    """
+
+    def __init__(self, ser):
+        super(_BasePoints, self).__init__()
+        self._element = ser
+        self._ser = ser
+
+    def __getitem__(self, idx):
+        if idx < 0 or idx >= self.__len__():
+            raise IndexError("point index out of range")
+        return Point(self._ser, idx)
+
+
+class BubblePoints(_BasePoints):
+    """
+    Sequence providing access to the individual data points in
+    a |BubbleSeries| object.
+    """
+
+    def __len__(self):
+        return min(
+            self._ser.xVal_ptCount_val,
+            self._ser.yVal_ptCount_val,
+            self._ser.bubbleSize_ptCount_val,
+        )
+
+
+class CategoryPoints(_BasePoints):
+    """
+    Sequence providing access to individual |Point| objects, each
+    representing the visual properties of a data point in the specified
+    category series.
+    """
+
+    def __len__(self):
+        return self._ser.cat_ptCount_val
+
+
+class Point(object):
+    """
+    Provides access to the properties of an individual data point in
+    a series, such as the visual properties of its marker and the text and
+    font of its data label.
+    """
+
+    def __init__(self, ser, idx):
+        super(Point, self).__init__()
+        self._element = ser
+        self._ser = ser
+        self._idx = idx
+
+    @lazyproperty
+    def data_label(self):
+        """
+        The |DataLabel| object representing the label on this data point.
+        """
+        return DataLabel(self._ser, self._idx)
+
+    @lazyproperty
+    def format(self):
+        """
+        The |ChartFormat| object providing access to the shape formatting
+        properties of this data point, such as line and fill.
+        """
+        dPt = self._ser.get_or_add_dPt_for_point(self._idx)
+        return ChartFormat(dPt)
+
+    @lazyproperty
+    def marker(self):
+        """
+        The |Marker| instance for this point, providing access to the visual
+        properties of the data point marker, such as fill and line. Setting
+        these properties overrides any value set at the series level.
+        """
+        dPt = self._ser.get_or_add_dPt_for_point(self._idx)
+        return Marker(dPt)
+
+
+class XyPoints(_BasePoints):
+    """
+    Sequence providing access to the individual data points in an |XySeries|
+    object.
+    """
+
+    def __len__(self):
+        return min(self._ser.xVal_ptCount_val, self._ser.yVal_ptCount_val)