ExcelAlchemy 2.2.4__tar.gz → 2.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.2.4
+Version: 2.2.5
 Summary: Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.
 Keywords: excel,openpyxl,pydantic,minio,schema
 Author: Ray
@@ -49,7 +49,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+The current stable release is `2.2.5`, which continues the 2.x line with richer import-failure feedback, clearer documentation entry points, stronger examples, and stronger smoke coverage.
+
+[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)
 
 ## Screenshots
 
@@ -114,6 +116,45 @@ alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
 template = alchemy.download_template_artifact(filename='people-template.xlsx')
 ```
 
+## Example Outputs
+
+These fixed outputs are generated from the repository examples by
+[`scripts/generate_example_output_assets.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/scripts/generate_example_output_assets.py).
+
+Import workflow:
+
+```text
+Employee import workflow completed
+Result: SUCCESS
+Success rows: 1
+Failed rows: 0
+Result workbook URL: None
+Created rows: 1
+Uploaded artifacts: []
+```
+
+Export workflow:
+
+```text
+Export workflow completed
+Artifact filename: employees-export.xlsx
+Artifact bytes: 6893
+Upload URL: memory://employees-export-upload.xlsx
+Uploaded objects: ['employees-export-upload.xlsx']
+```
+
+Full captured outputs:
+
+- [employee-import-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/employee-import-workflow.txt)
+- [create-or-update-import.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/create-or-update-import.txt)
+- [export-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/export-workflow.txt)
+- [date-and-range-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/date-and-range-fields.txt)
+- [selection-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
+
+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).
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/README-pypi.md

@@ -10,7 +10,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+The current stable release is `2.2.5`, which continues the 2.x line with richer import-failure feedback, clearer documentation entry points, stronger examples, and stronger smoke coverage.
+
+[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)
 
 ## Screenshots
 
@@ -75,6 +77,45 @@ alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
 template = alchemy.download_template_artifact(filename='people-template.xlsx')
 ```
 
+## Example Outputs
+
+These fixed outputs are generated from the repository examples by
+[`scripts/generate_example_output_assets.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/scripts/generate_example_output_assets.py).
+
+Import workflow:
+
+```text
+Employee import workflow completed
+Result: SUCCESS
+Success rows: 1
+Failed rows: 0
+Result workbook URL: None
+Created rows: 1
+Uploaded artifacts: []
+```
+
+Export workflow:
+
+```text
+Export workflow completed
+Artifact filename: employees-export.xlsx
+Artifact bytes: 6893
+Upload URL: memory://employees-export-upload.xlsx
+Uploaded objects: ['employees-export-upload.xlsx']
+```
+
+Full captured outputs:
+
+- [employee-import-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/employee-import-workflow.txt)
+- [create-or-update-import.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/create-or-update-import.txt)
+- [export-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/export-workflow.txt)
+- [date-and-range-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/date-and-range-fields.txt)
+- [selection-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
+
+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).
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

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

@@ -1,6 +1,6 @@
 """A Python Library for Reading and Writing Excel Files"""
 
-__version__ = '2.2.4'
+__version__ = '2.2.5'
 from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
 from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
 from excelalchemy._primitives.identity import (
@@ -48,13 +48,21 @@ from excelalchemy.core.storage_protocol import ExcelStorage
 from excelalchemy.exceptions import ConfigError, ExcelCellError, ExcelRowError, ProgrammaticError
 from excelalchemy.helper.pydantic import extract_pydantic_model
 from excelalchemy.metadata import ExcelMeta, FieldMeta, PatchFieldMeta
-from excelalchemy.results import ImportResult, ValidateHeaderResult, ValidateResult, ValidateRowResult
+from excelalchemy.results import (
+    CellErrorMap,
+    ImportResult,
+    RowIssueMap,
+    ValidateHeaderResult,
+    ValidateResult,
+    ValidateRowResult,
+)
 from excelalchemy.util.file import flatten
 
 __all__ = [
     'Base64Str',
     'Boolean',
     'BooleanCodec',
+    'CellErrorMap',
     'ColumnIndex',
     'CompositeExcelFieldCodec',
     'ConfigError',
@@ -104,6 +112,7 @@ __all__ = [
     'ProgrammaticError',
     'Radio',
     'RowIndex',
+    'RowIssueMap',
     'SingleChoiceCodec',
     'SingleOrganization',
     'SingleOrganizationCodec',

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/codecs/date_range.py

@@ -10,6 +10,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.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
@@ -53,7 +54,9 @@ class DateRange(CompositeExcelFieldCodec):
         declared = field_meta.declared
         presentation = field_meta.presentation
         if presentation.date_format is None:
-            raise RuntimeError(msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED))
+            raise ConfigError(
+                msg(MessageKey.DATE_FORMAT_NOT_CONFIGURED), message_key=MessageKey.DATE_FORMAT_NOT_CONFIGURED
+            )
 
         return '\n'.join(
             [

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/codecs/multi_checkbox.py

@@ -14,6 +14,12 @@ from excelalchemy.metadata import FieldMetaInfo
 class MultiCheckbox(ExcelFieldCodec, list[str]):
     __name__ = 'MultiChoice'
 
+    @staticmethod
+    def _coerce_items(value: object) -> list[object] | None:
+        if not isinstance(value, list):
+            return None
+        return cast(list[object], value)
+
     @classmethod
     def build_comment(cls, field_meta: FieldMetaInfo) -> str:
         declared = field_meta.declared
@@ -29,8 +35,8 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
 
     @classmethod
     def parse_input(cls, value: object, field_meta: FieldMetaInfo) -> list[str] | object:
-        if isinstance(value, list):
-            items = cast(list[object], value)
+        items = cls._coerce_items(value)
+        if items is not None:
             return [str(item).strip() for item in items]
 
         if isinstance(value, str):
@@ -45,10 +51,10 @@ class MultiCheckbox(ExcelFieldCodec, list[str]):
     def normalize_import_value(cls, value: object, field_meta: FieldMetaInfo) -> list[str]:  # OptionId
         declared = field_meta.declared
         presentation = field_meta.presentation
-        if not isinstance(value, list):
+        items = cls._coerce_items(value)
+        if items is None:
             raise ValueError(msg(MessageKey.OPTION_NOT_FOUND_HEADER_COMMENT))
 
-        items = cast(list[object], value)
         parsed = [str(item).strip() for item in items]
 
         if presentation.options is None:

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

@@ -74,7 +74,8 @@ class MultiOrganization(MultiCheckbox):
             return value
 
         if isinstance(value, list):
-            items = cast(list[object], value)
+            items = MultiOrganization._coerce_items(cast(object, value))
+            assert items is not None
             option_ids = [OptionId(option_id) for option_id in items]
             option_names = presentation.exchange_option_ids_to_names(option_ids, field_label=declared.label)
             return MULTI_CHECKBOX_SEPARATOR.join(map(str, option_names))

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

@@ -80,7 +80,8 @@ class MultiStaff(MultiCheckbox):
             return value
 
         if isinstance(value, list):
-            items = cast(list[object], value)
+            items = MultiStaff._coerce_items(cast(object, value))
+            assert items is not None
             option_ids = [OptionId(option_id) for option_id in items]
             if len(option_ids) != len(set(option_ids)):
                 raise ValueError(msg(MessageKey.OPTIONS_CONTAIN_DUPLICATES))

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/core/alchemy.py

@@ -9,7 +9,7 @@ from excelalchemy._primitives.constants import (
     RESULT_COLUMN_KEY,
 )
 from excelalchemy._primitives.header_models import ExcelHeader
-from excelalchemy._primitives.identity import ColumnIndex, DataUrlStr, Label, RowIndex, UniqueKey, UniqueLabel, UrlStr
+from excelalchemy._primitives.identity import DataUrlStr, Label, UniqueKey, UniqueLabel, UrlStr
 from excelalchemy._primitives.payloads import DataConverter, ExportRowPayload
 from excelalchemy.artifacts import ExcelArtifact
 from excelalchemy.codecs.base import SystemReserved
@@ -22,13 +22,13 @@ from excelalchemy.core.schema import ExcelSchemaLayout
 from excelalchemy.core.storage import build_storage_gateway
 from excelalchemy.core.storage_protocol import ExcelStorage
 from excelalchemy.core.table import WorksheetTable
-from excelalchemy.exceptions import ConfigError, ExcelCellError, ExcelRowError
+from excelalchemy.exceptions import ConfigError
 from excelalchemy.helper.pydantic import get_model_field_names
 from excelalchemy.i18n.messages import MessageKey, use_display_locale
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
 from excelalchemy.metadata import FieldMetaInfo
-from excelalchemy.results import ImportResult
+from excelalchemy.results import CellErrorMap, ImportResult, RowIssueMap
 from excelalchemy.util.file import flatten
 
 HEADER_HINT_LINE_COUNT = 1
@@ -210,24 +210,24 @@ class ExcelAlchemy[
         return self._last_import_session.header_table
 
     @property
-    def cell_error_map(self) -> dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]:
+    def cell_error_map(self) -> CellErrorMap:
         if self._last_import_session is None:
-            return {}
+            return CellErrorMap()
         return self._last_import_session.cell_error_map
 
     @property
-    def row_error_map(self) -> dict[RowIndex, list[ExcelRowError | ExcelCellError]]:
+    def row_error_map(self) -> RowIssueMap:
         if self._last_import_session is None:
-            return {}
+            return RowIssueMap()
         return self._last_import_session.row_error_map
 
     @property
-    def cell_errors(self) -> dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]:
+    def cell_errors(self) -> CellErrorMap:
         """Backward-compatible alias for cell_error_map."""
         return self.cell_error_map
 
     @property
-    def row_errors(self) -> dict[RowIndex, list[ExcelRowError | ExcelCellError]]:
+    def row_errors(self) -> RowIssueMap:
         """Backward-compatible alias for row_error_map."""
         return self.row_error_map
 

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/core/headers.py

@@ -1,7 +1,6 @@
 """Header parsing and validation helpers for import workbooks."""
 
 from collections.abc import Container, Sequence
-from typing import cast
 
 from excelalchemy._primitives.header_models import ExcelHeader
 from excelalchemy._primitives.identity import Label, UniqueLabel
@@ -129,12 +128,12 @@ class ExcelHeaderValidator:
 
     @staticmethod
     def _ordered_difference[T](values: Sequence[T], allowed: Container[T]) -> list[T]:
-        seen: set[Label] = set()
+        seen: set[T] = set()
         result: list[T] = []
         for value in values:
             if value in allowed or value in seen:
                 continue
-            seen.add(cast(Label, value))
+            seen.add(value)
             result.append(value)
         return result
 

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/core/import_session.py

@@ -5,13 +5,12 @@ from __future__ import annotations
 from dataclasses import dataclass, replace
 from enum import StrEnum
 from functools import cached_property
-from typing import cast
 
 from pydantic import BaseModel
 
 from excelalchemy._primitives.constants import REASON_COLUMN_KEY, RESULT_COLUMN_KEY
 from excelalchemy._primitives.header_models import ExcelHeader
-from excelalchemy._primitives.identity import ColumnIndex, DataUrlStr, RowIndex, UniqueLabel, UrlStr
+from excelalchemy._primitives.identity import DataUrlStr, RowIndex, UniqueLabel, UrlStr
 from excelalchemy._primitives.payloads import FlatRowPayload, ModelRowPayload
 from excelalchemy.codecs.base import SystemReserved
 from excelalchemy.config import ImporterConfig
@@ -21,13 +20,13 @@ from excelalchemy.core.rendering import ExcelRenderer
 from excelalchemy.core.rows import ImportIssueTracker, RowAggregator
 from excelalchemy.core.schema import ExcelSchemaLayout
 from excelalchemy.core.storage_protocol import ExcelStorage
-from excelalchemy.core.table import WorksheetTable
-from excelalchemy.exceptions import ConfigError, ExcelCellError, ExcelRowError
+from excelalchemy.core.table import WorksheetRow, WorksheetTable
+from excelalchemy.exceptions import ConfigError
 from excelalchemy.i18n.messages import MessageKey, use_display_locale
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
 from excelalchemy.metadata import FieldMetaInfo
-from excelalchemy.results import ImportResult, ValidateHeaderResult, ValidateResult
+from excelalchemy.results import CellErrorMap, ImportResult, RowIssueMap, ValidateHeaderResult, ValidateResult
 
 HEADER_HINT_LINE_COUNT = 1
 
@@ -104,20 +103,20 @@ class ImportSession[
         self._snapshot = ImportSessionSnapshot()
 
     @property
-    def cell_error_map(self) -> dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]:
+    def cell_error_map(self) -> CellErrorMap:
         return self.issue_tracker.cell_errors
 
     @property
-    def row_error_map(self) -> dict[RowIndex, list[ExcelRowError | ExcelCellError]]:
+    def row_error_map(self) -> RowIssueMap:
         return self.issue_tracker.row_errors
 
     @property
-    def cell_errors(self) -> dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]]:
+    def cell_errors(self) -> CellErrorMap:
         """Backward-compatible alias for cell_error_map."""
         return self.cell_error_map
 
     @property
-    def row_errors(self) -> dict[RowIndex, list[ExcelRowError | ExcelCellError]]:
+    def row_errors(self) -> RowIssueMap:
         """Backward-compatible alias for row_error_map."""
         return self.row_error_map
 
@@ -240,7 +239,7 @@ class ImportSession[
         processed_row_count = 0
         for table_row_index in range(self.extra_header_count_on_import, len(self.worksheet_table)):
             row = self.worksheet_table.row_at(table_row_index)
-            aggregate_data = self._aggregate_data(cast(FlatRowPayload, row.to_dict()))
+            aggregate_data = self._aggregate_data(self._row_payload(row))
             success = await self.executor.execute(RowIndex(table_row_index), aggregate_data, self.worksheet_table)
             processed_row_count += 1
             all_success = all_success and success
@@ -265,6 +264,13 @@ class ImportSession[
     def _aggregate_data(self, row_data: FlatRowPayload) -> ModelRowPayload:
         return self.row_aggregator.aggregate(row_data)
 
+    @staticmethod
+    def _row_payload(row: WorksheetRow) -> FlatRowPayload:
+        payload: FlatRowPayload = {}
+        for key, value in row.items():
+            payload[str(key)] = value
+        return payload
+
     def _render_import_result_excel(self) -> DataUrlStr:
         return self.renderer.render_data(
             self.worksheet_table,

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/core/rows.py

@@ -1,8 +1,6 @@
 """Row aggregation and import issue tracking helpers."""
 
-from collections import defaultdict
 from collections.abc import Iterator
-from typing import cast
 
 from excelalchemy._primitives.identity import ColumnIndex, Key, RowIndex, UniqueLabel
 from excelalchemy._primitives.payloads import AggregatedRowPayload, ModelRowPayload, RowPayloadLike
@@ -11,7 +9,7 @@ from excelalchemy.exceptions import ConfigError, ExcelCellError, ExcelRowError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import message as msg
 from excelalchemy.metadata import FieldMetaInfo
-from excelalchemy.results import ValidateRowResult
+from excelalchemy.results import CellErrorMap, RowIssueMap, ValidateRowResult
 from excelalchemy.util.file import value_is_nan
 
 from .schema import ExcelSchemaLayout
@@ -76,8 +74,8 @@ class ImportIssueTracker:
     def __init__(self, layout: ExcelSchemaLayout, import_result_field_meta: list[FieldMetaInfo]):
         self.layout = layout
         self.import_result_field_meta = import_result_field_meta
-        self.cell_errors: dict[RowIndex, dict[ColumnIndex, list[ExcelCellError]]] = {}
-        self.row_errors: dict[RowIndex, list[ExcelRowError | ExcelCellError]] = defaultdict(list)
+        self.cell_errors = CellErrorMap()
+        self.row_errors = RowIssueMap()
 
     def register_row_error(
         self,
@@ -86,9 +84,9 @@ class ImportIssueTracker:
     ) -> None:
         """Record one row-level issue or a batch of issues for the same row."""
         if isinstance(error, list):
-            self.row_errors[row_index].extend(error)
+            self.row_errors.add_many(row_index, error)
         else:
-            self.row_errors[row_index].append(error)
+            self.row_errors.add(row_index, error)
 
     def register_cell_errors(
         self,
@@ -99,8 +97,8 @@ class ImportIssueTracker:
         """Map cell errors from schema labels to rendered workbook coordinates."""
         for error in errors:
             for index in self._column_indices(worksheet_table, error.unique_label):
-                column_index = cast(ColumnIndex, index + len(self.import_result_field_meta))
-                self.cell_errors.setdefault(row_index, {}).setdefault(column_index, []).append(error)
+                column_index = ColumnIndex(index + len(self.import_result_field_meta))
+                self.cell_errors.add(row_index, column_index, error)
 
     def add_result_columns(
         self,
@@ -115,17 +113,15 @@ class ImportIssueTracker:
         reason: list[str] = []
 
         for index in worksheet_table.index[extra_header_count_on_import:]:
-            row_errors = self.row_errors.get(RowIndex(index))
+            row_errors = self.row_errors.at(RowIndex(index))
             if not row_errors:
                 result.append(str(ValidateRowResult.SUCCESS))
                 reason.append('')
                 continue
 
             result.append(str(ValidateRowResult.FAIL))
-            numbered_reasons = [
-                f'{idx}、{error!s}' for idx, error in enumerate(self.layout.order_errors(row_errors), start=1)
-            ]
-            reason.append('\n'.join(numbered_reasons))
+            ordered_errors = list(self.layout.order_errors(list(row_errors)))
+            reason.append('\n'.join(self.row_errors.numbered_messages(ordered_errors)))
 
         if extra_header_count_on_import == 1:
             result = [str(result_unique_label), *result]

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/core/schema.py

@@ -5,7 +5,6 @@ from collections import defaultdict
 from collections.abc import Iterable, Sequence
 from decimal import Decimal
 from itertools import chain
-from typing import cast
 
 from pydantic import BaseModel
 
@@ -88,11 +87,18 @@ class ExcelSchemaLayout:
         return sorted(
             field_metas,
             key=lambda x: (
-                orders.get(cast(Label, x.runtime.parent_label), Decimal('Infinity')),
+                cls._parent_order(orders, x),
                 x.runtime.offset,
             ),
         )
 
+    @staticmethod
+    def _parent_order(orders: dict[Label, int], field_meta: FieldMetaInfo) -> int | Decimal:
+        parent_label = field_meta.runtime.parent_label
+        if parent_label is None:
+            return Decimal('Infinity')
+        return orders.get(parent_label, Decimal('Infinity'))
+
     def has_merged_header(self, selected_keys: list[UniqueKey]) -> bool:
         """Return whether the selected keys need a two-row merged header."""
         return any(

{excelalchemy-2.2.4 → excelalchemy-2.2.5}/src/excelalchemy/core/writer.py

@@ -22,7 +22,7 @@ from excelalchemy._primitives.constants import (
 )
 from excelalchemy._primitives.identity import ColumnIndex, DataUrlStr, Label, RowIndex, UniqueLabel
 from excelalchemy.core.table import WorksheetTable, WorksheetValue
-from excelalchemy.exceptions import ExcelCellError
+from excelalchemy.exceptions import ExcelCellError, ProgrammaticError
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
 from excelalchemy.i18n.messages import message as msg
@@ -167,7 +167,10 @@ def _write_horizontally_merged_header(
         declared = field_meta.declared
         runtime = field_meta.runtime
         if runtime.parent_label is None:
-            raise RuntimeError(msg(MessageKey.PARENT_LABEL_EMPTY_RUNTIME))
+            raise ProgrammaticError(
+                msg(MessageKey.PARENT_LABEL_EMPTY_RUNTIME),
+                message_key=MessageKey.PARENT_LABEL_EMPTY_RUNTIME,
+            )
         counter[runtime.parent_label] += 1
 
     for openpyxl_col_index, column in enumerate(
@@ -178,7 +181,10 @@ def _write_horizontally_merged_header(
         declared = field_meta.declared
         runtime = field_meta.runtime
         if runtime.parent_label is None:
-            raise RuntimeError(msg(MessageKey.PARENT_LABEL_EMPTY_RUNTIME))
+            raise ProgrammaticError(
+                msg(MessageKey.PARENT_LABEL_EMPTY_RUNTIME),
+                message_key=MessageKey.PARENT_LABEL_EMPTY_RUNTIME,
+            )
         if declared.label != runtime.parent_label and runtime.offset == 0:
             cell = _worksheet_cell(worksheet, row=start_row, column=openpyxl_col_index)
             cell.value = str(runtime.parent_label)