feat(v2.1): add ImportSession

Author: ruicore

CHANGELOG.md

@@ -4,6 +4,57 @@ 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.1.0] - Unreleased
+
+This release continues the 2.x line with internal architecture cleanup, naming
+improvements, and stronger separation between long-lived facade state and
+single-run import workflow state.
+
+### Added
+
+- Added `ImportSession` as the one-shot import workflow runtime that keeps
+  worksheet state, header parsing state, issue tracking, and executor state out
+  of the long-lived `ExcelAlchemy` facade
+- Added normalized internal config layers:
+  `ImporterSchemaOptions`, `ImportBehavior`, `ExporterSchemaOptions`,
+  `ExportBehavior`, and `StorageOptions`
+- Added internal metadata layers:
+  `DeclaredFieldMeta`, `RuntimeFieldBinding`, `WorkbookPresentationMeta`, and
+  `ImportConstraints`
+- Added targeted regression tests for config normalization and split metadata
+  layering
+
+### Changed
+
+- Refactored `ExcelAlchemy.import_data()` to delegate import execution to
+  `ImportSession` while keeping the 2.x public API unchanged
+- Reduced facade responsibility so `ExcelAlchemy` now primarily owns durable
+  configuration and collaborator wiring rather than import-run state
+- Normalized storage resolution so internal code now reads `storage_options`
+  instead of scattering direct reads of `storage`, `minio`, `bucket_name`, and
+  `url_expires`
+- Updated import execution to consume normalized `schema_options` and
+  `behavior` objects instead of treating config as an all-in-one bus
+- Split `FieldMetaInfo` into internal declaration, runtime, presentation, and
+  constraint layers while preserving the existing `FieldMeta(...)` and
+  `ExcelMeta(...)` entry points
+- Improved internal naming by moving the primary worksheet variable vocabulary
+  from `df/header_df` to `worksheet_table/header_table`
+- Renamed `excelalchemy.util.convertor` to
+  `excelalchemy.util.converter`; the old path now remains as a deprecated
+  compatibility shim
+- Simplified generic type parameter names across the config, facade, storage,
+  executor, and import-session layers to better reflect their roles
+
+### Compatibility Notes
+
+- `df` and `header_df` remain available as backward-compatible aliases on the
+  facade and import session, but new internal code should prefer
+  `worksheet_table` and `header_table`
+- `excelalchemy.util.convertor` remains importable in 2.x and now emits the
+  standard deprecation warning that points to `excelalchemy.util.converter`
+- No public import/export workflow API was removed in this release
+
 ## [2.0.0.post1] - 2026-03-28
 
 This post-release updates the package presentation and release metadata for the

docs/releases/2.1.0.md

@@ -0,0 +1,93 @@
+# 2.1.0 Release Checklist
+
+This checklist is intended for the first feature release on top of the stable
+2.0 line.
+
+## Purpose
+
+- publish the first 2.1 release of ExcelAlchemy
+- ship the sessionized import workflow architecture
+- ship internal config normalization and metadata layering without breaking the
+  public 2.x API
+- confirm that naming cleanup and compatibility shims are documented clearly
+
+## Before Tagging
+
+1. Confirm the intended version in `src/excelalchemy/__init__.py`.
+2. Review the `2.1.0` section in `CHANGELOG.md`.
+3. Confirm `README.md`, `README-pypi.md`, and `MIGRATIONS.md` still describe the
+   recommended public paths correctly.
+4. Confirm the compatibility notes for:
+   - `excelalchemy.util.convertor`
+   - `df/header_df` compatibility aliases
+   - legacy Minio config path
+
+## Local Verification
+
+Run these commands from the repository root:
+
+```bash
+uv sync --extra development
+uv run ruff check .
+uv run pyright
+uv run pytest tests
+rm -rf dist
+uv build
+uvx twine check dist/*
+```
+
+Optional smoke tests:
+
+```bash
+uv venv .pkg-smoke-base --python 3.14
+uv pip install --python .pkg-smoke-base/bin/python dist/*.whl
+.pkg-smoke-base/bin/python -c "import excelalchemy; print(excelalchemy.__version__)"
+```
+
+```bash
+uv venv .pkg-smoke-minio --python 3.14
+uv pip install --python .pkg-smoke-minio/bin/python "dist/*.whl[minio]"
+.pkg-smoke-minio/bin/python -c "from excelalchemy.core.storage_minio import MinioStorageGateway; print(MinioStorageGateway.__name__)"
+```
+
+## GitHub Release Steps
+
+1. Push the release commit to the default branch.
+2. In GitHub Releases, draft a new release.
+3. Create a new tag: `v2.1.0`.
+4. Use the `2.1.0` section from `CHANGELOG.md` as the release notes base.
+5. Publish the release and monitor the `Upload Python Package` workflow.
+
+## Release Focus
+
+When reviewing the final release notes, make sure they communicate these three
+themes clearly:
+
+- `ExcelAlchemy` is now a lighter facade because import runtime state moved into
+  `ImportSession`
+- config is still easy to construct publicly, but internally it is now split
+  into schema, behavior, and storage layers
+- metadata now has clearer internal layering without forcing users to rewrite
+  their `FieldMeta(...)` or `ExcelMeta(...)` declarations
+
+## PyPI Verification
+
+After the workflow completes:
+
+1. Confirm the new release appears on PyPI.
+2. Confirm the long description renders correctly.
+3. Confirm screenshots and absolute links still work on the PyPI project page.
+4. Test base install:
+
+```bash
+pip install -U ExcelAlchemy
+```
+
+5. Test optional Minio install:
+
+```bash
+pip install -U "ExcelAlchemy[minio]"
+```
+
+6. Run one template-generation example.
+7. Run one import flow and one export flow.

src/excelalchemy/config.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import StrEnum
 from typing import TYPE_CHECKING, Self
 
@@ -15,7 +15,7 @@
 from excelalchemy.helper.pydantic import get_model_field_names
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import message as msg
-from excelalchemy.util.convertor import export_data_converter, import_data_converter
+from excelalchemy.util.converter import export_data_converter, import_data_converter
 
 if TYPE_CHECKING:
     from minio import Minio
@@ -34,10 +34,67 @@ class ImportMode(StrEnum):
     CREATE_OR_UPDATE = 'CREATE_OR_UPDATE'
 
 
+@dataclass(slots=True, frozen=True)
+class StorageOptions:
+    """Normalized storage backend settings shared by importer and exporter configs."""
+
+    storage: ExcelStorage | None
+    minio: Minio | None
+    bucket_name: str
+    url_expires: int
+
+    @property
+    def has_explicit_storage(self) -> bool:
+        return self.storage is not None
+
+    @property
+    def has_legacy_minio(self) -> bool:
+        return self.minio is not None
+
+
+@dataclass(slots=True, frozen=True)
+class ImporterSchemaOptions[ImportCreateModelT: BaseModel, ImportUpdateModelT: BaseModel]:
+    """Schema declaration and workbook presentation settings for imports."""
+
+    create_importer_model: type[ImportCreateModelT] | None
+    update_importer_model: type[ImportUpdateModelT] | None
+    sheet_name: str
+    locale: str
+
+
+@dataclass(slots=True, frozen=True)
+class ImportBehavior[ContextT]:
+    """Execution callbacks and import workflow policy."""
+
+    data_converter: DataConverter | None
+    creator: DmlCallback[ContextT] | None
+    updater: DmlCallback[ContextT] | None
+    context: ImportContext[ContextT]
+    is_data_exist: ExistenceCheckCallback[ContextT] | None
+    exec_formatter: Callable[[Exception], str]
+    import_mode: ImportMode
+
+
+@dataclass(slots=True, frozen=True)
+class ExporterSchemaOptions[ExportModelT: BaseModel]:
+    """Schema declaration and workbook presentation settings for exports."""
+
+    exporter_model: type[ExportModelT]
+    sheet_name: str
+    locale: str
+
+
+@dataclass(slots=True, frozen=True)
+class ExportBehavior:
+    """Execution behavior used when rendering export rows."""
+
+    data_converter: DataConverter | None
+
+
 @dataclass(slots=True)
-class ImporterConfig[ContextT, ImporterCreateModelT: BaseModel, ImporterUpdateModelT: BaseModel]:
-    create_importer_model: type[ImporterCreateModelT] | None = None
-    update_importer_model: type[ImporterUpdateModelT] | None = None
+class ImporterConfig[ContextT, ImportCreateModelT: BaseModel, ImportUpdateModelT: BaseModel]:
+    create_importer_model: type[ImportCreateModelT] | None = None
+    update_importer_model: type[ImportUpdateModelT] | None = None
 
     # The converter receives schema keys rather than workbook labels.
     data_converter: DataConverter | None = import_data_converter
@@ -57,6 +114,11 @@ class ImporterConfig[ContextT, ImporterCreateModelT: BaseModel, ImporterUpdateMo
     locale: str = 'zh-CN'
 
     sheet_name: str = 'Sheet1'
+    schema_options: ImporterSchemaOptions[ImportCreateModelT, ImportUpdateModelT] = field(
+        init=False, repr=False
+    )
+    behavior: ImportBehavior[ContextT] = field(init=False, repr=False)
+    storage_options: StorageOptions = field(init=False, repr=False)
 
     def validate_model(self) -> Self:
         if self.import_mode not in ImportMode.__members__.values():
@@ -100,11 +162,32 @@ def _validate_create_or_update(self) -> None:
 
     def __post_init__(self) -> None:
         self.validate_model()
+        self.schema_options = ImporterSchemaOptions(
+            create_importer_model=self.create_importer_model,
+            update_importer_model=self.update_importer_model,
+            sheet_name=self.sheet_name,
+            locale=self.locale,
+        )
+        self.behavior = ImportBehavior(
+            data_converter=self.data_converter,
+            creator=self.creator,
+            updater=self.updater,
+            context=self.context,
+            is_data_exist=self.is_data_exist,
+            exec_formatter=self.exec_formatter,
+            import_mode=self.import_mode,
+        )
+        self.storage_options = StorageOptions(
+            storage=self.storage,
+            minio=self.minio,
+            bucket_name=self.bucket_name,
+            url_expires=self.url_expires,
+        )
 
 
 @dataclass(slots=True)
-class ExporterConfig[ExporterModelT: BaseModel]:
-    exporter_model: type[ExporterModelT]
+class ExporterConfig[ExportModelT: BaseModel]:
+    exporter_model: type[ExportModelT]
     # The converter receives schema keys rather than workbook labels.
     data_converter: DataConverter | None = export_data_converter
 
@@ -115,6 +198,9 @@ class ExporterConfig[ExporterModelT: BaseModel]:
     locale: str = 'zh-CN'
 
     sheet_name: str = 'Sheet1'
+    schema_options: ExporterSchemaOptions[ExportModelT] = field(init=False, repr=False)
+    behavior: ExportBehavior = field(init=False, repr=False)
+    storage_options: StorageOptions = field(init=False, repr=False)
 
     def validate_model(self) -> Self:
         if not self.exporter_model:
@@ -123,3 +209,15 @@ def validate_model(self) -> Self:
 
     def __post_init__(self) -> None:
         self.validate_model()
+        self.schema_options = ExporterSchemaOptions(
+            exporter_model=self.exporter_model,
+            sheet_name=self.sheet_name,
+            locale=self.locale,
+        )
+        self.behavior = ExportBehavior(data_converter=self.data_converter)
+        self.storage_options = StorageOptions(
+            storage=self.storage,
+            minio=self.minio,
+            bucket_name=self.bucket_name,
+            url_expires=self.url_expires,
+        )

src/excelalchemy/core/abstract.py

@@ -11,11 +11,9 @@
 
 class ABCExcelAlchemy[
     ContextT,
-    ImporterCreateModelT: BaseModel,
-    ImporterUpdateModelT: BaseModel,
-    CreateModelT: BaseModel,
-    UpdateModelT: BaseModel,
-    ExporterModelT: BaseModel,
+    ImportCreateModelT: BaseModel,
+    ImportUpdateModelT: BaseModel,
+    ExportModelT: BaseModel,
 ](ABC):
     @abstractmethod
     def download_template(self, sample_data: list[ExportRowPayload] | None = None) -> DataUrlStr: