SpreadsheetDL

The Universal Spreadsheet Definition Language

Define spreadsheets declaratively in Python or YAML, export to ODS/XLSX/PDF. Built for AI integration with native MCP server. 11 domain plugins with 317+ specialized formulas.

---

Overview

SpreadsheetDL is a declarative spreadsheet definition language that lets you define structure, formulas, and styling once—then export to any format.

Key Features:

• 🤖 MCP-Native - Built-in Model Context Protocol server for AI assistants
• 📝 Declarative API - Define what you want, not how to build it (10 lines vs 100)
• 🌍 Multi-Format - Single definition → ODS, XLSX, PDF
• 🔧 Domain Plugins - 11 specialized domains (physics, engineering, finance, data science, etc.)
• ⚡ Type-Safe Formulas - FormulaBuilder with circular reference detection
• 🎨 Theme System - Professional styling without cell-by-cell code
• 🔒 Security Hardening - XXE protection, ZIP bomb detection, path traversal prevention

vs openpyxl/xlsxwriter:

• MCP-native (AI integration from day one)
• Declarative (not imperative cell-by-cell)
• Multi-format (not Excel-only)
• Domain-aware (317+ specialized formulas)

---

Quick Start

Installation

PyPI Package (Ready - Publishing in Progress):

Package is built and ready for publication. Once credentials are configured, install with:

uv pip install spreadsheet-dl                    # Basic installation
uv pip install spreadsheet-dl[security]          # With security enhancements (recommended)
uv pip install spreadsheet-dl[all]               # All features and domains

Install from Source (Current):

git clone https://github.com/lair-click-bats/spreadsheet-dl.git
cd spreadsheet-dl
uv sync

See Installation Guide for detailed options.

Quick Example

from spreadsheet_dl import create_spreadsheet, formula

# Define spreadsheet declaratively
builder = create_spreadsheet(theme="corporate")
builder.sheet("Q1 Budget") \
    .column("Category", width="5cm") \
    .column("Amount", width="4cm", type="currency") \
    .column("% of Total", width="4cm", type="percent") \
    .header_row() \
    .row().cell("Rent").cell(1500).cell(formula=formula().divide("B2", "B5")) \
    .row().cell("Utilities").cell(300).cell(formula=formula().divide("B3", "B5")) \
    .row().cell("Total").cell(formula=formula().sum("B2:B3"))

# Export to any format
builder.save("budget.ods")        # Native ODS
builder.export("budget.xlsx")     # Excel
builder.export("budget.pdf")      # PDF

Result: Professional spreadsheet with formulas, styling, and formatting—in 10 lines instead of 100.

Next Steps

For Users:

• 📖 Getting Started Guide - Your first spreadsheet in 5 minutes
• 🎓 Tutorials - Step-by-step learning path
• 📚 User Guide - Complete documentation
• 🔧 CLI Reference - Command-line usage

For Developers:

• 🧪 Test Suite Guide - Running and writing tests with markers
• 🤝 Contributing Guide - Development setup and workflow

---

Why SpreadsheetDL?

Declarative Paradigm

SpreadsheetDL brings declarative design to spreadsheets—the same paradigm shift that transformed other domains:

Domain	Imperative	Declarative
Data	Cursors, loops	SQL
Infrastructure	Manual provisioning	Terraform
UI	DOM manipulation	React
Spreadsheets	openpyxl	SpreadsheetDL

Code Comparison:

# openpyxl (imperative - 15+ lines)
ws['A1'] = 'Category'
ws['A1'].font = Font(bold=True, size=14, color='FFFFFF')
ws['A1'].fill = PatternFill(start_color='366092', fill_type='solid')
ws['A1'].alignment = Alignment(horizontal='center')
ws.column_dimensions['A'].width = 20
# ... repeat for every cell ...

# SpreadsheetDL (declarative - 3 lines)
builder.sheet("Budget") \
    .column("Category", width="5cm") \
    .header_row()  # Theme handles all styling

MCP-Native Integration

The only spreadsheet library with native Model Context Protocol support:

You: "Create a Q1 budget spreadsheet with corporate theme"
Claude (via MCP): *generates professional ODS with formulas and formatting*

You: "Add a chart showing spending by category"
Claude (via MCP): *adds chart with proper data references*

Built for AI integration from day one—not retrofitted.

Format Freedom

One definition, any output:

• ODS - Native format, open standard (LibreOffice, Collabora)
• XLSX - Microsoft Excel compatibility
• PDF - Distribution and reporting

Never be locked into a proprietary format.

Domain Expertise

11 specialized domains with 317+ formulas: Physics, Data Science, Engineering (electrical, mechanical, civil), Chemistry, Biology, Manufacturing, Finance, Education.

Domain expertise you don't have to recreate for every project. See Domain Plugins Documentation.

---

Documentation

User Guides

• Getting Started - Installation and first spreadsheet
• User Guide - Complete feature documentation
• CLI Reference - Command-line interface
• Best Practices - Tips and patterns

Tutorials

Learn step-by-step:

1. Create Your First Spreadsheet
2. Working with Data
3. Domain Plugins
4. Generate Reports
5. MCP Integration
6. Custom Themes

Technical Documentation

• Architecture - System design and structure
• API Reference - Complete Python API documentation
• MCP Integration - Model Context Protocol setup
• Domain Plugins - Specialized domain APIs
• Error Codes - Error handling reference

Examples

Working code in examples/:

• Basic API usage, data import, report generation
• Chart creation, theming, domain-specific examples
• MCP integration from Python

---

Built-in Themes

Theme	Description	Style
default	Clean professional	Blue headers, green/red status
corporate	Business-focused	Navy blue, brown accents
minimal	Distraction-free	Gray headers, subtle borders
dark	Dark mode	Dark backgrounds, light text
high_contrast	Accessibility	Bold colors, large fonts

Create custom themes with YAML. See Theme Creation Guide.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for development setup, coding standards, testing requirements, and commit message format.

For consistent messaging and terminology, see BRANDING.md.

Optional: This repo includes Claude Code configuration for AI-assisted development.

---

Security

SpreadsheetDL v0.1.0 includes comprehensive security hardening. See SECURITY.md for complete documentation.

Recommended installation (once published to PyPI):

uv pip install spreadsheet-dl[security]  # Includes defusedxml + cryptography

Current (from source):

uv sync  # Already includes security dependencies

---

License

MIT License - See LICENSE file.

---

Changelog

See CHANGELOG.md for detailed version history.

Recent releases:

• v0.1.0 (2026-01-06) - Initial public beta: Feature-complete, seeking community feedback

---

Links

• Documentation: docs/
• GitHub: github.com/lair-click-bats/spreadsheet-dl
• Issues: github.com/lair-click-bats/spreadsheet-dl/issues
• PyPI: pypi.org/project/spreadsheet-dl