ExcelAlchemy 2.2.3__tar.gz → 2.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.3
+Version: 2.2.4
 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.2.3 → excelalchemy-2.2.4}/src/excelalchemy/__init__.py

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

{excelalchemy-2.2.3 → excelalchemy-2.2.4}/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.4}/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.4}/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.4}/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.4}/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.4}/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
@@ -28,7 +28,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 +50,16 @@ class DateRange(CompositeExcelFieldCodec):
 
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
-        if field_meta.date_format is None:
+        declared = field_meta.declared
+        presentation = field_meta.presentation
+        if presentation.date_format is None:
             raise RuntimeError(msg(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 +94,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 +127,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 +182,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.4}/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))
 
 

{excelalchemy-2.2.3 → excelalchemy-2.2.4}/src/excelalchemy/codecs/multi_checkbox.py

@@ -16,12 +16,14 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
 
     @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_options,
+                declared.comment_required,
+                presentation.comment_options,
                 dmsg(MessageKey.COMMENT_SELECTION_MODE, value=dmsg(MessageKey.COMMENT_SELECTION_VALUE_MULTI)),
-                field_meta.comment_hint,
+                presentation.comment_hint,
             ]
         )
 
@@ -41,25 +43,27 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
 
     @classmethod
     def normalize_import_value(cls, value: object, field_meta: FieldMetaInfo) -> list[str]:  # OptionId
+        declared = field_meta.declared
+        presentation = field_meta.presentation
         if not isinstance(value, list):
             raise ValueError(msg(MessageKey.OPTION_NOT_FOUND_HEADER_COMMENT))
 
         items = cast(list[object], value)
         parsed = [str(item).strip() for item in items]
 
-        if field_meta.options is None:
+        if presentation.options is None:
             raise ProgrammaticError(msg(MessageKey.OPTIONS_CANNOT_BE_NONE_FOR_VALUE_TYPE, value_type=cls.__name__))
 
-        if not field_meta.options:  # empty
+        if not presentation.options:  # empty
             logging.warning(
-                'Field %s of type %s has no options; returning the original value', field_meta.label, cls.__name__
+                'Field %s of type %s has no options; returning the original value', declared.label, cls.__name__
             )
             return parsed
 
         if len(parsed) != len(set(parsed)):
             raise ValueError(msg(MessageKey.OPTIONS_CONTAIN_DUPLICATES))
 
-        result, errors = field_meta.exchange_names_to_option_ids_with_errors(parsed)
+        result, errors = presentation.exchange_names_to_option_ids_with_errors(parsed, field_label=declared.label)
 
         if errors:
             raise ValueError(*errors)
@@ -68,6 +72,8 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
 
     @classmethod
     def format_display_value(cls, value: str | list[OptionId] | None, field_meta: FieldMetaInfo) -> str:
+        declared = field_meta.declared
+        presentation = field_meta.presentation
         match value:
             case None | '':
                 return ''
@@ -75,7 +81,7 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
                 return value
             case list():
                 option_ids = [OptionId(option_id) for option_id in value]
-                option_names = field_meta.exchange_option_ids_to_names(option_ids)
+                option_names = presentation.exchange_option_ids_to_names(option_ids, field_label=declared.label)
                 return f'{MULTI_CHECKBOX_SEPARATOR}'.join(option_names)