ps-python-pptx 1.1.0__py3-none-any.whl

pptx/chart/series.py

@@ -0,0 +1,258 @@
+"""Series-related objects."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pptx.chart.datalabel import DataLabels
+from pptx.chart.marker import Marker
+from pptx.chart.point import BubblePoints, CategoryPoints, XyPoints
+from pptx.dml.chtfmt import ChartFormat
+from pptx.oxml.ns import qn
+from pptx.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 AreaSeries(_BaseCategorySeries):
+    """
+    A data point series belonging to an area plot.
+    """
+
+
+class BarSeries(_BaseCategorySeries):
+    """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):
+    """
+    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):
+    """
+    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)

pptx/chart/xlsx.py

@@ -0,0 +1,272 @@
+"""Chart builder and related objects."""
+
+from __future__ import annotations
+
+import io
+from contextlib import contextmanager
+
+from xlsxwriter import Workbook
+
+
+class _BaseWorkbookWriter(object):
+    """Base class for workbook writers, providing shared members."""
+
+    def __init__(self, chart_data):
+        super(_BaseWorkbookWriter, self).__init__()
+        self._chart_data = chart_data
+
+    @property
+    def xlsx_blob(self):
+        """bytes for Excel file containing chart_data."""
+        xlsx_file = io.BytesIO()
+        with self._open_worksheet(xlsx_file) as (workbook, worksheet):
+            self._populate_worksheet(workbook, worksheet)
+        return xlsx_file.getvalue()
+
+    @contextmanager
+    def _open_worksheet(self, xlsx_file):
+        """
+        Enable XlsxWriter Worksheet object to be opened, operated on, and
+        then automatically closed within a `with` statement. A filename or
+        stream object (such as an `io.BytesIO` instance) is expected as
+        *xlsx_file*.
+        """
+        workbook = Workbook(xlsx_file, {"in_memory": True})
+        worksheet = workbook.add_worksheet()
+        yield workbook, worksheet
+        workbook.close()
+
+    def _populate_worksheet(self, workbook, worksheet):
+        """
+        Must be overridden by each subclass to provide the particulars of
+        writing the spreadsheet data.
+        """
+        raise NotImplementedError("must be provided by each subclass")
+
+
+class CategoryWorkbookWriter(_BaseWorkbookWriter):
+    """
+    Determines Excel worksheet layout and can write an Excel workbook from
+    a CategoryChartData object. Serves as the authority for Excel worksheet
+    ranges.
+    """
+
+    @property
+    def categories_ref(self):
+        """
+        The Excel worksheet reference to the categories for this chart (not
+        including the column heading).
+        """
+        categories = self._chart_data.categories
+        if categories.depth == 0:
+            raise ValueError("chart data contains no categories")
+        right_col = chr(ord("A") + categories.depth - 1)
+        bottom_row = categories.leaf_count + 1
+        return "Sheet1!$A$2:$%s$%d" % (right_col, bottom_row)
+
+    def series_name_ref(self, series):
+        """
+        Return the Excel worksheet reference to the cell containing the name
+        for *series*. This also serves as the column heading for the series
+        values.
+        """
+        return "Sheet1!$%s$1" % self._series_col_letter(series)
+
+    def values_ref(self, series):
+        """
+        The Excel worksheet reference to the values for this series (not
+        including the column heading).
+        """
+        return "Sheet1!${col_letter}$2:${col_letter}${bottom_row}".format(
+            **{
+                "col_letter": self._series_col_letter(series),
+                "bottom_row": len(series) + 1,
+            }
+        )
+
+    @staticmethod
+    def _column_reference(column_number):
+        """Return str Excel column reference like 'BQ' for *column_number*.
+
+        *column_number* is an int in the range 1-16384 inclusive, where
+        1 maps to column 'A'.
+        """
+        if column_number < 1 or column_number > 16384:
+            raise ValueError("column_number must be in range 1-16384")
+
+        # ---Work right-to-left, one order of magnitude at a time. Note there
+        #    is no zero representation in Excel address scheme, so this is
+        #    not just a conversion to base-26---
+
+        col_ref = ""
+        while column_number:
+            remainder = column_number % 26
+            if remainder == 0:
+                remainder = 26
+
+            col_letter = chr(ord("A") + remainder - 1)
+            col_ref = col_letter + col_ref
+
+            # ---Advance to next order of magnitude or terminate loop. The
+            # minus-one in this expression reflects the fact the next lower
+            # order of magnitude has a minumum value of 1 (not zero). This is
+            # essentially the complement to the "if it's 0 make it 26' step
+            # above.---
+            column_number = (column_number - 1) // 26
+
+        return col_ref
+
+    def _populate_worksheet(self, workbook, worksheet):
+        """
+        Write the chart data contents to *worksheet* in category chart
+        layout. Write categories starting in the first column starting in
+        the second row, and proceeding one column per category level (for
+        charts having multi-level categories). Write series as columns
+        starting in the next following column, placing the series title in
+        the first cell.
+        """
+        self._write_categories(workbook, worksheet)
+        self._write_series(workbook, worksheet)
+
+    def _series_col_letter(self, series):
+        """
+        The letter of the Excel worksheet column in which the data for a
+        series appears.
+        """
+        column_number = 1 + series.categories.depth + series.index
+        return self._column_reference(column_number)
+
+    def _write_categories(self, workbook, worksheet):
+        """
+        Write the categories column(s) to *worksheet*. Categories start in
+        the first column starting in the second row, and proceeding one
+        column per category level (for charts having multi-level categories).
+        A date category is formatted as a date. All others are formatted
+        `General`.
+        """
+        categories = self._chart_data.categories
+        num_format = workbook.add_format({"num_format": categories.number_format})
+        depth = categories.depth
+        for idx, level in enumerate(categories.levels):
+            col = depth - idx - 1
+            self._write_cat_column(worksheet, col, level, num_format)
+
+    def _write_cat_column(self, worksheet, col, level, num_format):
+        """
+        Write a category column defined by *level* to *worksheet* at offset
+        *col* and formatted with *num_format*.
+        """
+        worksheet.set_column(col, col, 10)  # wide enough for a date
+        for off, name in level:
+            row = off + 1
+            worksheet.write(row, col, name, num_format)
+
+    def _write_series(self, workbook, worksheet):
+        """
+        Write the series column(s) to *worksheet*. Series start in the column
+        following the last categories column, placing the series title in the
+        first cell.
+        """
+        col_offset = self._chart_data.categories.depth
+        for idx, series in enumerate(self._chart_data):
+            num_format = workbook.add_format({"num_format": series.number_format})
+            series_col = idx + col_offset
+            worksheet.write(0, series_col, series.name)
+            worksheet.write_column(1, series_col, series.values, num_format)
+
+
+class XyWorkbookWriter(_BaseWorkbookWriter):
+    """
+    Determines Excel worksheet layout and can write an Excel workbook from XY
+    chart data. Serves as the authority for Excel worksheet ranges.
+    """
+
+    def series_name_ref(self, series):
+        """
+        Return the Excel worksheet reference to the cell containing the name
+        for *series*. This also serves as the column heading for the series
+        Y values.
+        """
+        row = self.series_table_row_offset(series) + 1
+        return "Sheet1!$B$%d" % row
+
+    def series_table_row_offset(self, series):
+        """
+        Return the number of rows preceding the data table for *series* in
+        the Excel worksheet.
+        """
+        title_and_spacer_rows = series.index * 2
+        data_point_rows = series.data_point_offset
+        return title_and_spacer_rows + data_point_rows
+
+    def x_values_ref(self, series):
+        """
+        The Excel worksheet reference to the X values for this chart (not
+        including the column label).
+        """
+        top_row = self.series_table_row_offset(series) + 2
+        bottom_row = top_row + len(series) - 1
+        return "Sheet1!$A$%d:$A$%d" % (top_row, bottom_row)
+
+    def y_values_ref(self, series):
+        """
+        The Excel worksheet reference to the Y values for this chart (not
+        including the column label).
+        """
+        top_row = self.series_table_row_offset(series) + 2
+        bottom_row = top_row + len(series) - 1
+        return "Sheet1!$B$%d:$B$%d" % (top_row, bottom_row)
+
+    def _populate_worksheet(self, workbook, worksheet):
+        """
+        Write chart data contents to *worksheet* in the standard XY chart
+        layout. Write the data for each series to a separate two-column
+        table, X values in column A and Y values in column B. Place the
+        series label in the first (heading) cell of the column.
+        """
+        chart_num_format = workbook.add_format({"num_format": self._chart_data.number_format})
+        for series in self._chart_data:
+            series_num_format = workbook.add_format({"num_format": series.number_format})
+            offset = self.series_table_row_offset(series)
+            # write X values
+            worksheet.write_column(offset + 1, 0, series.x_values, chart_num_format)
+            # write Y values
+            worksheet.write(offset, 1, series.name)
+            worksheet.write_column(offset + 1, 1, series.y_values, series_num_format)
+
+
+class BubbleWorkbookWriter(XyWorkbookWriter):
+    """
+    Service object that knows how to write an Excel workbook from bubble
+    chart data.
+    """
+
+    def bubble_sizes_ref(self, series):
+        """
+        The Excel worksheet reference to the range containing the bubble
+        sizes for *series* (not including the column heading cell).
+        """
+        top_row = self.series_table_row_offset(series) + 2
+        bottom_row = top_row + len(series) - 1
+        return "Sheet1!$C$%d:$C$%d" % (top_row, bottom_row)
+
+    def _populate_worksheet(self, workbook, worksheet):
+        """
+        Write chart data contents to *worksheet* in the bubble chart layout.
+        Write the data for each series to a separate three-column table with
+        X values in column A, Y values in column B, and bubble sizes in
+        column C. Place the series label in the first (heading) cell of the
+        values column.
+        """
+        chart_num_format = workbook.add_format({"num_format": self._chart_data.number_format})
+        for series in self._chart_data:
+            series_num_format = workbook.add_format({"num_format": series.number_format})
+            offset = self.series_table_row_offset(series)
+            # write X values
+            worksheet.write_column(offset + 1, 0, series.x_values, chart_num_format)
+            # write Y values
+            worksheet.write(offset, 1, series.name)
+            worksheet.write_column(offset + 1, 1, series.y_values, series_num_format)
+            # write bubble sizes
+            worksheet.write(offset, 2, "Size")
+            worksheet.write_column(offset + 1, 2, series.bubble_sizes, chart_num_format)