Metadata-Version: 2.4
Name: ExcelAlchemy
Version: 2.4.0
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`

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](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Integration Roadmap](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-roadmap.md) · [Platform Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md) · [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md) · [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.md) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md) · [API Response Cookbook](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.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',
            example_value='alice@company.com',
        ),
    ]


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:

```text
template -> preflight -> import -> remediation -> delivery
```

Minimal example:

```python
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](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
- [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
- [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.md)
- [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md)
- [API Response Cookbook](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.md)

## Example Outputs

These fixed outputs are generated from the repository examples by
[`scripts/generate_example_output_assets.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/scripts/generate_example_output_assets.py).

Import workflow:

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

Export workflow:

```text
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](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/employee-import-workflow.txt)
- [create-or-update-import.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/create-or-update-import.txt)
- [export-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/export-workflow.txt)
- [date-and-range-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/date-and-range-fields.txt)
- [selection-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
- [fastapi-reference.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.txt)

For a single GitHub page that combines screenshots, representative workflows,
and captured outputs, see the
[Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md).

If you want a copyable FastAPI-oriented reference layout rather than a single
example script, see the
[FastAPI reference project](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md).

## 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](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md)
- [Platform architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
- [Runtime model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
- [Integration blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.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)

