excel-orm 0.1.6__py3-none-any.whl

excel_orm/__init__.py

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

excel_orm/base.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    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/column.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date, datetime
+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
+    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
+        self.name: str | None = None
+
+    def __set_name__(self, owner: type[Any], name: str) -> None:
+        self.name = name
+        reg = owner.__dict__.get("__columns__")
+        if reg is None:
+            owner.__columns__ = []
+        owner.__columns__.append(self)
+
+    @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: ...
+
+    def __get__(self, obj: Owner | None, objtype: type[Owner] | None = None) -> T | Column:
+        if obj is None:
+            return self
+        if self.name is None:
+            raise RuntimeError("Column __set_name__ did not run.")
+        return obj._values.get(self.name)
+
+    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:
+        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,
+) -> Column[str]:
+    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,
+) -> Column[int]:
+    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) -> Column[bool]:
+    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) -> Column[date]:
+    _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/orm.py

@@ -0,0 +1,376 @@
+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
+    if s.endswith("y") and len(s) >= 2 and s[-2] not in "aeiou":
+        return s[:-1] + "ies"
+    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_fields: list[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
+
+    # 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
+
+    @property
+    def data_start_col(self) -> int:
+        return len(self.row_fields) + 1
+
+
+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
+
+        # 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 = cell.column_letter
+            ws.column_dimensions[col_letter].width = 14
+
+        if spec.row_values:
+            for i, rv in enumerate(spec.row_values):
+                r = spec.data_start_row + i
+
+                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
+        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]
+        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] = []
+        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_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_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
+                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)
+
+                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))
+
+                validate = getattr(obj, "validate", None)
+                if callable(validate):
+                    validate()
+
+                repo.append(obj)
+
+            r += 1

excel_orm-0.1.6.dist-info/METADATA

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: excel-orm
+Version: 0.1.6
+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.12
+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” 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.6.dist-info/RECORD

@@ -0,0 +1,7 @@
+excel_orm/__init__.py,sha256=L8BOQiL1OGb7legxP59h1iBcJc9-oF7YNu5D-Bmr_VQ,392
+excel_orm/base.py,sha256=P1jcbO93ohqQqQHLN-9V66pCRd9FdU_v91_0S9NKZ90,503
+excel_orm/column.py,sha256=jburc06vvCvmPV1Xa0UQ3FQHqk7Darz9yJDyJZhT1gs,5443
+excel_orm/orm.py,sha256=8vlJCdCxt-o13hq88JQnGkVPG3nLsd27Ooe7iAy_IkQ,12504
+excel_orm-0.1.6.dist-info/METADATA,sha256=_2pZUEcCkl8BQNWmEGDbTk4lGVBwMtFwUy6oYh3Bgro,9311
+excel_orm-0.1.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+excel_orm-0.1.6.dist-info/RECORD,,

excel_orm-0.1.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any