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/*

ExcelAlchemy 2.2.1

ExcelAlchemy 2.2.1

ExcelAlchemy 2.2.1 continues the stable 2.x line with deeper metadata layering, stronger internal immutability, and tighter type boundaries around the Pydantic adapter layer.

This release keeps the public import/export workflow API stable while making internal metadata behavior easier to reason about and less prone to hidden shared state.

Highlights

• split metadata layers now behave like immutable value objects
• facade-level metadata updates keep the 2.x ergonomics while replacing internal layers structurally
• workbook presentation internals now use immutable storage forms for character sets and options
• the Pydantic adapter layer now has clearer type boundaries around annotations, codecs, and normalized payloads

What changed

Metadata layering

• made DeclaredFieldMeta, RuntimeFieldBinding, WorkbookPresentationMeta, and ImportConstraints frozen internal structures
• updated FieldMetaInfo mutation paths to replace internal layer objects via structural updates instead of mutating them in place
• normalized workbook presentation internals so character sets and options are stored in immutable forms

Typing refinements

• tightened type boundaries in the Pydantic adapter around annotations, codecs, and normalized input payloads
• reduced ambiguity in metadata and adapter internals while preserving 2.x behavior

Regression coverage

• added tests that verify split metadata layers behave like immutable value objects
• added tests that verify facade-level metadata mutation replaces internal layers rather than mutating them in place

Compatibility notes

• no public import or export workflow API was removed in this release
• FieldMeta(...) and ExcelMeta(...) remain the stable public metadata entry points
• the metadata layering changes are internal and preserve the public 2.x surface

Verification

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

ExcelAlchemy 2.2.0

ExcelAlchemy 2.2.0

ExcelAlchemy 2.2.0 continues the stable 2.x line with runtime consolidation, clearer config ergonomics, and a more explicit protocol-first storage story.

This release keeps the public import/export workflow API stable while making the import runtime easier to reason about and the recommended integration paths clearer.

Highlights

• ImportSession now exposes a clearer lifecycle and final runtime snapshot
• ExcelAlchemy exposes last_import_snapshot as a facade-level view of the latest import run
• config construction is easier to read through dedicated helper constructors
• storage=... is now the clear recommended backend integration path for the 2.x line
• legacy Minio config remains supported in 2.x, but now emits an explicit deprecation warning

What changed

Import runtime lifecycle

• added ImportSessionPhase
• added ImportSessionSnapshot
• refined the one-shot import workflow so it now advances through explicit phases:
  • workbook loading
  • header validation
  • row preparation
  • row execution
  • result rendering
  • completion
• added ExcelAlchemy.last_import_snapshot as a read-only facade-level view of the latest import session state

Config ergonomics

• added recommended constructors:
  • ImporterConfig.for_create(...)
  • ImporterConfig.for_update(...)
  • ImporterConfig.for_create_or_update(...)
  • ExporterConfig.for_model(...)
  • ExporterConfig.for_storage(...)
• kept the existing ImporterConfig(...) and ExporterConfig(...) construction style compatible for 2.x users

Storage guidance

• clarified explicit storage=... as the recommended backend configuration path
• kept legacy minio, bucket_name, and url_expires support for 2.x compatibility
• added an explicit deprecation warning for the legacy built-in Minio config path
• reduced warning noise by emitting that deprecation warning once per compatibility scenario

Compatibility notes

• no public import or export workflow API was removed in this release
• legacy Minio configuration is still supported in 2.x
• direct ImporterConfig(...) and ExporterConfig(...) construction remain valid
• helper constructors are the recommended public path going forward

Verification

The release branch was verified with:

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

ExcelAlchemy 2.1.0

ExcelAlchemy 2.1.0

ExcelAlchemy 2.1.0 continues the stable 2.x line with internal architecture cleanup, clearer naming, and stronger separation between long-lived facade state and single-run import workflow state.

This release does not change the core public import/export workflow API. Instead, it makes the library easier to reason about, easier to extend, and better aligned with the design goals documented in the repository.

Highlights

• import runtime state moved into a dedicated ImportSession
• ExcelAlchemy is now a lighter facade focused on configuration and wiring
• config internals are normalized into schema, behavior, and storage layers
• FieldMetaInfo now uses clearer internal layering for declaration, runtime binding, workbook presentation, and import constraints
• internal naming is more explicit, including the shift from df/header_df toward worksheet_table/header_table
• excelalchemy.util.converter is now the canonical converter module name

What changed

Import workflow architecture

• added ImportSession as the one-shot import runtime
• moved worksheet state, header parsing state, issue tracking, and executor state out of the long-lived facade
• kept ExcelAlchemy.import_data(...) unchanged at the public API level

Config normalization

• added internal config layers:
  • ImporterSchemaOptions
  • ImportBehavior
  • ExporterSchemaOptions
  • ExportBehavior
  • StorageOptions
• kept ImporterConfig(...) and ExporterConfig(...) unchanged for users
• normalized internal storage resolution so the codebase now reads storage_options instead of scattering direct reads of storage, minio, bucket_name, and url_expires

Metadata layering

• split FieldMetaInfo into clearer internal layers:
  • declaration metadata
  • runtime field binding
  • workbook presentation metadata
  • import constraint metadata
• preserved existing FieldMeta(...) and ExcelMeta(...) usage

Naming cleanup

• simplified generic type parameter names across the core architecture
• moved internal workbook table vocabulary from df/header_df to worksheet_table/header_table
• renamed excelalchemy.util.convertor to excelalchemy.util.converter

Compatibility notes

• no public import/export workflow API was removed in this release
• df and header_df remain available as backward-compatible aliases in 2.x
• excelalchemy.util.convertor remains importable in 2.x and now acts as a deprecated compatibility shim
• legacy Minio configuration remains supported in 2.x while the internal storage path now prefers normalized storage options

Verification

The release branch was verified with:

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