release: v2.3

Author: ruicore

CHANGELOG.md

@@ -4,6 +4,64 @@ All notable changes to this project will be documented in this file.
 
 The format is inspired by Keep a Changelog and versioned according to PEP 440.
 
+## [2.3.0] - 2026-04-23
+
+This release continues the stable 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
+compact remediation-oriented payloads after failures.
+
+### Added
+
+- Added additive template UX metadata support through `hint=` and
+  `example_value=` so generated header comments can provide clearer workbook
+  input guidance
+- Added `ExcelAlchemy.preflight_import(...)` for lightweight structural import
+  validation before full import execution
+- Added `ImportPreflightResult` and `ImportPreflightStatus` as stable public
+  preflight result types
+- Added additive `on_event=` support on `ExcelAlchemy.import_data(...)` for
+  synchronous import lifecycle callbacks
+- Added `build_frontend_remediation_payload(...)` for compact retry-oriented
+  remediation payloads alongside the existing import result surfaces
+- Added a dedicated `WorksheetNotFoundError` exception so sheet-missing
+  preflight classification does not rely on backend-specific message parsing
+
+### Changed
+
+- Extended the import workflow so applications can combine template guidance,
+  preflight validation, lifecycle event observation, and remediation payloads
+  without replacing the existing full import API
+- Kept `ExcelAlchemy.import_data(...)` as the full validation and execution
+  path while clarifying that `preflight_import(...)` is structural only
+- Updated storage-backed workbook reading so preflight maps only explicit
+  worksheet-missing failures to `SHEET_MISSING` and re-raises unrelated
+  storage/runtime failures
+- Refined template comment rendering for single-staff guidance formatting
+- Expanded contract coverage for:
+  - preflight header validation
+  - missing and extra field handling
+  - row-count estimation
+  - import lifecycle event payloads
+  - remediation payload behavior
+
+### Documentation
+
+- Updated `README.md`, `README-pypi.md`, and onboarding docs to describe the
+  additive template guidance metadata
+- Updated `docs/getting-started.md` with practical preflight usage guidance and
+  a `preflight -> import` workflow example
+- Updated `docs/public-api.md` and `docs/result-objects.md` to document
+  `preflight_import(...)`, `ImportPreflightResult`, lifecycle callbacks, and
+  remediation payload helpers
+- Updated `docs/architecture.md`, `docs/domain-model.md`, examples, and
+  reference-app guidance to reflect the broader import workflow story
+- Added design plans under `plans/` for:
+  - template UX metadata v1
+  - job-friendly import lifecycle events v1
+  - import preflight v1
+  - front-end remediation payload v1
+
 ## [2.2.8] - 2026-04-05
 
 This release continues the stable 2.x line with a clearer integration reading

README-pypi.md

@@ -10,7 +10,10 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-The current stable release is `2.2.8`, which continues the 2.x line with a clearer integration roadmap, stronger import-failure payload smoke verification, and more direct install-time validation of the FastAPI reference app.
+The current stable release is `2.3.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.
 
 [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) · [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)
 

README.md

@@ -20,12 +20,20 @@ This repository is also a design artifact.
 It documents a series of deliberate engineering choices: `src/` layout, Pydantic v2 migration, pandas removal,
 pluggable storage, `uv`-based workflows, and locale-aware workbook output.
 
-The current stable release is `2.2.8`, which continues the ExcelAlchemy 2.x line with a clearer integration roadmap, stronger import-failure payload smoke verification, and more direct install-time validation of the FastAPI reference app.
+The current stable release is `2.3.0`, which continues the ExcelAlchemy 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 a Glance
 
 - Build Excel templates directly from typed Pydantic schemas
+- Guide users with workbook-facing input hints and examples
+- Run lightweight structural preflight checks before full import
 - Validate uploaded workbooks and write failures back to rows and cells
+- Observe import lifecycle progress through additive callbacks
+- Build remediation-oriented payloads for retry workflows
 - Keep storage pluggable through `ExcelStorage`
 - Render workbook-facing text in `zh-CN` or `en`
 - Stay lightweight at runtime with `openpyxl` instead of pandas
@@ -91,6 +99,89 @@ and a concrete example value.
 For browser downloads, prefer `template.as_bytes()` with a `Blob`, or return the bytes from your backend with
 `Content-Disposition: attachment`. A top-level navigation to a long `data:` URL is less reliable in modern browsers.
 
+## Import Workflow
+
+ExcelAlchemy is designed to work as a product-ready import layer rather than
+only a row-validation helper.
+
+The practical workflow in the 2.x line is:
+
+- generate a template with workbook-facing guidance
+- run `preflight_import(...)` as a lightweight structural gate
+- run `import_data(..., on_event=...)` for full validation and execution
+- build remediation-oriented payloads if the import fails
+
+Use `preflight_import(...)` when you want a fast answer to:
+
+- does the configured sheet exist
+- do the workbook headers match the schema
+- is the workbook structurally importable
+
+Use `import_data(...)` when you want the full workflow:
+
+- row validation
+- create / update callback execution
+- result workbook rendering
+- structured row and cell failure output
+
+Short example:
+
+```python
+from pydantic import BaseModel
+
+from excelalchemy import ExcelAlchemy, Email, FieldMeta, ImporterConfig, Number, String
+from excelalchemy.results import build_frontend_remediation_payload
+
+
+class EmployeeImporter(BaseModel):
+    full_name: String = FieldMeta(label='Full name', order=1, hint='Use the legal name')
+    age: Number = FieldMeta(label='Age', order=2)
+    work_email: Email = FieldMeta(label='Work email', order=3, example_value='alice@company.com')
+
+
+async def create_employee(row: dict[str, object], context: dict[str, object] | None) -> dict[str, object]:
+    return row
+
+
+alchemy = ExcelAlchemy(
+    ImporterConfig.for_create(
+        EmployeeImporter,
+        creator=create_employee,
+        storage=storage,
+        locale='en',
+    )
+)
+
+template = alchemy.download_template_artifact(filename='employee-template.xlsx')
+
+preflight = alchemy.preflight_import('employees.xlsx')
+if not preflight.is_valid:
+    response = {'preflight': preflight.to_api_payload()}
+else:
+    events: list[dict[str, object]] = []
+    result = await alchemy.import_data(
+        'employees.xlsx',
+        'employees-result.xlsx',
+        on_event=events.append,
+    )
+
+    response = {
+        'result': result.to_api_payload(),
+        'events': events,
+        'remediation': build_frontend_remediation_payload(
+            result=result,
+            cell_error_map=alchemy.cell_error_map,
+            row_error_map=alchemy.row_error_map,
+        ),
+    }
+```
+
+This keeps one clear separation:
+
+- template and preflight help before execution
+- import handles real validation and persistence
+- remediation helps API and frontend retry flows after failure
+
 ## When To Use / When Not To Use / Limitations & Gotchas
 
 ### When To Use
@@ -271,6 +362,7 @@ Import workflow output:
 
 ```text
 Employee import workflow completed
+Preflight: VALID
 Result: SUCCESS
 Success rows: 1
 Failed rows: 0

docs/examples-showcase.md

@@ -30,6 +30,7 @@ see
 Best entry point if you want to understand the core story:
 
 - generate a workbook template
+- run a lightweight structural preflight
 - accept a filled workbook
 - validate the upload
 - create domain rows
@@ -43,6 +44,7 @@ Fixed output:
 
 ```text
 Employee import workflow completed
+Preflight: VALID
 Result: SUCCESS
 Success rows: 1
 Failed rows: 0

docs/integration-roadmap.md

@@ -40,12 +40,14 @@ Recommended order:
 
 Focus on these objects:
 
+- `ImportPreflightResult`
 - `ImportResult`
 - `CellErrorMap`
 - `RowIssueMap`
 
 Use these payload helpers directly in your API layer:
 
+- `ExcelAlchemy.preflight_import(...)` when the endpoint wants a lightweight structural gate before the real import
 - `ImportResult.to_api_payload()`
 - `CellErrorMap.to_api_payload()`
 - `RowIssueMap.to_api_payload()`

examples/README.md

@@ -36,7 +36,7 @@ Use them to understand how the library is intended to be used from application c
   - Type: demo of the recommended declaration style.
 
 - `examples/employee_import_workflow.py`
-  - Demonstrates the basic import flow from template generation through import result handling.
+  - Demonstrates the basic import flow from template generation through preflight, lifecycle-event observation, and import result handling.
   - Type: runnable workflow demo.
 
 - `examples/create_or_update_import.py`

examples/employee_import_workflow.py

@@ -13,6 +13,7 @@
     ExcelStorage,
     FieldMeta,
     ImporterConfig,
+    ImportPreflightResult,
     ImportResult,
     Number,
     String,
@@ -82,7 +83,13 @@ async def create_employee(row: dict[str, object], context: dict[str, object] | N
     return row
 
 
-async def run_workflow() -> tuple[ImportResult, InMemoryImportStorage, dict[str, object], list[dict[str, object]]]:
+async def run_workflow() -> tuple[
+    ImportPreflightResult,
+    ImportResult,
+    InMemoryImportStorage,
+    dict[str, object],
+    list[dict[str, object]],
+]:
     storage = InMemoryImportStorage()
     context: dict[str, object] = {
         'created_rows': [],
@@ -106,6 +113,8 @@ async def run_workflow() -> tuple[ImportResult, InMemoryImportStorage, dict[str,
 
     template = alchemy.download_template_artifact(filename='employee-template.xlsx')
     _build_import_fixture(storage, template.as_bytes())
+    preflight = alchemy.preflight_import('employee-import.xlsx')
+    assert preflight.is_valid
 
     def handle_import_event(event: dict[str, object]) -> None:
         events.append(event)
@@ -131,17 +140,18 @@ def handle_import_event(event: dict[str, object]) -> None:
         'employee-import-result.xlsx',
         on_event=handle_import_event,
     )
-    return result, storage, context, events
+    return preflight, result, storage, context, events
 
 
 def main() -> None:
-    result, storage, context, events = asyncio.run(run_workflow())
+    preflight, result, storage, context, events = asyncio.run(run_workflow())
     created_rows = context['created_rows']
     job_progress = context['job_progress']
     assert isinstance(created_rows, list)
     assert isinstance(job_progress, dict)
 
     print('Employee import workflow completed')
+    print(f'Preflight: {preflight.status}')
     print(f'Result: {result.result}')
     print(f'Success rows: {result.success_count}')
     print(f'Failed rows: {result.fail_count}')

files/example-outputs/employee-import-workflow.txt

@@ -1,7 +1,10 @@
 Employee import workflow completed
+Preflight: VALID
 Result: SUCCESS
 Success rows: 1
 Failed rows: 0
 Result workbook URL: None
 Created rows: 1
 Uploaded artifacts: []
+Observed events: ['started', 'header_validated', 'row_processed', 'completed']
+Job progress: {'status': 'completed', 'processed_rows': 1, 'total_rows': 1, 'result': 'SUCCESS', 'result_workbook_url': None}

src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.8'
+__version__ = '2.3.0'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (