excel-orm 0.1.2__tar.gz → 0.1.4__tar.gz

{excel_orm-0.1.2 → excel_orm-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excel-orm
-Version: 0.1.2
+Version: 0.1.4
 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.4/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.2 → excel_orm-0.1.4}/pyproject.toml

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

{excel_orm-0.1.2 → excel_orm-0.1.4}/src/excel_orm/__init__.py

@@ -1,4 +1,12 @@
-from .column import Column, ColumnSpec, bool_column, date_column, int_column, text_column
+from .base import RowBase
+from .column import (
+    Column,
+    ColumnSpec,
+    bool_column,
+    date_column,
+    int_column,
+    text_column,
+)
 from .orm import ExcelFile, PivotSheetSpec, SheetSpec
 
 __all__ = [
@@ -6,6 +14,7 @@ __all__ = [
     "ColumnSpec",
     "ExcelFile",
     "PivotSheetSpec",
+    "RowBase",
     "SheetSpec",
     "bool_column",
     "date_column",

excel_orm-0.1.4/src/excel_orm/base.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from excel_orm import Column
+
+
+class RowBase:
+    __columns__: list[Column[Any]]
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._values: dict[str, Any] = {}
+
+        for col in getattr(self, "__columns__", []):
+            if col.name is None:
+                continue
+            self._values[col.name] = col.spec.default
+
+        for k, v in kwargs.items():
+            setattr(self, k, v)

{excel_orm-0.1.2 → excel_orm-0.1.4}/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.2 → excel_orm-0.1.4}/tests/conftest.py

@@ -2,6 +2,7 @@ from datetime import date
 
 import pytest
 
+from excel_orm.base import RowBase
 from src.excel_orm import (
     Column,
     ExcelFile,
@@ -15,12 +16,12 @@ from src.excel_orm import (
 
 @pytest.fixture
 def models():
-    class Car:
+    class Car(RowBase):
         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:
+    class ManufacturingPlant(RowBase):
         name: Column[str] = text_column(header="Factory Name", not_null=True)
         location: Column[str] = text_column(header="Location")
 
@@ -53,7 +54,7 @@ def demand_model():
 
 @pytest.fixture
 def demand_two_pivot():
-    class Demand:
+    class Demand(RowBase):
         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)

{excel_orm-0.1.2 → excel_orm-0.1.4}/tests/test_columns.py

@@ -4,11 +4,18 @@ from datetime import date, datetime
 
 import pytest
 
-from src.excel_orm import Column, bool_column, date_column, int_column, text_column
+from src.excel_orm import (
+    Column,
+    RowBase,
+    bool_column,
+    date_column,
+    int_column,
+    text_column,
+)
 
 
 def test_descriptor_stores_in_values_dict():
-    class Foo:
+    class Foo(RowBase):
         a: Column[str] = text_column(header="A")
 
     f = Foo()
@@ -20,14 +27,14 @@ def test_descriptor_stores_in_values_dict():
 
 
 def test_descriptor_class_level_access_returns_column():
-    class Foo:
+    class Foo(RowBase):
         a: Column[str] = text_column(header="A")
 
     assert isinstance(Foo.a, Column)
 
 
 def test_not_null_validation_raises_on_none_or_empty():
-    class Foo:
+    class Foo(RowBase):
         a: Column[str] = text_column(header="A", not_null=True)
 
     f = Foo()
@@ -108,3 +115,4 @@ def test_date_column_invalid_raises():
     col = date_column(header="D")
     with pytest.raises(ValueError):
         col.parse_cell("not-a-date")
+        col.parse_cell("   ")

{excel_orm-0.1.2 → excel_orm-0.1.4}/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, RowBase, text_column
+from excel_orm.orm import SheetSpec
 
 
 def test_generate_template_creates_sheet_and_titles_and_headers(tmp_path, excel_file):
@@ -305,3 +306,36 @@ def test_pivot_two_row_fields_template_and_parse_end_to_end(tmp_path, demand_two
         ("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(RowBase):
+        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.2 → excel_orm-0.1.4}/tests/test_orm_helpers.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from excel_orm import RowBase
 from src.excel_orm import Column, int_column, text_column
 from src.excel_orm.orm import (
     _camel_to_snake,
@@ -31,7 +32,7 @@ def test_repo_and_display_name():
 
 
 def test_get_model_columns_respects_annotation_order():
-    class A:
+    class A(RowBase):
         x: Column[str] = text_column(header="X")
         y: Column[int] = int_column(header="Y")
 
@@ -40,7 +41,7 @@ def test_get_model_columns_respects_annotation_order():
 
 
 def test_instantiate_model_sets_defaults_and_requires_set_name():
-    class A:
+    class A(RowBase):
         x: Column[str] = text_column(header="X", default="dflt")
 
     a = _instantiate_model(A)

{excel_orm-0.1.2 → excel_orm-0.1.4}/uv.lock

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

excel_orm-0.1.2/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 .
-```