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