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

{excel_orm-0.1.0 → excel_orm-0.1.2}/.gitignore

@@ -12,4 +12,5 @@ wheels/
 .ruff_cache/
 .pytest_cache/
 .git/
-.env
+.env
+.pypirc

excel_orm-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,80 @@
+# .pre-commit-config.yaml
+default_stages: [pre-commit]
+
+minimum_pre_commit_version: "3.7.0"
+
+exclude: |
+  (?x)(
+      ^\.venv/|
+      ^dist/|
+      ^build/|
+      ^\.mypy_cache/|
+      ^\.ruff_cache/|
+      ^\.pytest_cache/|
+      ^\.tox/|
+      ^node_modules/|
+      ^docs/_build/
+  )
+
+repos:
+  # -------------------------
+  # Baseline hygiene hooks
+  # -------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: check-added-large-files
+        args: ["--maxkb=1500"]
+      - id: detect-private-key
+      - id: debug-statements
+
+  # -------------------------
+  # uv: lockfile / export consistency
+  # Official hook repo: astral-sh/uv-pre-commit :contentReference[oaicite:1]{index=1}
+  # -------------------------
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.18
+    hooks:
+      # Ensure uv.lock matches pyproject.toml changes
+      - id: uv-lock
+        stages: [pre-commit]
+
+  # -------------------------
+  # Ruff (lint + format)
+  # Official integration: astral-sh/ruff-pre-commit :contentReference[oaicite:2]{index=2}
+  # Order note when using --fix: lint before format :contentReference[oaicite:3]{index=3}
+  # -------------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+        stages: [pre-commit]
+      - id: ruff-format
+        stages: [pre-commit]
+
+  # -------------------------
+  # Local hooks that run via uv so they use your pinned toolchain.
+  # This is the cleanest way to integrate ty + pytest today.
+  # ty CLI: `ty check` :contentReference[oaicite:4]{index=4}
+  # -------------------------
+  - repo: local
+    hooks:
+      - id: ty-check
+        name: ty (type check)
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: pytest
+        name: pytest
+        entry: uv run pytest -q
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

excel_orm-0.1.2/.python-version

@@ -0,0 +1 @@
+3.13

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excel-orm
-Version: 0.1.0
+Version: 0.1.2
 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

{excel_orm-0.1.0 → excel_orm-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "excel-orm"
-version = "0.1.0"
+version = "0.1.2"
 description = "A lightweight Excel ORM for generating templates and parsing typed row models."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -15,18 +15,16 @@ classifiers = [
   "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
 ]
-dependencies = [
-    "openpyxl>=3.1.5",
-]
+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",
+  "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]
@@ -58,5 +56,5 @@ Issues = "https://github.com/acdelrusso/excel-orm/issues"
 requires = ["hatchling>=1.25"]
 build-backend = "hatchling.build"
 
-[tool.hatch.build]
+[tool.hatch.build.targets.wheel]
 packages = ["src/excel_orm"]

{excel_orm-0.1.0 → excel_orm-0.1.2/src}/excel_orm/orm.py

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

excel_orm-0.1.2/tests/conftest.py

@@ -0,0 +1,86 @@
+from datetime import date
+
+import pytest
+
+from src.excel_orm import (
+    Column,
+    ExcelFile,
+    PivotSheetSpec,
+    SheetSpec,
+    date_column,
+    int_column,
+    text_column,
+)
+
+
+@pytest.fixture
+def models():
+    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")
+
+    return Car, ManufacturingPlant
+
+
+@pytest.fixture
+def excel_file(models):
+    Car, ManufacturingPlant = models
+    sheet = SheetSpec(
+        name="Cars",
+        models=[Car, ManufacturingPlant],
+        title_row=1,
+        header_row=2,
+        data_start_row=3,
+        template_table_gap=2,
+    )
+    return ExcelFile(sheets=[sheet])
+
+
+@pytest.fixture
+def demand_model():
+    class Demand:
+        dt: Column[date] = date_column(header="Date")
+        region: Column[str] = text_column(header="Region", not_null=True)
+        value: Column[int] = int_column(header="Value", not_null=True)
+
+    return Demand
+
+
+@pytest.fixture
+def demand_two_pivot():
+    class Demand:
+        dt: Column[date] = date_column(header="Date")
+        region: Column[str] = text_column(header="Region", not_null=True)
+        product: Column[str] = text_column(header="Product", not_null=True)
+        value: Column[int] = int_column(header="Value", not_null=True)
+
+    return Demand
+
+
+@pytest.fixture
+def pivot_excel_file(demand_model):
+    Demand = demand_model
+
+    # Pre-defined pivot values across the top of the sheet
+    pivot_values = [
+        date(2025, 6, 1),
+        date(2025, 7, 1),
+        date(2025, 8, 1),
+    ]
+
+    spec = PivotSheetSpec(
+        name="Demand",
+        model=Demand,
+        pivot_field="dt",
+        row_fields=["region"],
+        value_field="value",
+        pivot_values=pivot_values,
+        row_values=["NA", "EU"],  # seed some regions
+    )
+
+    return ExcelFile(sheets=[spec])

excel_orm-0.1.2/tests/test_columns.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+
+import pytest
+
+from src.excel_orm import Column, bool_column, date_column, int_column, text_column
+
+
+def test_descriptor_stores_in_values_dict():
+    class Foo:
+        a: Column[str] = text_column(header="A")
+
+    f = Foo()
+    f._values = {}  # ty:ignore[unresolved-attribute]
+
+    f.a = "hello"
+    assert f._values["a"] == "hello"  # ty:ignore[unresolved-attribute]
+    assert f.a == "hello"
+
+
+def test_descriptor_class_level_access_returns_column():
+    class Foo:
+        a: Column[str] = text_column(header="A")
+
+    assert isinstance(Foo.a, Column)
+
+
+def test_not_null_validation_raises_on_none_or_empty():
+    class Foo:
+        a: Column[str] = text_column(header="A", not_null=True)
+
+    f = Foo()
+    f._values = {}  # ty:ignore[unresolved-attribute]
+
+    with pytest.raises(ValueError):
+        f.a = None  # type: ignore[assignment]
+
+    with pytest.raises(ValueError):
+        f.a = ""
+
+
+def test_text_column_strip_and_none_to_empty_string():
+    col = text_column(header="X", strip=True)
+    assert col.parse_cell(None) == ""
+    assert col.parse_cell("  hi  ") == "hi"
+    assert col.parse_cell(123) == "123"
+
+
+def test_text_column_no_strip():
+    col = text_column(header="X", strip=False)
+    assert col.parse_cell("  hi  ") == "  hi  "
+
+
+def test_int_column_parsing():
+    col = int_column(header="Y")
+    assert col.parse_cell(None) == 0
+    assert col.parse_cell("") == 0
+    assert col.parse_cell("42") == 42
+    assert col.parse_cell(7) == 7
+
+
+def test_bool_column_parsing_valid_values():
+    col = bool_column(header="B")
+    assert col.parse_cell(None) is False
+    assert col.parse_cell("") is False
+    assert col.parse_cell(True) is True
+    assert col.parse_cell("YES") is True
+    assert col.parse_cell("0") is False
+    assert col.parse_cell("n") is False
+
+
+def test_bool_column_invalid_raises():
+    col = bool_column(header="B")
+    with pytest.raises(ValueError):
+        col.parse_cell("maybe")
+
+
+@pytest.mark.parametrize(
+    "raw, expected",
+    [
+        ("01-JUN-2025", date(2025, 6, 1)),
+        ("01-jun-2025", date(2025, 6, 1)),  # case-insensitive month
+        ("2025-06-01", date(2025, 6, 1)),
+        ("2025/06/01", date(2025, 6, 1)),
+        ("06/01/2025", date(2025, 6, 1)),  # per your formats list (US)
+        (datetime(2025, 6, 1, 12, 30), date(2025, 6, 1)),
+        (date(2025, 6, 1), date(2025, 6, 1)),
+        ("2025-06-01T13:45:00", date(2025, 6, 1)),  # ISO datetime
+    ],
+)
+def test_date_column_tryparse_cascade(raw, expected):
+    col = date_column(header="D")
+    assert col.parse_cell(raw) == expected
+
+
+def test_date_column_empty_raises():
+    col = date_column(header="D")
+    with pytest.raises(ValueError):
+        col.parse_cell(None)
+    with pytest.raises(ValueError):
+        col.parse_cell("")
+    with pytest.raises(ValueError):
+        col.parse_cell("   ")
+
+
+def test_date_column_invalid_raises():
+    col = date_column(header="D")
+    with pytest.raises(ValueError):
+        col.parse_cell("not-a-date")