excel-orm 0.1.1__tar.gz → 0.1.3__tar.gz

{excel_orm-0.1.1 → excel_orm-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excel-orm
-Version: 0.1.1
+Version: 0.1.3
 Summary: A lightweight Excel ORM for generating templates and parsing typed row models.
 Project-URL: Homepage, https://github.com/acdelrusso/excel-orm
 Project-URL: Repository, https://github.com/acdelrusso/excel-orm
@@ -23,38 +23,53 @@ Description-Content-Type: text/markdown
 A lightweight, typed “Excel ORM” for generating Excel templates and parsing Excel workbooks into Python objects using column descriptors.
 
 This project is designed for the common enterprise pattern where you:
-1) generate a structured `.xlsx` template for users,
-2) let users fill it in,
-3) load the workbook back into Python, producing typed objects grouped by model.
 
-It uses `openpyxl` for reading/writing Excel files and supports multiple model “tables” on the same worksheet.
+1. generate a structured `.xlsx` template for users,
+2. let users fill it in,
+3. load the workbook back into Python, producing typed objects grouped by model.
+
+It uses `openpyxl` for reading/writing Excel files and supports:
+
+* multiple model “tables” laid out horizontally on a worksheet, and
+* **pivot-style sheets** (matrix input) that expand into row objects.
 
 ---
 
 ## Features
 
-- **Typed column descriptors** (`text_column`, `int_column`, `bool_column`, `date_column`)
-- **Template generation** with:
-  - merged **table title cells** (pluralized model name)
-  - bold headers
-  - sensible column widths
-  - multiple tables laid out horizontally on the same sheet with a configurable gap
-- **Workbook parsing** into model-specific repositories:
-  - `excel_file.cars.all()` → `list[Car]`
-  - `excel_file.manufacturing_plants.all()` → `list[ManufacturingPlant]`
-- **Validation hooks**
-  - column-level `not_null`
-  - optional row exclusion rules via `excludes`
-  - optional model-level `validate()` method
+* **Typed column descriptors** (`text_column`, `int_column`, `bool_column`, `date_column`)
+* **Template generation** for standard tables:
+
+  * merged **table title cells** (pluralized model name)
+  * bold headers
+  * sensible column widths
+  * multiple tables laid out horizontally on the same sheet with a configurable gap
+* **Template generation** for pivot sheets:
+
+  * merged title across the **row header block + pivot header span**
+  * bold row-field headers in the left block (`row_fields`)
+  * pivot column headers rendered across the top (`pivot_values`)
+  * optional seeding of row keys down the left block (`row_values`)
+* **Workbook parsing** into model-specific repositories:
+
+  * `excel_file.cars.all()` → `list[Car]`
+  * `excel_file.manufacturing_plants.all()` → `list[ManufacturingPlant]`
+  * `excel_file.demands.all()` → `list[Demand]` (from pivot input)
+* **Validation hooks**
+
+  * column-level `not_null`
+  * optional row exclusion rules via `excludes`
+  * optional model-level `validate()` method
 
 ---
 
 ## Installation
 
-### From PyPI (once published)
+### From PyPI
+
 ```bash
 pip install excel-orm
-````
+```
 
 ### From source (uv)
 
@@ -72,7 +87,7 @@ uv sync
 
 ```python
 from excel_orm.column import Column, text_column, int_column
-from excel_orm.orm import ExcelFile, SheetSpec
+from excel_orm import ExcelFile, SheetSpec
 
 class Car:
     make: Column[str] = text_column(header="Make", not_null=True)
@@ -84,7 +99,7 @@ class ManufacturingPlant:
     location: Column[str] = text_column(header="Location")
 ```
 
-### 2) Declare a sheet containing multiple models
+### 2) Declare a sheet containing multiple models (standard tables)
 
 Each model becomes its own table on the same worksheet.
 
@@ -92,13 +107,9 @@ Each model becomes its own table on the same worksheet.
 sheet = SheetSpec(
     name="Cars",
     models=[Car, ManufacturingPlant],
-
-    # Layout rows
     title_row=1,
     header_row=2,
     data_start_row=3,
-
-    # Horizontal spacing between model tables
     template_table_gap=2,
 )
 ```
@@ -108,12 +119,8 @@ sheet = SheetSpec(
 ```python
 excel_file = ExcelFile(sheets=[sheet])
 
-# Generate a blank template workbook
 excel_file.generate_template("car_inventory_template.xlsx")
-
 # Users fill in data in Excel...
-
-# Load the filled workbook into repositories
 excel_file.load_data("car_inventory_data.xlsx")
 
 cars = excel_file.cars.all()
@@ -125,6 +132,84 @@ print(plants[0].name, plants[0].location)
 
 ---
 
+## Pivot Sheets
+
+Pivot sheets are useful when users prefer matrix-style input (e.g., values by multiple row keys × time), but your application wants row objects.
+
+### Pivot Layout Summary
+
+For a pivot sheet:
+
+* `row_fields` define the **leftmost columns** (starting at `row_header_col`)
+* `pivot_values` are written across the top row (`header_row`) starting at `data_start_col`
+* `data_start_col` is **computed** as:
+
+```python
+data_start_col = len(row_fields) + 1
+```
+
+Parsing behavior:
+
+* pivot headers are read from `header_row` across the top until the first blank header cell
+* parsing stops when the **row header block** (all `row_fields` columns) is blank for a row
+* each non-blank pivot cell emits one object (unless `include_blanks=True`)
+
+### 1) Define a “row” model
+
+```python
+from datetime import date
+from excel_orm.column import Column, text_column, date_column, int_column
+
+class Demand:
+    region: Column[str] = text_column(header="Region", not_null=True)
+    product: Column[str] = text_column(header="Product", not_null=True)
+    dt: Column[date] = date_column(header="Date", not_null=True)
+    value: Column[int] = int_column(header="Value", not_null=True)
+```
+
+### 2) Create a `PivotSheetSpec` (multi-row-fields)
+
+```python
+from datetime import date
+from excel_orm import ExcelFile, PivotSheetSpec
+
+spec = PivotSheetSpec(
+    name="Demand",
+    model=Demand,
+    pivot_field="dt",
+    row_fields=["region", "product"],
+    value_field="value",
+    pivot_values=[date(2025, 6, 1), date(2025, 7, 1), date(2025, 8, 1)],
+    # optional: seed row keys (must match row_fields arity)
+    row_values=[
+        ("NA", "SKU-1"),
+        ("NA", "SKU-2"),
+        ("EU", "SKU-1"),
+    ],
+)
+xf = ExcelFile(sheets=[spec])
+xf.generate_template("demand_template.xlsx")
+```
+
+### 3) Load a filled pivot sheet
+
+```python
+xf.load_data("demand_filled.xlsx")
+rows = xf.demands.all()
+
+# each element is a Demand row:
+# Demand(region="NA", product="SKU-1", dt=date(2025, 6, 1), value=10)
+```
+
+### `row_values` seeding rules
+
+* If `len(row_fields) == 1`, each `row_values` element may be a **single scalar** value (backward compatible).
+* If `len(row_fields) > 1`, each `row_values` element must be a **tuple/list with length == len(row_fields)**.
+
+  * Otherwise template generation raises `ValueError`.
+
+---
+
 ## How It Works
 
 ### Repositories
@@ -133,26 +218,27 @@ For each model you register, `ExcelFile` creates a repository attribute on the i
 
 * `Car` → `excel_file.cars`
 * `ManufacturingPlant` → `excel_file.manufacturing_plants`
+* `Demand` → `excel_file.demands`
 
-Repositories are simple list-like containers with an `all()` helper:
+Repositories are list-like containers with an `all()` helper:
 
 ```python
 cars = excel_file.cars.all()  # list[Car]
 ```
 
-### Multi-table Sheets
+### Multi-table Sheets (standard tables)
 
 A single worksheet can host multiple model tables. During template generation:
 
-* A merged title cell is written above each table (pluralized class name in title case).
-* Headers appear under the title.
-* Data rows begin at `data_start_row`.
-* Tables are placed horizontally with `template_table_gap` blank columns between them.
+* a merged title cell is written above each table (pluralized class name in title case)
+* headers appear under the title
+* data rows begin at `data_start_row`
+* tables are placed horizontally with `template_table_gap` blank columns between them
 
 During parsing:
 
-* The library locates each model table by matching the expected header sequence.
-* It reads contiguous rows until a blank row is encountered.
+* the library locates each model table by matching the expected header sequence
+* it reads contiguous rows until a blank row is encountered
 
 ---
 
@@ -167,8 +253,8 @@ class Example:
     name: Column[str] = text_column(header="Name", not_null=True, strip=True)
 ```
 
-* `None` parses to `""` (empty string).
-* `strip=True` trims whitespace.
+* `None` parses to `""` (empty string)
+* `strip=True` trims whitespace
 
 ### Integer
 
@@ -179,7 +265,7 @@ class Example:
     qty: Column[int] = int_column(header="Qty", not_null=True)
 ```
 
-* `None` or `""` parses to `0`.
+* `None` or `""` parses to `0`
 
 ### Boolean
 
@@ -201,6 +287,7 @@ Invalid values raise `ValueError`.
 ### Date
 
 ```python
+from datetime import date
 from excel_orm.column import Column, date_column
 
 class Example:
@@ -211,7 +298,7 @@ The date parser supports:
 
 * Excel-native `datetime`/`date` values from `openpyxl`
 * ISO strings like `2025-06-01` and `2025-06-01T13:45:00`
-* Common business formats including `01-JUN-2025`
+* common business formats including `01-JUN-2025`
 
 Invalid/empty values raise `ValueError`.
 
@@ -230,15 +317,13 @@ If a `not_null=True` column parses to `None` or `""`, a `ValueError` is raised.
 
 ### Row exclusion: `excludes`
 
-If you set `excludes`, rows matching those raw values in that column will be skipped.
+If you set `excludes`, rows matching those raw values in that column will be skipped during parsing.
 
 ```python
 status: Column[str] = text_column(header="Status")
-status.spec.excludes = {"IGNORE", "SKIP"}  # example pattern
+status.spec.excludes = {"IGNORE", "SKIP"}
 ```
 
-(If you want a nicer API for excludes, consider adding it directly to the column factory signature.)
-
 ### Model-level: `validate()`
 
 If your model defines a `validate(self)` method, it is called after a row is parsed.
@@ -263,7 +348,7 @@ class Car:
 uv run pytest
 ```
 
-### Lint/format (example)
+### Lint/format
 
 If you use Ruff:
 

excel_orm-0.1.3/README.md

@@ -0,0 +1,338 @@
+# Excel ORM
+
+A lightweight, typed “Excel ORM” for generating Excel templates and parsing Excel workbooks into Python objects using column descriptors.
+
+This project is designed for the common enterprise pattern where you:
+
+1. generate a structured `.xlsx` template for users,
+2. let users fill it in,
+3. load the workbook back into Python, producing typed objects grouped by model.
+
+It uses `openpyxl` for reading/writing Excel files and supports:
+
+* multiple model “tables” laid out horizontally on a worksheet, and
+* **pivot-style sheets** (matrix input) that expand into row objects.
+
+---
+
+## Features
+
+* **Typed column descriptors** (`text_column`, `int_column`, `bool_column`, `date_column`)
+* **Template generation** for standard tables:
+
+  * merged **table title cells** (pluralized model name)
+  * bold headers
+  * sensible column widths
+  * multiple tables laid out horizontally on the same sheet with a configurable gap
+* **Template generation** for pivot sheets:
+
+  * merged title across the **row header block + pivot header span**
+  * bold row-field headers in the left block (`row_fields`)
+  * pivot column headers rendered across the top (`pivot_values`)
+  * optional seeding of row keys down the left block (`row_values`)
+* **Workbook parsing** into model-specific repositories:
+
+  * `excel_file.cars.all()` → `list[Car]`
+  * `excel_file.manufacturing_plants.all()` → `list[ManufacturingPlant]`
+  * `excel_file.demands.all()` → `list[Demand]` (from pivot input)
+* **Validation hooks**
+
+  * column-level `not_null`
+  * optional row exclusion rules via `excludes`
+  * optional model-level `validate()` method
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install excel-orm
+```
+
+### From source (uv)
+
+```bash
+git clone <your-repo-url>
+cd excel-orm
+uv sync
+```
+
+---
+
+## Quick Start
+
+### 1) Define models using `Column[...]` descriptors
+
+```python
+from excel_orm.column import Column, text_column, int_column
+from excel_orm import ExcelFile, SheetSpec
+
+class Car:
+    make: Column[str] = text_column(header="Make", not_null=True)
+    model: Column[str] = text_column(header="Model", not_null=True)
+    year: Column[int] = int_column(header="Year", not_null=True)
+
+class ManufacturingPlant:
+    name: Column[str] = text_column(header="Factory Name", not_null=True)
+    location: Column[str] = text_column(header="Location")
+```
+
+### 2) Declare a sheet containing multiple models (standard tables)
+
+Each model becomes its own table on the same worksheet.
+
+```python
+sheet = SheetSpec(
+    name="Cars",
+    models=[Car, ManufacturingPlant],
+    title_row=1,
+    header_row=2,
+    data_start_row=3,
+    template_table_gap=2,
+)
+```
+
+### 3) Create an `ExcelFile`, generate a template, then load data
+
+```python
+excel_file = ExcelFile(sheets=[sheet])
+
+excel_file.generate_template("car_inventory_template.xlsx")
+# Users fill in data in Excel...
+excel_file.load_data("car_inventory_data.xlsx")
+
+cars = excel_file.cars.all()
+plants = excel_file.manufacturing_plants.all()
+
+print(cars[0].make, cars[0].year)
+print(plants[0].name, plants[0].location)
+```
+
+---
+
+## Pivot Sheets
+
+Pivot sheets are useful when users prefer matrix-style input (e.g., values by multiple row keys × time), but your application wants row objects.
+
+### Pivot Layout Summary
+
+For a pivot sheet:
+
+* `row_fields` define the **leftmost columns** (starting at `row_header_col`)
+* `pivot_values` are written across the top row (`header_row`) starting at `data_start_col`
+* `data_start_col` is **computed** as:
+
+```python
+data_start_col = len(row_fields) + 1
+```
+
+Parsing behavior:
+
+* pivot headers are read from `header_row` across the top until the first blank header cell
+* parsing stops when the **row header block** (all `row_fields` columns) is blank for a row
+* each non-blank pivot cell emits one object (unless `include_blanks=True`)
+
+### 1) Define a “row” model
+
+```python
+from datetime import date
+from excel_orm.column import Column, text_column, date_column, int_column
+
+class Demand:
+    region: Column[str] = text_column(header="Region", not_null=True)
+    product: Column[str] = text_column(header="Product", not_null=True)
+    dt: Column[date] = date_column(header="Date", not_null=True)
+    value: Column[int] = int_column(header="Value", not_null=True)
+```
+
+### 2) Create a `PivotSheetSpec` (multi-row-fields)
+
+```python
+from datetime import date
+from excel_orm import ExcelFile, PivotSheetSpec
+
+spec = PivotSheetSpec(
+    name="Demand",
+    model=Demand,
+    pivot_field="dt",
+    row_fields=["region", "product"],
+    value_field="value",
+    pivot_values=[date(2025, 6, 1), date(2025, 7, 1), date(2025, 8, 1)],
+    # optional: seed row keys (must match row_fields arity)
+    row_values=[
+        ("NA", "SKU-1"),
+        ("NA", "SKU-2"),
+        ("EU", "SKU-1"),
+    ],
+)
+xf = ExcelFile(sheets=[spec])
+xf.generate_template("demand_template.xlsx")
+```
+
+### 3) Load a filled pivot sheet
+
+```python
+xf.load_data("demand_filled.xlsx")
+rows = xf.demands.all()
+
+# each element is a Demand row:
+# Demand(region="NA", product="SKU-1", dt=date(2025, 6, 1), value=10)
+```
+
+### `row_values` seeding rules
+
+* If `len(row_fields) == 1`, each `row_values` element may be a **single scalar** value (backward compatible).
+* If `len(row_fields) > 1`, each `row_values` element must be a **tuple/list with length == len(row_fields)**.
+
+  * Otherwise template generation raises `ValueError`.
+
+---
+
+## How It Works
+
+### Repositories
+
+For each model you register, `ExcelFile` creates a repository attribute on the instance using a snake_case pluralized name:
+
+* `Car` → `excel_file.cars`
+* `ManufacturingPlant` → `excel_file.manufacturing_plants`
+* `Demand` → `excel_file.demands`
+
+Repositories are list-like containers with an `all()` helper:
+
+```python
+cars = excel_file.cars.all()  # list[Car]
+```
+
+### Multi-table Sheets (standard tables)
+
+A single worksheet can host multiple model tables. During template generation:
+
+* a merged title cell is written above each table (pluralized class name in title case)
+* headers appear under the title
+* data rows begin at `data_start_row`
+* tables are placed horizontally with `template_table_gap` blank columns between them
+
+During parsing:
+
+* the library locates each model table by matching the expected header sequence
+* it reads contiguous rows until a blank row is encountered
+
+---
+
+## Column Types
+
+### Text
+
+```python
+from excel_orm.column import Column, text_column
+
+class Example:
+    name: Column[str] = text_column(header="Name", not_null=True, strip=True)
+```
+
+* `None` parses to `""` (empty string)
+* `strip=True` trims whitespace
+
+### Integer
+
+```python
+from excel_orm.column import Column, int_column
+
+class Example:
+    qty: Column[int] = int_column(header="Qty", not_null=True)
+```
+
+* `None` or `""` parses to `0`
+
+### Boolean
+
+```python
+from excel_orm.column import Column, bool_column
+
+class Example:
+    active: Column[bool] = bool_column(header="Active")
+```
+
+Accepted values include:
+
+* True: `true, t, yes, y, 1` (case-insensitive)
+* False: `false, f, no, n, 0`
+* `None` / empty parses to `False`
+
+Invalid values raise `ValueError`.
+
+### Date
+
+```python
+from datetime import date
+from excel_orm.column import Column, date_column
+
+class Example:
+    start_date: Column[date] = date_column(header="Start Date")
+```
+
+The date parser supports:
+
+* Excel-native `datetime`/`date` values from `openpyxl`
+* ISO strings like `2025-06-01` and `2025-06-01T13:45:00`
+* common business formats including `01-JUN-2025`
+
+Invalid/empty values raise `ValueError`.
+
+---
+
+## Validation
+
+### Column-level: `not_null`
+
+```python
+class Car:
+    make: Column[str] = text_column(header="Make", not_null=True)
+```
+
+If a `not_null=True` column parses to `None` or `""`, a `ValueError` is raised.
+
+### Row exclusion: `excludes`
+
+If you set `excludes`, rows matching those raw values in that column will be skipped during parsing.
+
+```python
+status: Column[str] = text_column(header="Status")
+status.spec.excludes = {"IGNORE", "SKIP"}
+```
+
+### Model-level: `validate()`
+
+If your model defines a `validate(self)` method, it is called after a row is parsed.
+
+```python
+class Car:
+    make: Column[str] = text_column(header="Make", not_null=True)
+    year: Column[int] = int_column(header="Year", not_null=True)
+
+    def validate(self) -> None:
+        if self.year < 1886:
+            raise ValueError("Invalid car year")
+```
+
+---
+
+## Development
+
+### Run tests
+
+```bash
+uv run pytest
+```
+
+### Lint/format
+
+If you use Ruff:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```

{excel_orm-0.1.1 → excel_orm-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "excel-orm"
-version = "0.1.1"
+version = "0.1.3"
 description = "A lightweight Excel ORM for generating templates and parsing typed row models."
 readme = "README.md"
 requires-python = ">=3.13"

{excel_orm-0.1.1 → excel_orm-0.1.3}/src/excel_orm/column.py

@@ -3,11 +3,18 @@ from __future__ import annotations
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import date, datetime
-from typing import Any, TypeVar
+from typing import Any, Protocol, TypeVar, overload
 
 T = TypeVar("T")
 
 
+class HasValues(Protocol):
+    _values: dict[str, Any]
+
+
+Owner = TypeVar("Owner", bound=HasValues)
+
+
 @dataclass(frozen=True)
 class ColumnSpec[T]:
     header: str | None = None  # header string in Excel
@@ -22,22 +29,31 @@ class ColumnSpec[T]:
 class Column[T]:
     def __init__(self, spec: ColumnSpec[T]):
         self.spec = spec
+        self.name: str | None = None
 
-    def __set_name__(self, owner, name: str):
+    def __set_name__(self, owner: type[Any], name: str) -> None:
         self.name = name
-        # register in definition order
         reg = owner.__dict__.get("__columns__")
         if reg is None:
             owner.__columns__ = []
         owner.__columns__.append(self)
 
-    def __get__(self, obj, objtype=None) -> T | Column | None:
+    @overload
+    def __get__(self, obj: None, objtype: type[Owner] | None = None) -> Column[T]: ...
+    @overload
+    def __get__(self, obj: Owner, objtype: type[Owner] | None = None) -> T | None: ...
+
+    def __get__(self, obj: Owner | None, objtype: type[Owner] | None = None) -> T | Column | None:
         if obj is None:
             return self
-        return obj._values.get(self.name)  # centralized storage
+        if self.name is None:
+            raise RuntimeError("Column __set_name__ did not run.")
+        return obj._values.get(self.name)
 
-    def __set__(self, obj, value: T | None):
+    def __set__(self, obj: Owner, value: T | None) -> None:
         self.validate(value)
+        if self.name is None:
+            raise RuntimeError("Column __set_name__ did not run.")
         obj._values[self.name] = value
 
     def parse_cell(self, raw: Any) -> T | None:

{excel_orm-0.1.1 → excel_orm-0.1.3}/src/excel_orm/orm.py

@@ -23,6 +23,8 @@ def _pluralize(s: str) -> str:
     # keep deliberately simple; can be swapped for inflect later
     if s.endswith("s"):
         return s
+    if s.endswith("y") and len(s) >= 2 and s[-2] not in "aeiou":
+        return s[:-1] + "ies"
     return s + "s"
 
 
@@ -84,7 +86,7 @@ class PivotSheetSpec:
 
     # field names on the model
     pivot_field: str
-    row_field: str
+    row_fields: list[str]
     value_field: str
 
     # layout
@@ -92,7 +94,6 @@ class PivotSheetSpec:
     header_row: int = 2  # pivot headers
     row_header_col: int = 1
     data_start_row: int = 3
-    data_start_col: int = 2
 
     # template: define the pivot column values (dates) to render across the top
     pivot_values: list[Any] | None = None  # e.g., list[date]; required for generation
@@ -102,6 +103,10 @@ class PivotSheetSpec:
 
     include_blanks: bool = False  # whether to load blank cells as data points
 
+    @property
+    def data_start_col(self) -> int:
+        return len(self.row_fields) + 1
+
 
 AnySheetSpec = PivotSheetSpec | SheetSpec
 
@@ -274,39 +279,54 @@ class ExcelFile:
         tcell.font = title_font
         tcell.alignment = title_alignment
 
-        # Top-left corner header (row field name)
-        corner = ws.cell(spec.header_row, spec.row_header_col, spec.row_field.title())
-        corner.font = header_font
+        # Row field headers (left block)
+        for i, rf in enumerate(spec.row_fields):
+            c = spec.row_header_col + i
+            cell = ws.cell(spec.header_row, c, rf.title())
+            cell.font = header_font
+            col_letter = cell.column_letter
+            ws.column_dimensions[col_letter].width = max(12, min(40, len(str(rf)) + 4))
 
         # Pivot headers across the top
         for j, pv in enumerate(spec.pivot_values):
             c = spec.data_start_col + j
             cell = ws.cell(spec.header_row, c, pv)
             cell.font = header_font
-
-            col_letter = ws.cell(spec.header_row, c).column_letter
+            col_letter = cell.column_letter
             ws.column_dimensions[col_letter].width = 14
 
-        # Seed row keys (optional)
         if spec.row_values:
             for i, rv in enumerate(spec.row_values):
                 r = spec.data_start_row + i
-                ws.cell(r, spec.row_header_col, rv)
+
+                if len(spec.row_fields) == 1:
+                    # Back-compat: rv is a single value
+                    ws.cell(r, spec.row_header_col, rv)
+                else:
+                    # Expect rv to be a tuple/list matching row_fields
+                    if not isinstance(rv, (tuple, list)) or len(rv) != len(spec.row_fields):
+                        raise ValueError(
+                            "For multi-row_fields, PivotSheetSpec.row_values must be a list of "
+                            f"tuples/lists with length {len(spec.row_fields)}."
+                        )
+                    for k, part in enumerate(rv):
+                        ws.cell(r, spec.row_header_col + k, part)
 
     def _parse_pivot_sheet(self, ws: Worksheet, spec: PivotSheetSpec) -> None:
         model = spec.model
         cols = {c.name: c for c in _get_model_columns(model)}  # Column descriptors by field name
 
         # Validate fields exist
-        for fname in (spec.pivot_field, spec.row_field, spec.value_field):
-            if fname not in cols:
-                raise ValueError(
-                    f"{model.__name__} is missing Column field '{fname}' required by PivotSheetSpec."
-                )
+        required = [spec.pivot_field, spec.value_field, *spec.row_fields]
+        missing = [f for f in required if f not in cols]
+        if missing:
+            raise ValueError(
+                f"{model.__name__} is missing Column field(s) required by PivotSheetSpec: {missing}"
+            )
 
         pivot_col = cols[spec.pivot_field]
-        row_col = cols[spec.row_field]
         val_col = cols[spec.value_field]
+        row_cols = [cols[f] for f in spec.row_fields]
 
         # Determine pivot headers from sheet (or trust spec.pivot_values)
         pivot_headers: list[Any] = []
@@ -326,11 +346,13 @@ class ExcelFile:
 
         r = spec.data_start_row
         while r <= ws.max_row:
-            raw_row_key = ws.cell(r, spec.row_header_col).value
-            if raw_row_key is None or str(raw_row_key).strip() == "":
+            raw_parts = [
+                ws.cell(r, spec.row_header_col + i).value for i in range(len(spec.row_fields))
+            ]
+            if _row_is_blank(raw_parts):
                 break
 
-            row_key = row_col.parse_cell(raw_row_key)
+            row_parts = [row_cols[i].parse_cell(raw_parts[i]) for i in range(len(row_cols))]
 
             for j, pivot_value in enumerate(pivot_headers):
                 c = spec.data_start_col + j
@@ -340,7 +362,8 @@ class ExcelFile:
 
                 obj = _instantiate_model(model)
 
-                setattr(obj, spec.row_field, row_key)
+                for fname, parsed in zip(spec.row_fields, row_parts, strict=False):
+                    setattr(obj, fname, parsed)
                 setattr(obj, spec.pivot_field, pivot_value)
                 setattr(obj, spec.value_field, val_col.parse_cell(raw_val))
 

{excel_orm-0.1.1 → excel_orm-0.1.3}/tests/conftest.py

@@ -51,6 +51,17 @@ def demand_model():
     return Demand
 
 
+@pytest.fixture
+def demand_two_pivot():
+    class Demand:
+        dt: Column[date] = date_column(header="Date")
+        region: Column[str] = text_column(header="Region", not_null=True)
+        product: Column[str] = text_column(header="Product", not_null=True)
+        value: Column[int] = int_column(header="Value", not_null=True)
+
+    return Demand
+
+
 @pytest.fixture
 def pivot_excel_file(demand_model):
     Demand = demand_model
@@ -66,7 +77,7 @@ def pivot_excel_file(demand_model):
         name="Demand",
         model=Demand,
         pivot_field="dt",
-        row_field="region",
+        row_fields=["region"],
         value_field="value",
         pivot_values=pivot_values,
         row_values=["NA", "EU"],  # seed some regions

{excel_orm-0.1.1 → excel_orm-0.1.3}/tests/test_orm.py

@@ -5,7 +5,8 @@ from datetime import date, datetime
 import pytest
 from openpyxl import load_workbook
 
-from excel_orm import ExcelFile, PivotSheetSpec
+from excel_orm import Column, ExcelFile, PivotSheetSpec, text_column
+from excel_orm.orm import SheetSpec
 
 
 def test_generate_template_creates_sheet_and_titles_and_headers(tmp_path, excel_file):
@@ -183,7 +184,7 @@ def test_load_data_pivot_stops_at_blank_region_row(tmp_path, demand_model):
         name="Demand",
         model=demand_model,
         pivot_field="dt",
-        row_field="region",
+        row_fields=["region"],
         value_field="value",
         pivot_values=pivot_values,
         row_values=None,  # user-entered regions
@@ -230,3 +231,111 @@ def test_load_data_missing_pivot_sheet_raises(tmp_path, pivot_excel_file):
 
     with pytest.raises(ValueError):
         pivot_excel_file.load_data(str(p))
+
+
+def test_pivot_two_row_fields_template_and_parse_end_to_end(tmp_path, demand_two_pivot):
+    """
+    Two row_fields case:
+      row_fields: [region, product]
+      pivot cols: Jun, Jul
+      row_values seeded with composite keys (NA/ABC, EU/ABC)
+    Validate:
+      - template layout places row headers in A2,B2
+      - pivot headers start at C2,D2
+      - seeded keys appear in A3,B3 and A4,B4
+      - parsing emits correct objects with BOTH row fields populated
+    """
+    pivot_values = [date(2025, 6, 1), date(2025, 7, 1)]
+    spec = PivotSheetSpec(
+        name="Demand",
+        model=demand_two_pivot,
+        pivot_field="dt",
+        row_fields=["region", "product"],
+        value_field="value",
+        pivot_values=pivot_values,
+        row_values=[("NA", "ABC"), ("EU", "ABC")],
+        row_header_col=1,
+        include_blanks=False,
+    )
+    xf = ExcelFile(sheets=[spec])
+
+    out = tmp_path / "pivot_two_row_fields.xlsx"
+    xf.generate_template(str(out))
+
+    wb = load_workbook(out)
+    ws = wb["Demand"]
+
+    # Title merged across A..D (A,B row headers + C,D pivot headers)
+    assert ws["A1"].value == "Demands"
+    merged = [str(rng) for rng in ws.merged_cells.ranges]
+    assert "A1:D1" in merged
+
+    # Row field headers in A2,B2
+    assert ws["A2"].value == "Region"
+    assert ws["B2"].value == "Product"
+
+    # Pivot headers start at C2..D2
+    assert _as_date(ws["C2"].value) == date(2025, 6, 1)
+    assert _as_date(ws["D2"].value) == date(2025, 7, 1)
+
+    # Seeded composite keys appear across A/B
+    assert ws["A3"].value == "NA"
+    assert ws["B3"].value == "ABC"
+    assert ws["A4"].value == "EU"
+    assert ws["B4"].value == "ABC"
+
+    # Fill matrix values: (row 3: NA/ABC), (row 4: EU/ABC)
+    ws["C3"].value = 10  # NA/ABC, Jun
+    ws["D3"].value = 20  # NA/ABC, Jul
+    ws["C4"].value = 5  # EU/ABC, Jun
+    ws["D4"].value = 0  # EU/ABC, Jul
+
+    wb.save(out)
+
+    xf.load_data(str(out))
+    rows = xf.demands.all()  # repo name plural of Demand
+
+    # Expect 4 objects (2 rows x 2 pivots)
+    assert len(rows) == 4
+
+    got = {(r.region, r.product, r.dt, r.value) for r in rows}
+    expected = {
+        ("NA", "ABC", date(2025, 6, 1), 10),
+        ("NA", "ABC", date(2025, 7, 1), 20),
+        ("EU", "ABC", date(2025, 6, 1), 5),
+        ("EU", "ABC", date(2025, 7, 1), 0),
+    }
+    assert got == expected
+
+
+def test_duplicate_header_names_do_not_clash(tmp_path, models):
+    Car, _ = models
+
+    class ManufacturingPlant:
+        name: Column[str] = text_column(header="Make", not_null=True)
+        location: Column[str] = text_column(header="location")
+
+    sheet = SheetSpec(name="Cars", models=[Car, ManufacturingPlant])
+    file = ExcelFile(sheets=[sheet])
+    out = tmp_path / "duplicate_headers.xlsx"
+    file.generate_template(out)
+
+    wb = load_workbook(out)
+    ws = wb["Cars"]
+
+    ws["A3"].value = "Acura"
+    ws["B3"].value = "TSX"
+    ws["C3"].value = 2005
+
+    ws["F3"].value = "Duplicate"
+    ws["G3"].value = "New Jersey"
+
+    wb.save(out)
+
+    file.load_data(out)
+
+    cars = file.cars.all()
+    plants = file.manufacturing_plants.all()
+
+    assert plants[0].name == "Duplicate"
+    assert plants[0].location == "New Jersey"

{excel_orm-0.1.1 → excel_orm-0.1.3}/uv.lock

@@ -187,7 +187,7 @@ wheels = [
 
 [[package]]
 name = "excel-orm"
-version = "0.1.1"
+version = "0.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "openpyxl" },

excel_orm-0.1.1/README.md

@@ -1,253 +0,0 @@
-# Excel ORM
-
-A lightweight, typed “Excel ORM” for generating Excel templates and parsing Excel workbooks into Python objects using column descriptors.
-
-This project is designed for the common enterprise pattern where you:
-1) generate a structured `.xlsx` template for users,
-2) let users fill it in,
-3) load the workbook back into Python, producing typed objects grouped by model.
-
-It uses `openpyxl` for reading/writing Excel files and supports multiple model “tables” on the same worksheet.
-
----
-
-## Features
-
-- **Typed column descriptors** (`text_column`, `int_column`, `bool_column`, `date_column`)
-- **Template generation** with:
-  - merged **table title cells** (pluralized model name)
-  - bold headers
-  - sensible column widths
-  - multiple tables laid out horizontally on the same sheet with a configurable gap
-- **Workbook parsing** into model-specific repositories:
-  - `excel_file.cars.all()` → `list[Car]`
-  - `excel_file.manufacturing_plants.all()` → `list[ManufacturingPlant]`
-- **Validation hooks**
-  - column-level `not_null`
-  - optional row exclusion rules via `excludes`
-  - optional model-level `validate()` method
-
----
-
-## Installation
-
-### From PyPI (once published)
-```bash
-pip install excel-orm
-````
-
-### From source (uv)
-
-```bash
-git clone <your-repo-url>
-cd excel-orm
-uv sync
-```
-
----
-
-## Quick Start
-
-### 1) Define models using `Column[...]` descriptors
-
-```python
-from excel_orm.column import Column, text_column, int_column
-from excel_orm.orm import ExcelFile, SheetSpec
-
-class Car:
-    make: Column[str] = text_column(header="Make", not_null=True)
-    model: Column[str] = text_column(header="Model", not_null=True)
-    year: Column[int] = int_column(header="Year", not_null=True)
-
-class ManufacturingPlant:
-    name: Column[str] = text_column(header="Factory Name", not_null=True)
-    location: Column[str] = text_column(header="Location")
-```
-
-### 2) Declare a sheet containing multiple models
-
-Each model becomes its own table on the same worksheet.
-
-```python
-sheet = SheetSpec(
-    name="Cars",
-    models=[Car, ManufacturingPlant],
-
-    # Layout rows
-    title_row=1,
-    header_row=2,
-    data_start_row=3,
-
-    # Horizontal spacing between model tables
-    template_table_gap=2,
-)
-```
-
-### 3) Create an `ExcelFile`, generate a template, then load data
-
-```python
-excel_file = ExcelFile(sheets=[sheet])
-
-# Generate a blank template workbook
-excel_file.generate_template("car_inventory_template.xlsx")
-
-# Users fill in data in Excel...
-
-# Load the filled workbook into repositories
-excel_file.load_data("car_inventory_data.xlsx")
-
-cars = excel_file.cars.all()
-plants = excel_file.manufacturing_plants.all()
-
-print(cars[0].make, cars[0].year)
-print(plants[0].name, plants[0].location)
-```
-
----
-
-## How It Works
-
-### Repositories
-
-For each model you register, `ExcelFile` creates a repository attribute on the instance using a snake_case pluralized name:
-
-* `Car` → `excel_file.cars`
-* `ManufacturingPlant` → `excel_file.manufacturing_plants`
-
-Repositories are simple list-like containers with an `all()` helper:
-
-```python
-cars = excel_file.cars.all()  # list[Car]
-```
-
-### Multi-table Sheets
-
-A single worksheet can host multiple model tables. During template generation:
-
-* A merged title cell is written above each table (pluralized class name in title case).
-* Headers appear under the title.
-* Data rows begin at `data_start_row`.
-* Tables are placed horizontally with `template_table_gap` blank columns between them.
-
-During parsing:
-
-* The library locates each model table by matching the expected header sequence.
-* It reads contiguous rows until a blank row is encountered.
-
----
-
-## Column Types
-
-### Text
-
-```python
-from excel_orm.column import Column, text_column
-
-class Example:
-    name: Column[str] = text_column(header="Name", not_null=True, strip=True)
-```
-
-* `None` parses to `""` (empty string).
-* `strip=True` trims whitespace.
-
-### Integer
-
-```python
-from excel_orm.column import Column, int_column
-
-class Example:
-    qty: Column[int] = int_column(header="Qty", not_null=True)
-```
-
-* `None` or `""` parses to `0`.
-
-### Boolean
-
-```python
-from excel_orm.column import Column, bool_column
-
-class Example:
-    active: Column[bool] = bool_column(header="Active")
-```
-
-Accepted values include:
-
-* True: `true, t, yes, y, 1` (case-insensitive)
-* False: `false, f, no, n, 0`
-* `None` / empty parses to `False`
-
-Invalid values raise `ValueError`.
-
-### Date
-
-```python
-from excel_orm.column import Column, date_column
-
-class Example:
-    start_date: Column[date] = date_column(header="Start Date")
-```
-
-The date parser supports:
-
-* Excel-native `datetime`/`date` values from `openpyxl`
-* ISO strings like `2025-06-01` and `2025-06-01T13:45:00`
-* Common business formats including `01-JUN-2025`
-
-Invalid/empty values raise `ValueError`.
-
----
-
-## Validation
-
-### Column-level: `not_null`
-
-```python
-class Car:
-    make: Column[str] = text_column(header="Make", not_null=True)
-```
-
-If a `not_null=True` column parses to `None` or `""`, a `ValueError` is raised.
-
-### Row exclusion: `excludes`
-
-If you set `excludes`, rows matching those raw values in that column will be skipped.
-
-```python
-status: Column[str] = text_column(header="Status")
-status.spec.excludes = {"IGNORE", "SKIP"}  # example pattern
-```
-
-(If you want a nicer API for excludes, consider adding it directly to the column factory signature.)
-
-### Model-level: `validate()`
-
-If your model defines a `validate(self)` method, it is called after a row is parsed.
-
-```python
-class Car:
-    make: Column[str] = text_column(header="Make", not_null=True)
-    year: Column[int] = int_column(header="Year", not_null=True)
-
-    def validate(self) -> None:
-        if self.year < 1886:
-            raise ValueError("Invalid car year")
-```
-
----
-
-## Development
-
-### Run tests
-
-```bash
-uv run pytest
-```
-
-### Lint/format (example)
-
-If you use Ruff:
-
-```bash
-uv run ruff check .
-uv run ruff format .
-```