Metadata-Version: 2.4
Name: fast-office
Version: 0.1.0
Summary: Schema-driven Office document generation
Project-URL: Homepage, https://github.com/meltus-bwire/fast-office
Project-URL: Repository, https://github.com/meltus-bwire/fast-office
Author-email: Meltus Bwire <meltusbwire10@gmail.com>
License: MIT
License-File: LICENCE
Keywords: documents,docx,office,openxml,pptx,reporting,xlsx
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: lxml>=6.1.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pydantic-settings>=2.14.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-pptx>=1.0.2
Description-Content-Type: text/markdown

# Fast Office

A schema-driven Python package for generating Microsoft Office documents programmatically.

`fast-office` provides a structured and strongly-typed API for creating:

* Microsoft Word documents (`.docx`)
* Microsoft PowerPoint presentations (`.pptx`)
* Microsoft Excel workbooks (`.xlsx`)

The package is designed for applications that need reliable document generation at scale, including:

* AI document generation systems
* Automated reporting pipelines
* SaaS reporting platforms
* Workflow automation systems
* Data export engines

`fast-office` abstracts document creation into clean Python specifications using typed models powered by Pydantic.

---

## Built on

`fast-office` leverages:

* `python-docx`
* `python-pptx`
* `openpyxl`
* `lxml`

---

# Installation

## Using pip

```bash
pip install fast-office
```

---

## Using uv

```bash
uv add fast-office
```

---

# Core Concepts

## Specifications

Each document type uses a specification model.

Examples:

* `DocxSpec`
* `PptxSpec`
* `WorkbookSpec`

These specs define:

* Content
* Layout
* Styling
* Metadata
* Formatting

The generator then convert the specification into an Office document.

---

# DOCX Example

## Create a Word Document

```python
from fast_office.documents.docx import DocxGenerator
from fast_office.types.docx import (
    DocxHeading,
    DocxParagraph,
    DocxSection,
    DocxSpec,
)

spec = DocxSpec(
    title="Quarterly Report",
    author="Finance Team",
    font_name="Calibri",
    font_size=11,
    sections=[
        DocxSection(
            elements=[
                DocxHeading(
                    text="Executive Summary",
                    level=1,
                ),
                DocxParagraph(
                    text="Revenue increased by 18% year-over-year."
                ),
            ]
        )
    ]
)

generator = DocxGenerator(spec)
path = generator.generate()

print(path)
```

---

## DOCX Features

### Paragraphs

Supports:

* Alignment
* Styling
* Custom fonts
* Colors
* Rich formatting

---

### Tables

Generate structured tables with:

* Headers
* Cell formatting
* Borders
* Alignment
* Width controls

---

### Images

Insert:

* Local images
* Positioned images
* Resized images

---

### Headers & Footers

Configure:

* Header text
* Footer text
* Dynamic page numbers

---

# PPTX Example

## Create a PowerPoint Presentation

```python
from fast_office.documents.pptx import PptxGenerator
from fast_office.types.pptx import (
    PptxSlide,
    PptxSpec,
)

spec = PptxSpec(
    title="Startup Pitch Deck",
    slides=[
        PptxSlide(
            title="Problem",
            body="SMEs struggle with financial visibility.",
            speaker_notes="Focus on market pain points."
        ),
        PptxSlide(
            title="Solution",
            bullet_points=[
                "Automated reporting",
                "AI financial insights",
                "Real-time dashboards",
            ]
        ),
    ]
)

generator = PptxGenerator(spec)
path = generator.generate()

print(path)
```

---

## PPTX Features

### Slide Layouts

Supports multiple slide layouts including:

* Title slides
* Title + content
* Blank slides
* Custom positioned layouts

---

### Speaker Notes

Attach notes for presenters directly to slides.

---

### Charts

Generate chart-based slides using structured chart data.

Supported chart types include:

* Bar charts
* Column charts
* Pie charts
* Line charts

---

### Custom Elements

Add positioned:

* Text blocks
* Shapes
* Images
* Charts

using coordinate-based placement.

---

# XLSX Example

## Create an Excel Workbook

```python
from fast_office.documents.workbook import WorkbookGenerator
from fast_office.types.workbook import (
    WorkbookSpec,
    WorksheetSpec,
)

spec = WorkbookSpec(
    sheets=[
        WorksheetSpec(
            title="Revenue",
            cells={
                "A1": "Month",
                "B1": "Revenue",
                "A2": "January",
                "B2": 120000,
                "A3": "February",
                "B3": 148000,
            }
        )
    ]
)

generator = WorkbookGenerator(spec)
path = generator.generate()

print(path)
```

---

# Advanced XLSX Features

## Conditional Formatting

Supports:

* Color scales
* Data bars
* Formula rules
* Threshold-based highlighting

---

## Data Validation

Add spreadsheet validation such as:

* Dropdown lists
* Numeric ranges
* Date restrictions
* Formula validations

---

## Charts

Generate embedded Excel charts from worksheet data.

---

## Worksheet Protection

Protect:

* Worksheets
* Cells
* Workbook structures

---

## Named Ranges

Create reusable named ranges for:

* Formulas
* Reporting
* Financial models

---

# AI & Automation Use Cases

`fast-office` is especially useful for AI-native systems.

## Example Use Cases

### Financial Report Generation

Generate:

* Investment memos
* Financial statements
* Business valuation models
* KPI dashboards

---

### Pitch Deck Automation

Automatically create:

* Startup decks
* Investor teasers
* Sales presentations
* Strategic reports

---

### AI Agents

Integrate into:

* LangGraph agents
* Workflow orchestration systems
* Multi-agent pipelines
* LLM document workflows

---

### Enterprise Reporting

Generate:

* Weekly reports
* Board reports
* Operational summaries
* Compliance documents

---

# Architecture Overview

```text
User Input
     ↓
Pydantic Specifications
     ↓
Document Generators
     ↓
Underlying Office Engines
     ↓
Generated Office Files
```

---

# Design Philosophy

## 1. Declarative APIs

Documents should be described, not manually assembled.

---

## 2. Strong Validation

Invalid document structures should fail early.

---

## 3. Extensibility

The architecture supports future additions such as:

* PDF generation
* HTML export
* Template engines
* Theme systems
* Dynamic layouts

---

## 4. AI Compatibility

The specification-based design makes the package ideal for:

* Structured outputs
* Tool calling
* LLM pipelines
* Agentic workflows

---

# Supported Python Versions

* Python 3.12+

---

# Dependencies

Core dependencies include:

* `python-docx`
* `python-pptx`
* `openpyxl`
* `pydantic`
* `lxml`

---

# Roadmap

Potential future features:

* Template rendering engine
* HTML → DOCX conversion
* PDF export
* Markdown support
* Theme packs
* Dynamic table generation
* Advanced charting
* OpenXML-level editing
* Streaming document generation
* Cloud storage integrations

---

# Contributing

Contributions are welcome.

Areas that can benefit from contribution include:

* Additional document components
* New chart types
* Template systems
* Performance optimizations
* Improved typing
* Documentation
* Testing coverage

---

# Example Applications

## Automated Financial Reports

```python
report = build_financial_report(data)
path = report.generate()
```

---

## AI Generated Pitch Decks

```python
deck = build_pitch_deck(startup_data)
path = deck.generate()
```

---

## Spreadsheet Exports

```python
workbook = build_workbook(dataset)
path = workbook.generate()
```

---

# License

MIT License

---

# Summary

`fast-office` provides a structured, and extensible way to generate Office documents programmatically.

It abstracts away low-level Office APIs while maintaining flexibility, strong typing, and compatibility with automation systems.

Whether you are building:

* AI agents
* Reporting systems
* SaaS products
* Financial tooling
* Enterprise automation

`fast-office` offers a clean foundation for scalable document generation.
