Charts

python-pptx provides an API for adding and manipulating charts. A chart object, like a table, is not a shape. Rather it is a graphical object contained in a GraphicFrame shape. The shape API, such as position, size, shape id, and name, are provided by the graphic frame shape. The chart itself is accessed using the chart property on the graphic frame shape.

Chart objects

The Chart object is the root of a generally hierarchical graph of component objects that together provide access to the properties and methods required to specify and format a chart.

class pptx.chart.chart.Chart(chartSpace, chart_part)[source]

A chart object.

category_axis

The category axis of this chart. In the case of an XY or Bubble chart, this is the X axis. Raises ValueError if no category axis is defined (as is the case for a pie chart, for example).

chart_style

Read/write integer index of chart style used to format this chart. Range is from 1 to 48. Value is None if no explicit style has been assigned, in which case the default chart style is used. Assigning None causes any explicit setting to be removed. The integer index corresponds to the style’s position in the chart style gallery in the PowerPoint UI.

chart_title

A ChartTitle object providing access to title properties.

Calling this property is destructive in the sense it adds a chart title element (c:title) to the chart XML if one is not already present. Use has_title to test for presence of a chart title non-destructively.

chart_type

Read-only XL_CHART_TYPE enumeration value specifying the type of this chart. If the chart has two plots, for example, a line plot overlayed on a bar plot, the type reported is for the first (back-most) plot.

has_legend

Read/write boolean, True if the chart has a legend. Assigning True causes a legend to be added to the chart if it doesn’t already have one. Assigning False removes any existing legend definition along with any existing legend settings.

has_title

Read/write boolean, specifying whether this chart has a title.

Assigning True causes a title to be added if not already present. Assigning False removes any existing title along with its text and settings.

legend

A Legend object providing access to the properties of the legend for this chart.

plots

The sequence of plots in this chart. A plot, called a chart group in the Microsoft API, is a distinct sequence of one or more series depicted in a particular charting type. For example, a chart having a series plotted as a line overlaid on three series plotted as columns would have two plots; the first corresponding to the three column series and the second to the line series. Plots are sequenced in the order drawn, i.e. back-most to front-most. Supports len(), membership (e.g. p in plots), iteration, slicing, and indexed access (e.g. plot = plots[i]).

replace_data(chart_data)[source]

Use the categories and series values in the ChartData object chart_data to replace those in the XML and Excel worksheet for this chart.

series

A SeriesCollection object containing all the series in this chart. When the chart has multiple plots, all the series for the first plot appear before all those for the second, and so on. Series within a plot have an explicit ordering and appear in that sequence.

value_axis

The ValueAxis object providing access to properties of the value axis of this chart. Raises ValueError if the chart has no value axis.

class pptx.chart.chart.ChartTitle[source]

Provides properties for manipulating a chart title.

format

ChartFormat object providing access to line and fill formatting.

Return the ChartFormat object providing shape formatting properties for this chart title, such as its line color and fill.

has_text_frame

Read/write Boolean specifying whether this title has a text frame.

Return True if this chart title has a text frame, 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 its text and formatting.

text_frame

TextFrame instance for this chart title.

Return a TextFrame instance allowing read/write access to the text of this chart title and its text formatting properties. Accessing this property is destructive in the sense it adds a text frame if one is not present. Use has_text_frame to test for the presence of a text frame non-destructively.

Legend objects

A legend provides a visual key relating each series of data points to their assigned meaning by mapping a color, line type, or point shape to each series name. A legend is optional, but there can be at most one. Most aspects of a legend are determined automatically, but aspects of its position may be specified via the API.

class pptx.chart.chart.Legend[source]

Represents the legend in a chart. A chart can have at most one legend.

font

The Font object that provides access to the text properties for this legend, such as bold, italic, etc.

horz_offset

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.

include_in_layout

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.

position

Read/write XL_LEGEND_POSITION enumeration value specifying the general region of the chart in which to place the legend.

Axis objects

A chart typically has two axes, a category axis and a value axis. In general, one of these is horizontal and the other is vertical, where which is which depends on the chart type. For example, the category axis is horizontal on a column chart, but vertical on a bar chart.

A chart where the independent variable is in a continuous (numeric) range, such as an XY/scatter chart, does not have a category axis. Rather it has two value axes.

A category is perhaps most commonly a string label, such as 'East' or 'Revenue'; however a category can also be a number or a date (although all categories in a chart must be the same type).

When a chart’s categories are dates, the category axis is generally, but not necessarily a DateAxis object.

A Chart may have zero to four axes. A pie chart, for example, has neither a category nor a value axis.

class pptx.chart.axis._BaseAxis[source]

Base class for chart axis objects. All axis objects share these properties.

axis_title

An AxisTitle object providing access to title properties.

Calling this property is destructive in the sense that it adds an axis title element (c:title) to the axis XML if one is not already present. Use has_title to test for presence of axis title non-destructively.

format

The ChartFormat object providing access to the shape formatting properties of this axis, such as its line color and fill.

has_major_gridlines

Read/write boolean value specifying whether this axis has gridlines at its major tick mark locations. Assigning True to this property causes major gridlines to be displayed. Assigning False causes them to be removed.

has_minor_gridlines

Read/write boolean value specifying whether this axis has gridlines at its minor tick mark locations. Assigning True to this property causes minor gridlines to be displayed. Assigning False causes them to be removed.

has_title

Read/write boolean specifying whether this axis has a title.

True if this axis has a title, False otherwise. Assigning True causes an axis title to be added if not already present. Assigning False causes any existing title to be deleted.

major_gridlines

The MajorGridlines object representing the major gridlines for this axis.

major_tick_mark

Read/write XL_TICK_MARK value specifying the type of major tick mark to display on this axis.

maximum_scale

Read/write float value specifying the upper limit of the value range for this axis, the number at the top or right of the vertical or horizontal value scale, respectively. The value None indicates the upper limit should be determined automatically based on the range of data point values associated with the axis.

minimum_scale

Read/write float value specifying lower limit of value range, the number at the bottom or left of the value scale. None if no minimum scale has been set. The value None indicates the lower limit should be determined automatically based on the range of data point values associated with the axis.

minor_tick_mark

Read/write XL_TICK_MARK value specifying the type of minor tick mark for this axis.

tick_labels

The TickLabels instance providing access to axis tick label formatting properties. Tick labels are the numbers appearing on a value axis or the category names appearing on a category axis.

tick_label_position

Read/write XL_TICK_LABEL_POSITION value specifying where the tick labels for this axis should appear.

visible

Read/write. True if axis is visible, False otherwise.

class pptx.chart.axis.CategoryAxis[source]

A category axis of a chart.

category_type

A member of XL_CATEGORY_TYPE specifying the scale type of this axis. Unconditionally CATEGORY_SCALE for a CategoryAxis object.

class pptx.chart.axis.DateAxis[source]

A category axis with dates as its category labels and having some special display behaviors such as making length of equal periods equal and normalizing month start dates despite unequal month lengths.

category_type

A member of XL_CATEGORY_TYPE specifying the scale type of this axis. Unconditionally TIME_SCALE for a DateAxis object.

class pptx.chart.axis.AxisTitle[source]

Provides properties for manipulating axis title.

format

ChartFormat object providing access to shape formatting.

Return the ChartFormat object providing shape formatting properties for this axis title, such as its line color and fill.

has_text_frame

Read/write Boolean specifying presence of a text frame.

Return True if this axis title has a text frame, 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.

text_frame

TextFrame instance for this axis title.

Return a TextFrame instance allowing read/write access to the text of this axis title and its text formatting properties. Accessing this property is destructive as it adds a new text frame if not already present.

Value Axes

Some axis properties are only relevant to value axes, in particular, those related to numeric values rather than text category labels.

class pptx.chart.axis.ValueAxis[source]

An axis having continuous (as opposed to discrete) values. The vertical axis is generally a value axis, however both axes of an XY-type chart are value axes.

crosses

Member of XL_AXIS_CROSSES enumeration specifying the point on this axis where the other axis crosses, such as auto/zero, minimum, or maximum. Returns XL_AXIS_CROSSES.CUSTOM when a specific numeric crossing point (e.g. 1.5) is defined.

crosses_at

Numeric value on this axis at which the perpendicular axis crosses. Returns None if no crossing value is set.

major_unit

The float number of units between major tick marks on this value axis. None corresponds to the ‘Auto’ setting in the UI, and specifies the value should be calculated by PowerPoint based on the underlying chart data.

minor_unit

The float number of units between minor tick marks on this value axis. None corresponds to the ‘Auto’ setting in the UI, and specifies the value should be calculated by PowerPoint based on the underlying chart data.

MajorGridlines objects

Gridlines are the vertical and horizontal lines that extend major tick marks of an axis across the chart to ease comparison of a data point with the axis divisions.

class pptx.chart.axis.MajorGridlines[source]

Provides access to the properties of the major gridlines appearing on an axis.

format

The ChartFormat object providing access to the shape formatting properties of this data point, such as line and fill.

TickLabels objects

Tick labels are the numbers appearing on a value axis or the category names appearing on a category axis. Certain formatting options are available for changing how these labels are displayed.

class pptx.chart.axis.TickLabels[source]

A service class providing access to formatting of axis tick mark labels.

font

The Font object that provides access to the text properties for these tick labels, such as bold, italic, etc.

number_format

Read/write string (e.g. “$#,##0.00”) specifying the format for the numbers on this axis. The syntax for these strings is the same as it appears in the PowerPoint or Excel UI. Returns ‘General’ if no number format has been set. Note that this format string has no effect on rendered tick labels when number_format_is_linked() is True. Assigning a format string to this property automatically sets number_format_is_linked() to False.

number_format_is_linked

Read/write boolean specifying whether number formatting should be taken from the source spreadsheet rather than the value of number_format().

offset

Read/write int value in range 0-1000 specifying the spacing between the tick mark labels and the axis as a percentange of the default value. 100 if no label offset setting is present.

_BasePlot objects

A plot is a group of series all depicted using the same charting type, e.g. bar, column, line, etc. Most charts have only a single plot; however, a chart may have multiple, as in where a line plot appears overlaid on a bar plot in the same chart. In the Microsoft API, this concept has the name chart group. The term plot was chosen for python-pptx to avoid the common mistake of understanding a chart group to be a group of chart objects.

Certain properties must be set at the plot level. Some of those properties are not present on plots of all chart types. For example, gap_width is only present on a bar or column plot.

class pptx.chart.plot._BasePlot[source]

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.

categories

Returns a Categories sequence object containing a Category object for each of the category labels associated with this plot. The 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. Categories provides additional properties for dealing with hierarchical categories when required.

chart

The Chart object containing this plot.

data_labels

DataLabels instance providing properties and methods on the collection of data labels associated with this plot.

has_data_labels

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.

series

A sequence of Series objects representing the series in this plot, in the order they appear in the plot.

vary_by_categories

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.

BarPlot objects

The following properties are only present on bar-type plots, which includes both bar and column charts.

class pptx.chart.plot.BarPlot[source]

A bar chart-style plot.

gap_width

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.

overlap

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.

BubblePlot objects

The following properties are only present on bubble-type plots.

class pptx.chart.plot.BubblePlot[source]

A bubble chart plot.

bubble_scale

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.

Categories objects

Category plots provide access to a Categories object with their .categories property.

class pptx.chart.category.Categories[source]

A sequence of Category objects, each representing a category label on the chart. Provides properties for dealing with hierarchical categories.

depth

Return an integer representing the number of hierarchical levels in this category collection. Returns 1 for non-hierarchical categories and 0 if no categories are present (generally meaning no series are present).

flattened_labels

Return a sequence of tuples, each containing the flattened hierarchy of category labels for a leaf category. Each tuple is in parent -> child order, e.g. ('US', 'CA', 'San Francisco'), with the leaf category appearing last. If this categories collection is non-hierarchical, each tuple will contain only a leaf category label. If the plot has no series (and therefore no categories), an empty tuple is returned.

levels

Return a sequence of CategoryLevel objects representing the hierarchy of this category collection. The sequence is empty when the category collection is not hierarchical, that is, contains only leaf-level categories. The levels are ordered from the leaf level to the root level; so the first level will contain the same categories as this category collection.

Category objects

class pptx.chart.category.Category[source]

An extension of str that provides the category label as its string value, and additional attributes representing other aspects of the category.

idx

Return an integer representing the index reference of this category. For a leaf node, the index identifies the category. For a parent (or other ancestor) category, the index specifies the first leaf category that ancestor encloses.

label

Return the label of this category as a string.

CategoryLevel objects

class pptx.chart.category.CategoryLevel[source]

A sequence of Category objects representing a single level in a hierarchical category collection. This object is only used when the categories are hierarchical, meaning they have more than one level and higher level categories group those at lower levels.

DataLabels objects

A data label is text that labels a particular data point, usually with its value, allowing the point to be interpreted more clearly than just visually comparing its marker with its axis.

A DataLabels object is not a collection, such as a sequence, and it does not provide access to individual data points. Rather, it provides properties that allow all the data labels in its scope to be formatted at once.

class pptx.chart.datalabel.DataLabels[source]

Collection of data labels associated with a plot, and perhaps with a series or data point, although the latter two are not yet implemented.

font

The Font object that provides access to the text properties for these data labels, such as bold, italic, etc.

number_format

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 number_format_is_linked() is True. Assigning a format string to this property automatically sets number_format_is_linked() to False.

number_format_is_linked

Read/write boolean specifying whether number formatting should be taken from the source spreadsheet rather than the value of number_format().

position

Read/write XL_DATA_LABEL_POSITION 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.

class pptx.chart.datalabel.DataLabel[source]

The data label associated with an individual data point.

font

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.

has_text_frame

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.

position

Read/write XL_DATA_LABEL_POSITION 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.

text_frame

TextFrame instance for this data label, containing the text of the data label and providing access to its text formatting properties.

Series objects

A series is a sequence of data points that represent a coherent set of observations across each of the categories in the chart. For example, on a chart having regional categories “West”, “East”, and “Mid-west”, a series might be “Q1 Sales” and have values 42, 120, and 34. The series in this case coheres around the first quarter time period.

In general, the type (class) of a series object depends upon the chart type. The following properties are available on series objects of all types.

class pptx.chart.series._BaseSeries[source]

Base class for BarSeries and other series classes.

format

The ChartFormat instance for this series, providing access to shape properties such as fill and line.

index

The zero-based integer index of this series as reported in its c:ser/c:idx element.

name

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.

BarSeries objects

These properties are available on a series belonging to a bar-type plot.

class pptx.chart.series.BarSeries[source]

A data point series belonging to a bar plot.

fill

DEPRECATED. Use .format.fill instead.

Return the FillFormat object providing access to fill properties such as fill color.

invert_if_negative

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”.

line

DEPRECATED. Use .format.line instead.

Return the LineFormat object providing access to line properties such as line color and width.

format

The ChartFormat instance for this series, providing access to shape properties such as fill and line.

index

The zero-based integer index of this series as reported in its c:ser/c:idx element.

name

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.

points

The CategoryPoints object providing access to individual data points in this series.

values

Read-only. A sequence containing the float values for this series, in the order they appear on the chart.

LineSeries objects

These properties are available on a series belonging to a line-type plot.

class pptx.chart.series.LineSeries[source]

A data point series belonging to a line plot.

smooth

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.

format

The ChartFormat instance for this series, providing access to shape properties such as fill and line.

index

The zero-based integer index of this series as reported in its c:ser/c:idx element.

marker

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.

name

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.

points

The CategoryPoints object providing access to individual data points in this series.

values

Read-only. A sequence containing the float values for this series, in the order they appear on the chart.

XySeries objects

These properties are available on series belonging to an XY plot.

class pptx.chart.series.XySeries[source]

A data point series belonging to an XY (scatter) plot.

iter_values()[source]

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).

points

The XyPoints object providing access to individual data points in this series.

values

Read-only. A sequence containing the float values for this series, in the order they appear on the chart.

format

The ChartFormat instance for this series, providing access to shape properties such as fill and line.

index

The zero-based integer index of this series as reported in its c:ser/c:idx element.

marker

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.

name

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.

Point objects

An XY or bubble chart has a points attribute providing access to a sequence of Point objects. That sequence supports iteration, indexed access, and len().

class pptx.chart.point.CategoryPoints[source]

Sequence providing access to individual Point objects, each representing the visual properties of a data point in the specified category series.

class pptx.chart.point.BubblePoints[source]

Sequence providing access to the individual data points in a BubbleSeries object.

class pptx.chart.point.XyPoints[source]

Sequence providing access to the individual data points in an XySeries object.

class pptx.chart.point.Point[source]

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.

data_label

The DataLabel object representing the label on this data point.

format

The ChartFormat object providing access to the shape formatting properties of this data point, such as line and fill.

marker

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.