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

ExcelAlchemy 2.0.0.post1

ExcelAlchemy 2.0.0.post1

This post-release updates the package presentation on PyPI without changing the runtime behavior of ExcelAlchemy 2.0.0.

What changed

• added a dedicated PyPI-friendly long description via README-pypi.md
• switched package metadata to use the PyPI-specific README
• replaced relative README assets with PyPI-safe absolute links
• ensured screenshots and documentation links render correctly on the PyPI project page

Notes

• no runtime API changes
• no dependency changes
• no behavior changes to import/export workflows

Installation

pip install -U ExcelAlchemy

ExcelAlchemy 2.0.0

ExcelAlchemy 2.0.0

ExcelAlchemy 2.0.0 is the first stable public release of the 2.x line.

This release turns the project into a more focused, typed, and documentation-first Python library for Excel import/export workflows built around Pydantic models, locale-aware workbook output, and pluggable storage.

Highlights

• schema-driven Excel template generation from Pydantic models
• workbook import validation with row-level and cell-level feedback
• locale-aware workbook display text for zh-CN and en
• pluggable ExcelStorage protocol instead of a hard-coded backend
• optional built-in Minio backend via ExcelAlchemy[minio]
• runtime path simplified around openpyxl without pandas
• modernized Python codebase with ruff, pyright, contract tests, and stricter typing

What changed in 2.0

• migrated the internals to a cleaner src/ layout
• redesigned validation around Pydantic v2
• removed pandas from the runtime dependency path
• promoted protocol-based storage boundaries
• clarified public modules such as excelalchemy.codecs, excelalchemy.metadata, excelalchemy.config, and excelalchemy.exceptions
• added stronger documentation for architecture, locale policy, and migration

Compatibility notes

• Python 3.12, 3.13, and 3.14 are supported
• Pydantic v2 is required
• legacy excelalchemy.types.* imports remain as compatibility shims in 2.x and are planned for removal in 3.0

Installation

pip install ExcelAlchemy

Optional Minio support:

pip install "ExcelAlchemy[minio]"

Documentation

• README
• Architecture
• Migration Notes
• Locale Policy

Thanks for checking out the project

ExcelAlchemy 2.0.0rc1

Pre-release

This is the first public release candidate for the ExcelAlchemy 2.0 line.

2.0.0rc1 is intended to validate the real release pipeline and the new architecture before the final 2.0.0 release.

Highlights

• Migrated to a standard src/ layout
• Upgraded to Pydantic v2 with a dedicated adapter boundary
• Removed the runtime pandas dependency
• Added pluggable storage through ExcelStorage
• Made Minio an optional extra: pip install "ExcelAlchemy[minio]"
• Added locale-aware workbook display text with locale='zh-CN' | 'en'
• Modernized the project for Python 3.12-3.14, with Python 3.14 as the primary target
• Switched local development, CI, and packaging workflows to uv
• Reworked the documentation into architecture-focused project pages

Breaking Changes

• Python 3.10 and 3.11 are no longer supported
• ExcelAlchemy now targets Pydantic v2
• pandas is no longer installed or used at runtime
• Minio is no longer a core dependency
• Runtime exceptions are now standardized in English

Installation

Base install:

pip install --pre ExcelAlchemy

v1.1.0

• update pandas to 2.0.x

v1.0.0

• production ready release

0.1.0rc1

• add test for all value type

0.1.0rc0

• implement test for all value type

Fix for minio error

• update minio usage