ExcelAlchemy 2.2.3__tar.gz → 2.2.5__tar.gz

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.3
+Version: 2.2.5
 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
@@ -49,7 +49,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+The current stable release is `2.2.5`, which continues the 2.x line with richer import-failure feedback, clearer documentation entry points, stronger examples, and stronger smoke coverage.
+
+[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
 
 ## Screenshots
 
@@ -114,6 +116,45 @@ alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
 template = alchemy.download_template_artifact(filename='people-template.xlsx')
 ```
 
+## Example Outputs
+
+These fixed outputs are generated from the repository examples by
+[`scripts/generate_example_output_assets.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/scripts/generate_example_output_assets.py).
+
+Import workflow:
+
+```text
+Employee import workflow completed
+Result: SUCCESS
+Success rows: 1
+Failed rows: 0
+Result workbook URL: None
+Created rows: 1
+Uploaded artifacts: []
+```
+
+Export workflow:
+
+```text
+Export workflow completed
+Artifact filename: employees-export.xlsx
+Artifact bytes: 6893
+Upload URL: memory://employees-export-upload.xlsx
+Uploaded objects: ['employees-export-upload.xlsx']
+```
+
+Full captured outputs:
+
+- [employee-import-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/employee-import-workflow.txt)
+- [create-or-update-import.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/create-or-update-import.txt)
+- [export-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/export-workflow.txt)
+- [date-and-range-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/date-and-range-fields.txt)
+- [selection-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
+
+For a single GitHub page that combines screenshots, representative workflows,
+and captured outputs, see the
+[Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md).
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/README-pypi.md

@@ -10,7 +10,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+The current stable release is `2.2.5`, which continues the 2.x line with richer import-failure feedback, clearer documentation entry points, stronger examples, and stronger smoke coverage.
+
+[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
 
 ## Screenshots
 
@@ -75,6 +77,45 @@ alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
 template = alchemy.download_template_artifact(filename='people-template.xlsx')
 ```
 
+## Example Outputs
+
+These fixed outputs are generated from the repository examples by
+[`scripts/generate_example_output_assets.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/scripts/generate_example_output_assets.py).
+
+Import workflow:
+
+```text
+Employee import workflow completed
+Result: SUCCESS
+Success rows: 1
+Failed rows: 0
+Result workbook URL: None
+Created rows: 1
+Uploaded artifacts: []
+```
+
+Export workflow:
+
+```text
+Export workflow completed
+Artifact filename: employees-export.xlsx
+Artifact bytes: 6893
+Upload URL: memory://employees-export-upload.xlsx
+Uploaded objects: ['employees-export-upload.xlsx']
+```
+
+Full captured outputs:
+
+- [employee-import-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/employee-import-workflow.txt)
+- [create-or-update-import.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/create-or-update-import.txt)
+- [export-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/export-workflow.txt)
+- [date-and-range-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/date-and-range-fields.txt)
+- [selection-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
+
+For a single GitHub page that combines screenshots, representative workflows,
+and captured outputs, see the
+[Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md).
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.3'
+__version__ = '2.2.5'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (
@@ -48,13 +48,21 @@ from excelalchemy.core.storage_protocol import ExcelStorage
 from excelalchemy.exceptions import ConfigError, ExcelCellError, ExcelRowError, ProgrammaticError
 from excelalchemy.helper.pydantic import extract_pydantic_model
 from excelalchemy.metadata import ExcelMeta, FieldMeta, PatchFieldMeta
-from excelalchemy.results import ImportResult, ValidateHeaderResult, ValidateResult, ValidateRowResult
+from excelalchemy.results import (
+    CellErrorMap,
+    ImportResult,
+    RowIssueMap,
+    ValidateHeaderResult,
+    ValidateResult,
+    ValidateRowResult,
+)
 from excelalchemy.util.file import flatten
 
 __all__ = [
     'Base64Str',
     'Boolean',
     'BooleanCodec',
+    'CellErrorMap',
     'ColumnIndex',
     'CompositeExcelFieldCodec',
     'ConfigError',
@@ -104,6 +112,7 @@ __all__ = [
     'ProgrammaticError',
     'Radio',
     'RowIndex',
+    'RowIssueMap',
     'SingleChoiceCodec',
     'SingleOrganization',
     'SingleOrganizationCodec',

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/_primitives/constants.py

@@ -1,6 +1,5 @@
 from dataclasses import dataclass
 from enum import StrEnum
-from typing import Any
 
 from excelalchemy._primitives.identity import Key, Label, OptionId
 from excelalchemy.i18n.messages import MessageKey
@@ -38,8 +37,6 @@ MILLISECOND_TO_SECOND = 1000
 MAX_OPTIONS_COUNT = 100
 
 DEFAULT_FIELD_META_ORDER = -1
-type DictStrAny = dict[str, Any]
-type DictAny = dict[Any, Any]
 type SetStr = set[str]
 type ListStr = list[str]
 type IntStr = int | str

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/_primitives/identity.py

@@ -1,7 +1,5 @@
 """Internal typed primitives used across the ExcelAlchemy core layer."""
 
-from typing import Any
-
 from pydantic import GetCoreSchemaHandler
 from pydantic_core import core_schema
 
@@ -10,7 +8,7 @@ class _StringIdentity(str):
     @classmethod
     def __get_pydantic_core_schema__(
         cls,
-        source_type: Any,
+        source_type: object,
         handler: GetCoreSchemaHandler,
     ) -> core_schema.CoreSchema:
         return core_schema.no_info_after_validator_function(cls, core_schema.str_schema())
@@ -20,7 +18,7 @@ class _IntegerIdentity(int):
     @classmethod
     def __get_pydantic_core_schema__(
         cls,
-        source_type: Any,
+        source_type: object,
         handler: GetCoreSchemaHandler,
     ) -> core_schema.CoreSchema:
         return core_schema.no_info_after_validator_function(cls, core_schema.int_schema())

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/codecs/base.py

@@ -11,6 +11,13 @@ from excelalchemy._primitives.identity import Key
 if TYPE_CHECKING:
     from excelalchemy.metadata import FieldMetaInfo
 
+# These aliases remain `Any` intentionally because codec subclasses narrow their
+# accepted workbook values heavily. Using `object` here makes every override
+# incompatible under pyright's method override rules.
+type WorkbookInputValue = Any
+type WorkbookDisplayValue = Any
+type NormalizedImportValue = Any
+
 
 class ExcelFieldCodec(ABC):
     """Excel-facing field adapter responsible for comments, parsing, formatting, and normalization."""
@@ -22,17 +29,17 @@ class ExcelFieldCodec(ABC):
 
     @classmethod
     @abstractmethod
-    def parse_input(cls, value: Any, field_meta: FieldMetaInfo) -> Any:  # value is always not None
+    def parse_input(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> WorkbookInputValue:
         """Parse workbook input into the intermediate Python value consumed by the import pipeline."""
 
     @classmethod
     @abstractmethod
-    def format_display_value(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def format_display_value(cls, value: WorkbookDisplayValue, field_meta: FieldMetaInfo) -> WorkbookDisplayValue:
         """Format a raw worksheet value back into a user-recognizable display value."""
 
     @classmethod
     @abstractmethod
-    def normalize_import_value(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def normalize_import_value(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> NormalizedImportValue:
         """Validate and normalize parsed input before handing it to the Pydantic layer."""
 
     @classmethod
@@ -41,24 +48,24 @@ class ExcelFieldCodec(ABC):
         return cls.build_comment(field_meta)
 
     @classmethod
-    def serialize(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def serialize(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> WorkbookInputValue:
         """Backward-compatible alias for parse_input()."""
         return cls.parse_input(value, field_meta)
 
     @classmethod
-    def deserialize(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def deserialize(cls, value: WorkbookDisplayValue, field_meta: FieldMetaInfo) -> WorkbookDisplayValue:
         """Backward-compatible alias for format_display_value()."""
         return cls.format_display_value(value, field_meta)
 
     @classmethod
-    def __validate__(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def __validate__(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> NormalizedImportValue:
         """Backward-compatible alias for normalize_import_value()."""
         return cls.normalize_import_value(value, field_meta)
 
     @classmethod
     def __get_pydantic_core_schema__(
         cls,
-        source_type: Any,
+        source_type: object,
         handler: GetCoreSchemaHandler,
     ) -> core_schema.CoreSchema:
         # ExcelAlchemy runs metadata-aware validation in its adapter layer.
@@ -88,15 +95,23 @@ class SystemReserved(ExcelFieldCodec):
         return ''
 
     @classmethod
-    def parse_input(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def parse_input(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> WorkbookInputValue:
         return value
 
     @classmethod
-    def format_display_value(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def format_display_value(
+        cls,
+        value: WorkbookDisplayValue,
+        field_meta: FieldMetaInfo,
+    ) -> WorkbookDisplayValue:
         return value
 
     @classmethod
-    def normalize_import_value(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def normalize_import_value(
+        cls,
+        value: WorkbookInputValue,
+        field_meta: FieldMetaInfo,
+    ) -> NormalizedImportValue:
         return value
 
 
@@ -108,15 +123,23 @@ class Undefined(ExcelFieldCodec):
         return ''
 
     @classmethod
-    def parse_input(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def parse_input(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> WorkbookInputValue:
         return value
 
     @classmethod
-    def format_display_value(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def format_display_value(
+        cls,
+        value: WorkbookDisplayValue,
+        field_meta: FieldMetaInfo,
+    ) -> WorkbookDisplayValue:
         return value
 
     @classmethod
-    def normalize_import_value(cls, value: Any, field_meta: FieldMetaInfo) -> Any:
+    def normalize_import_value(
+        cls,
+        value: WorkbookInputValue,
+        field_meta: FieldMetaInfo,
+    ) -> NormalizedImportValue:
         return value
 
 

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/codecs/boolean.py

@@ -1,8 +1,7 @@
 import logging
-from typing import Any
 
 from excelalchemy.codecs import excel_choice_codec
-from excelalchemy.codecs.base import ExcelFieldCodec
+from excelalchemy.codecs.base import ExcelFieldCodec, WorkbookDisplayValue, WorkbookInputValue
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
@@ -31,19 +30,26 @@ class Boolean(ExcelFieldCodec):
 
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
+        declared = field_meta.declared
+        presentation = field_meta.presentation
         return '\n'.join(
             [
-                field_meta.comment_required,
-                field_meta.comment_hint,
+                declared.comment_required,
+                presentation.comment_hint,
             ]
         )
 
     @classmethod
-    def parse_input(cls, value: Any, field_meta: FieldMetaInfo) -> str:
+    def parse_input(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> str:
         return str(value).strip()
 
     @classmethod
-    def format_display_value(cls, value: bool | str | None | Any, field_meta: FieldMetaInfo) -> str:
+    def format_display_value(
+        cls,
+        value: bool | str | WorkbookDisplayValue | None,
+        field_meta: FieldMetaInfo,
+    ) -> str:
+        declared = field_meta.declared
         if value is None or value == '':
             return cls._false_display()
 
@@ -64,14 +70,14 @@ class Boolean(ExcelFieldCodec):
                 'Type %s could not deserialize %s for field %s; returning the default value %s',
                 cls.__name__,
                 value,
-                field_meta.label,
+                declared.label,
                 cls._false_display(),
             )
 
         return cls._true_display() if str(value) in cls._true_values() else cls._false_display()
 
     @classmethod
-    def normalize_import_value(cls, value: str | bool | Any, field_meta: FieldMetaInfo) -> bool:
+    def normalize_import_value(cls, value: str | bool | WorkbookInputValue, field_meta: FieldMetaInfo) -> bool:
         if isinstance(value, bool):
             return value
 

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/codecs/date.py

@@ -1,12 +1,17 @@
 import logging
 from datetime import datetime
-from typing import Any, cast
+from typing import cast
 
 import pendulum
 from pendulum import DateTime
 
 from excelalchemy._primitives.constants import DATE_FORMAT_TO_HINT_MAPPING, MILLISECOND_TO_SECOND, DataRangeOption
-from excelalchemy.codecs.base import ExcelFieldCodec
+from excelalchemy.codecs.base import (
+    ExcelFieldCodec,
+    NormalizedImportValue,
+    WorkbookDisplayValue,
+    WorkbookInputValue,
+)
 from excelalchemy.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import message as msg
@@ -18,36 +23,44 @@ class Date(ExcelFieldCodec, datetime):
 
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
-        if not field_meta.date_format:
+        declared = field_meta.declared
+        presentation = field_meta.presentation
+        if not presentation.date_format:
             raise ConfigError(msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED))
         return '\n'.join(
             [
-                field_meta.comment_required,
-                field_meta.comment_date_format,
-                field_meta.comment_date_range_option,
-                field_meta.comment_hint,
+                declared.comment_required,
+                presentation.comment_date_format,
+                presentation.comment_date_range_option,
+                presentation.comment_hint,
             ]
         )
 
     @classmethod
-    def parse_input(cls, value: str | DateTime | Any, field_meta: FieldMetaInfo) -> datetime | Any:
+    def parse_input(
+        cls,
+        value: str | DateTime | WorkbookInputValue,
+        field_meta: FieldMetaInfo,
+    ) -> datetime | WorkbookInputValue:
+        declared = field_meta.declared
+        presentation = field_meta.presentation
         if isinstance(value, DateTime):
             logging.info(
                 'Codec %s received a parsed datetime for %s; returning it unchanged: %s',
                 cls.__name__,
-                field_meta.label,
+                declared.label,
                 value,
             )
             return value
 
-        if not field_meta.date_format:
+        if not presentation.date_format:
             raise ConfigError(msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED))
 
         value = str(value).strip()
         try:
             v = value.replace('/', '-')  # pendulum does not accept "/" as a date separator here.
             dt: DateTime = cast(DateTime, pendulum.parse(v))
-            return dt.replace(tzinfo=field_meta.timezone)
+            return dt.replace(tzinfo=presentation.timezone)
         except Exception as exc:
             logging.warning(
                 'ValueType <%s> could not parse Excel input %s; returning the original value. Reason: %s',
@@ -58,27 +71,33 @@ class Date(ExcelFieldCodec, datetime):
             return value
 
     @classmethod
-    def format_display_value(cls, value: str | datetime | None | Any, field_meta: FieldMetaInfo) -> str:
+    def format_display_value(
+        cls,
+        value: str | datetime | WorkbookDisplayValue | None,
+        field_meta: FieldMetaInfo,
+    ) -> str:
+        presentation = field_meta.presentation
         match value:
             case None | '':
                 return ''
             case datetime():
-                return value.strftime(field_meta.python_date_format)
+                return value.strftime(presentation.python_date_format)
             case int() | float():
                 return datetime.fromtimestamp(int(value) / MILLISECOND_TO_SECOND).strftime(
-                    field_meta.python_date_format
+                    presentation.python_date_format
                 )
             case _:
                 return str(value) if value is not None else ''
 
     @classmethod
-    def normalize_import_value(cls, value: Any, field_meta: FieldMetaInfo) -> int:
-        if field_meta.date_format is None:
+    def normalize_import_value(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> NormalizedImportValue:
+        presentation = field_meta.presentation
+        if presentation.date_format is None:
             raise ConfigError(msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED))
 
         if not isinstance(value, datetime):
             raise ValueError(
-                msg(MessageKey.ENTER_DATE_FORMAT, date_format=DATE_FORMAT_TO_HINT_MAPPING[field_meta.date_format])
+                msg(MessageKey.ENTER_DATE_FORMAT, date_format=DATE_FORMAT_TO_HINT_MAPPING[presentation.date_format])
             )
 
         parsed = cls._parse_date(value, field_meta)
@@ -91,17 +110,19 @@ class Date(ExcelFieldCodec, datetime):
 
     @staticmethod
     def _parse_date(v: datetime, field_meta: FieldMetaInfo) -> datetime:
-        format_ = field_meta.python_date_format
+        presentation = field_meta.presentation
+        format_ = presentation.python_date_format
         parsed = datetime.strptime(v.strftime(format_), format_)
-        parsed = parsed.replace(tzinfo=field_meta.timezone)
+        parsed = parsed.replace(tzinfo=presentation.timezone)
         return parsed
 
     @staticmethod
     def _validate_date_range(parsed: datetime, field_meta: FieldMetaInfo) -> list[str]:
-        now = datetime.now(tz=field_meta.timezone)
+        presentation = field_meta.presentation
+        now = datetime.now(tz=presentation.timezone)
         errors: list[str] = []
 
-        match field_meta.date_range_option:
+        match presentation.date_range_option:
             case DataRangeOption.PRE:
                 if parsed > now:
                     errors.append(msg(MessageKey.DATE_MUST_BE_EARLIER_THAN_NOW))

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/codecs/date_range.py

@@ -1,7 +1,7 @@
 import logging
 from collections.abc import Mapping
 from datetime import datetime
-from typing import Any, cast
+from typing import cast
 
 import pendulum
 from pendulum import DateTime
@@ -10,6 +10,7 @@ from pydantic import BaseModel
 from excelalchemy._primitives.constants import DATE_FORMAT_TO_PYTHON_MAPPING, MILLISECOND_TO_SECOND, DataRangeOption
 from excelalchemy._primitives.identity import Key
 from excelalchemy.codecs.base import CompositeExcelFieldCodec
+from excelalchemy.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
@@ -28,7 +29,7 @@ class DateRange(CompositeExcelFieldCodec):
     __name__ = 'DateRange'
 
     @classmethod
-    def model_validate(cls, obj: Any) -> 'DateRange':
+    def model_validate(cls, obj: object) -> 'DateRange':
         impl = _DateRangeImpl.model_validate(obj)
         self = cls(impl.start, impl.end)
         return self
@@ -50,14 +51,18 @@ class DateRange(CompositeExcelFieldCodec):
 
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
-        if field_meta.date_format is None:
-            raise RuntimeError(msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED))
+        declared = field_meta.declared
+        presentation = field_meta.presentation
+        if presentation.date_format is None:
+            raise ConfigError(
+                msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED), message_key=MessageKey.DATE_FORMAT_NOT_CONFIGURED
+            )
 
         return '\n'.join(
             [
-                field_meta.comment_required,
-                field_meta.comment_date_format,
-                dmsg(MessageKey.COMMENT_DATE_RANGE_START_NOT_AFTER_END, extra_hint=field_meta.hint or ''),
+                declared.comment_required,
+                presentation.comment_date_format,
+                dmsg(MessageKey.COMMENT_DATE_RANGE_START_NOT_AFTER_END, extra_hint=presentation.hint or ''),
             ]
         )
 
@@ -92,20 +97,21 @@ class DateRange(CompositeExcelFieldCodec):
         value: object,
         field_meta: FieldMetaInfo,
     ) -> 'DateRange':
+        presentation = field_meta.presentation
         try:
             parsed = DateRange.model_validate(value)
-            parsed.start = pendulum.instance(parsed.start, tz=field_meta.timezone) if parsed.start else None
-            parsed.end = pendulum.instance(parsed.end, tz=field_meta.timezone) if parsed.end else None
+            parsed.start = pendulum.instance(parsed.start, tz=presentation.timezone) if parsed.start else None
+            parsed.end = pendulum.instance(parsed.end, tz=presentation.timezone) if parsed.end else None
         except Exception as exc:
             raise ValueError(msg(MessageKey.INVALID_INPUT)) from exc
 
         errors: list[str] = []
-        now = datetime.now(tz=field_meta.timezone)
+        now = datetime.now(tz=presentation.timezone)
 
         if parsed.start and parsed.end and parsed.start > parsed.end:
             errors.append(msg(MessageKey.DATE_RANGE_START_AFTER_END))
 
-        match field_meta.date_range_option:
+        match presentation.date_range_option:
             case DataRangeOption.PRE:
                 if (parsed.start and parsed.start > now) or (parsed.end and parsed.end > now):
                     errors.append(msg(MessageKey.DATE_MUST_BE_EARLIER_THAN_NOW))
@@ -124,7 +130,8 @@ class DateRange(CompositeExcelFieldCodec):
     def format_display_value(cls, value: object | None, field_meta: FieldMetaInfo) -> str:
         if value is None or value == '':
             return ''
-        date_format = field_meta.must_date_format
+        presentation = field_meta.presentation
+        date_format = presentation.must_date_format
         py_date_format = DATE_FORMAT_TO_PYTHON_MAPPING[date_format]
 
         if isinstance(value, str):
@@ -178,11 +185,12 @@ class DateRange(CompositeExcelFieldCodec):
 
     @staticmethod
     def _parse_datetime_text(value: str, field_meta: FieldMetaInfo) -> DateTime:
+        presentation = field_meta.presentation
         parsed = pendulum.parse(value)
         if isinstance(parsed, DateTime):
-            return parsed.replace(tzinfo=field_meta.timezone)
+            return parsed.replace(tzinfo=presentation.timezone)
         if isinstance(parsed, datetime):
-            return pendulum.instance(parsed).replace(tzinfo=field_meta.timezone)
+            return pendulum.instance(parsed).replace(tzinfo=presentation.timezone)
         raise ValueError(msg(MessageKey.INVALID_INPUT))
 
 

{excelalchemy-2.2.3 → excelalchemy-2.2.5}/src/excelalchemy/codecs/money.py

@@ -1,5 +1,7 @@
-from typing import Any, ClassVar
+from dataclasses import replace
+from typing import ClassVar
 
+from excelalchemy.codecs.base import NormalizedImportValue, WorkbookDisplayValue, WorkbookInputValue
 from excelalchemy.codecs.number import Number
 from excelalchemy.metadata import FieldMetaInfo
 
@@ -10,7 +12,10 @@ class Money(Number):
     @classmethod
     def _money_field_meta(cls, field_meta: FieldMetaInfo) -> FieldMetaInfo:
         money_field_meta = field_meta.clone()
-        money_field_meta.fraction_digits = cls.MONEY_FRACTION_DIGITS
+        money_field_meta.presentation_meta = replace(
+            money_field_meta.presentation_meta,
+            fraction_digits=cls.MONEY_FRACTION_DIGITS,
+        )
         return money_field_meta
 
     @classmethod
@@ -18,11 +23,19 @@ class Money(Number):
         return super().build_comment(cls._money_field_meta(field_meta))
 
     @classmethod
-    def format_display_value(cls, value: str | None | Any, field_meta: FieldMetaInfo) -> str:
+    def format_display_value(
+        cls,
+        value: str | WorkbookDisplayValue | None,
+        field_meta: FieldMetaInfo,
+    ) -> str:
         return super().format_display_value(value, cls._money_field_meta(field_meta))
 
     @classmethod
-    def normalize_import_value(cls, value: Any, field_meta: FieldMetaInfo) -> float | int:
+    def normalize_import_value(
+        cls,
+        value: WorkbookInputValue,
+        field_meta: FieldMetaInfo,
+    ) -> NormalizedImportValue:
         return super().normalize_import_value(value, cls._money_field_meta(field_meta))