ExcelAlchemy 2.1.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

GitHub Repository · Full README · 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'),
    ]


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

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
• Architecture notes
• Locale policy
• Migration notes