excel-orm 0.1.7__tar.gz → 0.2.0__tar.gz

{excel_orm-0.1.7 → excel_orm-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excel-orm
-Version: 0.1.7
+Version: 0.2.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
@@ -28,10 +28,15 @@ This project is designed for the common enterprise pattern where you:
 2. let users fill it in,
 3. load the workbook back into Python, producing typed objects grouped by model.
 
+Or, going the other direction:
+
+1. build a collection of model objects in Python,
+2. write them directly to a structured `.xlsx` file in one call.
+
 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.
+* multiple model "tables" laid out horizontally on a worksheet, and
+* **pivot-style sheets** (matrix input/output) that expand into row objects.
 
 ---
 
@@ -55,6 +60,11 @@ It uses `openpyxl` for reading/writing Excel files and supports:
   * `excel_file.cars.all()` → `list[Car]`
   * `excel_file.manufacturing_plants.all()` → `list[ManufacturingPlant]`
   * `excel_file.demands.all()` → `list[Demand]` (from pivot input)
+* **Two-way binding** — write Python objects back to Excel:
+
+  * `excel_file.add_data(objects)` to pre-populate repos
+  * `generate_template(filename)` writes data rows when repos are populated, or a blank template when they are empty
+  * pivot sheets write a fully populated matrix from repo contents
 * **Validation hooks**
 
   * column-level `not_null`
@@ -130,6 +140,35 @@ print(cars[0].make, cars[0].year)
 print(plants[0].name, plants[0].location)
 ```
 
+### 4) Write Python objects back to Excel
+
+Instead of asking users to fill a template, you can populate an `ExcelFile` directly from Python objects and generate a pre-filled workbook.
+
+```python
+excel_file = ExcelFile(sheets=[sheet])
+
+cars = [
+    Car(make="Toyota", model="Camry", year=2020),
+    Car(make="Honda", model="Civic", year=2019),
+]
+plants = [
+    ManufacturingPlant(name="Plant A", location="NJ"),
+]
+
+excel_file.add_data(cars)
+excel_file.add_data(plants)
+
+# generate_template detects populated repos and writes data rows automatically.
+excel_file.generate_template("car_inventory_filled.xlsx")
+```
+
+You can also append directly to a repo attribute:
+
+```python
+excel_file.cars.append(Car(make="Ford", model="F-150", year=2022))
+excel_file.generate_template("car_inventory_filled.xlsx")
+```
+
 ---
 
 ## Pivot Sheets
@@ -201,6 +240,23 @@ rows = xf.demands.all()
 # Demand(region="NA", product="SKU-1", dt=date(2025, 6, 1), value=10)
 ```
 
+### 4) Write pivot data from Python objects
+
+```python
+xf = ExcelFile(sheets=[spec])
+
+xf.add_data([
+    Demand(region="NA", product="SKU-1", dt=date(2025, 6, 1), value=10),
+    Demand(region="NA", product="SKU-1", dt=date(2025, 7, 1), value=20),
+    Demand(region="EU", product="SKU-1", dt=date(2025, 6, 1), value=5),
+])
+
+# Writes title, row/pivot headers, and a filled matrix in one call.
+xf.generate_template("demand_output.xlsx")
+```
+
+If `pivot_values` is not set on the spec, the pivot column order is inferred from the insertion order of pivot field values across the repo objects. Missing `(row_key, pivot_value)` combinations write a blank cell.
+
 ### `row_values` seeding rules
 
 * If `len(row_fields) == 1`, each `row_values` element may be a **single scalar** value (backward compatible).
@@ -226,6 +282,23 @@ Repositories are list-like containers with an `all()` helper:
 cars = excel_file.cars.all()  # list[Car]
 ```
 
+You can populate repos in two ways before calling `generate_template()`:
+
+**Via `add_data()`** (validated — raises `ValueError` for unregistered model types):
+
+```python
+excel_file.add_data([Car(make="Toyota", model="Camry", year=2020)])
+```
+
+**Via direct list operations** on the repo attribute:
+
+```python
+excel_file.cars.append(Car(make="Honda", model="Civic", year=2019))
+excel_file.cars.extend([...])
+```
+
+Populating repos before calling `generate_template()` writes the data into the generated file. Empty repos produce a blank template.
+
 ### Multi-table Sheets (standard tables)
 
 A single worksheet can host multiple model tables. During template generation:

{excel_orm-0.1.7 → excel_orm-0.2.0}/README.md

@@ -8,10 +8,15 @@ This project is designed for the common enterprise pattern where you:
 2. let users fill it in,
 3. load the workbook back into Python, producing typed objects grouped by model.
 
+Or, going the other direction:
+
+1. build a collection of model objects in Python,
+2. write them directly to a structured `.xlsx` file in one call.
+
 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.
+* multiple model "tables" laid out horizontally on a worksheet, and
+* **pivot-style sheets** (matrix input/output) that expand into row objects.
 
 ---
 
@@ -35,6 +40,11 @@ It uses `openpyxl` for reading/writing Excel files and supports:
   * `excel_file.cars.all()` → `list[Car]`
   * `excel_file.manufacturing_plants.all()` → `list[ManufacturingPlant]`
   * `excel_file.demands.all()` → `list[Demand]` (from pivot input)
+* **Two-way binding** — write Python objects back to Excel:
+
+  * `excel_file.add_data(objects)` to pre-populate repos
+  * `generate_template(filename)` writes data rows when repos are populated, or a blank template when they are empty
+  * pivot sheets write a fully populated matrix from repo contents
 * **Validation hooks**
 
   * column-level `not_null`
@@ -110,6 +120,35 @@ print(cars[0].make, cars[0].year)
 print(plants[0].name, plants[0].location)
 ```
 
+### 4) Write Python objects back to Excel
+
+Instead of asking users to fill a template, you can populate an `ExcelFile` directly from Python objects and generate a pre-filled workbook.
+
+```python
+excel_file = ExcelFile(sheets=[sheet])
+
+cars = [
+    Car(make="Toyota", model="Camry", year=2020),
+    Car(make="Honda", model="Civic", year=2019),
+]
+plants = [
+    ManufacturingPlant(name="Plant A", location="NJ"),
+]
+
+excel_file.add_data(cars)
+excel_file.add_data(plants)
+
+# generate_template detects populated repos and writes data rows automatically.
+excel_file.generate_template("car_inventory_filled.xlsx")
+```
+
+You can also append directly to a repo attribute:
+
+```python
+excel_file.cars.append(Car(make="Ford", model="F-150", year=2022))
+excel_file.generate_template("car_inventory_filled.xlsx")
+```
+
 ---
 
 ## Pivot Sheets
@@ -181,6 +220,23 @@ rows = xf.demands.all()
 # Demand(region="NA", product="SKU-1", dt=date(2025, 6, 1), value=10)
 ```
 
+### 4) Write pivot data from Python objects
+
+```python
+xf = ExcelFile(sheets=[spec])
+
+xf.add_data([
+    Demand(region="NA", product="SKU-1", dt=date(2025, 6, 1), value=10),
+    Demand(region="NA", product="SKU-1", dt=date(2025, 7, 1), value=20),
+    Demand(region="EU", product="SKU-1", dt=date(2025, 6, 1), value=5),
+])
+
+# Writes title, row/pivot headers, and a filled matrix in one call.
+xf.generate_template("demand_output.xlsx")
+```
+
+If `pivot_values` is not set on the spec, the pivot column order is inferred from the insertion order of pivot field values across the repo objects. Missing `(row_key, pivot_value)` combinations write a blank cell.
+
 ### `row_values` seeding rules
 
 * If `len(row_fields) == 1`, each `row_values` element may be a **single scalar** value (backward compatible).
@@ -206,6 +262,23 @@ Repositories are list-like containers with an `all()` helper:
 cars = excel_file.cars.all()  # list[Car]
 ```
 
+You can populate repos in two ways before calling `generate_template()`:
+
+**Via `add_data()`** (validated — raises `ValueError` for unregistered model types):
+
+```python
+excel_file.add_data([Car(make="Toyota", model="Camry", year=2020)])
+```
+
+**Via direct list operations** on the repo attribute:
+
+```python
+excel_file.cars.append(Car(make="Honda", model="Civic", year=2019))
+excel_file.cars.extend([...])
+```
+
+Populating repos before calling `generate_template()` writes the data into the generated file. Empty repos produce a blank template.
+
 ### Multi-table Sheets (standard tables)
 
 A single worksheet can host multiple model tables. During template generation:

{excel_orm-0.1.7 → excel_orm-0.2.0}/pyproject.toml

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

{excel_orm-0.1.7 → excel_orm-0.2.0}/src/excel_orm/__init__.py

@@ -4,6 +4,7 @@ from .column import (
     ColumnSpec,
     bool_column,
     date_column,
+    float_column,
     int_column,
     text_column,
 )
@@ -18,6 +19,7 @@ __all__ = [
     "SheetSpec",
     "bool_column",
     "date_column",
+    "float_column",
     "int_column",
     "text_column",
 ]

{excel_orm-0.1.7 → excel_orm-0.2.0}/src/excel_orm/column.py

@@ -112,6 +112,27 @@ def int_column(
     )
 
 
+def float_column(
+    header: str | None = None,
+    *,
+    default: float | None = None,
+    not_null: bool = False,
+) -> Column[float]:
+    def parse(raw: Any) -> float:
+        if raw is None or raw == "":
+            return 0.0
+        return float(raw)
+
+    return Column(
+        ColumnSpec[float](
+            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 == "":

{excel_orm-0.1.7 → excel_orm-0.2.0}/src/excel_orm/orm.py

@@ -130,6 +130,16 @@ class ExcelFile:
                 self._repos[model] = repo
                 setattr(self, repo_name, repo)
 
+    def add_data(self, objects: list[Any]) -> None:
+        for obj in objects:
+            model = type(obj)
+            repo = self._repos.get(model)
+            if repo is None:
+                raise ValueError(
+                    f"Model type '{model.__name__}' is not registered with this ExcelFile."
+                )
+            repo.append(obj)
+
     def generate_template(self, filename: str) -> None:
         wb = Workbook()
         default_ws = wb.active
@@ -182,6 +192,13 @@ class ExcelFile:
                 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))
 
+            repo = self._repos[model]
+            for row_idx, obj in enumerate(repo):
+                r = spec.data_start_row + row_idx
+                for j, col in enumerate(cols):
+                    rendered = col.spec.renderer(getattr(obj, col.name))
+                    ws.cell(row=r, column=start_col + j, value=rendered)
+
             current_col = end_col + 1 + spec.template_table_gap
 
     def load_data(self, filename: str) -> None:
@@ -259,15 +276,28 @@ class ExcelFile:
         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)
 
+        repo = self._repos[spec.model]
+        col_map = {c.name: c for c in _get_model_columns(spec.model)}
+
+        # Determine effective pivot values: prefer spec, infer from repo, else error
+        if spec.pivot_values:
+            effective_pivot_values = spec.pivot_values
+        elif repo:
+            seen_pv: dict[Any, None] = {}
+            for obj in repo:
+                seen_pv[getattr(obj, spec.pivot_field)] = None
+            effective_pivot_values = list(seen_pv.keys())
+        else:
+            raise ValueError(
+                "PivotSheetSpec.pivot_values is required for template generation when no data is present."
+            )
+
         # Title merged across the pivot header span
-        end_col = spec.data_start_col + len(spec.pivot_values) - 1
+        end_col = spec.data_start_col + len(effective_pivot_values) - 1
 
         ws.merge_cells(
             start_row=spec.title_row,
@@ -288,14 +318,40 @@ class ExcelFile:
             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):
+        for j, pv in enumerate(effective_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:
+        if repo:
+            # Collect ordered unique row keys from repo
+            seen_row_keys: dict[tuple, None] = {}
+            for obj in repo:
+                key = tuple(getattr(obj, f) for f in spec.row_fields)
+                seen_row_keys[key] = None
+            row_keys = list(seen_row_keys.keys())
+
+            # Build (row_key, pivot_value) -> rendered cell value lookup
+            val_col_obj = col_map[spec.value_field]
+            lookup: dict[tuple, Any] = {}
+            for obj in repo:
+                row_key = tuple(getattr(obj, f) for f in spec.row_fields)
+                pv = getattr(obj, spec.pivot_field)
+                lookup[(row_key, pv)] = val_col_obj.spec.renderer(getattr(obj, spec.value_field))
+
+            # Write row keys and matrix values
+            for i, row_key in enumerate(row_keys):
+                r = spec.data_start_row + i
+                for k, part in enumerate(row_key):
+                    rendered_key = col_map[spec.row_fields[k]].spec.renderer(part)
+                    ws.cell(r, spec.row_header_col + k, rendered_key)
+                for j, pv in enumerate(effective_pivot_values):
+                    c = spec.data_start_col + j
+                    ws.cell(r, c, lookup.get((row_key, pv)))
+
+        elif spec.row_values:
             for i, rv in enumerate(spec.row_values):
                 r = spec.data_start_row + i
 

{excel_orm-0.1.7 → excel_orm-0.2.0}/tests/test_columns.py

@@ -9,6 +9,7 @@ from src.excel_orm import (
     RowBase,
     bool_column,
     date_column,
+    float_column,
     int_column,
     text_column,
 )
@@ -67,6 +68,14 @@ def test_int_column_parsing():
     assert col.parse_cell(7) == 7
 
 
+def test_float_column_parsing():
+    col = float_column(header="Z")
+    assert col.parse_cell(None) == 0.0
+    assert col.parse_cell("") == 0.0
+    assert col.parse_cell("3.14") == 3.14
+    assert col.parse_cell(2) == 2.0
+
+
 def test_bool_column_parsing_valid_values():
     col = bool_column(header="B")
     assert col.parse_cell(None) is False