Add import lifecycle event callback

Author: ruicore

docs/architecture.md

@@ -46,6 +46,8 @@ flowchart LR
 - owns the user-facing workflow
 - coordinates import/export operations
 - keeps the top-level API compact
+- exposes `import_data(..., on_event=...)` as an additive progress-reporting
+  hook for import runs
 
 ### Schema
 
@@ -77,6 +79,15 @@ flowchart LR
 - dispatches create/update/upsert logic
 - isolates backend execution from parsing concerns
 
+### Import Session
+
+`src/excelalchemy/core/import_session.py`
+
+- owns one import run's lifecycle and mutable runtime state
+- emits structured lifecycle events when `on_event=...` is supplied
+- keeps those events on the same synchronous path as header validation, row
+  execution, and result workbook rendering
+
 ### Rendering
 
 `src/excelalchemy/core/rendering.py`

docs/domain-model.md

@@ -33,6 +33,7 @@ For component structure, see [`docs/architecture.md`](architecture.md).
 | Worksheet table | `src/excelalchemy/core/table.py` | Lightweight internal 2D table abstraction used for workbook import/export flow instead of pandas. | Internal, but important to understand |
 | Import session | `src/excelalchemy/core/import_session.py` | Owns one import run’s lifecycle, state, counts, header table, worksheet table, and result rendering decisions. | Internal |
 | Import session snapshot | `src/excelalchemy/core/import_session.py` | Immutable summary of the current import session phase and counts. | Internal |
+| Import lifecycle event callback | `src/excelalchemy/core/alchemy.py`, `src/excelalchemy/core/import_session.py` | Optional per-run callback passed to `ExcelAlchemy.import_data(...)` for synchronous lifecycle events. | Public concept |
 | Row aggregator | `src/excelalchemy/core/rows.py` | Reconstructs flattened worksheet rows back into model-shaped payloads. | Internal |
 | Import issue tracker | `src/excelalchemy/core/rows.py` | Maps cell and row issues back into workbook coordinates and result columns. | Internal |
 | Import executor | `src/excelalchemy/core/executor.py` | Validates row payloads and dispatches configured create/update/upsert callbacks. | Internal |
@@ -69,6 +70,8 @@ For component structure, see [`docs/architecture.md`](architecture.md).
 ### Execution responsibilities
 
 - `ExcelAlchemy` turns a config and schema into a usable workflow object.
+- `ExcelAlchemy.import_data(..., on_event=...)` can report lifecycle progress
+  to a job or service layer while keeping the import itself synchronous.
 - `ExcelSchemaLayout` turns schema declarations into a flattened Excel layout.
 - `ExcelHeaderParser` and `ExcelHeaderValidator` decide whether an uploaded workbook matches that layout.
 - `RowAggregator` reconstructs model-shaped data from worksheet rows.
@@ -106,6 +109,7 @@ For component structure, see [`docs/architecture.md`](architecture.md).
 - `ExcelStorage` provides workbook input as `WorksheetTable` and accepts rendered workbook output for upload.
 - During import:
   - `ImportSession` coordinates the lifecycle
+  - an optional `on_event` callback can observe lifecycle milestones inline
   - `ExcelHeaderParser` parses header rows
   - `ExcelHeaderValidator` validates them against `ExcelSchemaLayout`
   - `RowAggregator` reconstructs row payloads
@@ -137,6 +141,7 @@ For component structure, see [`docs/architecture.md`](architecture.md).
 - `ImportResult`
 - `CellErrorMap`
 - `RowIssueMap`
+- `ExcelAlchemy.import_data(..., on_event=...)`
 
 ### Internal concepts
 
@@ -179,6 +184,9 @@ The import flow is the richest lifecycle in the repository.
 - Start point:
   - `ExcelAlchemy.import_data(...)`
   - implemented in `src/excelalchemy/core/alchemy.py`
+- Optional public progress hook:
+  - `ExcelAlchemy.import_data(..., on_event=...)`
+  - emits simple event dictionaries during the same synchronous import run
 - Runtime owner:
   - `ImportSession`
   - `src/excelalchemy/core/import_session.py`
@@ -197,6 +205,12 @@ The import flow is the richest lifecycle in the repository.
     - `HEADER_INVALID`
     - `DATA_INVALID`
     - `SUCCESS`
+- Event vocabulary:
+  - `started`
+  - `header_validated`
+  - `row_processed`
+  - `completed`
+  - `failed`
 - Workbook-facing row result concept:
   - `ValidateRowResult`
   - values:

docs/public-api.md

@@ -49,6 +49,9 @@ These modules are the recommended import paths for application code:
   The recommended backend configuration pattern in the 2.x line.
 - `ExcelArtifact`
   The recommended return shape when you need bytes, base64, or data URLs.
+- `ExcelAlchemy.import_data(..., on_event=...)`
+  The additive public hook for synchronous import lifecycle events during one
+  import run.
 - import inspection names:
   Prefer `worksheet_table`, `header_table`, `cell_error_map`, and
   `row_error_map` when reading import-run state from the facade.
@@ -113,6 +116,35 @@ For most application code, these are the recommended import paths:
 - `from excelalchemy.results import ...`
   Use this if you need result models or richer error-map helper types directly.
 
+For synchronous job-style progress reporting, you can attach an event callback
+to the existing import call:
+
+```python
+job_state = {'status': 'pending', 'processed_rows': 0, 'total_rows': 0}
+
+def handle_import_event(event: dict[str, object]) -> None:
+    if event['event'] == 'started':
+        job_state['status'] = 'running'
+    elif event['event'] == 'row_processed':
+        job_state['processed_rows'] = event['processed_row_count']
+        job_state['total_rows'] = event['total_row_count']
+    elif event['event'] == 'completed':
+        job_state['status'] = 'completed'
+        job_state['result'] = event['result']
+    elif event['event'] == 'failed':
+        job_state['status'] = 'failed'
+
+result = await alchemy.import_data(
+    'employees.xlsx',
+    'employee-import-result.xlsx',
+    on_event=handle_import_event,
+)
+```
+
+This is still a synchronous import. The callback runs inline during normal
+header validation, row execution, and result rendering, which makes it useful
+for service-layer progress tracking without introducing a new execution model.
+
 If you are building API responses from import failures, the recommended public
 result helpers are:
 

examples/employee_import_workflow.py

@@ -82,9 +82,17 @@ async def create_employee(row: dict[str, object], context: dict[str, object] | N
     return row
 
 
-async def run_workflow() -> tuple[ImportResult, InMemoryImportStorage, dict[str, object]]:
+async def run_workflow() -> tuple[ImportResult, InMemoryImportStorage, dict[str, object], list[dict[str, object]]]:
     storage = InMemoryImportStorage()
-    context: dict[str, object] = {'created_rows': []}
+    context: dict[str, object] = {
+        'created_rows': [],
+        'job_progress': {
+            'status': 'pending',
+            'processed_rows': 0,
+            'total_rows': 0,
+        },
+    }
+    events: list[dict[str, object]] = []
 
     alchemy = ExcelAlchemy(
         ImporterConfig.for_create(
@@ -98,14 +106,40 @@ async def run_workflow() -> tuple[ImportResult, InMemoryImportStorage, dict[str,
 
     template = alchemy.download_template_artifact(filename='employee-template.xlsx')
     _build_import_fixture(storage, template.as_bytes())
-    result = await alchemy.import_data('employee-import.xlsx', 'employee-import-result.xlsx')
-    return result, storage, context
+
+    def handle_import_event(event: dict[str, object]) -> None:
+        events.append(event)
+        job_progress = context['job_progress']
+        assert isinstance(job_progress, dict)
+
+        match event['event']:
+            case 'started':
+                job_progress['status'] = 'running'
+            case 'row_processed':
+                job_progress['processed_rows'] = event['processed_row_count']
+                job_progress['total_rows'] = event['total_row_count']
+            case 'completed':
+                job_progress['status'] = 'completed'
+                job_progress['result'] = event['result']
+                job_progress['result_workbook_url'] = event['url']
+            case 'failed':
+                job_progress['status'] = 'failed'
+                job_progress['error'] = event['error_message']
+
+    result = await alchemy.import_data(
+        'employee-import.xlsx',
+        'employee-import-result.xlsx',
+        on_event=handle_import_event,
+    )
+    return result, storage, context, events
 
 
 def main() -> None:
-    result, storage, context = asyncio.run(run_workflow())
+    result, storage, context, events = asyncio.run(run_workflow())
     created_rows = context['created_rows']
+    job_progress = context['job_progress']
     assert isinstance(created_rows, list)
+    assert isinstance(job_progress, dict)
 
     print('Employee import workflow completed')
     print(f'Result: {result.result}')
@@ -114,6 +148,8 @@ def main() -> None:
     print(f'Result workbook URL: {result.url}')
     print(f'Created rows: {len(created_rows)}')
     print(f'Uploaded artifacts: {sorted(storage.uploaded)}')
+    print(f'Observed events: {[event["event"] for event in events]}')
+    print(f'Job progress: {job_progress}')
 
 
 if __name__ == '__main__':