ExcelAlchemy 2.2.5__tar.gz → 2.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.5
+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,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.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) · [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) · [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.6}/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.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) · [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) · [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.6}/src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.5'
+__version__ = '2.2.6'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (
@@ -50,8 +50,10 @@ from excelalchemy.helper.pydantic import extract_pydantic_model
 from excelalchemy.metadata import ExcelMeta, FieldMeta, PatchFieldMeta
 from excelalchemy.results import (
     CellErrorMap,
+    CellIssueRecord,
     ImportResult,
     RowIssueMap,
+    RowIssueRecord,
     ValidateHeaderResult,
     ValidateResult,
     ValidateRowResult,
@@ -63,6 +65,7 @@ __all__ = [
     'Boolean',
     'BooleanCodec',
     'CellErrorMap',
+    'CellIssueRecord',
     'ColumnIndex',
     'CompositeExcelFieldCodec',
     'ConfigError',
@@ -113,6 +116,7 @@ __all__ = [
     'Radio',
     'RowIndex',
     'RowIssueMap',
+    'RowIssueRecord',
     'SingleChoiceCodec',
     'SingleOrganization',
     'SingleOrganizationCodec',

{excelalchemy-2.2.5 → 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.5 → 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.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/date_range.py

@@ -9,7 +9,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
 from excelalchemy.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -66,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:
@@ -76,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):
@@ -86,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.5 → 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.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/multi_checkbox.py

@@ -14,6 +14,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):
@@ -53,7 +84,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]
 
@@ -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.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.5 → 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

{excelalchemy-2.2.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/organization.py

@@ -13,6 +13,10 @@ from excelalchemy.metadata import FieldMetaInfo
 class SingleOrganization(Radio):
     __name__ = 'SingleOrganization'
 
+    @classmethod
+    def selection_entity_singular(cls) -> str | None:
+        return 'organization'
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -48,6 +52,10 @@ class SingleOrganization(Radio):
 class MultiOrganization(MultiCheckbox):
     __name__ = 'MultiOrganization'
 
+    @classmethod
+    def selection_entity_plural(cls) -> str | None:
+        return 'organizations'
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared

{excelalchemy-2.2.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/phone_number.py

@@ -10,6 +10,10 @@ PHONE_NUMBER_PATTERN = re.compile(r'^((0\d{2,3}-\d{7,8})|(1[3456789]\d{9}))$')
 
 
 class PhoneNumber(String):
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        return msg(MessageKey.VALID_PHONE_NUMBER_REQUIRED)
+
     @classmethod
     def normalize_import_value(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> str:
         parsed = str(value)

{excelalchemy-2.2.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/radio.py

@@ -13,6 +13,37 @@ from excelalchemy.metadata import FieldMetaInfo
 class Radio(ExcelFieldCodec, str):
     __name__ = 'SingleChoice'
 
+    @classmethod
+    def selection_entity_singular(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 = cls.selection_entity_singular()
+        if entity is None:
+            base_message = msg(MessageKey.SELECT_ONE_CONFIGURED_OPTION)
+        else:
+            base_message = msg(MessageKey.SELECT_ONE_CONFIGURED_ENTITY, entity=entity)
+
+        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)
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -57,7 +88,7 @@ class Radio(ExcelFieldCodec, str):
         declared = field_meta.declared
         presentation = field_meta.presentation
         if MULTI_CHECKBOX_SEPARATOR in value:
-            raise ValueError(msg(MessageKey.MULTIPLE_SELECTIONS_NOT_SUPPORTED))
+            raise ValueError(cls._compose_selection_message(field_meta))
 
         parsed = value.strip()
 
@@ -76,7 +107,7 @@ class Radio(ExcelFieldCodec, str):
 
         options_name_map = presentation.options_name_map(field_label=declared.label)
         if parsed not in options_name_map:
-            raise ValueError(msg(MessageKey.OPTION_NOT_FOUND_FIELD_COMMENT))
+            raise ValueError(cls._compose_selection_message(field_meta))
 
         return options_name_map[parsed].id
 

{excelalchemy-2.2.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/staff.py

@@ -14,6 +14,10 @@ from excelalchemy.metadata import FieldMetaInfo
 class SingleStaff(Radio):
     __name__ = 'SingleStaff'
 
+    @classmethod
+    def selection_entity_singular(cls) -> str | None:
+        return 'staff member'
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -53,6 +57,10 @@ class SingleStaff(Radio):
 class MultiStaff(MultiCheckbox):
     __name__ = 'MultiStaff'
 
+    @classmethod
+    def selection_entity_plural(cls) -> str | None:
+        return 'staff members'
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared

{excelalchemy-2.2.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/tree.py

@@ -11,6 +11,10 @@ from excelalchemy.metadata import FieldMetaInfo
 class SingleTreeNode(Radio):
     __name__ = 'SingleTreeNode'
 
+    @classmethod
+    def selection_entity_singular(cls) -> str | None:
+        return 'tree node'
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -47,6 +51,10 @@ class SingleTreeNode(Radio):
 class MultiTreeNode(MultiCheckbox):
     __name__ = 'MultiTreeNode'
 
+    @classmethod
+    def selection_entity_plural(cls) -> str | None:
+        return 'tree nodes'
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared

{excelalchemy-2.2.5 → excelalchemy-2.2.6}/src/excelalchemy/codecs/url.py

@@ -10,6 +10,10 @@ from excelalchemy.metadata import FieldMetaInfo
 class Url(String):
     _validator = TypeAdapter(HttpUrl)
 
+    @classmethod
+    def expected_input_message(cls, field_meta: FieldMetaInfo) -> str | None:
+        return msg(MessageKey.VALID_URL_REQUIRED)
+
     @classmethod
     def normalize_import_value(cls, value: WorkbookInputValue, field_meta: FieldMetaInfo) -> str:
         parsed = str(value)