ExcelAlchemy 2.2.4__tar.gz → 2.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.4
+Version: 2.2.6
 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.6`, which continues the 2.x line with stronger result-object guidance, a copyable FastAPI reference project, more robust smoke verification, and clearer codec fallback 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) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.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,72 @@ 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)
+- [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.6/README-pypi.md

@@ -0,0 +1,159 @@
+# ExcelAlchemy
+
+Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.
+
+ExcelAlchemy turns Pydantic models into typed workbook contracts:
+
+- generate Excel templates from code
+- validate uploaded workbooks
+- map failures back to rows and cells
+- render workbook-facing output in `zh-CN` or `en`
+- keep storage pluggable through `ExcelStorage`
+
+The current stable release is `2.2.6`, which continues the 2.x line with stronger result-object guidance, a copyable FastAPI reference project, more robust smoke verification, and clearer codec fallback 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) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.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
+
+### Template
+
+![Excel template screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-template-en.png)
+
+### Import Result
+
+![Excel import result screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-import-result-en.png)
+
+## Install
+
+```bash
+pip install ExcelAlchemy
+```
+
+Optional Minio support:
+
+```bash
+pip install "ExcelAlchemy[minio]"
+```
+
+## Minimal Example
+
+```python
+from pydantic import BaseModel
+
+from excelalchemy import ExcelAlchemy, FieldMeta, ImporterConfig, Number, String
+
+
+class Importer(BaseModel):
+    age: Number = FieldMeta(label='Age', order=1)
+    name: String = FieldMeta(label='Name', order=2)
+
+
+alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
+template = alchemy.download_template_artifact(filename='people-template.xlsx')
+
+excel_bytes = template.as_bytes()
+```
+
+## Modern Annotated Example
+
+```python
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from excelalchemy import Email, ExcelAlchemy, ExcelMeta, ImporterConfig
+
+
+class Importer(BaseModel):
+    email: Annotated[
+        Email,
+        Field(min_length=10),
+        ExcelMeta(label='Email', order=1, hint='Use your work email'),
+    ]
+
+
+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)
+- [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
+- locale-aware workbook comments and result workbooks
+- pluggable storage instead of a hard-coded backend
+- `openpyxl`-based runtime path without pandas
+- contract tests, Ruff, and Pyright in the development workflow
+
+## Learn More
+
+- [Full project README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md)
+- [Architecture notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md)
+- [Locale policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md)
+- [Migration notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)

{excelalchemy-2.2.4 → excelalchemy-2.2.6}/src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.4'
+__version__ = '2.2.6'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (
@@ -48,13 +48,24 @@ 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,
+    CellIssueRecord,
+    ImportResult,
+    RowIssueMap,
+    RowIssueRecord,
+    ValidateHeaderResult,
+    ValidateResult,
+    ValidateRowResult,
+)
 from excelalchemy.util.file import flatten
 
 __all__ = [
     'Base64Str',
     'Boolean',
     'BooleanCodec',
+    'CellErrorMap',
+    'CellIssueRecord',
     'ColumnIndex',
     'CompositeExcelFieldCodec',
     'ConfigError',
@@ -104,6 +115,8 @@ __all__ = [
     'ProgrammaticError',
     'Radio',
     'RowIndex',
+    'RowIssueMap',
+    'RowIssueRecord',
     'SingleChoiceCodec',
     'SingleOrganization',
     'SingleOrganizationCodec',

{excelalchemy-2.2.4 → excelalchemy-2.2.6}/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
@@ -19,6 +20,63 @@ type WorkbookDisplayValue = Any
 type NormalizedImportValue = Any
 
 
+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 log_codec_parse_fallback(
+    codec_name: str,
+    value: object,
+    *,
+    field_label: str | None = None,
+    exc: Exception,
+) -> None:
+    field_context = f' for field "{field_label}"' if field_label else ''
+    logging.warning(
+        'Codec %s could not parse workbook input%s; keeping the original value %r. Reason: %s',
+        codec_name,
+        field_context,
+        value,
+        _summarize_exception(exc),
+    )
+
+
+def log_codec_render_fallback(
+    codec_name: str,
+    value: object,
+    *,
+    field_label: str | None = None,
+    exc: Exception,
+) -> None:
+    field_context = f' for field "{field_label}"' if field_label else ''
+    logging.warning(
+        'Codec %s could not format workbook value%s; returning %r as-is. Reason: %s',
+        codec_name,
+        field_context,
+        value,
+        _summarize_exception(exc),
+    )
+
+
 class ExcelFieldCodec(ABC):
     """Excel-facing field adapter responsible for comments, parsing, formatting, and normalization."""
 
@@ -42,6 +100,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.4 → excelalchemy-2.2.6}/src/excelalchemy/codecs/date.py

@@ -11,6 +11,7 @@ from excelalchemy.codecs.base import (
     NormalizedImportValue,
     WorkbookDisplayValue,
     WorkbookInputValue,
+    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
@@ -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.4 → excelalchemy-2.2.6}/src/excelalchemy/codecs/date_range.py

@@ -9,7 +9,8 @@ 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
+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
@@ -53,7 +54,9 @@ class DateRange(CompositeExcelFieldCodec):
         declared = field_meta.declared
         presentation = field_meta.presentation
         if presentation.date_format is None:
-            raise RuntimeError(msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED))
+            raise ConfigError(
+                msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED), message_key=MessageKey.DATE_FORMAT_NOT_CONFIGURED
+            )
 
         return '\n'.join(
             [
@@ -63,8 +66,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:
@@ -73,7 +81,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):
@@ -83,7 +91,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

{excelalchemy-2.2.4 → excelalchemy-2.2.6}/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.4 → excelalchemy-2.2.6}/src/excelalchemy/codecs/multi_checkbox.py

@@ -14,6 +14,43 @@ 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):
+            return None
+        return cast(list[object], value)
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -29,8 +66,8 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
 
     @classmethod
     def parse_input(cls, value: object, field_meta: FieldMetaInfo) -> list[str] | object:
-        if isinstance(value, list):
-            items = cast(list[object], value)
+        items = cls._coerce_items(value)
+        if items is not None:
             return [str(item).strip() for item in items]
 
         if isinstance(value, str):
@@ -45,10 +82,10 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
     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 = cls._coerce_items(value)
+        if items is None:
+            raise ValueError(cls._compose_selection_message(field_meta))
 
-        items = cast(list[object], value)
         parsed = [str(item).strip() for item in items]
 
         if presentation.options is None:
@@ -66,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.4 → excelalchemy-2.2.6}/src/excelalchemy/codecs/number.py

@@ -6,6 +6,7 @@ from excelalchemy.codecs.base import (
     NormalizedImportValue,
     WorkbookDisplayValue,
     WorkbookInputValue,
+    log_codec_parse_fallback,
 )
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -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.4 → excelalchemy-2.2.6}/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