ExcelAlchemy 2.2.7__tar.gz → 2.2.8__tar.gz

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

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

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.7'
+__version__ = '2.2.8'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (

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.7 → 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.7 → excelalchemy-2.2.8}/src/excelalchemy/metadata.py

@@ -2,7 +2,6 @@
 
 import copy
 import datetime
-import logging
 from collections.abc import Callable, Mapping, Set
 from dataclasses import dataclass, field, replace
 from functools import cached_property
@@ -25,6 +24,10 @@ from excelalchemy._primitives.constants import (
     IntStr,
     Option,
 )
+from excelalchemy._primitives.diagnostics import (
+    log_metadata_large_option_set,
+    log_metadata_missing_option_id,
+)
 from excelalchemy._primitives.identity import Key, Label, OptionId, UniqueKey, UniqueLabel
 from excelalchemy.codecs.base import ExcelFieldCodec, UndefinedFieldCodec
 from excelalchemy.exceptions import ConfigError, ProgrammaticError
@@ -188,22 +191,14 @@ class WorkbookPresentationMeta:
         if self.options is None:
             return {}
         if len(self.options) > MAX_OPTIONS_COUNT:
-            logging.warning(
-                'Field "%s" defines %s options; please confirm that this is intentional because options are not meant for large datasets',
-                field_label,
-                len(self.options),
-            )
+            log_metadata_large_option_set(field_label=str(field_label), option_count=len(self.options))
         return {option.id: option for option in self.options}
 
     def options_name_map(self, *, field_label: Label) -> dict[str, Option]:
         if self.options is None:
             return {}
         if len(self.options) > MAX_OPTIONS_COUNT:
-            logging.warning(
-                'Field "%s" defines %s options; please confirm that this is intentional because options are not meant for large datasets',
-                field_label,
-                len(self.options),
-            )
+            log_metadata_large_option_set(field_label=str(field_label), option_count=len(self.options))
         return {option.name: option for option in self.options}
 
     def exchange_option_ids_to_names(
@@ -220,7 +215,7 @@ class WorkbookPresentationMeta:
             try:
                 option_names.append(option_id_map[normalized_id].name)
             except KeyError:
-                logging.warning('Could not find option id %s; returning the original value', normalized_id)
+                log_metadata_missing_option_id(option_id=str(normalized_id), field_label=str(field_label))
                 option_names.append(normalized_id)
 
         return option_names

{excelalchemy-2.2.7 → excelalchemy-2.2.8}/src/excelalchemy/results.py

@@ -152,6 +152,30 @@ class CellErrorMap(dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]):
     def messages_at(self, row_index: RowIndex | int, column_index: ColumnIndex | int) -> tuple[str, ...]:
         return tuple(str(error) for error in self.at(row_index, column_index))
 
+    def field_labels(self) -> tuple[str, ...]:
+        return tuple(sorted({str(error.label) for error in self.flatten()}))
+
+    def parent_labels(self) -> tuple[str, ...]:
+        return tuple(sorted({str(error.parent_label) for error in self.flatten() if error.parent_label is not None}))
+
+    def unique_labels(self) -> tuple[str, ...]:
+        return tuple(sorted({str(error.unique_label) for error in self.flatten()}))
+
+    def codes(self) -> tuple[str, ...]:
+        return tuple(sorted({error.code for error in self.flatten()}))
+
+    def row_indices(self) -> tuple[RowIndex, ...]:
+        return tuple(sorted(self.keys()))
+
+    def row_numbers_for_humans(self) -> tuple[int, ...]:
+        return tuple(_row_number_for_humans(row_index) for row_index in self.row_indices())
+
+    def column_indices(self) -> tuple[ColumnIndex, ...]:
+        return tuple(sorted({column_index for row in self.values() for column_index in row}))
+
+    def column_numbers_for_humans(self) -> tuple[int, ...]:
+        return tuple(_column_number_for_humans(column_index) for column_index in self.column_indices())
+
     def flatten(self) -> tuple[ExcelCellError, ...]:
         return tuple(error for row in self.values() for errors in row.values() for error in errors)
 
@@ -223,6 +247,32 @@ class CellErrorMap(dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]):
             )
         return tuple(sorted(summaries, key=lambda summary: summary.code))
 
+    def grouped_messages_by_field(self) -> dict[str, tuple[str, ...]]:
+        return {
+            summary.unique_label: tuple(
+                record.error.display_message
+                for record in self.records()
+                if str(record.error.unique_label) == summary.unique_label
+            )
+            for summary in self.summary_by_field()
+        }
+
+    def grouped_messages_by_row(self) -> dict[int, tuple[str, ...]]:
+        return {
+            int(summary.row_index): tuple(
+                record.error.display_message for record in self.records() if record.row_index == summary.row_index
+            )
+            for summary in self.summary_by_row()
+        }
+
+    def grouped_messages_by_code(self) -> dict[str, tuple[str, ...]]:
+        return {
+            summary.code: tuple(
+                record.error.display_message for record in self.records() if record.error.code == summary.code
+            )
+            for summary in self.summary_by_code()
+        }
+
     def to_dict(self) -> dict[int, dict[int, list[dict[str, object]]]]:
         return {
             int(row_index): {
@@ -236,6 +286,23 @@ class CellErrorMap(dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]):
             'error_count': self.error_count,
             'items': [record.to_dict() for record in self.records()],
             'by_row': self.to_dict(),
+            'facets': {
+                'field_labels': list(self.field_labels()),
+                'parent_labels': list(self.parent_labels()),
+                'unique_labels': list(self.unique_labels()),
+                'codes': list(self.codes()),
+                'row_numbers_for_humans': list(self.row_numbers_for_humans()),
+                'column_numbers_for_humans': list(self.column_numbers_for_humans()),
+            },
+            'grouped': {
+                'messages_by_field': {
+                    key: list(messages) for key, messages in self.grouped_messages_by_field().items()
+                },
+                'messages_by_row': {
+                    str(row_index): list(messages) for row_index, messages in self.grouped_messages_by_row().items()
+                },
+                'messages_by_code': {key: list(messages) for key, messages in self.grouped_messages_by_code().items()},
+            },
             'summary': {
                 'by_field': [summary.to_dict() for summary in self.summary_by_field()],
                 'by_row': [summary.to_dict() for summary in self.summary_by_row()],
@@ -267,6 +334,32 @@ class RowIssueMap(dict[RowIndex, list[RowIssue]]):
     def messages_for_row(self, row_index: RowIndex | int) -> tuple[str, ...]:
         return tuple(str(error) for error in self.at(row_index))
 
+    def field_labels(self) -> tuple[str, ...]:
+        return tuple(sorted({str(error.label) for error in self.flatten() if isinstance(error, ExcelCellError)}))
+
+    def parent_labels(self) -> tuple[str, ...]:
+        return tuple(
+            sorted(
+                {
+                    str(error.parent_label)
+                    for error in self.flatten()
+                    if isinstance(error, ExcelCellError) and error.parent_label is not None
+                }
+            )
+        )
+
+    def unique_labels(self) -> tuple[str, ...]:
+        return tuple(sorted({str(error.unique_label) for error in self.flatten() if isinstance(error, ExcelCellError)}))
+
+    def codes(self) -> tuple[str, ...]:
+        return tuple(sorted({error.code for error in self.flatten()}))
+
+    def row_indices(self) -> tuple[RowIndex, ...]:
+        return tuple(sorted(self.keys()))
+
+    def row_numbers_for_humans(self) -> tuple[int, ...]:
+        return tuple(_row_number_for_humans(row_index) for row_index in self.row_indices())
+
     def numbered_messages_for_row(self, row_index: RowIndex | int) -> tuple[str, ...]:
         return self.numbered_messages(self.at(row_index))
 
@@ -318,6 +411,22 @@ class RowIssueMap(dict[RowIndex, list[RowIssue]]):
             )
         return tuple(sorted(summaries, key=lambda summary: summary.code))
 
+    def grouped_messages_by_row(self) -> dict[int, tuple[str, ...]]:
+        return {
+            int(summary.row_index): tuple(
+                record.error.display_message for record in self.records() if record.row_index == summary.row_index
+            )
+            for summary in self.summary_by_row()
+        }
+
+    def grouped_messages_by_code(self) -> dict[str, tuple[str, ...]]:
+        return {
+            summary.code: tuple(
+                record.error.display_message for record in self.records() if record.error.code == summary.code
+            )
+            for summary in self.summary_by_code()
+        }
+
     def to_dict(self) -> dict[int, list[dict[str, object]]]:
         return {int(row_index): [error.to_dict() for error in errors] for row_index, errors in self.items()}
 
@@ -326,6 +435,19 @@ class RowIssueMap(dict[RowIndex, list[RowIssue]]):
             'error_count': self.error_count,
             'items': [record.to_dict() for record in self.records()],
             'by_row': self.to_dict(),
+            'facets': {
+                'field_labels': list(self.field_labels()),
+                'parent_labels': list(self.parent_labels()),
+                'unique_labels': list(self.unique_labels()),
+                'codes': list(self.codes()),
+                'row_numbers_for_humans': list(self.row_numbers_for_humans()),
+            },
+            'grouped': {
+                'messages_by_row': {
+                    str(row_index): list(messages) for row_index, messages in self.grouped_messages_by_row().items()
+                },
+                'messages_by_code': {key: list(messages) for key, messages in self.grouped_messages_by_code().items()},
+            },
             'summary': {
                 'by_row': [summary.to_dict() for summary in self.summary_by_row()],
                 'by_code': [summary.to_dict() for summary in self.summary_by_code()],