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

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

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

excel_orm-0.1.1/.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.1/.python-version

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excel-orm
-Version: 0.1.0
+Version: 0.1.1
 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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "excel-orm"
-version = "0.1.0"
+version = "0.1.1"
 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.1/tests/conftest.py

@@ -0,0 +1,75 @@
+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 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_field="region",
+        value_field="value",
+        pivot_values=pivot_values,
+        row_values=["NA", "EU"],  # seed some regions
+    )
+
+    return ExcelFile(sheets=[spec])

excel_orm-0.1.1/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")

excel_orm-0.1.1/tests/test_orm.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+
+import pytest
+from openpyxl import load_workbook
+
+from excel_orm import ExcelFile, PivotSheetSpec
+
+
+def test_generate_template_creates_sheet_and_titles_and_headers(tmp_path, excel_file):
+    out = tmp_path / "template.xlsx"
+    excel_file.generate_template(str(out))
+
+    wb = load_workbook(out)
+    assert "Cars" in wb.sheetnames
+    ws = wb["Cars"]
+
+    # Cars block: title row merged across A..C, title value "Cars"
+    assert ws["A1"].value == "Cars"
+    merged = [str(rng) for rng in ws.merged_cells.ranges]
+    assert "A1:C1" in merged
+
+    # Cars headers on row 2
+    assert ws["A2"].value == "Make"
+    assert ws["B2"].value == "Model"
+    assert ws["C2"].value == "Year"
+
+    # ManufacturingPlant block starts after 2-col gap: Cars ends at C, so start at F
+    assert ws["F1"].value == "Manufacturing Plants"
+    assert "F1:G1" in merged
+    assert ws["F2"].value == "Factory Name"
+    assert ws["G2"].value == "Location"
+
+
+def test_load_data_end_to_end(tmp_path, excel_file):
+    """
+    Create a workbook that matches the template layout, fill a few rows,
+    load it, and verify repositories.
+    """
+    out = tmp_path / "data.xlsx"
+    excel_file.generate_template(str(out))
+
+    # Fill data
+    from openpyxl import load_workbook
+
+    wb = load_workbook(out)
+    ws = wb["Cars"]
+
+    # Cars data at row 3+
+    ws["A3"].value = "Toyota"
+    ws["B3"].value = "Camry"
+    ws["C3"].value = 2020
+
+    ws["A4"].value = "Honda"
+    ws["B4"].value = "Civic"
+    ws["C4"].value = "2019"  # string should parse to int
+
+    # Plants data at row 3+ (F,G)
+    ws["F3"].value = "Plant 1"
+    ws["G3"].value = "NJ"
+
+    ws["F4"].value = "Plant 2"
+    ws["G4"].value = "PA"
+
+    wb.save(out)
+
+    # Load
+    excel_file.load_data(str(out))
+
+    cars = excel_file.cars.all()
+    plants = excel_file.manufacturing_plants.all()
+
+    assert len(cars) == 2
+    assert cars[0].make == "Toyota"
+    assert cars[0].model == "Camry"
+    assert cars[0].year == 2020
+    assert cars[1].year == 2019
+
+    assert len(plants) == 2
+    assert plants[0].name == "Plant 1"
+    assert plants[0].location == "NJ"
+
+
+def test_load_data_missing_sheet_raises(tmp_path, excel_file):
+    # Create a workbook with a different sheet name
+    from openpyxl import Workbook
+
+    p = tmp_path / "wrong.xlsx"
+    wb = Workbook()
+    wb.active.title = "NotCars"
+    wb.save(p)
+
+    with pytest.raises(ValueError):
+        excel_file.load_data(str(p))
+
+
+def _as_date(x) -> date:
+    """openpyxl may return date or datetime depending on formatting; normalize."""
+    if isinstance(x, datetime):
+        return x.date()
+    if isinstance(x, date):
+        return x
+    raise TypeError(f"Expected date/datetime, got {type(x)}: {x!r}")
+
+
+def test_generate_template_pivot_sheet_layout(tmp_path, pivot_excel_file, demand_model):
+    out = tmp_path / "pivot_template.xlsx"
+    pivot_excel_file.generate_template(str(out))
+
+    wb = load_workbook(out)
+    assert "Demand" in wb.sheetnames
+    ws = wb["Demand"]
+
+    # Title merged across A..D (A for row header + 3 pivot columns -> B,C,D)
+    assert ws["A1"].value == "Demands"
+    merged = [str(rng) for rng in ws.merged_cells.ranges]
+    assert "A1:D1" in merged
+
+    # Corner header for row keys (Region)
+    assert ws["A2"].value in {"Region"}  # explicit
+
+    # Pivot headers across B2..D2
+    assert _as_date(ws["B2"].value) == date(2025, 6, 1)
+    assert _as_date(ws["C2"].value) == date(2025, 7, 1)
+    assert _as_date(ws["D2"].value) == date(2025, 8, 1)
+
+    # Seeded row values appear in A3, A4
+    assert ws["A3"].value == "NA"
+    assert ws["A4"].value == "EU"
+
+
+def test_load_data_pivot_end_to_end_skips_blank_cells(tmp_path, pivot_excel_file):
+    """
+    Fill a demand pivot matrix:
+      rows: NA, EU
+      cols: Jun, Jul, Aug
+    Leave one cell blank and verify it is not emitted (include_blanks=False).
+    """
+    out = tmp_path / "pivot_data.xlsx"
+    pivot_excel_file.generate_template(str(out))
+
+    wb = load_workbook(out)
+    ws = wb["Demand"]
+
+    # NA row at row 3
+    ws["B3"].value = 10  # NA, Jun
+    ws["C3"].value = 20  # NA, Jul
+    ws["D3"].value = None  # NA, Aug (blank -> should skip)
+
+    # EU row at row 4
+    ws["B4"].value = 5  # EU, Jun
+    ws["C4"].value = 0  # EU, Jul (explicit 0 should be included)
+    ws["D4"].value = 15  # EU, Aug
+
+    wb.save(out)
+
+    pivot_excel_file.load_data(str(out))
+
+    # Repo name is plural snake_case of Demand -> demands
+    rows = pivot_excel_file.demands.all()
+    assert len(rows) == 5  # 6 cells minus 1 blank = 5
+
+    # Compare as a set of tuples to avoid ordering assumptions
+    got = {(r.region, r.dt, r.value) for r in rows}
+    expected = {
+        ("NA", date(2025, 6, 1), 10),
+        ("NA", date(2025, 7, 1), 20),
+        # ("NA", date(2025, 8, 1), ?) skipped
+        ("EU", date(2025, 6, 1), 5),
+        ("EU", date(2025, 7, 1), 0),
+        ("EU", date(2025, 8, 1), 15),
+    }
+    assert got == expected
+
+
+def test_load_data_pivot_stops_at_blank_region_row(tmp_path, demand_model):
+    """
+    If the region cell is blank, parsing should stop (contiguous-block rule for row labels).
+    """
+    pivot_values = [date(2025, 6, 1), date(2025, 7, 1)]
+    spec = PivotSheetSpec(
+        name="Demand",
+        model=demand_model,
+        pivot_field="dt",
+        row_field="region",
+        value_field="value",
+        pivot_values=pivot_values,
+        row_values=None,  # user-entered regions
+    )
+    xf = ExcelFile(sheets=[spec])
+
+    out = tmp_path / "stop_rule.xlsx"
+    xf.generate_template(str(out))
+
+    wb = load_workbook(out)
+    ws = wb["Demand"]
+
+    # Row 3 has region, row 4 is blank region -> stop; row 5 should not be read
+    ws["A3"].value = "NA"
+    ws["B3"].value = 1
+    ws["C3"].value = 2
+
+    ws["A4"].value = ""  # stop condition
+
+    ws["A5"].value = "EU"
+    ws["B5"].value = 9
+    ws["C5"].value = 9
+
+    wb.save(out)
+
+    xf.load_data(str(out))
+    rows = xf.demands.all()  # ty:ignore[unresolved-attribute]
+
+    got = {(r.region, r.dt, r.value) for r in rows}
+    assert got == {
+        ("NA", date(2025, 6, 1), 1),
+        ("NA", date(2025, 7, 1), 2),
+    }
+
+
+def test_load_data_missing_pivot_sheet_raises(tmp_path, pivot_excel_file):
+    # Create a workbook with a different sheet name
+    from openpyxl import Workbook
+
+    p = tmp_path / "wrong.xlsx"
+    wb = Workbook()
+    wb.active.title = "NotDemand"
+    wb.save(p)
+
+    with pytest.raises(ValueError):
+        pivot_excel_file.load_data(str(p))

excel_orm-0.1.1/tests/test_orm_helpers.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from src.excel_orm import Column, int_column, text_column
+from src.excel_orm.orm import (
+    _camel_to_snake,
+    _display_name_for_model,
+    _get_model_columns,
+    _instantiate_model,
+    _pluralize,
+    _repo_name_for_model,
+)
+
+
+def test_camel_to_snake():
+    assert _camel_to_snake("Car") == "car"
+    assert _camel_to_snake("ManufacturingPlant") == "manufacturing_plant"
+    assert _camel_to_snake("HTTPServer") == "http_server"
+
+
+def test_pluralize():
+    assert _pluralize("car") == "cars"
+    assert _pluralize("class") == "class"  # your simple rule: if endswith s, keep as-is
+
+
+def test_repo_and_display_name():
+    class ManufacturingPlant:
+        pass
+
+    assert _repo_name_for_model(ManufacturingPlant) == "manufacturing_plants"
+    assert _display_name_for_model(ManufacturingPlant) == "Manufacturing Plants"
+
+
+def test_get_model_columns_respects_annotation_order():
+    class A:
+        x: Column[str] = text_column(header="X")
+        y: Column[int] = int_column(header="Y")
+
+    cols = _get_model_columns(A)
+    assert [c.name for c in cols] == ["x", "y"]
+
+
+def test_instantiate_model_sets_defaults_and_requires_set_name():
+    class A:
+        x: Column[str] = text_column(header="X", default="dflt")
+
+    a = _instantiate_model(A)
+    assert a._values["x"] == "dflt"  # ty:ignore[unresolved-attribute]