ExcelAlchemy 2.1.0__tar.gz → 2.2.2__tar.gz

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.1.0
+Version: 2.2.2
 Summary: Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.
 Keywords: excel,openpyxl,pydantic,minio,schema
 Author: Ray

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.1.0'
+__version__ = '2.2.2'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/src/excelalchemy/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from enum import StrEnum
@@ -9,6 +10,7 @@ from typing import TYPE_CHECKING, Self
 
 from pydantic import BaseModel
 
+from excelalchemy._primitives.deprecation import DEPRECATION_REMOVAL_VERSION, ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.payloads import DataConverter, DmlCallback, ExistenceCheckCallback, ImportContext
 from excelalchemy.core.storage_protocol import ExcelStorage
 from excelalchemy.exceptions import ConfigError
@@ -21,6 +23,9 @@ if TYPE_CHECKING:
     from minio import Minio
 
 
+_EMITTED_STORAGE_DEPRECATION_WARNINGS: set[bool] = set()
+
+
 class ExcelMode(StrEnum):
     """Top-level Excel workflow mode."""
 
@@ -51,6 +56,10 @@ class StorageOptions:
     def has_legacy_minio(self) -> bool:
         return self.minio is not None
 
+    @property
+    def uses_legacy_minio_path(self) -> bool:
+        return self.storage is None and self.minio is not None
+
 
 @dataclass(slots=True, frozen=True)
 class ImporterSchemaOptions[ImportCreateModelT: BaseModel, ImportUpdateModelT: BaseModel]:
@@ -118,6 +127,116 @@ class ImporterConfig[ContextT, ImportCreateModelT: BaseModel, ImportUpdateModelT
     behavior: ImportBehavior[ContextT] = field(init=False, repr=False)
     storage_options: StorageOptions = field(init=False, repr=False)
 
+    @classmethod
+    def for_create(
+        cls,
+        importer_model: type[ImportCreateModelT],
+        *,
+        data_converter: DataConverter | None = import_data_converter,
+        creator: DmlCallback[ContextT] | None = None,
+        updater: DmlCallback[ContextT] | None = None,
+        context: ImportContext[ContextT] = None,
+        is_data_exist: ExistenceCheckCallback[ContextT] | None = None,
+        exec_formatter: Callable[[Exception], str] = str,
+        storage: ExcelStorage | None = None,
+        minio: Minio | None = None,
+        bucket_name: str = 'excel',
+        url_expires: int = 3600,
+        locale: str = 'zh-CN',
+        sheet_name: str = 'Sheet1',
+    ) -> Self:
+        """Build a create-mode importer config through the recommended constructor."""
+        return cls(
+            create_importer_model=importer_model,
+            data_converter=data_converter,
+            creator=creator,
+            updater=updater,
+            context=context,
+            is_data_exist=is_data_exist,
+            exec_formatter=exec_formatter,
+            import_mode=ImportMode.CREATE,
+            storage=storage,
+            minio=minio,
+            bucket_name=bucket_name,
+            url_expires=url_expires,
+            locale=locale,
+            sheet_name=sheet_name,
+        )
+
+    @classmethod
+    def for_update(
+        cls,
+        importer_model: type[ImportUpdateModelT],
+        *,
+        data_converter: DataConverter | None = import_data_converter,
+        creator: DmlCallback[ContextT] | None = None,
+        updater: DmlCallback[ContextT] | None = None,
+        context: ImportContext[ContextT] = None,
+        is_data_exist: ExistenceCheckCallback[ContextT] | None = None,
+        exec_formatter: Callable[[Exception], str] = str,
+        storage: ExcelStorage | None = None,
+        minio: Minio | None = None,
+        bucket_name: str = 'excel',
+        url_expires: int = 3600,
+        locale: str = 'zh-CN',
+        sheet_name: str = 'Sheet1',
+    ) -> Self:
+        """Build an update-mode importer config through the recommended constructor."""
+        return cls(
+            update_importer_model=importer_model,
+            data_converter=data_converter,
+            creator=creator,
+            updater=updater,
+            context=context,
+            is_data_exist=is_data_exist,
+            exec_formatter=exec_formatter,
+            import_mode=ImportMode.UPDATE,
+            storage=storage,
+            minio=minio,
+            bucket_name=bucket_name,
+            url_expires=url_expires,
+            locale=locale,
+            sheet_name=sheet_name,
+        )
+
+    @classmethod
+    def for_create_or_update(
+        cls,
+        *,
+        create_importer_model: type[ImportCreateModelT],
+        update_importer_model: type[ImportUpdateModelT],
+        is_data_exist: ExistenceCheckCallback[ContextT],
+        data_converter: DataConverter | None = import_data_converter,
+        creator: DmlCallback[ContextT] | None = None,
+        updater: DmlCallback[ContextT] | None = None,
+        context: ImportContext[ContextT] = None,
+        exec_formatter: Callable[[Exception], str] = str,
+        storage: ExcelStorage | None = None,
+        minio: Minio | None = None,
+        bucket_name: str = 'excel',
+        url_expires: int = 3600,
+        locale: str = 'zh-CN',
+        sheet_name: str = 'Sheet1',
+    ) -> Self:
+        """Build a create-or-update importer config through the recommended constructor."""
+        return cls(
+            create_importer_model=create_importer_model,
+            update_importer_model=update_importer_model,
+            data_converter=data_converter,
+            creator=creator,
+            updater=updater,
+            context=context,
+            is_data_exist=is_data_exist,
+            exec_formatter=exec_formatter,
+            import_mode=ImportMode.CREATE_OR_UPDATE,
+            storage=storage,
+            minio=minio,
+            bucket_name=bucket_name,
+            url_expires=url_expires,
+            locale=locale,
+            sheet_name=sheet_name,
+        )
+
     def validate_model(self) -> Self:
         if self.import_mode not in ImportMode.__members__.values():
             raise ConfigError(msg(MessageKey.INVALID_IMPORT_MODE, import_mode=self.import_mode))
@@ -181,6 +300,8 @@ class ImporterConfig[ContextT, ImportCreateModelT: BaseModel, ImportUpdateModelT
             bucket_name=self.bucket_name,
             url_expires=self.url_expires,
         )
+        if self.storage_options.has_legacy_minio:
+            _warn_legacy_storage_path(has_explicit_storage=self.storage_options.has_explicit_storage)
 
 
 @dataclass(slots=True)
@@ -200,6 +321,50 @@ class ExporterConfig[ExportModelT: BaseModel]:
     behavior: ExportBehavior = field(init=False, repr=False)
     storage_options: StorageOptions = field(init=False, repr=False)
 
+    @classmethod
+    def for_model(
+        cls,
+        exporter_model: type[ExportModelT],
+        *,
+        data_converter: DataConverter | None = export_data_converter,
+        storage: ExcelStorage | None = None,
+        minio: Minio | None = None,
+        bucket_name: str = 'excel',
+        url_expires: int = 3600,
+        locale: str = 'zh-CN',
+        sheet_name: str = 'Sheet1',
+    ) -> Self:
+        """Build an exporter config through the recommended constructor."""
+        return cls(
+            exporter_model=exporter_model,
+            data_converter=data_converter,
+            storage=storage,
+            minio=minio,
+            bucket_name=bucket_name,
+            url_expires=url_expires,
+            locale=locale,
+            sheet_name=sheet_name,
+        )
+
+    @classmethod
+    def for_storage(
+        cls,
+        exporter_model: type[ExportModelT],
+        *,
+        storage: ExcelStorage,
+        data_converter: DataConverter | None = export_data_converter,
+        locale: str = 'zh-CN',
+        sheet_name: str = 'Sheet1',
+    ) -> Self:
+        """Build an exporter config for the recommended explicit-storage path."""
+        return cls.for_model(
+            exporter_model,
+            data_converter=data_converter,
+            storage=storage,
+            locale=locale,
+            sheet_name=sheet_name,
+        )
+
     def validate_model(self) -> Self:
         if not self.exporter_model:
             raise ValueError(msg(MessageKey.EXPORTER_MODEL_CANNOT_BE_EMPTY))
@@ -219,3 +384,26 @@ class ExporterConfig[ExportModelT: BaseModel]:
             bucket_name=self.bucket_name,
             url_expires=self.url_expires,
         )
+        if self.storage_options.has_legacy_minio:
+            _warn_legacy_storage_path(has_explicit_storage=self.storage_options.has_explicit_storage)
+
+
+def _warn_legacy_storage_path(*, has_explicit_storage: bool) -> None:
+    """Emit a deprecation warning for the legacy built-in Minio config path."""
+    if has_explicit_storage in _EMITTED_STORAGE_DEPRECATION_WARNINGS:
+        return
+    _EMITTED_STORAGE_DEPRECATION_WARNINGS.add(has_explicit_storage)
+
+    detail = (
+        ' The explicit `storage=` backend will be used.'
+        if has_explicit_storage
+        else ' Prefer passing `storage=` with `MinioStorageGateway` or a custom `ExcelStorage` implementation.'
+    )
+    warnings.warn(
+        (
+            '`minio`, `bucket_name`, and `url_expires` are deprecated configuration fields and will be removed in '
+            f'ExcelAlchemy {DEPRECATION_REMOVAL_VERSION}.{detail}'
+        ),
+        category=ExcelAlchemyDeprecationWarning,
+        stacklevel=3,
+    )

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/src/excelalchemy/core/alchemy.py

@@ -16,7 +16,7 @@ from excelalchemy.codecs.base import SystemReserved
 from excelalchemy.config import ExcelMode, ExporterConfig, ImporterConfig, ImportMode
 from excelalchemy.core.abstract import ABCExcelAlchemy
 from excelalchemy.core.headers import ExcelHeaderParser, ExcelHeaderValidator
-from excelalchemy.core.import_session import ImportSession, build_import_result_field_meta
+from excelalchemy.core.import_session import ImportSession, ImportSessionSnapshot, build_import_result_field_meta
 from excelalchemy.core.rendering import ExcelRenderer
 from excelalchemy.core.schema import ExcelSchemaLayout
 from excelalchemy.core.storage import build_storage_gateway
@@ -217,6 +217,12 @@ class ExcelAlchemy[
             return {}
         return self._last_import_session.row_errors
 
+    @property
+    def last_import_snapshot(self) -> ImportSessionSnapshot | None:
+        if self._last_import_session is None:
+            return None
+        return self._last_import_session.snapshot
+
     @property
     def input_excel_has_merged_header(self) -> bool:
         return self._require_last_import_session().input_excel_has_merged_header

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/src/excelalchemy/core/import_session.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass, replace
+from enum import StrEnum
 from functools import cached_property
 from typing import cast
 
@@ -30,6 +32,34 @@ from excelalchemy.results import ImportResult, ValidateHeaderResult, ValidateRes
 HEADER_HINT_LINE_COUNT = 1
 
 
+class ImportSessionPhase(StrEnum):
+    """High-level lifecycle phase for a one-shot import session."""
+
+    INITIALIZED = 'INITIALIZED'
+    WORKBOOK_LOADED = 'WORKBOOK_LOADED'
+    HEADERS_VALIDATED = 'HEADERS_VALIDATED'
+    ROWS_PREPARED = 'ROWS_PREPARED'
+    ROWS_EXECUTED = 'ROWS_EXECUTED'
+    RESULT_RENDERED = 'RESULT_RENDERED'
+    COMPLETED = 'COMPLETED'
+
+
+@dataclass(slots=True, frozen=True)
+class ImportSessionSnapshot:
+    """Immutable snapshot of the current session lifecycle state."""
+
+    phase: ImportSessionPhase = ImportSessionPhase.INITIALIZED
+    input_excel_name: str | None = None
+    output_excel_name: str | None = None
+    has_merged_header: bool | None = None
+    data_row_count: int = 0
+    processed_row_count: int = 0
+    success_count: int = 0
+    fail_count: int = 0
+    rendered_result_workbook: bool = False
+    result: ValidateResult | None = None
+
+
 class ImportSession[
     ContextT,
     ImportCreateModelT: BaseModel,
@@ -71,6 +101,7 @@ class ImportSession[
         self.issue_tracker = ImportIssueTracker(self.layout, self.import_result_field_meta)
         self.row_aggregator = RowAggregator(self.layout, self.behavior.import_mode)
         self.executor = ImportExecutor(self.config, self.issue_tracker, lambda: self.context)
+        self._snapshot = ImportSessionSnapshot()
 
     @property
     def cell_errors(self):
@@ -80,6 +111,10 @@ class ImportSession[
     def row_errors(self):
         return self.issue_tracker.row_errors
 
+    @property
+    def snapshot(self) -> ImportSessionSnapshot:
+        return self._snapshot
+
     @cached_property
     def input_excel_has_merged_header(self) -> bool:
         if not self._state_df_has_been_loaded:
@@ -101,42 +136,73 @@ class ImportSession[
 
     async def run(self, input_excel_name: str, output_excel_name: str) -> ImportResult:
         with use_display_locale(self.locale):
+            self._snapshot = replace(
+                self._snapshot,
+                phase=ImportSessionPhase.INITIALIZED,
+                input_excel_name=input_excel_name,
+                output_excel_name=output_excel_name,
+                rendered_result_workbook=False,
+                result=None,
+                data_row_count=0,
+                processed_row_count=0,
+                success_count=0,
+                fail_count=0,
+            )
+
             validate_header = self._validate_header(input_excel_name)
             if not validate_header.is_valid:
-                return ImportResult.from_validate_header_result(validate_header)
-
-            self.worksheet_table = self.worksheet_table.iloc[1:]
-            self._set_columns(self.worksheet_table)
-            self.worksheet_table = self.worksheet_table.reset_index(drop=True)
-
-            all_success, success_count, fail_count = True, 0, 0
-            for table_row_index in range(self.extra_header_count_on_import, len(self.worksheet_table)):
-                row = self.worksheet_table.row_at(table_row_index)
-                aggregate_data = self._aggregate_data(cast(FlatRowPayload, row.to_dict()))
-                success = await self.executor.execute(RowIndex(table_row_index), aggregate_data, self.worksheet_table)
-                all_success = all_success and success
-                success_count, fail_count = (
-                    (success_count + 1, fail_count) if success else (success_count, fail_count + 1)
+                header_result = ImportResult.from_validate_header_result(validate_header)
+                self._snapshot = replace(
+                    self._snapshot,
+                    phase=ImportSessionPhase.COMPLETED,
+                    has_merged_header=self.input_excel_has_merged_header,
+                    result=header_result.result,
                 )
+                return header_result
+
+            self._prepare_rows_for_execution()
+
+            all_success, success_count, fail_count = await self._execute_rows()
 
             url = None
             if not all_success:
                 self._add_result_column()
                 content_with_prefix = self._render_import_result_excel()
                 url = self._upload_file(output_excel_name, content_with_prefix)
+                self._snapshot = replace(
+                    self._snapshot,
+                    phase=ImportSessionPhase.RESULT_RENDERED,
+                    rendered_result_workbook=True,
+                )
 
-            return ImportResult(
+            import_result = ImportResult(
                 result=(ValidateResult.DATA_INVALID, ValidateResult.SUCCESS)[int(all_success)],
                 url=url,
                 success_count=success_count,
                 fail_count=fail_count,
             )
+            self._snapshot = replace(
+                self._snapshot,
+                phase=ImportSessionPhase.COMPLETED,
+                success_count=success_count,
+                fail_count=fail_count,
+                result=import_result.result,
+            )
+            return import_result
 
     def _validate_header(self, input_excel_name: str) -> ValidateHeaderResult:
-        self._read_dataframe(input_excel_name)
-        return self.header_validator.validate(self.input_excel_headers, self.layout, self.behavior.import_mode)
+        self._load_workbook(input_excel_name)
+        validate_header = self.header_validator.validate(
+            self.input_excel_headers, self.layout, self.behavior.import_mode
+        )
+        self._snapshot = replace(
+            self._snapshot,
+            phase=ImportSessionPhase.HEADERS_VALIDATED,
+            has_merged_header=self.input_excel_has_merged_header,
+        )
+        return validate_header
 
-    def _read_dataframe(self, input_excel_name: str) -> WorksheetTable:
+    def _load_workbook(self, input_excel_name: str) -> WorksheetTable:
         if not self._state_df_has_been_loaded:
             worksheet_table = self.storage_gateway.read_excel_table(
                 input_excel_name,
@@ -146,8 +212,39 @@ class ImportSession[
             self.worksheet_table = worksheet_table
             self.header_table = worksheet_table.head(2)
             self._state_df_has_been_loaded = True
+            self._snapshot = replace(self._snapshot, phase=ImportSessionPhase.WORKBOOK_LOADED)
         return self.worksheet_table
 
+    def _prepare_rows_for_execution(self) -> None:
+        self.worksheet_table = self.worksheet_table.iloc[1:]
+        self._set_columns(self.worksheet_table)
+        self.worksheet_table = self.worksheet_table.reset_index(drop=True)
+        self._snapshot = replace(
+            self._snapshot,
+            phase=ImportSessionPhase.ROWS_PREPARED,
+            data_row_count=max(0, len(self.worksheet_table) - self.extra_header_count_on_import),
+        )
+
+    async def _execute_rows(self) -> tuple[bool, int, int]:
+        all_success, success_count, fail_count = True, 0, 0
+        processed_row_count = 0
+        for table_row_index in range(self.extra_header_count_on_import, len(self.worksheet_table)):
+            row = self.worksheet_table.row_at(table_row_index)
+            aggregate_data = self._aggregate_data(cast(FlatRowPayload, row.to_dict()))
+            success = await self.executor.execute(RowIndex(table_row_index), aggregate_data, self.worksheet_table)
+            processed_row_count += 1
+            all_success = all_success and success
+            success_count, fail_count = (success_count + 1, fail_count) if success else (success_count, fail_count + 1)
+
+        self._snapshot = replace(
+            self._snapshot,
+            phase=ImportSessionPhase.ROWS_EXECUTED,
+            processed_row_count=processed_row_count,
+            success_count=success_count,
+            fail_count=fail_count,
+        )
+        return all_success, success_count, fail_count
+
     def _set_columns(self, worksheet_table: WorksheetTable) -> WorksheetTable:
         return self.header_parser.apply_columns(
             worksheet_table,

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/src/excelalchemy/helper/pydantic.py

@@ -1,7 +1,7 @@
 from collections.abc import Generator, Iterable, Mapping
 from dataclasses import dataclass
 from types import UnionType
-from typing import Any, Union, cast, get_args, get_origin
+from typing import Union, cast, get_args, get_origin
 
 from pydantic import BaseModel, ValidationError
 from pydantic.fields import FieldInfo
@@ -23,23 +23,23 @@ class PydanticFieldAdapter:
     raw_field: FieldInfo
 
     @property
-    def annotation(self) -> Any:
+    def annotation(self) -> object:
         return self.raw_field.annotation
 
     @property
-    def excel_codec(self) -> type[Any]:
+    def excel_codec(self) -> type[ExcelFieldCodec]:
         annotation = self.annotation
         origin = get_origin(annotation)
         if origin in (UnionType, Union):
             args = [arg for arg in get_args(annotation) if arg is not type(None)]
             if len(args) != 1:
                 raise ProgrammaticError(msg(MessageKey.UNSUPPORTED_FIELD_TYPE_DECLARATION, annotation=annotation))
-            return cast(type[Any], args[0])
+            return cast(type[ExcelFieldCodec], args[0])
 
-        return cast(type[Any], annotation)
+        return cast(type[ExcelFieldCodec], annotation)
 
     @property
-    def value_type(self) -> type[Any]:
+    def value_type(self) -> type[ExcelFieldCodec]:
         """Backward-compatible alias for excel_codec."""
         return self.excel_codec
 
@@ -67,14 +67,14 @@ class PydanticFieldAdapter:
         declared = self.declared_metadata
         return declared.bind_runtime(
             required=self.required,
-            excel_codec=cast(type[ExcelFieldCodec], self.excel_codec),
+            excel_codec=self.excel_codec,
             parent_label=declared.label,
             parent_key=Key(self.name),
             key=Key(self.name),
             offset=0,
         )
 
-    def validate_value(self, raw_value: Any) -> Any:
+    def validate_value(self, raw_value: object) -> object:
         if raw_value is None:
             if self.allows_none and not self.required:
                 return None
@@ -116,12 +116,12 @@ def get_model_field_names(model: type[BaseModel]) -> list[str]:
 
 
 def instantiate_pydantic_model[ModelT: BaseModel](
-    data: Mapping[str, Any],
+    data: Mapping[str, object],
     model: type[ModelT],
 ) -> ModelT | list[ExcelCellError | ExcelRowError]:
     """Instantiate a Pydantic model and return mapped Excel errors when validation fails."""
     model_adapter = PydanticModelAdapter(model)
-    normalized_data: dict[str, Any] = {}
+    normalized_data: dict[str, object] = {}
     errors: list[ExcelCellError | ExcelRowError] = []
     failed_fields: set[str] = set()
 
@@ -158,18 +158,14 @@ def _extract_pydantic_model(model: PydanticModelAdapter) -> Generator[FieldMetaI
                 inherited = sub_field_info.inherited_from(declared_metadata)
                 yield inherited.bind_runtime(
                     required=field_adapter.required,
-                    excel_codec=cast(type[ExcelFieldCodec], excel_codec),
+                    excel_codec=excel_codec,
                     parent_label=declared_metadata.label,
                     parent_key=Key(field_adapter.name),
                     key=key,
                     offset=offset,
                 )
-
-        elif issubclass(excel_codec, ExcelFieldCodec):
-            yield field_adapter.runtime_metadata()
-
         else:
-            raise ProgrammaticError(msg(MessageKey.VALUE_TYPE_DECLARATION_UNSUPPORTED, value_type=excel_codec))
+            yield field_adapter.runtime_metadata()
 
 
 def _handle_error(
@@ -188,7 +184,7 @@ def _handle_error(
 
 
 def _model_validate[ModelT: BaseModel](
-    data: dict[str, Any],
+    data: dict[str, object],
     model: type[ModelT],
     model_adapter: PydanticModelAdapter,
     failed_fields: set[str],

{excelalchemy-2.1.0 → excelalchemy-2.2.2}/src/excelalchemy/metadata.py

@@ -4,7 +4,7 @@ import copy
 import datetime
 import logging
 from collections.abc import Callable, Mapping, Set
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from functools import cached_property
 from typing import Any, Self, cast
 
@@ -37,6 +37,16 @@ type FieldDefaultFactory = Callable[[], object]
 type FieldIncludeExclude = Set[IntStr] | bool | None
 
 
+def _normalize_character_set(character_set: set[CharacterSet] | None) -> frozenset[CharacterSet]:
+    return frozenset(character_set or set(CharacterSet))
+
+
+def _normalize_options(options: list[Option] | tuple[Option, ...] | None) -> tuple[Option, ...] | None:
+    if options is None:
+        return None
+    return tuple(options)
+
+
 class PatchFieldMeta(BaseModel):
     unique: bool | None = False  # Workbook hint only. Runtime uniqueness is enforced elsewhere.
     is_primary_key: bool | None = False  # Workbook hint only. Runtime primary-key behavior is configured separately.
@@ -44,7 +54,7 @@ class PatchFieldMeta(BaseModel):
     options: list[Option] | None = None
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class DeclaredFieldMeta:
     """Static workbook field declaration supplied by user code."""
 
@@ -56,7 +66,7 @@ class DeclaredFieldMeta:
     order: int
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class RuntimeFieldBinding:
     """Runtime identity assigned after schema extraction flattens the model."""
 
@@ -67,21 +77,21 @@ class RuntimeFieldBinding:
     excel_codec: type[ExcelFieldCodec] = UndefinedFieldCodec
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class WorkbookPresentationMeta:
     """Workbook-facing comment and formatting metadata."""
 
-    character_set: set[CharacterSet] = field(default_factory=lambda: set(CharacterSet))
+    character_set: frozenset[CharacterSet] = field(default_factory=lambda: frozenset(CharacterSet))
     fraction_digits: int | None = None
     timezone: datetime.timezone = field(default_factory=lambda: datetime.timezone(datetime.timedelta(hours=8), 'CST'))
     date_format: DateFormat | None = None
     date_range_option: DataRangeOption | None = None
-    options: list[Option] | None = None
+    options: tuple[Option, ...] | None = None
     unit: str | None = None
     hint: str | None = None
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class ImportConstraints:
     """Importer-side validation hints mirrored from Pydantic constraints."""
 
@@ -136,12 +146,12 @@ class FieldMetaInfo:
         )
         self.runtime_binding = RuntimeFieldBinding()
         self.presentation_meta = WorkbookPresentationMeta(
-            character_set=character_set or set(CharacterSet),
+            character_set=_normalize_character_set(character_set),
             fraction_digits=fraction_digits,
             timezone=timezone or datetime.timezone(datetime.timedelta(hours=8), 'CST'),
             date_format=date_format,
             date_range_option=date_range_option,
-            options=options,
+            options=_normalize_options(options),
             unit=unit,
             hint=hint,
         )
@@ -196,7 +206,7 @@ class FieldMetaInfo:
 
     @excel_codec.setter
     def excel_codec(self, value: type[ExcelFieldCodec]) -> None:
-        self.runtime_binding.excel_codec = value
+        self.runtime_binding = replace(self.runtime_binding, excel_codec=value)
 
     @property
     def value_type(self) -> type[ExcelFieldCodec]:
@@ -383,7 +393,7 @@ class FieldMetaInfo:
 
     @label.setter
     def label(self, value: str | Label) -> None:
-        self.declared_meta.label = Label(value)
+        self.declared_meta = replace(self.declared_meta, label=Label(value))
 
     @property
     def is_primary_key(self) -> bool:
@@ -391,7 +401,7 @@ class FieldMetaInfo:
 
     @is_primary_key.setter
     def is_primary_key(self, value: bool) -> None:
-        self.declared_meta.is_primary_key = value
+        self.declared_meta = replace(self.declared_meta, is_primary_key=value)
 
     @property
     def unique(self) -> bool:
@@ -399,7 +409,7 @@ class FieldMetaInfo:
 
     @unique.setter
     def unique(self, value: bool) -> None:
-        self.declared_meta.unique = value
+        self.declared_meta = replace(self.declared_meta, unique=value)
 
     @property
     def ignore_import(self) -> bool:
@@ -407,7 +417,7 @@ class FieldMetaInfo:
 
     @ignore_import.setter
     def ignore_import(self, value: bool) -> None:
-        self.declared_meta.ignore_import = value
+        self.declared_meta = replace(self.declared_meta, ignore_import=value)
 
     @property
     def required(self) -> bool | None:
@@ -415,7 +425,7 @@ class FieldMetaInfo:
 
     @required.setter
     def required(self, value: bool | None) -> None:
-        self.declared_meta.required = value
+        self.declared_meta = replace(self.declared_meta, required=value)
 
     @property
     def order(self) -> int:
@@ -423,7 +433,7 @@ class FieldMetaInfo:
 
     @order.setter
     def order(self, value: int) -> None:
-        self.declared_meta.order = value
+        self.declared_meta = replace(self.declared_meta, order=value)
 
     @property
     def parent_label(self) -> Label | None:
@@ -431,7 +441,7 @@ class FieldMetaInfo:
 
     @parent_label.setter
     def parent_label(self, value: Label | None) -> None:
-        self.runtime_binding.parent_label = value
+        self.runtime_binding = replace(self.runtime_binding, parent_label=value)
 
     @property
     def key(self) -> Key | None:
@@ -439,7 +449,7 @@ class FieldMetaInfo:
 
     @key.setter
     def key(self, value: Key | None) -> None:
-        self.runtime_binding.key = value
+        self.runtime_binding = replace(self.runtime_binding, key=value)
 
     @property
     def parent_key(self) -> Key | None:
@@ -447,7 +457,7 @@ class FieldMetaInfo:
 
     @parent_key.setter
     def parent_key(self, value: Key | None) -> None:
-        self.runtime_binding.parent_key = value
+        self.runtime_binding = replace(self.runtime_binding, parent_key=value)
 
     @property
     def offset(self) -> int:
@@ -455,15 +465,15 @@ class FieldMetaInfo:
 
     @offset.setter
     def offset(self, value: int) -> None:
-        self.runtime_binding.offset = value
+        self.runtime_binding = replace(self.runtime_binding, offset=value)
 
     @property
     def character_set(self) -> set[CharacterSet]:
-        return self.presentation_meta.character_set
+        return set(self.presentation_meta.character_set)
 
     @character_set.setter
     def character_set(self, value: set[CharacterSet]) -> None:
-        self.presentation_meta.character_set = value
+        self.presentation_meta = replace(self.presentation_meta, character_set=_normalize_character_set(value))
 
     @property
     def fraction_digits(self) -> int | None:
@@ -471,7 +481,7 @@ class FieldMetaInfo:
 
     @fraction_digits.setter
     def fraction_digits(self, value: int | None) -> None:
-        self.presentation_meta.fraction_digits = value
+        self.presentation_meta = replace(self.presentation_meta, fraction_digits=value)
 
     @property
     def timezone(self) -> datetime.timezone:
@@ -479,7 +489,7 @@ class FieldMetaInfo:
 
     @timezone.setter
     def timezone(self, value: datetime.timezone) -> None:
-        self.presentation_meta.timezone = value
+        self.presentation_meta = replace(self.presentation_meta, timezone=value)
 
     @property
     def date_format(self) -> DateFormat | None:
@@ -487,7 +497,7 @@ class FieldMetaInfo:
 
     @date_format.setter
     def date_format(self, value: DateFormat | None) -> None:
-        self.presentation_meta.date_format = value
+        self.presentation_meta = replace(self.presentation_meta, date_format=value)
 
     @property
     def date_range_option(self) -> DataRangeOption | None:
@@ -495,15 +505,17 @@ class FieldMetaInfo:
 
     @date_range_option.setter
     def date_range_option(self, value: DataRangeOption | None) -> None:
-        self.presentation_meta.date_range_option = value
+        self.presentation_meta = replace(self.presentation_meta, date_range_option=value)
 
     @property
     def options(self) -> list[Option] | None:
-        return self.presentation_meta.options
+        if self.presentation_meta.options is None:
+            return None
+        return list(self.presentation_meta.options)
 
     @options.setter
     def options(self, value: list[Option] | None) -> None:
-        self.presentation_meta.options = value
+        self.presentation_meta = replace(self.presentation_meta, options=_normalize_options(value))
 
     @property
     def unit(self) -> str | None:
@@ -511,7 +523,7 @@ class FieldMetaInfo:
 
     @unit.setter
     def unit(self, value: str | None) -> None:
-        self.presentation_meta.unit = value
+        self.presentation_meta = replace(self.presentation_meta, unit=value)
 
     @property
     def hint(self) -> str | None:
@@ -519,7 +531,7 @@ class FieldMetaInfo:
 
     @hint.setter
     def hint(self, value: str | None) -> None:
-        self.presentation_meta.hint = value
+        self.presentation_meta = replace(self.presentation_meta, hint=value)
 
     @property
     def importer_ge(self) -> float | None:
@@ -527,7 +539,7 @@ class FieldMetaInfo:
 
     @importer_ge.setter
     def importer_ge(self, value: float | None) -> None:
-        self.import_constraints.ge = value
+        self.import_constraints = replace(self.import_constraints, ge=value)
 
     @property
     def importer_le(self) -> float | None:
@@ -535,7 +547,7 @@ class FieldMetaInfo:
 
     @importer_le.setter
     def importer_le(self, value: float | None) -> None:
-        self.import_constraints.le = value
+        self.import_constraints = replace(self.import_constraints, le=value)
 
     @property
     def importer_max_digits(self) -> int | None:
@@ -543,7 +555,7 @@ class FieldMetaInfo:
 
     @importer_max_digits.setter
     def importer_max_digits(self, value: int | None) -> None:
-        self.import_constraints.max_digits = value
+        self.import_constraints = replace(self.import_constraints, max_digits=value)
 
     @property
     def importer_decimal_places(self) -> int | None:
@@ -551,7 +563,7 @@ class FieldMetaInfo:
 
     @importer_decimal_places.setter
     def importer_decimal_places(self, value: int | None) -> None:
-        self.import_constraints.decimal_places = value
+        self.import_constraints = replace(self.import_constraints, decimal_places=value)
 
     @property
     def importer_min_length(self) -> int | None:
@@ -559,7 +571,7 @@ class FieldMetaInfo:
 
     @importer_min_length.setter
     def importer_min_length(self, value: int | None) -> None:
-        self.import_constraints.min_length = value
+        self.import_constraints = replace(self.import_constraints, min_length=value)
 
     @property
     def importer_max_length(self) -> int | None:
@@ -567,7 +579,7 @@ class FieldMetaInfo:
 
     @importer_max_length.setter
     def importer_max_length(self, value: int | None) -> None:
-        self.import_constraints.max_length = value
+        self.import_constraints = replace(self.import_constraints, max_length=value)
 
     @property
     def importer_min_items(self) -> int | None:
@@ -575,7 +587,7 @@ class FieldMetaInfo:
 
     @importer_min_items.setter
     def importer_min_items(self, value: int | None) -> None:
-        self.import_constraints.min_items = value
+        self.import_constraints = replace(self.import_constraints, min_items=value)
 
     @property
     def importer_max_items(self) -> int | None:
@@ -583,7 +595,7 @@ class FieldMetaInfo:
 
     @importer_max_items.setter
     def importer_max_items(self, value: int | None) -> None:
-        self.import_constraints.max_items = value
+        self.import_constraints = replace(self.import_constraints, max_items=value)
 
     @property
     def importer_unique_items(self) -> bool | None:
@@ -591,7 +603,7 @@ class FieldMetaInfo:
 
     @importer_unique_items.setter
     def importer_unique_items(self, value: bool | None) -> None:
-        self.import_constraints.unique_items = value
+        self.import_constraints = replace(self.import_constraints, unique_items=value)
 
 
 def extract_declared_field_metadata(field_info: FieldInfo) -> FieldMetaInfo: