ExcelAlchemy 2.4.0

Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.

ExcelAlchemy

Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.

ExcelAlchemy turns Pydantic models into typed workbook contracts:

• generate Excel templates from code
• validate uploaded workbooks
• map failures back to rows and cells
• render workbook-facing output in zh-CN or en
• keep storage pluggable through ExcelStorage

The current stable release is 2.4.0, which continues the 2.x line with a more complete import workflow: clearer template guidance before upload, lightweight structural preflight before execution, synchronous lifecycle visibility during import, and remediation-oriented payloads after failures.

At the top level, that import workflow is:

• template authoring
• preflight gate
• import runtime
• result intelligence
• artifact and delivery

GitHub Repository · Full README · Getting Started · Integration Roadmap · Platform Architecture · Runtime Model · Integration Blueprints · Result Objects · API Response Cookbook · Examples Showcase · Architecture · Migration Notes

Screenshots

Template

Import Result

Install

pip install ExcelAlchemy

Optional Minio support:

pip install "ExcelAlchemy[minio]"

Minimal Example

from pydantic import BaseModel

from excelalchemy import ExcelAlchemy, FieldMeta, ImporterConfig, Number, String


class Importer(BaseModel):
    age: Number = FieldMeta(label='Age', order=1)
    name: String = FieldMeta(label='Name', order=2)


alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
template = alchemy.download_template_artifact(filename='people-template.xlsx')

excel_bytes = template.as_bytes()

Modern Annotated Example

from typing import Annotated

from pydantic import BaseModel, Field

from excelalchemy import Email, ExcelAlchemy, ExcelMeta, ImporterConfig


class Importer(BaseModel):
    email: Annotated[
        Email,
        Field(min_length=10),
        ExcelMeta(
            label='Email',
            order=1,
            hint='Use your work email',
            example_value='[e-mail]',
        ),
    ]


alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
template = alchemy.download_template_artifact(filename='people-template.xlsx')

This template metadata is additive: it leaves the worksheet layout alone and improves the generated header comment with both guidance text and a concrete example value.

Import Workflow Overview

The shortest path through the import workflow is:

template -> preflight -> import -> remediation -> delivery

Minimal example:

from excelalchemy.results import build_frontend_remediation_payload


events: list[dict[str, object]] = []

preflight = alchemy.preflight_import('employees.xlsx')
if preflight.is_valid:
    result = await alchemy.import_data(
        'employees.xlsx',
        'employees-result.xlsx',
        on_event=events.append,
    )
    payload = build_frontend_remediation_payload(
        result=result,
        cell_error_map=alchemy.cell_error_map,
        row_error_map=alchemy.row_error_map,
    )

See also:

• Platform Architecture
• Runtime Model
• Integration Blueprints
• Result Objects
• API Response Cookbook

Example Outputs

These fixed outputs are generated from the repository examples by scripts/generate_example_output_assets.py.

Import workflow:

Employee import workflow completed
Result: SUCCESS
Success rows: 1
Failed rows: 0
Result workbook URL: None
Created rows: 1
Uploaded artifacts: []

Export workflow:

Export workflow completed
Artifact filename: employees-export.xlsx
Artifact bytes: 6893
Upload URL: memory://employees-export-upload.xlsx
Uploaded objects: ['employees-export-upload.xlsx']

Full captured outputs:

• employee-import-workflow.txt
• create-or-update-import.txt
• export-workflow.txt
• date-and-range-fields.txt
• selection-fields.txt
• fastapi-reference.txt

For a single GitHub page that combines screenshots, representative workflows, and captured outputs, see the Examples Showcase.

If you want a copyable FastAPI-oriented reference layout rather than a single example script, see the FastAPI reference project.

Error Feedback

ExcelAlchemy keeps workbook-facing validation feedback readable while also supporting API-friendly inspection in application code.

The stable 2.x result surface includes:

• alchemy.cell_error_map
• alchemy.row_error_map

These objects remain dict-like for compatibility, but also expose helpers such as:

• messages_at(...)
• messages_for_row(...)
• flatten()
• to_api_payload()

Common field types now also produce more business-oriented error wording, such as expected date formats, sample email/phone/URL formats, and clearer messages for configured selection fields.

Why ExcelAlchemy

• Pydantic v2-based schema extraction and validation
• locale-aware workbook comments and result workbooks
• pluggable storage instead of a hard-coded backend
• openpyxl-based runtime path without pandas
• contract tests, Ruff, and Pyright in the development workflow

Learn More

• Full project README
• Platform architecture
• Runtime model
• Integration blueprints
• Architecture notes
• Locale policy
• Migration notes