ExcelAlchemy 2.3.0__tar.gz → 2.4.0__tar.gz

{excelalchemy-2.3.0 → excelalchemy-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelAlchemy
-Version: 2.3.0
+Version: 2.4.0
 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,12 +49,20 @@ 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.3.0`, which continues the 2.x line with a
+The current stable release is `2.4.0`, which continues the 2.x line with a
 more complete import workflow: clearer template guidance before upload,
 lightweight structural preflight before execution, synchronous lifecycle
 visibility during import, and remediation-oriented payloads after failures.
 
-[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)
+At the top level, that import workflow is:
+
+- template authoring
+- preflight gate
+- import runtime
+- result intelligence
+- artifact and delivery
+
+[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) · [Platform Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md) · [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md) · [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.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
 
@@ -128,6 +136,44 @@ This template metadata is additive: it leaves the worksheet layout alone and
 improves the generated header comment with both guidance text and a concrete
 example value.
 
+## Import Workflow Overview
+
+The shortest path through the import workflow is:
+
+```text
+template -> preflight -> import -> remediation -> delivery
+```
+
+Minimal example:
+
+```python
+from excelalchemy.results import build_frontend_remediation_payload
+
+
+events: list[dict[str, object]] = []
+
+preflight = alchemy.preflight_import('employees.xlsx')
+if preflight.is_valid:
+    result = await alchemy.import_data(
+        'employees.xlsx',
+        'employees-result.xlsx',
+        on_event=events.append,
+    )
+    payload = build_frontend_remediation_payload(
+        result=result,
+        cell_error_map=alchemy.cell_error_map,
+        row_error_map=alchemy.row_error_map,
+    )
+```
+
+See also:
+
+- [Platform Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
+- [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
+- [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.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)
+
 ## Example Outputs
 
 These fixed outputs are generated from the repository examples by
@@ -205,6 +251,9 @@ for configured selection fields.
 ## Learn More
 
 - [Full project README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md)
+- [Platform architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
+- [Runtime model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
+- [Integration blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.md)
 - [Architecture notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md)
 - [Locale policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md)
 - [Migration notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)

{excelalchemy-2.3.0 → excelalchemy-2.4.0}/README-pypi.md

@@ -10,12 +10,20 @@ 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.3.0`, which continues the 2.x line with a
+The current stable release is `2.4.0`, which continues the 2.x line with a
 more complete import workflow: clearer template guidance before upload,
 lightweight structural preflight before execution, synchronous lifecycle
 visibility during import, and remediation-oriented payloads after failures.
 
-[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)
+At the top level, that import workflow is:
+
+- template authoring
+- preflight gate
+- import runtime
+- result intelligence
+- artifact and delivery
+
+[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) · [Platform Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md) · [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md) · [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.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
 
@@ -89,6 +97,44 @@ This template metadata is additive: it leaves the worksheet layout alone and
 improves the generated header comment with both guidance text and a concrete
 example value.
 
+## Import Workflow Overview
+
+The shortest path through the import workflow is:
+
+```text
+template -> preflight -> import -> remediation -> delivery
+```
+
+Minimal example:
+
+```python
+from excelalchemy.results import build_frontend_remediation_payload
+
+
+events: list[dict[str, object]] = []
+
+preflight = alchemy.preflight_import('employees.xlsx')
+if preflight.is_valid:
+    result = await alchemy.import_data(
+        'employees.xlsx',
+        'employees-result.xlsx',
+        on_event=events.append,
+    )
+    payload = build_frontend_remediation_payload(
+        result=result,
+        cell_error_map=alchemy.cell_error_map,
+        row_error_map=alchemy.row_error_map,
+    )
+```
+
+See also:
+
+- [Platform Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
+- [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
+- [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.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)
+
 ## Example Outputs
 
 These fixed outputs are generated from the repository examples by
@@ -166,6 +212,9 @@ for configured selection fields.
 ## Learn More
 
 - [Full project README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md)
+- [Platform architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
+- [Runtime model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
+- [Integration blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.md)
 - [Architecture notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md)
 - [Locale policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md)
 - [Migration notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)

{excelalchemy-2.3.0 → excelalchemy-2.4.0}/src/excelalchemy/README.md

@@ -20,6 +20,13 @@ It is meant for developers and AI agents who need to change implementation detai
   - the internal orchestration that implements import, export, template generation, rendering, and storage integration
   - compatibility modules retained for the 2.x line
 - The package is organized around a small public facade and a set of focused internal collaborators.
+- In the v2.4 docs, those collaborators are also described through a higher-level
+  import platform model:
+  - template authoring
+  - preflight gate
+  - import runtime
+  - result intelligence
+  - artifact and delivery
 
 ## High-Level Package Structure
 
@@ -263,6 +270,13 @@ These exist to support the 2.x line and should not be treated as preferred imple
 
 ## Major Internal Flows
 
+The package guide keeps the internal ownership view.
+If you want the capability-oriented platform view above these flows, start with:
+
+- [`../../docs/platform-architecture.md`](../../docs/platform-architecture.md)
+- [`../../docs/runtime-model.md`](../../docs/runtime-model.md)
+- [`../../docs/platform-code-mapping.md`](../../docs/platform-code-mapping.md)
+
 ### Import validation flow
 
 The import path is implemented roughly in this order:

{excelalchemy-2.3.0 → excelalchemy-2.4.0}/src/excelalchemy/__init__.py

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

{excelalchemy-2.3.0 → excelalchemy-2.4.0}/src/excelalchemy/core/alchemy.py

@@ -152,6 +152,13 @@ class ExcelAlchemy[
         *,
         on_event: Callable[[dict[str, object]], None] | None = None,
     ) -> ImportResult:
+        """Run one import session and optionally emit additive runtime events.
+
+        The callback receives best-effort event dictionaries emitted inline on
+        the same import path. These events are useful for service-layer
+        progress tracking, but they do not create a separate job framework or
+        background execution model.
+        """
         assert isinstance(self.config, ImporterConfig)
         if self.excel_mode != ExcelMode.IMPORT:
             raise ConfigError(msg(MessageKey.IMPORT_MODE_ONLY_METHOD))

{excelalchemy-2.3.0 → excelalchemy-2.4.0}/src/excelalchemy/core/import_session.py

@@ -66,7 +66,13 @@ class ImportSession[
     ImportCreateModelT: BaseModel,
     ImportUpdateModelT: BaseModel,
 ]:
-    """Keep all single-run import state outside of the long-lived facade."""
+    """Keep all single-run import state outside of the long-lived facade.
+
+    This class owns the concrete runtime event payloads emitted during one
+    import run. Platform docs may describe broader stage labels such as
+    "Rows Processed", while the runtime event dictionaries emitted here keep
+    their current concrete names such as ``row_processed``.
+    """
 
     def __init__(
         self,