Aspose.Cells FOSS
Python
Sparkline

Sparkline — Aspose.Cells FOSS for Python API Reference

Sparklines are miniature charts embedded in individual cells, introduced in Excel 2010. aspose-cells-foss manages sparklines through SparklineGroup and SparklineGroupCollection (ws.sparkline_groups). Each group holds one or more Sparkline objects sharing the same type and color settings.

Package: aspose.cells_foss

from aspose.cells_foss import SparklineType, SparklineEmptyCells, Sparkline, SparklineGroup

SparklineType

SparklineType is an IntEnum identifying the visual form of a sparkline group.

MemberValueDescription
LINE0Line sparkline — renders data as a connected line.
COLUMN1Column sparkline — renders data as vertical bars.
WIN_LOSS2Win/loss sparkline — each value is shown as a positive or negative block.

SparklineEmptyCells

SparklineEmptyCells is an IntEnum controlling how empty cells are handled within a sparkline.

MemberValueDescription
ZERO0Treats empty cells as zero.
GAP1Leaves a gap where cells are empty (line is broken).
CONNECTED2Connects adjacent non-empty values, skipping the gap.

Sparkline

A Sparkline binds a single data range to a single cell location.

Constructor 

Sparkline(data_range: str, cell_reference: str)
ParameterTypeDescription
data_rangestrA1-style range containing the sparkline source data (e.g., "Sheet1!B2:G2").
cell_referencestrA1-style cell address where the sparkline is displayed (e.g., "H2").

Properties

PropertyTypeDescription
data_rangestrSource data range.
cell_referencestrDisplay cell address.

SparklineGroup

A SparklineGroup defines the shared visual settings (type, colors, empty-cell handling) for a set of sparklines. SparklineGroup objects are not constructed directly — use ws.sparkline_groups.add(...) or ws.sparkline_groups.add_group(...).

Properties

PropertyTypeDescription
typeSparklineTypeSparkline form: LINE, COLUMN, or WIN_LOSS.
display_empty_cells_asSparklineEmptyCellsHow to handle empty cells in the data range.
color_seriesstrColor for the main sparkline line/bars, as RRGGBB hex.
color_negativestrColor for negative-value bars (WIN_LOSS and COLUMN), as RRGGBB hex.
color_axisstrColor of the zero-axis line, as RRGGBB hex.
color_markersstrColor of data-point markers on line sparklines, as RRGGBB hex.
color_firststrHighlight color for the first data point, as RRGGBB hex.
color_laststrHighlight color for the last data point, as RRGGBB hex.
color_highstrHighlight color for the highest data point, as RRGGBB hex.
color_lowstrHighlight color for the lowest data point, as RRGGBB hex.
sparklineslist[Sparkline]Read-only list of individual sparklines in this group.
countintNumber of sparklines in this group (read-only).

Methods

add_sparkline 

group.add_sparkline(data_range: str, cell_reference: str) -> Sparkline

Adds an individual sparkline to this group and returns the new Sparkline object.

SparklineGroupCollection

SparklineGroupCollection is accessed as ws.sparkline_groups. It contains all sparkline groups on a worksheet.

Methods

add 

ws.sparkline_groups.add(
    sparkline_type=SparklineType.LINE,
    data_range=None,
    is_vertical=False,
    location_range=None
) -> SparklineGroup

Creates a new group and optionally populates it with sparklines derived from data_range (rows or columns depending on is_vertical) placed into cells described by location_range. Returns the new SparklineGroup.

ParameterTypeDescription
sparkline_typeSparklineTypeVisual form of the sparklines.
data_rangestr | NoneSource data range for bulk creation.
is_verticalboolWhen True, each column in data_range feeds one sparkline; when False, each row does.
location_rangestr | NoneSingle-row or single-column range of cells where sparklines are placed.

add_group 

ws.sparkline_groups.add_group(sparkline_type=SparklineType.LINE) -> SparklineGroup

Creates an empty group of the given type. Sparklines must be added individually with group.add_sparkline(...).

Properties and Iteration

MemberDescription
countNumber of sparkline groups on this worksheet (read-only).
__len__()Returns count.
__iter__()Iterates over all SparklineGroup objects.
__getitem__(index)Returns the SparklineGroup at zero-based index.

Example

The following example writes monthly revenue data for three regions and adds a line sparkline for each row.

from aspose.cells_foss import Workbook, SparklineType, SparklineEmptyCells

wb = Workbook()
ws = wb.worksheets[0]
ws.name = "Trends"

# Write headers
months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
for col, m in enumerate(months):
    ws.cells[0][col + 1].put_value(m)

ws.cells["A1"].put_value("Region")
ws.cells["H1"].put_value("Trend")

# Write three rows of data
regions = [
    ("North", [12000, 14500, 13800, 16200, 15900, 17400]),
    ("South", [9800,  10200, 11500, 10900, 12300, 13100]),
    ("West",  [7500,   8100,  7900,  8800,  9200, 10500]),
]
for row_i, (name, values) in enumerate(regions, start=1):
    ws.cells[row_i][0].put_value(name)
    for col_i, v in enumerate(values):
        ws.cells[row_i][col_i + 1].put_value(v)

# Add a line sparkline group — one sparkline per data row
group = ws.sparkline_groups.add(
    sparkline_type=SparklineType.LINE,
    data_range="Trends!B2:G4",
    is_vertical=False,
    location_range="Trends!H2:H4",
)

# Customize colors
group.color_series = "4472C4"       # blue lines
group.color_high   = "70AD47"       # green for peak
group.color_low    = "FF0000"       # red for trough
group.display_empty_cells_as = SparklineEmptyCells.GAP

wb.save("sparklines.xlsx")

See Also