ExcelAlchemy 2.2.5__tar.gz → 2.2.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.5
+Version: 2.2.7
 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,9 +49,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-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.
+The current stable release is `2.2.7`, which continues the 2.x line with stronger API-facing result payloads, a more complete FastAPI reference app, harder install-time smoke verification, and more consistent codec diagnostics.
 
-[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)
+[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) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md) · [API Response Cookbook](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.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
 
@@ -150,11 +150,38 @@ Full captured outputs:
 - [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)
+- [fastapi-reference.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.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).
 
+If you want a copyable FastAPI-oriented reference layout rather than a single
+example script, see the
+[FastAPI reference project](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md).
+
+## Error Feedback
+
+ExcelAlchemy keeps workbook-facing validation feedback readable while also
+supporting API-friendly inspection in application code.
+
+The stable 2.x result surface includes:
+
+- `alchemy.cell_error_map`
+- `alchemy.row_error_map`
+
+These objects remain dict-like for compatibility, but also expose helpers such
+as:
+
+- `messages_at(...)`
+- `messages_for_row(...)`
+- `flatten()`
+- `to_api_payload()`
+
+Common field types now also produce more business-oriented error wording, such
+as expected date formats, sample email/phone/URL formats, and clearer messages
+for configured selection fields.
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

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

@@ -10,9 +10,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-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.
+The current stable release is `2.2.7`, which continues the 2.x line with stronger API-facing result payloads, a more complete FastAPI reference app, harder install-time smoke verification, and more consistent codec diagnostics.
 
-[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)
+[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) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md) · [API Response Cookbook](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.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
 
@@ -111,11 +111,38 @@ Full captured outputs:
 - [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)
+- [fastapi-reference.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.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).
 
+If you want a copyable FastAPI-oriented reference layout rather than a single
+example script, see the
+[FastAPI reference project](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md).
+
+## Error Feedback
+
+ExcelAlchemy keeps workbook-facing validation feedback readable while also
+supporting API-friendly inspection in application code.
+
+The stable 2.x result surface includes:
+
+- `alchemy.cell_error_map`
+- `alchemy.row_error_map`
+
+These objects remain dict-like for compatibility, but also expose helpers such
+as:
+
+- `messages_at(...)`
+- `messages_for_row(...)`
+- `flatten()`
+- `to_api_payload()`
+
+Common field types now also produce more business-oriented error wording, such
+as expected date formats, sample email/phone/URL formats, and clearer messages
+for configured selection fields.
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

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

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.5'
+__version__ = '2.2.7'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (
@@ -50,8 +50,13 @@ from excelalchemy.helper.pydantic import extract_pydantic_model
 from excelalchemy.metadata import ExcelMeta, FieldMeta, PatchFieldMeta
 from excelalchemy.results import (
     CellErrorMap,
+    CellIssueRecord,
+    CodeIssueSummary,
+    FieldIssueSummary,
     ImportResult,
     RowIssueMap,
+    RowIssueRecord,
+    RowIssueSummary,
     ValidateHeaderResult,
     ValidateResult,
     ValidateRowResult,
@@ -63,6 +68,8 @@ __all__ = [
     'Boolean',
     'BooleanCodec',
     'CellErrorMap',
+    'CellIssueRecord',
+    'CodeIssueSummary',
     'ColumnIndex',
     'CompositeExcelFieldCodec',
     'ConfigError',
@@ -84,6 +91,7 @@ __all__ = [
     'ExcelRowError',
     'ExcelStorage',
     'ExporterConfig',
+    'FieldIssueSummary',
     'FieldMeta',
     'ImportMode',
     'ImportResult',
@@ -113,6 +121,8 @@ __all__ = [
     'Radio',
     'RowIndex',
     'RowIssueMap',
+    'RowIssueRecord',
+    'RowIssueSummary',
     'SingleChoiceCodec',
     'SingleOrganization',
     'SingleOrganizationCodec',

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

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+import logging
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from pydantic import GetCoreSchemaHandler
 from pydantic_core import core_schema
@@ -18,6 +19,103 @@ type WorkbookInputValue = Any
 type WorkbookDisplayValue = Any
 type NormalizedImportValue = Any
 
+CODEC_LOGGER_NAME = 'excelalchemy.codecs'
+codec_logger = logging.getLogger(CODEC_LOGGER_NAME)
+
+
+def _summarize_exception(exc: Exception) -> str:
+    details: list[str] = []
+    for arg in exc.args:
+        if isinstance(arg, list):
+            raw_items = cast(list[object], arg)
+            list_items: list[str] = []
+            for item in raw_items:
+                item_text = item.__name__ if isinstance(item, type) else str(item).strip()
+                if item_text:
+                    list_items.append(item_text)
+            if list_items:
+                details.append(', '.join(list_items))
+            continue
+
+        text = str(arg).strip()
+        if text:
+            details.append(text)
+
+    if details:
+        return '; '.join(details)
+    return exc.__class__.__name__
+
+
+def _fallback_reason(*, exc: Exception | None = None, reason: str | None = None) -> str:
+    if reason:
+        return reason
+    if exc is not None:
+        return _summarize_exception(exc)
+    return 'No additional details'
+
+
+def log_codec_parse_fallback(
+    codec_name: str,
+    value: object,
+    *,
+    field_label: str | None = None,
+    exc: Exception | None = None,
+    reason: str | None = None,
+) -> None:
+    field_context = f' for field "{field_label}"' if field_label else ''
+    codec_logger.warning(
+        'Codec %s could not parse workbook input%s; keeping the original value %r. Reason: %s',
+        codec_name,
+        field_context,
+        value,
+        _fallback_reason(exc=exc, reason=reason),
+    )
+
+
+def log_codec_render_fallback(
+    codec_name: str,
+    value: object,
+    *,
+    field_label: str | None = None,
+    exc: Exception | None = None,
+    reason: str | None = None,
+) -> None:
+    field_context = f' for field "{field_label}"' if field_label else ''
+    codec_logger.warning(
+        'Codec %s could not format workbook value%s; returning %r as-is. Reason: %s',
+        codec_name,
+        field_context,
+        value,
+        _fallback_reason(exc=exc, reason=reason),
+    )
+
+
+def log_codec_option_resolution_fallback(
+    codec_name: str,
+    value: object,
+    *,
+    field_label: str | None = None,
+    exc: Exception | None = None,
+    reason: str | None = None,
+) -> None:
+    field_context = f' for field "{field_label}"' if field_label else ''
+    codec_logger.warning(
+        'Codec %s could not resolve a configured option%s; returning %r as-is. Reason: %s',
+        codec_name,
+        field_context,
+        value,
+        _fallback_reason(exc=exc, reason=reason),
+    )
+
+
+def log_codec_missing_options(codec_name: str, *, field_label: str | None = None) -> None:
+    field_context = f' for field "{field_label}"' if field_label else ''
+    codec_logger.warning(
+        'Codec %s is missing configured options%s; workbook comments and validation may be incomplete.',
+        codec_name,
+        field_context,
+    )
+
 
 class ExcelFieldCodec(ABC):
     """Excel-facing field adapter responsible for comments, parsing, formatting, and normalization."""
@@ -42,6 +140,11 @@ class ExcelFieldCodec(ABC):
     def normalize_import_value(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> NormalizedImportValue:
         """Validate and normalize parsed input before handing it to the Pydantic layer."""
 
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        """Return a user-facing input hint for invalid values when one is known."""
+        return None
+
     @classmethod
     def comment(cls, field_meta: FieldMetaInfo) -> str:
         """Backward-compatible alias for build_comment()."""

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

@@ -1,7 +1,10 @@
-import logging
-
 from excelalchemy.codecs import excel_choice_codec
-from excelalchemy.codecs.base import ExcelFieldCodec, WorkbookDisplayValue, WorkbookInputValue
+from excelalchemy.codecs.base import (
+    ExcelFieldCodec,
+    WorkbookDisplayValue,
+    WorkbookInputValue,
+    log_codec_render_fallback,
+)
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
@@ -63,15 +66,19 @@ class Boolean(ExcelFieldCodec):
             if value in cls._false_values():
                 return cls._false_display()
             if value not in cls._true_values() | cls._false_values():
-                logging.warning('Could not recognize boolean value %s; returning the original value', value)
+                log_codec_render_fallback(
+                    cls.__name__,
+                    value,
+                    field_label=declared.label,
+                    reason=f'Expected {cls._true_display()!r} or {cls._false_display()!r}',
+                )
                 return value
         else:
-            logging.warning(
-                'Type %s could not deserialize %s for field %s; returning the default value %s',
+            log_codec_render_fallback(
                 cls.__name__,
                 value,
-                declared.label,
-                cls._false_display(),
+                field_label=declared.label,
+                reason=f'Expected a boolean or one of {cls._true_display()!r}/{cls._false_display()!r}',
             )
 
         return cls._true_display() if str(value) in cls._true_values() else cls._false_display()

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

@@ -1,4 +1,3 @@
-import logging
 from datetime import datetime
 from typing import cast
 
@@ -11,6 +10,8 @@ from excelalchemy.codecs.base import (
     NormalizedImportValue,
     WorkbookDisplayValue,
     WorkbookInputValue,
+    codec_logger,
+    log_codec_parse_fallback,
 )
 from excelalchemy.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey
@@ -21,6 +22,13 @@ from excelalchemy.metadata import FieldMetaInfo
 class Date(ExcelFieldCodec, datetime):
     __name__ = 'Date'
 
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        presentation = field_meta.presentation
+        if presentation.date_format is None:
+            return None
+        return msg(MessageKey.ENTER_DATE_FORMAT, date_format=DATE_FORMAT_TO_HINT_MAPPING[presentation.date_format])
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -45,7 +53,7 @@ class Date(ExcelFieldCodec, datetime):
         declared = field_meta.declared
         presentation = field_meta.presentation
         if isinstance(value, DateTime):
-            logging.info(
+            codec_logger.info(
                 'Codec %s received a parsed datetime for %s; returning it unchanged: %s',
                 cls.__name__,
                 declared.label,
@@ -62,12 +70,7 @@ class Date(ExcelFieldCodec, datetime):
             dt: DateTime = cast(DateTime, pendulum.parse(v))
             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',
-                cls.__name__,
-                value,
-                exc,
-            )
+            log_codec_parse_fallback(cls.__name__, value, field_label=declared.label, exc=exc)
             return value
 
     @classmethod

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

@@ -1,4 +1,3 @@
-import logging
 from collections.abc import Mapping
 from datetime import datetime
 from typing import cast
@@ -9,7 +8,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.codecs.base import CompositeExcelFieldCodec, log_codec_parse_fallback, log_codec_render_fallback
 from excelalchemy.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -66,8 +65,13 @@ class DateRange(CompositeExcelFieldCodec):
             ]
         )
 
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        return msg(MessageKey.ENTER_DATE_RANGE_EXPECTED_FORMAT)
+
     @classmethod
     def parse_input(cls, value: object, field_meta: FieldMetaInfo) -> object:
+        declared = field_meta.declared
         mapping = cls._coerce_mapping(value)
         if mapping is not None:
             try:
@@ -76,7 +80,7 @@ class DateRange(CompositeExcelFieldCodec):
                     'end': cls._parse_optional_datetime(mapping.get('end'), field_meta),
                 }
             except Exception as exc:
-                logging.warning('Could not parse value %s for field %s. Reason: %s', value, cls.__name__, exc)
+                log_codec_parse_fallback(cls.__name__, value, field_label=declared.label, exc=exc)
                 return value
 
         if isinstance(value, datetime):
@@ -86,7 +90,7 @@ class DateRange(CompositeExcelFieldCodec):
             try:
                 return cls._parse_datetime_text(value, field_meta)
             except Exception as exc:
-                logging.warning('Could not parse value %s for field %s. Reason: %s', value, cls.__name__, exc)
+                log_codec_parse_fallback(cls.__name__, value, field_label=declared.label, exc=exc)
                 return value
 
         return value
@@ -144,7 +148,12 @@ class DateRange(CompositeExcelFieldCodec):
         if mapping is not None:
             return cls.__deserialize__dict(py_date_format, mapping)
 
-        logging.warning('%s could not be deserialized; returning the original value', cls.__name__)
+        log_codec_render_fallback(
+            cls.__name__,
+            value,
+            field_label=field_meta.declared.label,
+            reason='The workbook value is not a string, datetime, or start/end mapping',
+        )
         return str(value)
 
     @classmethod

{excelalchemy-2.2.5 → excelalchemy-2.2.7}/src/excelalchemy/codecs/email.py

@@ -11,6 +11,10 @@ from excelalchemy.metadata import FieldMetaInfo
 class Email(String):
     _validator: ClassVar[TypeAdapter[EmailStr]] = TypeAdapter(EmailStr)
 
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        return msg(MessageKey.VALID_EMAIL_REQUIRED)
+
     @classmethod
     def normalize_import_value(cls, value: object, field_meta: FieldMetaInfo) -> str:
         # Try to parse the value as a string

{excelalchemy-2.2.5 → excelalchemy-2.2.7}/src/excelalchemy/codecs/multi_checkbox.py

@@ -1,9 +1,8 @@
-import logging
 from typing import cast
 
 from excelalchemy._primitives.constants import MULTI_CHECKBOX_SEPARATOR
 from excelalchemy._primitives.identity import OptionId
-from excelalchemy.codecs.base import ExcelFieldCodec
+from excelalchemy.codecs.base import ExcelFieldCodec, log_codec_missing_options, log_codec_parse_fallback
 from excelalchemy.exceptions import ProgrammaticError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -14,6 +13,37 @@ from excelalchemy.metadata import FieldMetaInfo
 class MultiCheckbox(ExcelFieldCodec, list[str]):
     __name__ = 'MultiChoice'
 
+    @classmethod
+    def selection_entity_plural(cls) -> str | None:
+        return None
+
+    @classmethod
+    def _options_preview(cls, field_meta: FieldMetaInfo, *, limit: int = 5) -> str | None:
+        options = field_meta.presentation.options
+        if not options:
+            return None
+        preview = MULTI_CHECKBOX_SEPARATOR.join(option.name for option in options[:limit])
+        if len(options) > limit:
+            preview = f'{preview}{MULTI_CHECKBOX_SEPARATOR}...'
+        return preview
+
+    @classmethod
+    def _compose_selection_message(cls, field_meta: FieldMetaInfo) -> str:
+        entity_plural = cls.selection_entity_plural()
+        if entity_plural is None:
+            base_message = msg(MessageKey.SELECT_ONLY_CONFIGURED_OPTIONS)
+        else:
+            base_message = msg(MessageKey.SELECT_ONLY_CONFIGURED_ENTITIES, entity_plural=entity_plural)
+
+        preview = cls._options_preview(field_meta)
+        if preview is None:
+            return base_message
+        return f'{base_message}. {msg(MessageKey.VALID_VALUES_INCLUDE, options=preview)}'
+
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        return cls._compose_selection_message(field_meta)
+
     @staticmethod
     def _coerce_items(value: object) -> list[object] | None:
         if not isinstance(value, list):
@@ -42,8 +72,11 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
         if isinstance(value, str):
             return [item.strip() for item in value.split(MULTI_CHECKBOX_SEPARATOR)]
 
-        logging.warning(
-            'ValueType <%s> could not parse Excel input %s; returning the original value', cls.__name__, value
+        log_codec_parse_fallback(
+            cls.__name__,
+            value,
+            field_label=field_meta.declared.label,
+            reason='Expected a delimited string or a list of selected values',
         )
         return value
 
@@ -53,7 +86,7 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
         presentation = field_meta.presentation
         items = cls._coerce_items(value)
         if items is None:
-            raise ValueError(msg(MessageKey.OPTION_NOT_FOUND_HEADER_COMMENT))
+            raise ValueError(cls._compose_selection_message(field_meta))
 
         parsed = [str(item).strip() for item in items]
 
@@ -61,9 +94,7 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
             raise ProgrammaticError(msg(MessageKey.OPTIONS_CANNOT_BE_NONE_FOR_VALUE_TYPE, value_type=cls.__name__))
 
         if not presentation.options:  # empty
-            logging.warning(
-                'Field %s of type %s has no options; returning the original value', declared.label, cls.__name__
-            )
+            log_codec_missing_options(cls.__name__, field_label=declared.label)
             return parsed
 
         if len(parsed) != len(set(parsed)):
@@ -72,7 +103,7 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
         result, errors = presentation.exchange_names_to_option_ids_with_errors(parsed, field_label=declared.label)
 
         if errors:
-            raise ValueError(*errors)
+            raise ValueError(cls._compose_selection_message(field_meta))
         else:
             return result
 

{excelalchemy-2.2.5 → excelalchemy-2.2.7}/src/excelalchemy/codecs/number.py

@@ -1,4 +1,3 @@
-import logging
 from decimal import ROUND_DOWN, Context, Decimal, InvalidOperation
 
 from excelalchemy.codecs.base import (
@@ -6,6 +5,8 @@ from excelalchemy.codecs.base import (
     NormalizedImportValue,
     WorkbookDisplayValue,
     WorkbookInputValue,
+    codec_logger,
+    log_codec_parse_fallback,
 )
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -23,7 +24,7 @@ def canonicalize_decimal(value: Decimal, digits_limit: int | None) -> Decimal:
                 context=Context(rounding=ROUND_DOWN),
             )
         except InvalidOperation as e:
-            logging.warning('fraction_digits is too small and causes precision loss: %s', e)
+            codec_logger.warning('Codec Number detected precision loss while quantizing fraction_digits: %s', e)
     return value
 
 
@@ -64,6 +65,7 @@ class Number(Decimal, ExcelFieldCodec):
         value: str | int | float | WorkbookInputValue | None,
         field_meta: FieldMetaInfo,
     ) -> Decimal | WorkbookInputValue:
+        declared = field_meta.declared
         if isinstance(value, str):
             value = value.strip()
         if value is None:
@@ -71,12 +73,7 @@ class Number(Decimal, ExcelFieldCodec):
         try:
             return transform_decimal(Decimal(str(value)))
         except Exception as exc:
-            logging.warning(
-                'ValueType <%s> could not parse Excel input %s; returning the original value. Reason: %s',
-                cls.__name__,
-                value,
-                exc,
-            )
+            log_codec_parse_fallback(cls.__name__, value, field_label=declared.label, exc=exc)
             return str(value)
 
     @classmethod
@@ -90,13 +87,7 @@ class Number(Decimal, ExcelFieldCodec):
 
         try:
             return str(transform_decimal(Decimal(value)))
-        except Exception as exc:
-            logging.warning(
-                'ValueType <%s> could not parse Excel input %s; returning the original value. Reason: %s',
-                cls.__name__,
-                value,
-                exc,
-            )
+        except Exception:
             return str(value)
 
     @classmethod

{excelalchemy-2.2.5 → excelalchemy-2.2.7}/src/excelalchemy/codecs/number_range.py

@@ -1,10 +1,9 @@
-import logging
 from collections.abc import Mapping
 from decimal import Decimal
 from typing import cast
 
 from excelalchemy._primitives.identity import Key
-from excelalchemy.codecs.base import CompositeExcelFieldCodec
+from excelalchemy.codecs.base import CompositeExcelFieldCodec, log_codec_parse_fallback
 from excelalchemy.codecs.number import Number, canonicalize_decimal, transform_decimal
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -35,8 +34,13 @@ class NumberRange(CompositeExcelFieldCodec):
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         return Number.build_comment(field_meta)
 
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        return msg(MessageKey.ENTER_NUMBER_RANGE_EXPECTED_FORMAT)
+
     @classmethod
     def parse_input(cls, value: object, field_meta: FieldMetaInfo) -> object:
+        declared = field_meta.declared
         if isinstance(value, str):
             value = value.strip()
 
@@ -50,12 +54,7 @@ class NumberRange(CompositeExcelFieldCodec):
                 end = cls._parse_decimal_boundary(mapping['end'])
                 return NumberRange(start, end)
             except (KeyError, TypeError, ValueError) as exc:
-                logging.warning(
-                    '%s could not parse Excel input %s; returning the original value. Reason: %s',
-                    cls.__name__,
-                    value,
-                    exc,
-                )
+                log_codec_parse_fallback(cls.__name__, value, field_label=declared.label, exc=exc)
         return value
 
     @classmethod
@@ -68,13 +67,7 @@ class NumberRange(CompositeExcelFieldCodec):
             if parsed is None:
                 return ''
             return str(transform_decimal(canonicalize_decimal(parsed, presentation.fraction_digits)))
-        except Exception as exc:
-            logging.warning(
-                'ValueType <%s> could not parse Excel input %s; returning the original value. Reason: %s',
-                cls.__name__,
-                value,
-                exc,
-            )
+        except Exception:
             return str(value)
 
     @classmethod