excel-orm 0.1.0__tar.gz

excel_orm-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.ruff_cache/
+.pytest_cache/
+.git/
+.env

excel_orm-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: excel-orm
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/acdelrusso/excel-orm/issues
+Author: Anthony Del Russo
+License: MIT
+Keywords: etl,excel,openpyxl,orm
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.13
+Requires-Dist: openpyxl>=3.1.5
+Description-Content-Type: text/markdown
+
+# 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 .
+```

excel_orm-0.1.0/README.md

@@ -0,0 +1,253 @@
+# 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 .
+```

excel_orm-0.1.0/excel_orm/__init__.py

@@ -0,0 +1,14 @@
+from .column import Column, ColumnSpec, bool_column, date_column, int_column, text_column
+from .orm import ExcelFile, PivotSheetSpec, SheetSpec
+
+__all__ = [
+    "Column",
+    "ColumnSpec",
+    "ExcelFile",
+    "PivotSheetSpec",
+    "SheetSpec",
+    "bool_column",
+    "date_column",
+    "int_column",
+    "text_column",
+]

excel_orm-0.1.0/excel_orm/column.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ColumnSpec[T]:
+    header: str | None = None  # header string in Excel
+    default: T | None = None
+    not_null: bool = False  # parsed value cannot be None/empty
+    excludes: set[Any] | None = None  # raw values that mark row as excluded
+    parser: Callable[[Any], T] = lambda x: x  # raw -> parsed
+    renderer: Callable[[T | None], Any] = lambda x: x  # parsed -> raw
+    validator: Callable[[T | None], None] = lambda _: None
+
+
+class Column[T]:
+    def __init__(self, spec: ColumnSpec[T]):
+        self.spec = spec
+
+    def __set_name__(self, owner, name: str):
+        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:
+        if obj is None:
+            return self
+        return obj._values.get(self.name)  # centralized storage
+
+    def __set__(self, obj, value: T | None):
+        self.validate(value)
+        obj._values[self.name] = value
+
+    def parse_cell(self, raw: Any) -> T | None:
+        return self.spec.parser(raw)
+
+    def validate(self, value: T | None) -> None:
+        if self.spec.not_null and (value is None or value == ""):
+            raise ValueError(f"{self.name} cannot be null/empty")
+        self.spec.validator(value)
+
+
+def text_column(
+    header: str | None = None,
+    *,
+    default: str | None = None,
+    strip: bool = True,
+    not_null: bool = False,
+):
+    def parse(raw: Any) -> str:
+        if raw is None:
+            return ""
+        s = str(raw)
+        if strip:
+            s = s.strip()
+        return s
+
+    return Column(
+        ColumnSpec[str](
+            header=header,
+            default=default,
+            not_null=not_null,
+            parser=parse,
+            renderer=lambda v: "" if v is None else v,
+        )
+    )
+
+
+def int_column(
+    header: str | None = None,
+    *,
+    default: int | None = None,
+    not_null: bool = False,
+):
+    def parse(raw: Any) -> int:
+        if raw is None or raw == "":
+            return 0
+        return int(raw)
+
+    return Column(
+        ColumnSpec[int](
+            header=header,
+            default=default,
+            not_null=not_null,
+            parser=parse,
+        )
+    )
+
+
+def bool_column(header: str | None = None, *, default: bool | None = None):
+    def parse(raw: Any) -> bool:
+        if raw is None or raw == "":
+            return False
+        if isinstance(raw, bool):
+            return raw
+        s = str(raw).strip().lower()
+        if s in {"true", "t", "yes", "y", "1"}:
+            return True
+        if s in {"false", "f", "no", "n", "0"}:
+            return False
+        raise ValueError(f"Invalid boolean: {raw}")
+
+    return Column(
+        ColumnSpec[bool](
+            header=header,
+            default=default,
+            parser=parse,
+        )
+    )
+
+
+def date_column(header: str | None = None, *, default: date | None = None):
+    _DATE_FORMATS: tuple[str, ...] = (
+        "%d-%b-%Y",  # 01-JUN-2025  (your requirement)
+        "%d-%b-%y",  # 01-JUN-25
+        "%d %b %Y",  # 01 JUN 2025
+        "%d %b %y",  # 01 JUN 25
+        "%d/%b/%Y",  # 01/JUN/2025
+        "%Y-%m-%d",  # 2025-06-01
+        "%Y/%m/%d",  # 2025/06/01
+        "%m/%d/%Y",  # 06/01/2025
+        "%m/%d/%y",  # 06/01/25
+        "%d/%m/%Y",  # 01/06/2025
+        "%d/%m/%y",  # 01/06/25
+    )
+
+    def parse(raw: Any) -> date:
+        if raw is None or raw == "":
+            raise ValueError("Date Value was empty")
+
+        if isinstance(raw, date) and not isinstance(raw, datetime):
+            return raw
+
+        if isinstance(raw, datetime):
+            return raw.date()
+
+        s = str(raw).strip()
+        if s == "":
+            raise ValueError("Date Value was empty")
+
+        # 1) ISO-8601 fast path (handles "2025-06-01" and "2025-06-01T13:45:00", etc.)
+        try:
+            dt = datetime.fromisoformat(s)
+            return dt.date()
+        except ValueError:
+            pass
+
+        # 2) Try known patterns (case-insensitive month abbreviations like JUN)
+        s_norm = s.upper()
+
+        for fmt in _DATE_FORMATS:
+            try:
+                return datetime.strptime(s_norm, fmt).date()
+            except ValueError:
+                continue
+
+        raise ValueError(f"Invalid date value: {raw!r}")
+
+    return Column(
+        ColumnSpec[date](
+            header=header,
+            default=default,
+            parser=parse,
+            renderer=lambda d: None if d is None else d,  # openpyxl handles date types
+        )
+    )

excel_orm-0.1.0/excel_orm/orm.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from openpyxl import Workbook, load_workbook
+from openpyxl.styles import Alignment, Font
+from openpyxl.worksheet.worksheet import Worksheet
+
+from .column import Column
+
+M = TypeVar("M")
+
+
+def _camel_to_snake(name: str) -> str:
+    s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
+    s2 = re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1)
+    return s2.lower()
+
+
+def _pluralize(s: str) -> str:
+    # keep deliberately simple; can be swapped for inflect later
+    if s.endswith("s"):
+        return s
+    return s + "s"
+
+
+def _repo_name_for_model(model: type[Any]) -> str:
+    return _pluralize(_camel_to_snake(model.__name__))
+
+
+def _display_name_for_model(model: type[Any]) -> str:
+    # "manufacturing_plants" -> "Manufacturing Plants"
+    return _repo_name_for_model(model).replace("_", " ").title()
+
+
+def _get_model_columns(model: type[Any]) -> list[Column[Any]]:
+    return list(getattr(model, "__columns__", []))
+
+
+def _normalize_header(v: Any) -> str:
+    if v is None:
+        return ""
+    return str(v).strip()
+
+
+def _row_is_blank(values: list[Any]) -> bool:
+    return all(_normalize_header(v) == "" for v in values)
+
+
+def _instantiate_model[M](model: type[M]) -> M:
+    obj = model.__new__(model)
+    obj._values = {}
+    # defaults
+    for col in _get_model_columns(model):
+        if col.name is None:
+            raise RuntimeError("Column __set_name__ did not run.")
+        obj._values[col.name] = col.spec.default
+    return obj
+
+
+class Repository(list[M]):
+    def all(self) -> list[M]:
+        return list(self)
+
+
+@dataclass(frozen=True)
+class SheetSpec:
+    name: str
+    models: list[type[Any]]
+
+    title_row: int = 1
+    header_row: int = 2
+    data_start_row: int = 3
+
+    template_table_gap: int = 2
+
+
+@dataclass(frozen=True)
+class PivotSheetSpec:
+    name: str
+    model: type[Any]  # single model only
+
+    # field names on the model
+    pivot_field: str
+    row_field: str
+    value_field: str
+
+    # layout
+    title_row: int = 1
+    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
+
+    # optional: seed row keys (regions) on template
+    row_values: list[Any] | None = None
+
+    include_blanks: bool = False  # whether to load blank cells as data points
+
+
+AnySheetSpec = PivotSheetSpec | SheetSpec
+
+
+class ExcelFile:
+    def __init__(self, *, sheets: list[AnySheetSpec]):
+        self.sheets = sheets
+
+        self._repos: dict[type[Any], Repository[Any]] = {}
+
+        for sheet in sheets:
+            models = [sheet.model] if isinstance(sheet, PivotSheetSpec) else sheet.models
+
+            for model in models:
+                repo_name = _repo_name_for_model(model)
+                if hasattr(self, repo_name):
+                    raise ValueError(
+                        f"Duplicate repo name '{repo_name}' for model {model.__name__}"
+                    )
+                repo = Repository()
+                self._repos[model] = repo
+                setattr(self, repo_name, repo)
+
+    def generate_template(self, filename: str) -> None:
+        wb = Workbook()
+        default_ws = wb.active
+        if self.sheets:
+            wb.remove(default_ws)
+
+        for sheet in self.sheets:
+            ws = wb.create_sheet(title=sheet.name)
+            if isinstance(sheet, PivotSheetSpec):
+                self._write_pivot_sheet_template(ws, sheet)
+            else:
+                self._write_sheet_template(ws, sheet)
+
+        wb.save(filename)
+
+    def _write_sheet_template(self, ws: Worksheet, spec: SheetSpec) -> None:
+        current_col = 1  # 1-based index
+
+        title_font = Font(bold=True)
+        title_alignment = Alignment(horizontal="center", vertical="center")
+
+        header_font = Font(bold=True)
+
+        for model in spec.models:
+            cols = _get_model_columns(model)
+            headers = [c.spec.header or c.name for c in cols]
+            width = len(headers)
+
+            start_col = current_col
+            end_col = current_col + width - 1
+
+            # ---- merged title row ----
+            ws.merge_cells(
+                start_row=spec.title_row,
+                start_column=start_col,
+                end_row=spec.title_row,
+                end_column=end_col,
+            )
+            title_cell = ws.cell(
+                row=spec.title_row, column=start_col, value=_display_name_for_model(model)
+            )
+            title_cell.font = title_font
+            title_cell.alignment = title_alignment
+
+            for j, h in enumerate(headers):
+                c = start_col + j
+                cell = ws.cell(row=spec.header_row, column=c, value=h)
+                cell.font = header_font
+
+                col_letter = ws.cell(row=spec.header_row, column=c).column_letter
+                ws.column_dimensions[col_letter].width = max(12, min(40, len(str(h)) + 4))
+
+            current_col = end_col + 1 + spec.template_table_gap
+
+    def load_data(self, filename: str) -> None:
+        wb = load_workbook(filename=filename, data_only=True)
+        for repo in self._repos.values():
+            repo.clear()
+
+        for sheet_spec in self.sheets:
+            if sheet_spec.name not in wb.sheetnames:
+                raise ValueError(f"Workbook missing sheet '{sheet_spec.name}'")
+            ws = wb[sheet_spec.name]
+            if isinstance(sheet_spec, PivotSheetSpec):
+                self._parse_pivot_sheet(ws, sheet_spec)
+            else:
+                self._parse_sheet(ws, sheet_spec)
+
+    def _parse_sheet(self, ws: Worksheet, spec: SheetSpec) -> None:
+        for model in spec.models:
+            found = self._find_header(ws, spec, model)
+            if found is None:
+                continue
+
+            _, start_col = found
+            cols = _get_model_columns(model)
+            width = len(cols)
+
+            repo: Repository[Any] = self._repos[model]
+
+            r = spec.data_start_row
+            while r <= ws.max_row:
+                row_vals = [ws.cell(row=r, column=start_col + j).value for j in range(width)]
+                if _row_is_blank(row_vals):
+                    break
+
+                # excludes (raw-value based)
+                if any(
+                    col.spec.excludes and row_vals[i] in col.spec.excludes
+                    for i, col in enumerate(cols)
+                ):
+                    r += 1
+                    continue
+
+                obj = _instantiate_model(model)
+                for i, col in enumerate(cols):
+                    raw = row_vals[i]
+                    parsed = col.parse_cell(raw)
+                    setattr(obj, col.name, parsed)
+
+                validate = getattr(obj, "validate", None)
+                if callable(validate):
+                    validate()
+
+                repo.append(obj)
+                r += 1
+
+    def _find_header(
+        self, ws: Worksheet, spec: SheetSpec, model: type[Any]
+    ) -> tuple[int, int] | None:
+        cols = _get_model_columns(model)
+        expected = [_normalize_header(c.spec.header) for c in cols]
+        if not expected:
+            return None
+
+        r = spec.header_row
+        width = len(expected)
+        max_c = ws.max_column or 0
+
+        for start_col in range(1, max_c - width + 2):
+            actual = [
+                _normalize_header(ws.cell(row=r, column=start_col + j).value) for j in range(width)
+            ]
+            if actual == expected:
+                return (r, start_col)
+
+        return None
+
+    def _write_pivot_sheet_template(self, ws: Worksheet, spec: PivotSheetSpec) -> None:
+        if not spec.pivot_values:
+            raise ValueError("PivotSheetSpec.pivot_values is required for template generation.")
+
+        title_font = Font(bold=True)
+        title_alignment = Alignment(horizontal="center", vertical="center")
+        header_font = Font(bold=True)
+
+        # Title merged across the pivot header span
+        end_col = spec.data_start_col + len(spec.pivot_values) - 1
+
+        ws.merge_cells(
+            start_row=spec.title_row,
+            start_column=spec.row_header_col,
+            end_row=spec.title_row,
+            end_column=end_col,
+        )
+        tcell = ws.cell(spec.title_row, spec.row_header_col, _display_name_for_model(spec.model))
+        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
+
+        # 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
+            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)
+
+    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."
+                )
+
+        pivot_col = cols[spec.pivot_field]
+        row_col = cols[spec.row_field]
+        val_col = cols[spec.value_field]
+
+        # Determine pivot headers from sheet (or trust spec.pivot_values)
+        pivot_headers: list[Any] = []
+        j = 0
+        while True:
+            c = spec.data_start_col + j
+            raw = ws.cell(spec.header_row, c).value
+            if raw is None or str(raw).strip() == "":
+                break
+            pivot_headers.append(pivot_col.parse_cell(raw))
+            j += 1
+
+        if not pivot_headers:
+            return
+
+        repo: Repository[Any] = self._repos[model]
+
+        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() == "":
+                break
+
+            row_key = row_col.parse_cell(raw_row_key)
+
+            for j, pivot_value in enumerate(pivot_headers):
+                c = spec.data_start_col + j
+                raw_val = ws.cell(r, c).value
+                if not spec.include_blanks and (raw_val is None or raw_val == ""):
+                    continue
+
+                obj = _instantiate_model(model)
+
+                setattr(obj, spec.row_field, row_key)
+                setattr(obj, spec.pivot_field, pivot_value)
+                setattr(obj, spec.value_field, val_col.parse_cell(raw_val))
+
+                validate = getattr(obj, "validate", None)
+                if callable(validate):
+                    validate()
+
+                repo.append(obj)
+
+            r += 1

excel_orm-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "excel-orm"
+version = "0.1.0"
+description = "A lightweight Excel ORM for generating templates and parsing typed row models."
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+authors = [{ name = "Anthony Del Russo" }]
+keywords = ["excel", "orm", "openpyxl", "etl"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+    "openpyxl>=3.1.5",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.3.0",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.10",
+    "twine>=6.2.0",
+    "ty>=0.0.8",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ty]
+
+[tool.ty.rules]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/acdelrusso/excel-orm"
+Repository = "https://github.com/acdelrusso/excel-orm"
+Issues = "https://github.com/acdelrusso/excel-orm/issues"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+packages = ["src/excel_orm"]