ExcelAlchemy 3.0.0

3.0.0 Release Notes and Checklist

This document records the final release positioning and verification checklist
for the stable 3.0.0 release.

Purpose

• publish the first stable ExcelAlchemy 3.0 package
• finalize the breaking 3.0 public API around typed Pydantic models and
  explicit ExcelColumn(...) workbook metadata
• confirm current docs, examples, and smoke assets describe 3.0 instead of the
  retired 2.x compatibility surface
• trigger the GitHub Release workflow that builds, verifies, and publishes the
  Python package to PyPI

Release Positioning

3.0.0 is a stable breaking release:

• Python type annotations define the data shape
• Pydantic Field(...) stays responsible for Pydantic validation
• ExcelColumn(...) carries workbook-facing metadata
• codec helpers are explicit objects instead of fake Python scalar/container
  types
• storage configuration uses storage=... with an ExcelStorage
  implementation
• 2.x compatibility imports, legacy config fields, and facade aliases are no
  longer current API

Before Tagging

1. Confirm the package version in src/excelalchemy/__init__.py is 3.0.0.
2. Confirm pyproject.toml no longer marks the package as alpha.
3. Review the 3.0.0 section in CHANGELOG.md.
4. Confirm README entry points describe ExcelAlchemy 3.0 as stable:
   • README.md
   • README-pypi.md
   • README_cn.md
5. Confirm the release smoke scripts:
   • scripts/smoke_package.py
   • scripts/smoke_examples.py
   • scripts/smoke_docs_assets.py
   • scripts/smoke_api_payload_snapshot.py

Local Verification

Run these commands from the repository root:

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest --cov=excelalchemy --cov-report=term-missing:skip-covered tests
uv run python scripts/smoke_package.py
uv run python scripts/smoke_examples.py
uv run python scripts/smoke_docs_assets.py
uv run python scripts/smoke_api_payload_snapshot.py
uv build
uvx twine check dist/*

GitHub Release Steps

1. Push the release commit.
2. Create and publish the tag v3.0.0.
3. Publish a GitHub Release for v3.0.0 using this document and the
   CHANGELOG.md entry as release-note sources.
4. Confirm the Upload Python Package workflow succeeds.
5. Confirm the published package version is 3.0.0.

The publish workflow verifies that the release tag, after removing the v
prefix, matches excelalchemy.__version__.

v2.4.0

2.4.0 Release Notes

Summary

2.4.0 is not a feature-heavy API release.
It is the release that makes ExcelAlchemy’s existing import capabilities legible
as one coherent Import Platform Layer.

The underlying importance is architectural clarity:

• the repository now explains the import workflow as one connected model instead
  of a set of adjacent features
• backend and frontend integrators can see where template guidance, preflight,
  import execution, result handling, remediation, and delivery fit together
• the public API stays stable while the mental model becomes clearer

This matters because production import work is usually not just "run import."
It is a staged workflow that starts before upload and continues after runtime
validation.

The Import Workflow

In 2.4.0, the import workflow is described explicitly as:

template -> preflight -> import -> result -> remediation -> delivery

More concretely:

• template authoring defines the workbook contract and user guidance
• preflight provides a lightweight structural gate
• import runtime performs the real synchronous execution
• result intelligence exposes the structured outcome of that run
• remediation payloads provide an additive retry-oriented projection
• artifact and delivery return or upload template/result workbooks through the
  storage seam

This release does not introduce a new import engine.
It makes the existing import workflow explicit and easier to use correctly.

What Changed

Architecture

• added a platform-level architecture view for the existing import system
• clarified the distinction between platform architecture and internal component
  architecture
• documented the runtime model as a sequence of stages rather than only a list
  of APIs
• documented how current code maps to the platform layers without requiring a
  refactor

Primary new architecture docs:

• docs/platform-architecture.md
• docs/runtime-model.md
• docs/integration-blueprints.md
• docs/platform-code-mapping.md

Documentation

• added the new platform architecture documentation set
• improved cross-linking from the main README and repository-facing entry docs
• aligned public API and result-object docs to the platform vocabulary
• aligned example and package guides to the same import workflow framing

Developer Experience

• clarified the top-level mental model for the import workflow
• made the shortest integration path more visible:
  • template
  • preflight
  • import
  • remediation
• made backend/frontend integration guidance easier to discover
• added blueprint-style integration references for synchronous, worker-based,
  and remediation-loop usage

Internal Alignment

• completed a minimal alignment pass for terminology consistency
• added low-risk docstring clarification around lifecycle event semantics
• preserved existing public API behavior and 2.x compatibility surfaces
• completed self-review and readiness review for the architecture-consolidation
  scope

Example

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,
    )

This example reflects the intended 2.4.0 usage story:

• preflight is the cheap structural decision
• import is the real runtime path
• lifecycle events remain additive
• remediation remains additive on top of stable result objects

Migration And Compatibility

There is no breaking change in 2.4.0.

This release does not:

• add a new runtime framework
• add a job system
• replace the existing import pipeline
• remove 2.x compatibility surfaces
• redefine the stable result objects

Instead, 2.4.0 gives the existing 2.x system a clearer structure:

• clearer architecture expression
• clearer documentation entry points
• clearer guidance for integration work

The practical effect is improved understanding and safer integration, not a new
behavioral contract.

ExcelAlchemy 2.3

ExcelAlchemy 2.3

ExcelAlchemy 2.3 makes the import path more usable as a complete backend workflow instead of a single execution step. This release brings together template guidance, lightweight preflight checks, structured import events, and remediation-oriented result helpers so applications can guide users before upload, validate structure before execution, observe progress during import, and return actionable follow-up data after failures.

This is an additive release. ExcelAlchemy.import_data(...) remains the full validation and execution entry point. What changed is the developer experience around that path.

Unified Import Workflow

Template guidance before upload

Templates can now carry richer workbook-facing guidance through additive metadata such as hint= and example_value=. This improves generated header comments and helps users fill workbooks more accurately before they reach the backend.

Preflight before execution

ExcelAlchemy.preflight_import(...) adds a lightweight structural validation step for uploaded workbooks. It is intended to:

• confirm the configured sheet exists
• validate headers against the schema
• detect basic structural problems
• estimate row count

Preflight stays intentionally narrow. It does not execute row logic, run deep validation, or try to approximate the full import result.

Import with lifecycle visibility

ExcelAlchemy.import_data(...) now supports additive lifecycle callbacks through on_event=. This gives service layers a simple way to observe progress and state transitions during import without introducing a separate async or job execution model.

Typical uses include:

• updating job status
• reporting progress to an API
• recording row counts and completion state
• handling unexpected failures with more context

Remediation after failures

When imports fail, build_frontend_remediation_payload(...) provides a compact, frontend-oriented summary of what to do next. This works alongside the existing result surfaces and helps applications return retry-friendly guidance instead of only raw issue details.

Developer Experience Improvements

• clearer separation between structural preflight and full import execution
• a cleaner backend flow: template -> preflight -> import -> remediation
• more practical API-facing integration patterns in the docs and examples
• improved template comment quality without changing workbook layout
• stronger support for service-layer progress reporting and failure handling

Example Workflow

preflight = alchemy.preflight_import("employees.xlsx")

if not preflight.is_valid:
    return {"preflight": preflight.to_api_payload()}

events: list[dict[str, object]] = []

result = await alchemy.import_data(
    "employees.xlsx",
    "employees-result.xlsx",
    on_event=events.append,
)

remediation = build_frontend_remediation_payload(
    result=result,
    cell_error_map=alchemy.cell_error_map,
    row_error_map=alchemy.row_error_map,
)

Compatibility

• additive release; existing import/export usage remains valid
• import_data(...) remains the full execution path
• preflight_import(...) is structural only
• lifecycle events are optional
• remediation payload helpers are opt-in
• template UX metadata does not change worksheet layout

Summary

ExcelAlchemy 2.3 is primarily about making import easier to integrate as a real product workflow. It gives applications better guidance before upload, a safer checkpoint before execution, better visibility during processing, and more practical outputs after failure.

ExcelAlchemy 2.2.8

ExcelAlchemy 2.2.8

ExcelAlchemy 2.2.8 continues the stable 2.x line with a clearer integration reading path and stronger release verification.

Highlights

• added docs/integration-roadmap.md so new adopters can see what to read first for backend, frontend, and migration work
• added a stable import-failure API payload snapshot for release smoke verification
• release checks now run python -m examples.fastapi_reference.app directly after installation

Compatibility

• no public import/export workflow API was removed
• ImportResult, CellErrorMap, and RowIssueMap remain stable for 2.x integrations
• storage=... remains the recommended 2.x backend configuration path

ExcelAlchemy 2.2.7

ExcelAlchemy 2.2.7

ExcelAlchemy 2.2.7 continues the stable 2.x line with stronger API-facing result payloads, a more complete FastAPI reference app, harder install-time smoke verification, and more consistent codec diagnostics.

Highlights

• strengthened ImportResult, CellErrorMap, and RowIssueMap for frontend and API consumption
• added docs/api-response-cookbook.md
• expanded examples/fastapi_reference/ into a more copyable minimal application
• hardened release smoke verification to cover failed-import payloads, generated assets, docs, and FastAPI HTTP behavior
• unified codec fallback logging under excelalchemy.codecs

Compatibility

• no public import/export workflow API was removed
• storage=... remains the recommended 2.x backend configuration path
• result objects remain stable for 2.x integrations

ExcelAlchemy 2.2.6

ExcelAlchemy 2.2.6

ExcelAlchemy 2.2.6 continues the stable 2.x line with better integration guidance, stronger release verification, and clearer runtime diagnostics.

Highlights

• added docs/result-objects.md to document ImportResult, CellErrorMap, and RowIssueMap as first-class integration surfaces
• added a copyable FastAPI reference project under examples/fastapi_reference/
• strengthened release smoke verification to cover:
  • successful imports
  • failed imports
  • structured error payloads
  • export upload behavior
• improved codec fallback warnings so invalid workbook input is easier to debug

Compatibility

• no public import/export workflow API was removed
• storage=... remains the recommended 2.x backend configuration path
• result objects remain stable for 2.x integrations

Verification

uv run ruff check .
uv run pyright
uv run pytest -q
./.venv/bin/python scripts/smoke_package.py
./.venv/bin/python scripts/smoke_examples.py
./.venv/bin/python scripts/generate_example_output_assets.py
uv build
uvx twine check dist/*

ExcelAlchemy 2.2.5

ExcelAlchemy 2.2.5

ExcelAlchemy 2.2.5 continues the stable 2.x line with stronger import-failure UX, clearer documentation boundaries, stronger examples and showcase assets, and better smoke coverage for release verification.

This release keeps the public import/export workflow API stable while making failures easier to inspect, examples easier to follow, and release validation more robust.

Highlights

• richer workbook-facing error access through CellErrorMap and RowIssueMap
• more natural validation messages for common import failures
• clearer getting-started, public API, migration, examples, and showcase documentation paths
• more realistic repository examples with direct smoke coverage
• stronger package, example, and generated-asset smoke verification

What changed

Error UX polish

• added richer error access containers while preserving 2.x dict-like compatibility
• improved error inspection through helpers such as:
  • at(...)
  • messages_at(...)
  • messages_for_row(...)
  • numbered_messages_for_row(...)
  • flatten()
  • to_dict()
• unified exception boundaries around ProgrammaticError, ConfigError, ExcelCellError, and ExcelRowError
• improved repr output and structured error serialization
• normalized common validation messages into more natural workbook-facing text

Documentation and guidance

• added docs/getting-started.md
• strengthened docs/public-api.md
• expanded docs/examples-showcase.md
• clarified the recommended 2.x path for backend integration with storage=...
• linked README, PyPI README, migrations, examples, showcase, and public API docs into a clearer documentation flow

Examples and showcase

• added more business-oriented examples, including:
  • employee import workflow
  • create-or-update import workflow
  • export workflow
  • selection-heavy forms
  • date and range fields
  • Minio-backed configuration
  • FastAPI upload flow
• expanded examples/README.md into a recommended reading order
• added generated example-output assets for documentation and showcase use

Smoke and release verification

• strengthened installed-package smoke coverage
• added repository example smoke coverage
• added generated-output asset smoke coverage
• kept optional dependency paths non-blocking where appropriate

Typing and internal cleanup

• continued consolidating layered metadata usage across internal consumers
• reduced low-value typing gray areas and unnecessary casts in the runtime path
• preserved the stable public 2.x API while tightening internal typing boundaries

Compatibility notes

• no public import or export workflow API was removed in this release
• storage=... remains the recommended 2.x backend configuration path
• legacy built-in Minio fields remain available as compatibility surface in 2.x
• FieldMeta(...) and ExcelMeta(...) remain the stable public metadata entry points

Verification

uv run ruff check .
uv run pyright
uv run pytest -q
./.venv/bin/python scripts/smoke_package.py
./.venv/bin/python scripts/smoke_examples.py
./.venv/bin/python scripts/generate_example_output_assets.py
rm -rf dist
uv build
uvx twine check dist/*

ExcelAlchemy 2.2.4

ExcelAlchemy 2.2.4

ExcelAlchemy 2.2.4 continues the stable 2.x line with a focused validation fix in the Pydantic adapter, continued metadata and typing cleanup, and a stronger set of real examples.

This release keeps the public import/export workflow API stable while making invalid annotated declarations fail correctly, reducing internal typing gray areas, and making the repository easier to learn from.

Highlights

• unsupported Annotated[..., Field(...), ExcelMeta(...)] declarations now fail with the intended ProgrammaticError
• metadata internals continue moving toward layered objects rather than a flat central record
• runtime typing boundaries are more explicit and less ad hoc
• the repository now includes more realistic workflow examples with direct smoke coverage

What changed

Validation fix

• restored explicit ProgrammaticError handling for unsupported annotated declarations that use native Python types instead of ExcelFieldCodec subclasses
• tightened codec resolution in the Pydantic adapter so unsupported declarations fail at the codec resolution boundary instead of being treated as valid runtime metadata
• preserved existing behavior for valid codec-based declarations

Metadata and typing cleanup

• continued treating FieldMetaInfo as a compatibility facade over layered metadata objects
• moved more internal consumers and built-in codecs onto declared, runtime, presentation, and constraints
• reduced remaining runtime typing gray areas by replacing loose Any usage with explicit boundary aliases or object
• removed the final type: ignore hotspot from the number codec path

Examples and smoke coverage

• added:
  • examples/employee_import_workflow.py
  • examples/create_or_update_import.py
  • examples/date_and_range_fields.py
  • examples/selection_fields.py
  • examples/export_workflow.py
  • examples/minio_storage.py
• added examples/README.md with a recommended reading order
• added smoke coverage for repository examples in the test suite

Compatibility notes

• no public import or export workflow API was removed in this release
• valid codec-based declarations continue to work unchanged
• unsupported native annotations with ExcelMeta(...) now fail early with the intended ProgrammaticError
• the built-in Minio path remains available in 2.x and still uses the current compatibility-based configuration path

Verification

uv run ruff check .
uv run pyright
uv run pytest tests
uv build
uvx twine check dist/*

ExcelAlchemy 2.2.3

ExcelAlchemy 2.2.3

ExcelAlchemy 2.2.3 continues the stable 2.x line with a focused validation fix in the Pydantic adapter layer.

This release keeps the public import/export workflow API stable while restoring the intended failure mode for unsupported annotated declarations.

Highlights

• unsupported Annotated[..., Field(...), ExcelMeta(...)] declarations now fail with the intended ProgrammaticError
• codec resolution in the Pydantic adapter is stricter and more explicit
• the validation fix is protected by an integration regression test

What changed

Validation fix

• restored explicit ProgrammaticError handling for unsupported annotated declarations that use native Python types instead of ExcelFieldCodec subclasses
• tightened codec resolution in the Pydantic adapter so unsupported declarations fail at the codec resolution boundary instead of being treated as valid runtime metadata
• preserved the existing behavior for valid ExcelFieldCodec and CompositeExcelFieldCodec declarations

Regression coverage

• added an integration regression test for unsupported annotated declarations
• verified that native Python annotations paired with ExcelMeta(...) do not silently enter the workbook schema path

Compatibility notes

• no public import or export workflow API was removed in this release
• valid codec-based declarations continue to work unchanged
• unsupported native annotations with ExcelMeta(...) now fail early with the intended ProgrammaticError

Verification

uv run ruff check src/excelalchemy/helper/pydantic.py tests/integration/test_excelalchemy_workflows.py
uv run pyright
uv run pytest tests/integration/test_excelalchemy_workflows.py -q
uv build
uvx twine check dist/*

ExcelAlchemy 2.2.2

ExcelAlchemy 2.2.2

ExcelAlchemy 2.2.2 continues the stable 2.x line with stronger developer ergonomics, clearer public API guidance, and better release-time smoke coverage.

This release keeps the public import/export workflow API stable while making the repository easier to adopt, easier to navigate, and safer to publish.

Highlights

• added real integration examples instead of relying only on README snippets
• documented stable public modules, compatibility modules, and internal modules explicitly
• strengthened package publishing with installed-package smoke tests
• updated README and migration guidance to point users toward the recommended config and storage paths

What changed

Examples

• added examples/annotated_schema.py
• added examples/custom_storage.py
• added examples/fastapi_upload.py

These examples cover:

• Annotated[..., Field(...), ExcelMeta(...)] declarations
• custom ExcelStorage integrations
• a realistic FastAPI upload flow

Public API guidance

• added docs/public-api.md
• documented:
  • stable public modules
  • compatibility modules
  • internal modules
  • recommended import style

Release hardening

• added scripts/smoke_package.py
• updated the release workflow to run package-level smoke tests after wheel and source-distribution installation
• smoke verification now covers:
  • template generation
  • import execution
  • export artifact generation

Documentation updates

• updated README.md
• updated README_cn.md
• updated MIGRATIONS.md

Compatibility notes

• no public import or export workflow API was removed in this release
• the new examples and docs clarify recommended public paths without changing existing 2.x compatibility behavior

Verification

uv run ruff check .
uv run pyright
uv run pytest tests
./.venv/bin/python scripts/smoke_package.py
uv build
uvx twine check dist/*