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.
A chart object.
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).
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.
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.
Member of XL_CHART_TYPE enumeration specifying 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. Read-only.
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.
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.
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]).
Use the categories and series values in the ChartData object
chart_data to replace those in the XML and Excel worksheet for this
chart.
Provides properties for manipulating a chart title.
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.
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.
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.
Represents the legend in a chart. A chart can have at most one legend.
The Font object that provides access to the text properties for
this legend, such as bold, italic, etc.
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.
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.
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.
Base class for chart axis objects. All axis objects share these properties.
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.
The ChartFormat object providing access to the shape formatting
properties of this axis, such as its line color and fill.
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.
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.
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.
The MajorGridlines object representing the major gridlines for
this axis.
Read/write XL_TICK_MARK value specifying the type of major tick mark to display on this axis.
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.
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.
Read/write XL_TICK_MARK value specifying the type of minor tick mark for this axis.
Read/write bool value specifying whether to reverse plotting order for axis.
For a category axis, this reverses the order in which the categories are displayed. This may be desired, for example, on a (horizontal) bar-chart where by default the first category appears at the bottom. Since we read from top-to-bottom, many viewers may find it most natural for the first category to appear on top.
For a value axis, it reverses the direction of increasing value from bottom-to-top to top-to-bottom.
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.
Read/write XL_TICK_LABEL_POSITION value specifying where the tick labels for this axis should appear.
Read/write. True if axis is visible, False otherwise.
A category axis of a chart.
A member of XL_CATEGORY_TYPE specifying the scale type of this
axis. Unconditionally CATEGORY_SCALE for a CategoryAxis object.
A category axis with dates as its category labels.
This axis-type has some special display behaviors such as making length of equal periods equal and normalizing month start dates despite unequal month lengths.
A member of XL_CATEGORY_TYPE specifying the scale type of this
axis. Unconditionally TIME_SCALE for a DateAxis object.
Provides properties for manipulating axis title.
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.
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.
Some axis properties are only relevant to value axes, in particular, those related to numeric values rather than text category labels.
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.
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.
Numeric value on this axis at which the perpendicular axis crosses.
Returns None if no crossing value is set.
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.
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.
Provides access to the properties of the major gridlines appearing on an axis.
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.
A service class providing access to formatting of axis tick mark labels.
The Font object that provides access to the text properties for
these tick labels, such as bold, italic, etc.
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.
Read/write boolean specifying whether number formatting should be
taken from the source spreadsheet rather than the value of
number_format().
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.
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.
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.
DataLabels instance providing properties and methods on the
collection of data labels associated with this plot.
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.
A sequence of Series objects representing the series in this plot,
in the order they appear in the plot.
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.
A bar chart-style plot.
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.
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.
Categories objects¶Category plots provide access to a Categories object with their
.categories property.
A sequence of Category objects, each representing a category
label on the chart. Provides properties for dealing with hierarchical
categories.
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).
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.
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¶An extension of str that provides the category label as its string value, and additional attributes representing other aspects of the category.
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.
Return the label of this category as a string.
CategoryLevel objects¶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.
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.
The Font object that provides access to the text properties for
these data labels, such as bold, italic, etc.
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.
Read/write boolean specifying whether number formatting should be
taken from the source spreadsheet rather than the value of
number_format().
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.
Read/write. True when name of category should appear in label.
Read/write. True when data label displays legend-color swatch.
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.
Read/write. True when data label displays series name.
Read/write. True when label displays numeric value of datapoint.
The data label associated with an individual data point.
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.
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.
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.
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.
Base class for BarSeries and other series classes.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
AreaSeries objects¶These properties are available on a series belonging to an area-type plot such as AREA_STACKED.
A data point series belonging to an area plot.
DataLabels object controlling data labels for this series.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
The CategoryPoints object providing access to individual data
points in this series.
Read-only. A sequence containing the float values for this series, in the order they appear on the chart.
BarSeries objects¶These properties are available on a series belonging to a bar-type plot. Note that column charts are also bar-type charts.
A data point series belonging to a bar plot.
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”.
DataLabels object controlling data labels for this series.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
The CategoryPoints object providing access to individual data
points in this series.
Read-only. A sequence containing the float values for this series, in the order they appear on the chart.
BubbleSeries objects¶These properties are available on series belonging to a bubble chart.
A data point series belonging to a bubble plot.
The BubblePoints object providing access to individual data point
objects used to discover and adjust the formatting and data labels of
a data point.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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).
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.
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.
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.
A data point series belonging to a line plot.
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.
DataLabels object controlling data labels for this series.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
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.
The CategoryPoints object providing access to individual data
points in this series.
Read-only. A sequence containing the float values for this series, in the order they appear on the chart.
Marker objects¶A marker is the small shape (e.g. diamond or circle) that “marks” each individual data point connected by a series line in a line-type plot.
Represents a data point marker, such as a diamond or circle, on a line-type chart.
The ChartFormat instance for this marker, providing access to shape
properties such as fill and line.
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.
The lxml element proxied by this object.
A member of the XL_MARKER_STYLE 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.
PieSeries objects¶These properties are available on a series belonging to a pie chart.
A data point series belonging to a pie plot.
DataLabels object controlling data labels for this series.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
The CategoryPoints object providing access to individual data
points in this series.
Read-only. A sequence containing the float values for this series, in the order they appear on the chart.
RadarSeries objects¶These properties are available on a series belonging to a radar chart.
A data point series belonging to a radar plot.
DataLabels object controlling data labels for this series.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
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.
The CategoryPoints object providing access to individual data
points in this series.
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.
A data point series belonging to an XY (scatter) plot.
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).
Read-only. A sequence containing the float values for this series, in the order they appear on the chart.
The ChartFormat instance for this series, providing access to shape
properties such as fill and line.
The zero-based integer index of this series as reported in its c:ser/c:idx element.
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.
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().
Sequence providing access to individual Point objects, each
representing the visual properties of a data point in the specified
category series.
Sequence providing access to the individual data points in
a BubbleSeries object.
Sequence providing access to the individual data points in an XySeries
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.
The ChartFormat object providing access to the shape formatting
properties of this data point, such as line and fill.