Metadata-Version: 2.4
Name: ExcelAlchemy
Version: 2.0.0.post1
Summary: Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.
Keywords: excel,openpyxl,pydantic,minio,schema
Author: Ray
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Requires-Dist: pydantic[email] >=2.12, <3
Requires-Dist: openpyxl >=3.1.5, <4
Requires-Dist: pendulum >=3.2.0, <4
Requires-Dist: minio >=7.2.20, <8 ; extra == "development"
Requires-Dist: pre-commit ; extra == "development"
Requires-Dist: pyright==1.1.408 ; extra == "development"
Requires-Dist: pytest ; extra == "development"
Requires-Dist: coverage ; extra == "development"
Requires-Dist: pytest-cov ; extra == "development"
Requires-Dist: ruff ; extra == "development"
Requires-Dist: minio >=7.2.20, <8 ; extra == "minio"
Project-URL: Documentation, https://github.com/RayCarterLab/ExcelAlchemy#readme
Project-URL: Home, https://github.com/RayCarterLab/ExcelAlchemy
Project-URL: Issues, https://github.com/RayCarterLab/ExcelAlchemy/issues
Project-URL: Repository, https://github.com/RayCarterLab/ExcelAlchemy
Provides-Extra: development
Provides-Extra: minio

# 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](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)

## Screenshots

### Template

![Excel template screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-template-en.png)

### Import Result

![Excel import result screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-import-result-en.png)

## Install

```bash
pip install ExcelAlchemy
```

Optional Minio support:

```bash
pip install "ExcelAlchemy[minio]"
```

## Minimal Example

```python
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

```python
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](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md)
- [Architecture notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md)
- [Locale policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md)
- [Migration notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)

