ExcelAlchemy 2.2.6__tar.gz → 2.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.6
+Version: 2.2.8
 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.8`, which continues the 2.x line with a clearer integration roadmap, stronger import-failure payload smoke verification, and more direct install-time validation of the FastAPI reference app.
 
-[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) · [Integration Roadmap](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-roadmap.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.8}/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.8`, which continues the 2.x line with a clearer integration roadmap, stronger import-failure payload smoke verification, and more direct install-time validation of the FastAPI reference app.
 
-[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) · [Integration Roadmap](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-roadmap.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.8}/src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.6'
+__version__ = '2.2.8'
 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.8/src/excelalchemy/_primitives/diagnostics.py

@@ -0,0 +1,50 @@
+"""Named diagnostic loggers and helpers for developer-facing runtime output."""
+
+from __future__ import annotations
+
+import logging
+
+RUNTIME_LOGGER_NAME = 'excelalchemy.runtime'
+METADATA_LOGGER_NAME = 'excelalchemy.metadata'
+
+runtime_logger = logging.getLogger(RUNTIME_LOGGER_NAME)
+metadata_logger = logging.getLogger(METADATA_LOGGER_NAME)
+
+
+def log_runtime_context_replacement() -> None:
+    runtime_logger.warning(
+        'Replacing an existing conversion context; subsequent imports will use the new runtime context.'
+    )
+
+
+def log_runtime_exporter_inference(*, source: str) -> None:
+    runtime_logger.info('Inferring exporter_model from %s.', source)
+
+
+def log_runtime_export_requested_in_import_mode() -> None:
+    runtime_logger.info('Export requested while configured in import mode; inferring exporter_model and continuing.')
+
+
+def log_runtime_ignoring_unrecognized_export_keys(*, unrecognized: set[str], model_keys: list[str]) -> None:
+    runtime_logger.warning(
+        'Ignoring export keys that are not present in the exporter model. Ignored keys: %s. Exporter model keys: %s.',
+        sorted(unrecognized),
+        model_keys,
+    )
+
+
+def log_metadata_large_option_set(*, field_label: str, option_count: int) -> None:
+    metadata_logger.warning(
+        'Field "%s" defines %s options. Options are intended for bounded vocabularies, so review this field if it '
+        'represents a large dataset.',
+        field_label,
+        option_count,
+    )
+
+
+def log_metadata_missing_option_id(*, option_id: str, field_label: str) -> None:
+    metadata_logger.warning(
+        'Could not resolve option id %s for field "%s"; returning the original workbook value.',
+        option_id,
+        field_label,
+    )

{excelalchemy-2.2.6 → excelalchemy-2.2.8}/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.8}/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.8}/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.8}/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.8}/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.8}/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.8}/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.8}/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.8}/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.8}/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.8}/src/excelalchemy/core/alchemy.py

@@ -1,4 +1,3 @@
-import logging
 from collections.abc import Sequence
 from typing import cast
 
@@ -8,6 +7,12 @@ from excelalchemy._primitives.constants import (
     REASON_COLUMN_KEY,
     RESULT_COLUMN_KEY,
 )
+from excelalchemy._primitives.diagnostics import (
+    log_runtime_context_replacement,
+    log_runtime_export_requested_in_import_mode,
+    log_runtime_exporter_inference,
+    log_runtime_ignoring_unrecognized_export_keys,
+)
 from excelalchemy._primitives.header_models import ExcelHeader
 from excelalchemy._primitives.identity import DataUrlStr, Label, UniqueKey, UniqueLabel, UrlStr
 from excelalchemy._primitives.payloads import DataConverter, ExportRowPayload
@@ -174,7 +179,7 @@ class ExcelAlchemy[
 
     def add_context(self, context: ContextT) -> None:
         if self._context is not None:
-            logging.warning('An existing conversion context is being replaced')
+            log_runtime_context_replacement()
         self._context = context
         if self._last_import_session is not None:
             self._last_import_session.context = context
@@ -263,10 +268,10 @@ class ExcelAlchemy[
             if self.config.schema_options.create_importer_model and self.config.schema_options.update_importer_model:
                 raise ConfigError(msg(MessageKey.EXPORTER_MODEL_INFERENCE_CONFLICT))
             if self.config.schema_options.create_importer_model:
-                logging.info('Inferring exporter_model from create_importer_model')
+                log_runtime_exporter_inference(source='create_importer_model')
                 return cast(type[ExportModelT], self.config.schema_options.create_importer_model)
             if self.config.schema_options.update_importer_model:
-                logging.info('Inferring exporter_model from update_importer_model')
+                log_runtime_exporter_inference(source='update_importer_model')
                 return cast(type[ExportModelT], self.config.schema_options.update_importer_model)
             raise ConfigError(msg(MessageKey.EXPORTER_MODEL_CANNOT_BE_INFERRED))
 
@@ -285,7 +290,7 @@ class ExcelAlchemy[
         self, data: list[ExportRowPayload], keys: Sequence[str] | None = None
     ) -> tuple[WorksheetTable, bool]:
         if self.excel_mode == ExcelMode.IMPORT:
-            logging.info('Export requested while configured in import mode; continuing with exporter_model inference')
+            log_runtime_export_requested_in_import_mode()
 
         input_keys = (
             list(keys)
@@ -298,9 +303,7 @@ class ExcelAlchemy[
         )
         model_keys = get_model_field_names(self.exporter_model)
         if unrecognized := (set(input_keys) - set(model_keys)):
-            logging.warning(
-                'Ignoring keys not present in the exporter model: %s (model keys: %s)', unrecognized, model_keys
-            )
+            log_runtime_ignoring_unrecognized_export_keys(unrecognized=unrecognized, model_keys=model_keys)
 
         selected_keys = self._select_output_excel_keys(list(set(input_keys).intersection(set(model_keys))))
         has_merged_header = self.has_merged_header(selected_keys)

{excelalchemy-2.2.6 → excelalchemy-2.2.8}/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