Aspose.Cells FOSS for Python

Package Information


PyPI package	`aspose-cells-foss`
Python import	`from aspose.cells_foss import ...`
Version	26.3.1
License	MIT
Python requirement	>= 3.7
Dependencies	`pycryptodome>=3.15.0`, `olefile>=0.46`

Modules

Module	Description
aspose.cells_foss	Core spreadsheet API: workbooks, worksheets, cells, styles, charts, format handlers

Note: There is no aspose.pydrawing module in Aspose.Cells FOSS. Colors are expressed as 8-digit AARRGGBB hex strings (e.g., "FFFF0000" for opaque red).

aspose.cells_foss

Classes

Class	Page	Description
`Workbook`	workbook	Entry point for creating, loading, and saving spreadsheet files
`Worksheet`	worksheet	Represents a single sheet; provides access to cells, charts, and pictures
`Cells`	cells	Dictionary-like collection of `Cell` objects within a `Worksheet`
`Cell`	cell	Represents an individual cell; value, formula, and style
`Style`	style	Cell formatting: font, fill, borders, alignment, number format, protection
`Font`	style	Font properties: name, size, color, bold, italic, underline, strikethrough
`Fill`	style	Background fill: solid, gradient, or pattern
`NumberFormat`	style	Built-in number format lookup utilities
`SaveFormat`	workbook	Enumeration of supported output formats (XLSX, CSV, MARKDOWN, JSON)
`Chart`	chart	Represents a chart embedded in a worksheet
`ChartType`	chart	Enum: LINE, BAR, PIE, AREA, STOCK, and more
`NSeries`	chart	Data series collection on a chart
`ChartSeries`	chart	A single data series with values, categories, and error bars
`ChartAxis`	chart	Axis settings: scale, format, title
`ChartView3D`	chart	3D rotation and perspective settings
`ChartErrorBars`	chart	Error bar configuration for a series
`DataValidation`	data-validation	Single validation rule on a cell range
`DataValidationCollection`	data-validation	All validation rules for a worksheet
`DataValidationType`	data-validation	Enum: WHOLE_NUMBER, DECIMAL, LIST, DATE, TIME, TEXT_LENGTH, CUSTOM
`DataValidationOperator`	data-validation	Enum: BETWEEN, EQUAL, GREATER_THAN, etc.
`DataValidationAlertStyle`	data-validation	Enum: STOP, WARNING, INFORMATION
`CSVHandler`	csv-handler	Static methods for CSV export and CSV data handling
`CSVLoadOptions`	csv-handler	Options for loading CSV files
`CSVSaveOptions`	csv-handler	Options for saving CSV files
`MarkdownHandler`	markdown-handler	Static methods for Markdown export
`MarkdownSaveOptions`	markdown-handler	Options for Markdown export
`JsonHandler`	json-handler	Static methods for JSON export
`JsonSaveOptions`	json-handler	Options for JSON export
`Shape`	shape	Drawing shape with fill, line, text, and font formatting
`ShapeCollection`	shape	All shapes in a worksheet (`ws.shapes`)
`MsoDrawingType`	shape	Enum: RECTANGLE, OVAL, TEXT_BOX, ARROW, etc.
`Table`	table	Excel table (structured reference) in a worksheet
`TableCollection`	table	All tables in a worksheet (`ws.tables`)
`TableColumn`	table	Column definition within a Table
`TableStyleInfo`	table	Visual style settings for a Table
`SparklineGroup`	sparkline	Group of sparkline charts sharing a visual style
`SparklineGroupCollection`	sparkline	All sparkline groups (`ws.sparkline_groups`)
`Sparkline`	sparkline	A single sparkline cell linked to a data range
`SparklineType`	sparkline	Enum: LINE, COLUMN, WIN_LOSS
`HorizontalPageBreakCollection`	page-break	Manual horizontal page breaks (`ws.horizontal_page_breaks`)
`VerticalPageBreakCollection`	page-break	Manual vertical page breaks (`ws.vertical_page_breaks`)
`AgileEncryptionParameters`	encryption	AES-256/SHA-512 encryption parameters (recommended)
`StandardEncryptionParameters`	encryption	Legacy AES-128/SHA-1 encryption parameters
`CipherAlgorithm`	encryption	Enum: AES_128, AES_192, AES_256
`HashAlgorithm`	encryption	Enum: SHA1, SHA256, SHA384, SHA512

Workbook

Constructors

Signature	Description
`Workbook()`	Create a new empty workbook (XLSX format)
`Workbook(file_path: str)`	Load a workbook from a file path
`Workbook(file_path: str, password: str)`	Load a password-protected workbook

Key Properties

Property	Type	Description
`worksheets`	list	Access worksheets by index: `workbook.worksheets[0]`

Key Methods

Method	Return	Description
`save(file_path)`	None	Save to file; format inferred from extension
`save(file_path, save_format)`	None	Save with explicit SaveFormat
`save_as_csv(file_path, options=None)`	None	Save as CSV
`save_as_markdown(file_path, options=None)`	None	Save as Markdown tables
`save_as_json(file_path, options=None)`	None	Save as JSON
`load_csv(file_path, options=None)`	None	Populate the workbook from a CSV file
`add_worksheet(name=None)`	Worksheet	Add a new worksheet
`get_worksheet(index_or_name)`	Worksheet	Get worksheet by index or name
`remove_worksheet(index_or_name)`	None	Remove a worksheet
`copy_worksheet(index_or_name_or_ws)`	Worksheet	Copy an existing worksheet
`protect(password=None, lock_structure=True)`	None	Password-protect the workbook
`unprotect(password=None)`	None	Remove workbook protection
`is_protected()`	bool	Check if the workbook is protected

Worksheet

Key Properties

Property	Type	Description
`name`	str	Worksheet tab name
`cells`	Cells	All cells in this worksheet
`charts`	ChartCollection	All charts in this worksheet

Cells

Cells supports dictionary-style access by cell address string.

Access Patterns

# Read a cell value
value = ws.cells["A1"].value

# Set a cell value directly
ws.cells["A1"].value = "Hello"

# Assign a Cell object
from aspose.cells_foss import Cell
ws.cells["A1"] = Cell(42)
ws.cells["A2"] = Cell(3.14)
ws.cells["A3"] = Cell("Hello World")
ws.cells["A4"] = Cell(None, "=SUM(A1:A3)")   # formula cell

Cell

Constructor

Signature	Description
`Cell(value=None)`	Create a cell with a value (int, float, str, or None)
`Cell(value, formula)`	Create a formula cell (value is typically None)

Key Properties

Property	Type	Description
`value`	Any	Cell value (str, int, float, or None)
`formula`	str	Formula string (e.g., `"=SUM(A1:A5)"`)
`style`	Style	Cell style (font, fill)

Style

Property	Type	Description
`font`	Font	Font settings for this style
`fill`	Fill	Background fill settings

Font

Colors are expressed as 8-digit AARRGGBB hex strings without a # prefix. Examples: "FFFF0000" = opaque red, "FF0000FF" = opaque blue, "FF000000" = black.

Property	Type	Default	Description
`name`	str	Calibri	Font family name
`size`	float	11	Font size in points
`color`	str	FF000000	8-digit AARRGGBB hex color string
`bold`	bool	False	Bold text
`italic`	bool	False	Italic text
`underline`	bool	False	Underlined text
`strikethrough`	bool	False	Strikethrough text

Constructor

Font(name="Calibri", size=11, color="FF000000",
     bold=False, italic=False, underline=False, strikethrough=False)

Fill

Method	Description
`set_solid_fill(color)`	Solid background; `color` is an 8-digit AARRGGBB hex string
`set_pattern_fill(pattern_type, fg_color, bg_color)`	Patterned fill
`set_no_fill()`	Remove background fill

MarkdownHandler

Method	Return	Description
`MarkdownHandler.save_markdown_to_string(workbook)`	str	Export workbook to a Markdown string in memory

MarkdownSaveOptions

Property	Type	Default	Description
`default_alignment`	str	left	Column alignment: left, right, or center
`include_worksheet_name`	bool	True	Whether to include the sheet name as a heading
`header_level`	int	2	Markdown heading level (1-6)
`worksheet_index`	int	0	Sheet index to export; -1 exports all sheets

ChartCollection

Charts are added using dedicated per-type methods. Row and column indices are zero-based.

Method	Return	Description
`add_bar(top_row, left_col, bottom_row, right_col)`	Chart	Add a column (vertical bar) chart
`add_line(top_row, left_col, bottom_row, right_col)`	Chart	Add a line chart
`add_pie(top_row, left_col, bottom_row, right_col)`	Chart	Add a pie chart

Chart

Property	Type	Description
`title`	str	Chart title as a plain string (not `.title.text`)
`category_data`	str	Cell range for x-axis category labels
`n_series`	NSeries	Data series collection
`show_legend`	bool	Whether to display the legend
`legend_position`	str	Legend position: right, bottom, left, or top

NSeries

Method	Description
`add(data_range, category_data=None, name=None)`	Add a named data series

SaveFormat Enumeration

Constant	Output Format
`SaveFormat.XLSX`	Excel XML format (default)
`SaveFormat.CSV`	Comma-separated values
`SaveFormat.TSV`	Read-only constant. `workbook.save()` does not support TSV — raises `ValueError` at runtime.
`SaveFormat.MARKDOWN`	Markdown tables
`SaveFormat.JSON`	JSON-structured data

Note: SaveFormat.PDF, SaveFormat.HTML, SaveFormat.PNG, SaveFormat.TIFF, SaveFormat.DOCX, and SaveFormat.PPTX are not available in Aspose.Cells FOSS. These formats require the commercial aspose-cells-python package.

Code Examples

Create, style, and save a workbook

from aspose.cells_foss import Workbook, Cell

wb = Workbook()
ws = wb.worksheets[0]

ws.cells["A1"].value = "Revenue Report"
ws.cells["A2"].value = 125000

ws.cells["A1"].style.font.bold = True
ws.cells["A1"].style.font.size = 14
ws.cells["A1"].style.font.color = "FF1E64C8"   # Blue (AARRGGBB, no #)

wb.save("report.xlsx")

Export to Markdown in memory

from aspose.cells_foss import Workbook, Cell, MarkdownHandler

wb = Workbook()
ws = wb.worksheets[0]
ws.cells["A1"].value = "Name"
ws.cells["B1"].value = "Score"
ws.cells["A2"].value = "Alice"
ws.cells["B2"].value = 95

md = MarkdownHandler.save_markdown_to_string(wb)
print(md)

Build a line chart

from aspose.cells_foss import Workbook, Cell

wb = Workbook()
ws = wb.worksheets[0]

for i, (m, v) in enumerate([("Jan", 50), ("Feb", 80), ("Mar", 120)], start=2):
    ws.cells[f"A{i}"].value = m
    ws.cells[f"B{i}"].value = v

chart = ws.charts.add_line(5, 0, 18, 7)
chart.title = "Monthly Trend"
chart.category_data = "A2:A4"
chart.n_series.add("B2:B4", category_data="A2:A4", name="Sales")

wb.save("trend.xlsx")

Related Resources

Developer Guide: Tutorials for all core features
Getting Started / Installation: pip install and setup
Knowledge Base: Task-oriented how-to guides
Product Overview: Features and capabilities summary
GitHub Repository
Blog: Introducing Aspose.Cells FOSS: Library overview and quick start