ExcelAlchemy 2.2.5

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.2.5, which continues the 2.x line with richer import-failure feedback, clearer documentation entry points, stronger examples, and stronger smoke coverage.

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


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

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

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

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