ExcelAlchemy 2.2.6__tar.gz → 2.2.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.6
+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.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.
+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) · [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)
+[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
 

{excelalchemy-2.2.6 → 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.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.
+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) · [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)
+[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
 

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

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.6'
+__version__ = '2.2.7'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (
@@ -51,9 +51,12 @@ from excelalchemy.metadata import ExcelMeta, FieldMeta, PatchFieldMeta
 from excelalchemy.results import (
     CellErrorMap,
     CellIssueRecord,
+    CodeIssueSummary,
+    FieldIssueSummary,
     ImportResult,
     RowIssueMap,
     RowIssueRecord,
+    RowIssueSummary,
     ValidateHeaderResult,
     ValidateResult,
     ValidateRowResult,
@@ -66,6 +69,7 @@ __all__ = [
     'BooleanCodec',
     'CellErrorMap',
     'CellIssueRecord',
+    'CodeIssueSummary',
     'ColumnIndex',
     'CompositeExcelFieldCodec',
     'ConfigError',
@@ -87,6 +91,7 @@ __all__ = [
     'ExcelRowError',
     'ExcelStorage',
     'ExporterConfig',
+    'FieldIssueSummary',
     'FieldMeta',
     'ImportMode',
     'ImportResult',
@@ -117,6 +122,7 @@ __all__ = [
     'RowIndex',
     'RowIssueMap',
     'RowIssueRecord',
+    'RowIssueSummary',
     'SingleChoiceCodec',
     'SingleOrganization',
     'SingleOrganizationCodec',

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

@@ -19,6 +19,9 @@ 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] = []
@@ -43,20 +46,29 @@ def _summarize_exception(exc: Exception) -> str:
     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,
+    exc: Exception | None = None,
+    reason: str | None = None,
 ) -> None:
     field_context = f' for field "{field_label}"' if field_label else ''
-    logging.warning(
+    codec_logger.warning(
         'Codec %s could not parse workbook input%s; keeping the original value %r. Reason: %s',
         codec_name,
         field_context,
         value,
-        _summarize_exception(exc),
+        _fallback_reason(exc=exc, reason=reason),
     )
 
 
@@ -65,15 +77,43 @@ def log_codec_render_fallback(
     value: object,
     *,
     field_label: str | None = None,
-    exc: Exception,
+    exc: Exception | None = None,
+    reason: str | None = None,
 ) -> None:
     field_context = f' for field "{field_label}"' if field_label else ''
-    logging.warning(
+    codec_logger.warning(
         'Codec %s could not format workbook value%s; returning %r as-is. Reason: %s',
         codec_name,
         field_context,
         value,
-        _summarize_exception(exc),
+        _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,
     )
 
 

{excelalchemy-2.2.6 → 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.6 → 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,7 @@ from excelalchemy.codecs.base import (
     NormalizedImportValue,
     WorkbookDisplayValue,
     WorkbookInputValue,
+    codec_logger,
     log_codec_parse_fallback,
 )
 from excelalchemy.exceptions import ConfigError
@@ -53,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,

{excelalchemy-2.2.6 → 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, log_codec_parse_fallback
+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
@@ -149,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.6 → 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
@@ -73,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
 
@@ -92,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)):

{excelalchemy-2.2.6 → 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,7 @@ from excelalchemy.codecs.base import (
     NormalizedImportValue,
     WorkbookDisplayValue,
     WorkbookInputValue,
+    codec_logger,
     log_codec_parse_fallback,
 )
 from excelalchemy.i18n.messages import MessageKey
@@ -24,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
 
 

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

@@ -1,8 +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 log_codec_option_resolution_fallback, log_codec_render_fallback
 from excelalchemy.codecs.multi_checkbox import MultiCheckbox
 from excelalchemy.codecs.radio import Radio
 from excelalchemy.i18n.messages import MessageKey
@@ -44,7 +44,7 @@ class SingleOrganization(Radio):
         try:
             return presentation.options_id_map(field_label=declared.label)[OptionId(value.strip())].name
         except KeyError:
-            logging.warning('Could not resolve organization option %s; returning the original value', value)
+            log_codec_option_resolution_fallback(cls.__name__, value, field_label=declared.label)
 
         return value
 
@@ -88,7 +88,12 @@ class MultiOrganization(MultiCheckbox):
             option_names = presentation.exchange_option_ids_to_names(option_ids, field_label=declared.label)
             return MULTI_CHECKBOX_SEPARATOR.join(map(str, option_names))
 
-        logging.warning('%s could not be deserialized; returning the original value', cls.__name__)
+        log_codec_render_fallback(
+            cls.__name__,
+            value,
+            field_label=declared.label,
+            reason='The workbook value is not a string or a list of option ids',
+        )
         return str(value)
 
     @classmethod

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

@@ -1,8 +1,12 @@
-import logging
-
 from excelalchemy._primitives.constants import MULTI_CHECKBOX_SEPARATOR
 from excelalchemy._primitives.identity import OptionId
-from excelalchemy.codecs.base import ExcelFieldCodec, WorkbookDisplayValue, WorkbookInputValue
+from excelalchemy.codecs.base import (
+    ExcelFieldCodec,
+    WorkbookDisplayValue,
+    WorkbookInputValue,
+    log_codec_missing_options,
+    log_codec_option_resolution_fallback,
+)
 from excelalchemy.exceptions import ProgrammaticError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
@@ -49,7 +53,7 @@ class Radio(ExcelFieldCodec, str):
         declared = field_meta.declared
         presentation = field_meta.presentation
         if not presentation.options:
-            logging.error('Field %s of type %s must define options', declared.label, cls.__name__)
+            log_codec_missing_options(cls.__name__, field_label=declared.label)
 
         return '\n'.join(
             [
@@ -74,13 +78,7 @@ class Radio(ExcelFieldCodec, str):
         try:
             return presentation.options_id_map(field_label=declared.label)[value.strip()].name
         except Exception as exc:
-            logging.warning(
-                'Type %s could not resolve option %s for field %s; returning the original value. Reason: %s',
-                cls.__name__,
-                value,
-                declared.label,
-                exc,
-            )
+            log_codec_option_resolution_fallback(cls.__name__, value, field_label=declared.label, exc=exc)
         return value if value is not None else ''
 
     @classmethod
@@ -96,9 +94,7 @@ class Radio(ExcelFieldCodec, str):
             raise ProgrammaticError(msg(MessageKey.OPTIONS_CANNOT_BE_NONE_FOR_SELECTION_FIELDS))
 
         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
 
         options_id_map = presentation.options_id_map(field_label=declared.label)

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

@@ -1,8 +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 log_codec_option_resolution_fallback, log_codec_render_fallback
 from excelalchemy.codecs.multi_checkbox import MultiCheckbox
 from excelalchemy.codecs.radio import Radio
 from excelalchemy.i18n.messages import MessageKey
@@ -45,12 +45,7 @@ class SingleStaff(Radio):
         try:
             return presentation.options_id_map(field_label=declared.label)[OptionId(value.strip())].name
         except KeyError:
-            logging.warning(
-                'Type %s could not resolve option %s for field %s; returning the original value',
-                cls.__name__,
-                value,
-                declared.label,
-            )
+            log_codec_option_resolution_fallback(cls.__name__, value, field_label=declared.label)
         return value
 
 
@@ -97,7 +92,12 @@ class MultiStaff(MultiCheckbox):
             option_names = presentation.exchange_option_ids_to_names(option_ids, field_label=declared.label)
             return f'{MULTI_CHECKBOX_SEPARATOR}'.join(option_names)
 
-        logging.warning('%s could not be deserialized', cls.__name__)
+        log_codec_render_fallback(
+            cls.__name__,
+            value,
+            field_label=declared.label,
+            reason='The workbook value is not a string or a list of option ids',
+        )
         return str(value)
 
 

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

@@ -1,6 +1,8 @@
-import logging
-
-from excelalchemy.codecs.base import WorkbookDisplayValue, WorkbookInputValue
+from excelalchemy.codecs.base import (
+    WorkbookDisplayValue,
+    WorkbookInputValue,
+    log_codec_option_resolution_fallback,
+)
 from excelalchemy.codecs.multi_checkbox import MultiCheckbox
 from excelalchemy.codecs.radio import Radio
 from excelalchemy.i18n.messages import MessageKey
@@ -43,7 +45,7 @@ class SingleTreeNode(Radio):
         try:
             return presentation.options_id_map(field_label=declared.label)[value.strip()].name
         except KeyError:
-            logging.warning('Could not resolve tree option %s; returning the original value', value)
+            log_codec_option_resolution_fallback(cls.__name__, value, field_label=declared.label)
 
         return value if value is not None else ''
 

{excelalchemy-2.2.6 → excelalchemy-2.2.7}/src/excelalchemy/exceptions.py

@@ -30,10 +30,22 @@ class ExcelAlchemyError(Exception):
     def __str__(self) -> str:
         return self.message
 
+    @property
+    def display_message(self) -> str:
+        return self.message
+
+    @property
+    def code(self) -> str:
+        if self.message_key is not None:
+            return self.message_key.value
+        return type(self).__name__
+
     def to_dict(self) -> dict[str, object]:
         payload: dict[str, object] = {
             'type': type(self).__name__,
+            'code': self.code,
             'message': self.message,
+            'display_message': self.display_message,
         }
         if self.message_key is not None:
             payload['message_key'] = self.message_key.value
@@ -66,6 +78,10 @@ class ExcelCellError(ExcelAlchemyError):
     def __str__(self) -> str:
         return f'【{self.label}】{self.message}'
 
+    @property
+    def display_message(self) -> str:
+        return str(self)
+
     def __repr__(self) -> str:
         return (
             f"{type(self).__name__}(label=Label('{self.label}'), "
@@ -103,6 +119,7 @@ class ExcelCellError(ExcelAlchemyError):
     def to_dict(self) -> dict[str, object]:
         payload = super().to_dict()
         payload['label'] = str(self.label)
+        payload['field_label'] = str(self.label)
         payload['parent_label'] = None if self.parent_label is None else str(self.parent_label)
         payload['unique_label'] = str(self.unique_label)
         return payload