f8-engine 0.6.0__tar.gz → 0.6.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. {f8_engine-0.6.0 → f8_engine-0.6.1}/Cargo.lock +3 -3
  2. {f8_engine-0.6.0 → f8_engine-0.6.1}/Cargo.toml +1 -1
  3. {f8_engine-0.6.0 → f8_engine-0.6.1}/PKG-INFO +19 -17
  4. {f8_engine-0.6.0 → f8_engine-0.6.1}/README.md +18 -16
  5. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/compiled/mod.rs +43 -41
  6. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/compiled/model.rs +2 -2
  7. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/emission/workbook.rs +11 -10
  8. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/eval/model.rs +1 -1
  9. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/graph/resolve.rs +1 -1
  10. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/ir/expand.rs +9 -9
  11. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/ir/symbol.rs +2 -2
  12. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/layout/mod.rs +18 -15
  13. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/table.rs +14 -7
  14. {f8_engine-0.6.0 → f8_engine-0.6.1}/pyproject.toml +18 -23
  15. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/audit.py +4 -4
  16. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/builder.py +11 -6
  17. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/skills/f8-modeling/SKILL.md +1 -0
  18. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/skills/f8-modeling/references/auditing-and-repair.md +35 -35
  19. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/skills/f8-modeling/references/functions.md +47 -47
  20. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/skills/f8-modeling/references/syntax-and-grid.md +53 -53
  21. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/types.py +2 -2
  22. {f8_engine-0.6.0 → f8_engine-0.6.1}/LICENSE +0 -0
  23. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/Cargo.toml +0 -0
  24. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/compiled/error.rs +0 -0
  25. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/emission/error.rs +0 -0
  26. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/emission/format.rs +0 -0
  27. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/emission/mod.rs +0 -0
  28. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/error.rs +0 -0
  29. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/eval/context.rs +0 -0
  30. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/eval/error.rs +0 -0
  31. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/eval/expr.rs +0 -0
  32. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/eval/mod.rs +0 -0
  33. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/graph/cycle.rs +0 -0
  34. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/graph/dependency.rs +0 -0
  35. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/graph/error.rs +0 -0
  36. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/graph/mod.rs +0 -0
  37. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/ir/cell.rs +0 -0
  38. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/ir/error.rs +0 -0
  39. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/ir/id.rs +0 -0
  40. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/ir/mod.rs +0 -0
  41. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/layout/a1.rs +0 -0
  42. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/layout/error.rs +0 -0
  43. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/lowering/address.rs +0 -0
  44. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/lowering/error.rs +0 -0
  45. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/lowering/mod.rs +0 -0
  46. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/compiler/mod.rs +0 -0
  47. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/expr/ast.rs +0 -0
  48. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/expr/error.rs +0 -0
  49. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/expr/mod.rs +0 -0
  50. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/expr/parser.rs +0 -0
  51. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/binder.rs +0 -0
  52. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/common.rs +0 -0
  53. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/date/constructors.rs +0 -0
  54. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/date/mod.rs +0 -0
  55. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/date/parts.rs +0 -0
  56. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/date/yearfrac.rs +0 -0
  57. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/error.rs +0 -0
  58. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/financial/annuity.rs +0 -0
  59. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/financial/discounting.rs +0 -0
  60. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/financial/irr.rs +0 -0
  61. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/financial/mod.rs +0 -0
  62. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/information/mod.rs +0 -0
  63. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/logical/boolean.rs +0 -0
  64. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/logical/branching.rs +0 -0
  65. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/logical/error_handling.rs +0 -0
  66. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/logical/mod.rs +0 -0
  67. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/lookup/index.rs +0 -0
  68. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/lookup/mod.rs +0 -0
  69. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/lookup/search.rs +0 -0
  70. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/lookup/xlookup.rs +0 -0
  71. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/lookup/xmatch.rs +0 -0
  72. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/math/aggregation.rs +0 -0
  73. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/math/basic.rs +0 -0
  74. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/math/mod.rs +0 -0
  75. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/math/product.rs +0 -0
  76. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/math/rounding.rs +0 -0
  77. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/mod.rs +0 -0
  78. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/registry.rs +0 -0
  79. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/traits.rs +0 -0
  80. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/functions/typecheck.rs +0 -0
  81. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/lib.rs +0 -0
  82. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/error.rs +0 -0
  83. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/format.rs +0 -0
  84. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/id.rs +0 -0
  85. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/manifest.rs +0 -0
  86. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/mod.rs +0 -0
  87. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/model/theme.rs +0 -0
  88. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/value/date.rs +0 -0
  89. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/value/error.rs +0 -0
  90. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/value/format.rs +0 -0
  91. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-core/src/value/mod.rs +0 -0
  92. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-python/Cargo.toml +0 -0
  93. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-python/src/error.rs +0 -0
  94. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-python/src/lib.rs +0 -0
  95. {f8_engine-0.6.0 → f8_engine-0.6.1}/crates/f8-python/src/model.rs +0 -0
  96. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/__init__.py +0 -0
  97. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/__main__.py +0 -0
  98. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/_core.pyi +0 -0
  99. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/cli.py +0 -0
  100. {f8_engine-0.6.0 → f8_engine-0.6.1}/python/f8/py.typed +0 -0
@@ -58,7 +58,7 @@ checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
58
58
 
59
59
  [[package]]
60
60
  name = "f8-core"
61
- version = "0.6.0"
61
+ version = "0.6.1"
62
62
  dependencies = [
63
63
  "indexmap",
64
64
  "petgraph",
@@ -71,7 +71,7 @@ dependencies = [
71
71
 
72
72
  [[package]]
73
73
  name = "f8-python"
74
- version = "0.6.0"
74
+ version = "0.6.1"
75
75
  dependencies = [
76
76
  "f8-core",
77
77
  "pyo3",
@@ -80,7 +80,7 @@ dependencies = [
80
80
 
81
81
  [[package]]
82
82
  name = "f8-wasm"
83
- version = "0.6.0"
83
+ version = "0.6.1"
84
84
  dependencies = [
85
85
  "f8-core",
86
86
  "rust_xlsxwriter",
@@ -3,7 +3,7 @@ resolver = "3"
3
3
  members = ["crates/f8-core", "crates/f8-python"]
4
4
 
5
5
  [workspace.package]
6
- version = "0.6.0"
6
+ version = "0.6.1"
7
7
  edition = "2024"
8
8
  description = "Financial modeling engine with compiler verification and live Excel formulas"
9
9
  authors = ["Michael (Chencheng) Hu, CFA"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: f8-engine
3
- Version: 0.6.0
3
+ Version: 0.6.1
4
4
  Classifier: Development Status :: 4 - Beta
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: Intended Audience :: Financial and Insurance Industry
@@ -124,40 +124,42 @@ compiled.save("forecast.xlsx")
124
124
  ### TypeScript
125
125
 
126
126
  ```typescript
127
- import { Model } from "f8-engine";
127
+ import { Model } from "f8-engine"
128
128
 
129
- const years = ["2025A", "2026E", "2027E"] as const;
130
- const capex = { "2025A": 25.0, "2026E": 30.0, "2027E": 35.0 };
131
- const depr = { "2025A": -15.0, "2026E": -18.0, "2027E": -22.0 };
129
+ const years = ["2025A", "2026E", "2027E"] as const
130
+ const capex = { "2025A": 25.0, "2026E": 30.0, "2027E": 35.0 }
131
+ const depr = { "2025A": -15.0, "2026E": -18.0, "2027E": -22.0 }
132
132
 
133
- const model = new Model({ name: "Operating Forecast" });
134
- const sheet = model.addSheet("Summary");
133
+ const model = new Model({ name: "Operating Forecast" })
134
+ const sheet = model.addSheet("Summary")
135
135
 
136
- const ppe = sheet.addTable("PPE", "PP&E Corkscrew Schedule", { subtitle: "($ in millions)" });
137
- ppe.addColumn("item", { role: "descriptor", header: "Line Item" });
136
+ const ppe = sheet.addTable("PPE", "PP&E Corkscrew Schedule", {
137
+ subtitle: "($ in millions)",
138
+ })
139
+ ppe.addColumn("item", { role: "descriptor", header: "Line Item" })
138
140
  for (const year of years) {
139
- ppe.addColumn(year, { header: year, format: "currency", decimals: 1 });
141
+ ppe.addColumn(year, { header: year, format: "currency", decimals: 1 })
140
142
  }
141
143
 
142
144
  ppe.addRow("beg_balance", {
143
145
  cells: { item: "Beginning Balance", "2025A": 100.0 },
144
146
  expr: 'PPE["end_balance", col.prev]',
145
- });
146
- ppe.addRow("capex", { cells: { item: "Capital Expenditures", ...capex } });
147
- ppe.addRow("depreciation", { cells: { item: "Depreciation", ...depr } });
147
+ })
148
+ ppe.addRow("capex", { cells: { item: "Capital Expenditures", ...capex } })
149
+ ppe.addRow("depreciation", { cells: { item: "Depreciation", ...depr } })
148
150
  ppe.addRow("end_balance", {
149
151
  cells: { item: "Ending Balance" },
150
152
  expr: 'SUM(PPE["beg_balance".."depreciation", @col])',
151
153
  style: "total",
152
- });
154
+ })
153
155
 
154
- const compiled = model.compile();
156
+ const compiled = model.compile()
155
157
 
156
158
  // Audit evaluated values in memory (or pass { view: "formulas" } to inspect lowered Excel formulas)
157
- console.log(compiled.table("PPE").toMarkdown());
159
+ console.log(compiled.table("PPE").toMarkdown())
158
160
 
159
161
  // Emit a live .xlsx workbook with native Excel formulas and styling (you don't have to)
160
- compiled.save("forecast.xlsx");
162
+ compiled.save("forecast.xlsx")
161
163
  ```
162
164
 
163
165
  Output:
@@ -98,40 +98,42 @@ compiled.save("forecast.xlsx")
98
98
  ### TypeScript
99
99
 
100
100
  ```typescript
101
- import { Model } from "f8-engine";
101
+ import { Model } from "f8-engine"
102
102
 
103
- const years = ["2025A", "2026E", "2027E"] as const;
104
- const capex = { "2025A": 25.0, "2026E": 30.0, "2027E": 35.0 };
105
- const depr = { "2025A": -15.0, "2026E": -18.0, "2027E": -22.0 };
103
+ const years = ["2025A", "2026E", "2027E"] as const
104
+ const capex = { "2025A": 25.0, "2026E": 30.0, "2027E": 35.0 }
105
+ const depr = { "2025A": -15.0, "2026E": -18.0, "2027E": -22.0 }
106
106
 
107
- const model = new Model({ name: "Operating Forecast" });
108
- const sheet = model.addSheet("Summary");
107
+ const model = new Model({ name: "Operating Forecast" })
108
+ const sheet = model.addSheet("Summary")
109
109
 
110
- const ppe = sheet.addTable("PPE", "PP&E Corkscrew Schedule", { subtitle: "($ in millions)" });
111
- ppe.addColumn("item", { role: "descriptor", header: "Line Item" });
110
+ const ppe = sheet.addTable("PPE", "PP&E Corkscrew Schedule", {
111
+ subtitle: "($ in millions)",
112
+ })
113
+ ppe.addColumn("item", { role: "descriptor", header: "Line Item" })
112
114
  for (const year of years) {
113
- ppe.addColumn(year, { header: year, format: "currency", decimals: 1 });
115
+ ppe.addColumn(year, { header: year, format: "currency", decimals: 1 })
114
116
  }
115
117
 
116
118
  ppe.addRow("beg_balance", {
117
119
  cells: { item: "Beginning Balance", "2025A": 100.0 },
118
120
  expr: 'PPE["end_balance", col.prev]',
119
- });
120
- ppe.addRow("capex", { cells: { item: "Capital Expenditures", ...capex } });
121
- ppe.addRow("depreciation", { cells: { item: "Depreciation", ...depr } });
121
+ })
122
+ ppe.addRow("capex", { cells: { item: "Capital Expenditures", ...capex } })
123
+ ppe.addRow("depreciation", { cells: { item: "Depreciation", ...depr } })
122
124
  ppe.addRow("end_balance", {
123
125
  cells: { item: "Ending Balance" },
124
126
  expr: 'SUM(PPE["beg_balance".."depreciation", @col])',
125
127
  style: "total",
126
- });
128
+ })
127
129
 
128
- const compiled = model.compile();
130
+ const compiled = model.compile()
129
131
 
130
132
  // Audit evaluated values in memory (or pass { view: "formulas" } to inspect lowered Excel formulas)
131
- console.log(compiled.table("PPE").toMarkdown());
133
+ console.log(compiled.table("PPE").toMarkdown())
132
134
 
133
135
  // Emit a live .xlsx workbook with native Excel formulas and styling (you don't have to)
134
- compiled.save("forecast.xlsx");
136
+ compiled.save("forecast.xlsx")
135
137
  ```
136
138
 
137
139
  Output:
@@ -434,7 +434,7 @@ impl CompiledModel {
434
434
  Ok(TableInspection {
435
435
  table_id: table.clone(),
436
436
  title: table_spec.title.clone(),
437
- subtitle: table_spec.subtitle.clone(),
437
+ subtitles: table_spec.subtitles.clone(),
438
438
  sheet,
439
439
  columns,
440
440
  rows,
@@ -553,46 +553,48 @@ impl CompiledModel {
553
553
  }
554
554
  }
555
555
 
556
- // 2. Subtitle Banner
557
- if let (Some(subtitle_row), Some(subtitle)) = (placement.subtitle_row, &table.subtitle)
558
- {
559
- for col in placement.start_col..=placement.end_col {
560
- let physical_a1 = coordinate_to_a1(col, subtitle_row)
561
- .unwrap_or_else(|_| format!("R{subtitle_row}C{col}"));
562
- if col == placement.start_col {
563
- cells_map.insert(
564
- (subtitle_row, col),
565
- SheetCellInspection {
566
- physical_col: col,
567
- physical_a1,
568
- table_id: Some(table.id.clone()),
569
- row_id: None,
570
- col_id: None,
571
- kind: SheetCellKind::TableSubtitle,
572
- is_descriptor: false,
573
- value: CellValue::Text(subtitle.clone()),
574
- formatted_value: Some(subtitle.clone()),
575
- formula_expr: None,
576
- excel_formula: None,
577
- },
578
- );
579
- } else {
580
- cells_map.insert(
581
- (subtitle_row, col),
582
- SheetCellInspection {
583
- physical_col: col,
584
- physical_a1,
585
- table_id: Some(table.id.clone()),
586
- row_id: None,
587
- col_id: None,
588
- kind: SheetCellKind::TableSubtitle,
589
- is_descriptor: false,
590
- value: CellValue::Empty,
591
- formatted_value: None,
592
- formula_expr: None,
593
- excel_formula: None,
594
- },
595
- );
556
+ // 2. Subtitle Banners
557
+ if let Some((subtitle_start_row, _)) = placement.subtitle_row_range {
558
+ for (idx, subtitle) in table.subtitles.iter().enumerate() {
559
+ let subtitle_row = subtitle_start_row + idx as u32;
560
+ for col in placement.start_col..=placement.end_col {
561
+ let physical_a1 = coordinate_to_a1(col, subtitle_row)
562
+ .unwrap_or_else(|_| format!("R{subtitle_row}C{col}"));
563
+ if col == placement.start_col {
564
+ cells_map.insert(
565
+ (subtitle_row, col),
566
+ SheetCellInspection {
567
+ physical_col: col,
568
+ physical_a1,
569
+ table_id: Some(table.id.clone()),
570
+ row_id: None,
571
+ col_id: None,
572
+ kind: SheetCellKind::TableSubtitle,
573
+ is_descriptor: false,
574
+ value: CellValue::Text(subtitle.clone()),
575
+ formatted_value: Some(subtitle.clone()),
576
+ formula_expr: None,
577
+ excel_formula: None,
578
+ },
579
+ );
580
+ } else {
581
+ cells_map.insert(
582
+ (subtitle_row, col),
583
+ SheetCellInspection {
584
+ physical_col: col,
585
+ physical_a1,
586
+ table_id: Some(table.id.clone()),
587
+ row_id: None,
588
+ col_id: None,
589
+ kind: SheetCellKind::TableSubtitle,
590
+ is_descriptor: false,
591
+ value: CellValue::Empty,
592
+ formatted_value: None,
593
+ formula_expr: None,
594
+ excel_formula: None,
595
+ },
596
+ );
597
+ }
596
598
  }
597
599
  }
598
600
  }
@@ -119,8 +119,8 @@ pub struct TableInspection {
119
119
  pub table_id: TableId,
120
120
  /// Table display title.
121
121
  pub title: String,
122
- /// Table display subtitle if defined.
123
- pub subtitle: Option<String>,
122
+ /// Table display subtitle lines.
123
+ pub subtitles: Vec<String>,
124
124
  /// Worksheet containing this table.
125
125
  pub sheet: SheetId,
126
126
  /// Declared columns with header label tiers.
@@ -203,16 +203,17 @@ impl WorkbookEmitter {
203
203
  }
204
204
  }
205
205
 
206
- // Table Subtitle Banner
207
- if let (Some(subtitle_row), Some(subtitle)) =
208
- (placement.subtitle_row, &table.subtitle)
209
- {
210
- worksheet.write_string_with_format(
211
- subtitle_row,
212
- excel_col_u16(placement.start_col)?,
213
- subtitle,
214
- &format_cache.subtitle_format(),
215
- )?;
206
+ // Table Subtitle Banners
207
+ if let Some((subtitle_start_row, _)) = placement.subtitle_row_range {
208
+ for (idx, subtitle) in table.subtitles.iter().enumerate() {
209
+ let subtitle_row = subtitle_start_row + idx as u32;
210
+ worksheet.write_string_with_format(
211
+ subtitle_row,
212
+ excel_col_u16(placement.start_col)?,
213
+ subtitle,
214
+ &format_cache.subtitle_format(),
215
+ )?;
216
+ }
216
217
  }
217
218
 
218
219
  // Multi-Tier Column Headers
@@ -138,7 +138,7 @@ mod tests {
138
138
  let table = TableSpec {
139
139
  id: TableId::from("T"),
140
140
  title: "T".into(),
141
- subtitle: None,
141
+ subtitles: Vec::new(),
142
142
  currency: None,
143
143
  collapsible: false,
144
144
  placement: crate::model::table::PlacementSpec::default(),
@@ -625,7 +625,7 @@ mod tests {
625
625
  let target_table = TableSpec {
626
626
  id: TableId::from("Target"),
627
627
  title: "Target".into(),
628
- subtitle: None,
628
+ subtitles: Vec::new(),
629
629
  currency: None,
630
630
  collapsible: false,
631
631
  placement: crate::model::table::PlacementSpec::default(),
@@ -485,7 +485,7 @@ mod tests {
485
485
  let table = TableSpec {
486
486
  id: TableId::new("Assumptions"),
487
487
  title: "Model Assumptions".to_string(),
488
- subtitle: None,
488
+ subtitles: Vec::new(),
489
489
  currency: None,
490
490
  collapsible: false,
491
491
  placement: crate::model::table::PlacementSpec::default(),
@@ -556,7 +556,7 @@ mod tests {
556
556
  let table = TableSpec {
557
557
  id: TableId::new("Unregistered"),
558
558
  title: "Unregistered Table".to_string(),
559
- subtitle: None,
559
+ subtitles: Vec::new(),
560
560
  currency: None,
561
561
  collapsible: false,
562
562
  placement: crate::model::table::PlacementSpec::default(),
@@ -576,7 +576,7 @@ mod tests {
576
576
  let table = TableSpec {
577
577
  id: TableId::new("BadExpr"),
578
578
  title: "Bad Expr Table".to_string(),
579
- subtitle: None,
579
+ subtitles: Vec::new(),
580
580
  currency: None,
581
581
  collapsible: false,
582
582
  placement: crate::model::table::PlacementSpec::default(),
@@ -594,7 +594,7 @@ mod tests {
594
594
  let table = TableSpec {
595
595
  id: TableId::new("T1"),
596
596
  title: "Table 1".to_string(),
597
- subtitle: None,
597
+ subtitles: Vec::new(),
598
598
  currency: None,
599
599
  collapsible: false,
600
600
  placement: crate::model::table::PlacementSpec::default(),
@@ -616,7 +616,7 @@ mod tests {
616
616
  let table = TableSpec {
617
617
  id: TableId::new("ConflictTable"),
618
618
  title: "Conflict Table".to_string(),
619
- subtitle: None,
619
+ subtitles: Vec::new(),
620
620
  currency: None,
621
621
  collapsible: false,
622
622
  placement: crate::model::table::PlacementSpec::default(),
@@ -643,7 +643,7 @@ mod tests {
643
643
  let table = TableSpec {
644
644
  id: TableId::new("ConflictResolved"),
645
645
  title: "Resolved Table".to_string(),
646
- subtitle: None,
646
+ subtitles: Vec::new(),
647
647
  currency: None,
648
648
  collapsible: false,
649
649
  placement: crate::model::table::PlacementSpec::default(),
@@ -665,7 +665,7 @@ mod tests {
665
665
  let table = TableSpec {
666
666
  id: TableId::new("UnassignedTable"),
667
667
  title: "Unassigned Table".to_string(),
668
- subtitle: None,
668
+ subtitles: Vec::new(),
669
669
  currency: None,
670
670
  collapsible: false,
671
671
  placement: crate::model::table::PlacementSpec::default(),
@@ -689,7 +689,7 @@ mod tests {
689
689
  let table = TableSpec {
690
690
  id: TableId::new("FmtConflict"),
691
691
  title: "Format Conflict Table".to_string(),
692
- subtitle: None,
692
+ subtitles: Vec::new(),
693
693
  currency: None,
694
694
  collapsible: false,
695
695
  placement: crate::model::table::PlacementSpec::default(),
@@ -730,7 +730,7 @@ mod tests {
730
730
  let table = TableSpec {
731
731
  id: TableId::new("FmtResolved"),
732
732
  title: "Format Resolved Table".to_string(),
733
- subtitle: None,
733
+ subtitles: Vec::new(),
734
734
  currency: None,
735
735
  collapsible: false,
736
736
  placement: crate::model::table::PlacementSpec::default(),
@@ -258,7 +258,7 @@ mod tests {
258
258
  let table = TableSpec {
259
259
  id: TableId::new("IncomeStatement"),
260
260
  title: "Income Statement".to_string(),
261
- subtitle: None,
261
+ subtitles: Vec::new(),
262
262
  currency: None,
263
263
  collapsible: false,
264
264
  placement: crate::model::table::PlacementSpec::default(),
@@ -314,7 +314,7 @@ mod tests {
314
314
  let table = TableSpec {
315
315
  id: TableId::new("T"),
316
316
  title: "Structural Slots".to_string(),
317
- subtitle: None,
317
+ subtitles: Vec::new(),
318
318
  currency: None,
319
319
  collapsible: false,
320
320
  placement: crate::model::table::PlacementSpec::default(),
@@ -90,8 +90,8 @@ pub struct TablePlacement {
90
90
  pub end_row: u32,
91
91
  /// Physical row index of the table title banner if present.
92
92
  pub title_row: Option<u32>,
93
- /// Physical row index of the table subtitle banner if present.
94
- pub subtitle_row: Option<u32>,
93
+ /// Inclusive physical row range of table subtitle banners, or None if the table has zero subtitles.
94
+ pub subtitle_row_range: Option<(u32, u32)>,
95
95
  /// Physical row index of the blank buffer gutter below title/subtitle if present.
96
96
  pub title_gutter_row: Option<u32>,
97
97
  /// Inclusive physical row range of header tiers, or None if the table has zero headers.
@@ -296,24 +296,27 @@ impl LayoutPlanner {
296
296
  None
297
297
  };
298
298
 
299
- // Table Subtitle Row
300
- let subtitle_row = if table.subtitle.is_some() {
301
- let r = current_row;
302
- if r >= MAX_EXCEL_ROWS {
303
- return Err(LayoutError::GridLimitExceeded {
304
- dimension: "rows",
305
- max: MAX_EXCEL_ROWS,
306
- actual: r,
307
- });
299
+ // Table Subtitle Rows
300
+ let subtitle_row_range = if !table.subtitles.is_empty() {
301
+ let subtitle_start = current_row;
302
+ for _ in &table.subtitles {
303
+ if current_row >= MAX_EXCEL_ROWS {
304
+ return Err(LayoutError::GridLimitExceeded {
305
+ dimension: "rows",
306
+ max: MAX_EXCEL_ROWS,
307
+ actual: current_row,
308
+ });
309
+ }
310
+ current_row += 1;
308
311
  }
309
- current_row += 1;
310
- Some(r)
312
+ let subtitle_end = current_row - 1;
313
+ Some((subtitle_start, subtitle_end))
311
314
  } else {
312
315
  None
313
316
  };
314
317
 
315
318
  // Title Buffer Gutter
316
- let title_gutter_row = if title_row.is_some() || subtitle_row.is_some() {
319
+ let title_gutter_row = if title_row.is_some() || subtitle_row_range.is_some() {
317
320
  let r = current_row;
318
321
  if r >= MAX_EXCEL_ROWS {
319
322
  return Err(LayoutError::GridLimitExceeded {
@@ -458,7 +461,7 @@ impl LayoutPlanner {
458
461
  end_col,
459
462
  end_row: table_end_row,
460
463
  title_row,
461
- subtitle_row,
464
+ subtitle_row_range,
462
465
  title_gutter_row,
463
466
  header_row_range,
464
467
  body_row_range: (body_start_row, body_end_row),
@@ -988,8 +988,8 @@ impl PlacementSpec {
988
988
  pub struct TableSpec {
989
989
  pub id: TableId,
990
990
  pub title: String,
991
- #[serde(default, skip_serializing_if = "Option::is_none")]
992
- pub subtitle: Option<String>,
991
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
992
+ pub subtitles: Vec<String>,
993
993
  #[serde(default, skip_serializing_if = "Option::is_none")]
994
994
  pub currency: Option<CurrencyCode>,
995
995
  #[serde(default, skip_serializing_if = "std::ops::Not::not")]
@@ -1006,7 +1006,7 @@ impl TableSpec {
1006
1006
  Self {
1007
1007
  id: id.into(),
1008
1008
  title: title.into(),
1009
- subtitle: None,
1009
+ subtitles: Vec::new(),
1010
1010
  currency: None,
1011
1011
  collapsible: false,
1012
1012
  placement: PlacementSpec::default(),
@@ -1017,7 +1017,16 @@ impl TableSpec {
1017
1017
 
1018
1018
  /// Builder method attaching a subtitle banner.
1019
1019
  pub fn with_subtitle(mut self, subtitle: impl Into<String>) -> Self {
1020
- self.subtitle = Some(subtitle.into());
1020
+ self.subtitles.push(subtitle.into());
1021
+ self
1022
+ }
1023
+
1024
+ /// Builder method attaching multi-row subtitle banners.
1025
+ pub fn with_subtitles(
1026
+ mut self,
1027
+ subtitles: impl IntoIterator<Item = impl Into<String>>,
1028
+ ) -> Self {
1029
+ self.subtitles = subtitles.into_iter().map(Into::into).collect();
1021
1030
  self
1022
1031
  }
1023
1032
 
@@ -1082,9 +1091,7 @@ impl TableSpec {
1082
1091
  table: self.id.clone(),
1083
1092
  });
1084
1093
  }
1085
- if let Some(subtitle) = &self.subtitle
1086
- && subtitle.trim().is_empty()
1087
- {
1094
+ if self.subtitles.iter().any(|s| s.trim().is_empty()) {
1088
1095
  return Err(ModelError::EmptyTableSubtitle {
1089
1096
  table: self.id.clone(),
1090
1097
  });
@@ -12,17 +12,17 @@ authors = [{ name = "Michael (Chencheng) Hu, CFA" }]
12
12
  requires-python = ">=3.12"
13
13
  keywords = ["excel", "financial-modeling", "spreadsheet", "xlsx", "compiler"]
14
14
  classifiers = [
15
- "Development Status :: 4 - Beta",
16
- "Intended Audience :: Developers",
17
- "Intended Audience :: Financial and Insurance Industry",
18
- "Programming Language :: Python :: 3",
19
- "Programming Language :: Python :: 3.12",
20
- "Programming Language :: Python :: 3.13",
21
- "Programming Language :: Python :: 3.14",
22
- "Programming Language :: Python :: Implementation :: CPython",
23
- "Programming Language :: Rust",
24
- "Topic :: Office/Business :: Financial :: Spreadsheet",
25
- "Typing :: Typed",
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "Intended Audience :: Financial and Insurance Industry",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Programming Language :: Python :: 3.14",
22
+ "Programming Language :: Python :: Implementation :: CPython",
23
+ "Programming Language :: Rust",
24
+ "Topic :: Office/Business :: Financial :: Spreadsheet",
25
+ "Typing :: Typed",
26
26
  ]
27
27
  dependencies = []
28
28
 
@@ -36,12 +36,7 @@ Issues = "https://github.com/mhcfa/f8/issues"
36
36
  f8 = "f8.cli:main"
37
37
 
38
38
  [dependency-groups]
39
- dev = [
40
- "maturin>=1.8",
41
- "pytest>=8.0",
42
- "ruff>=0.9",
43
- "pyright>=1.1",
44
- ]
39
+ dev = ["maturin>=1.8", "pytest>=8.0", "ruff>=0.9", "pyright>=1.1"]
45
40
 
46
41
  [tool.maturin]
47
42
  manifest-path = "crates/f8-python/Cargo.toml"
@@ -52,12 +47,12 @@ strip = true
52
47
 
53
48
  [tool.uv]
54
49
  cache-keys = [
55
- { file = "pyproject.toml" },
56
- { file = "Cargo.toml" },
57
- { file = "Cargo.lock" },
58
- { file = "crates/f8-python/Cargo.toml" },
59
- { file = "crates/f8-python/src/**/*.rs" },
60
- { file = "crates/f8-core/src/**/*.rs" },
50
+ { file = "pyproject.toml" },
51
+ { file = "Cargo.toml" },
52
+ { file = "Cargo.lock" },
53
+ { file = "crates/f8-python/Cargo.toml" },
54
+ { file = "crates/f8-python/src/**/*.rs" },
55
+ { file = "crates/f8-core/src/**/*.rs" },
61
56
  ]
62
57
 
63
58
  [[tool.uv.index]]
@@ -100,7 +100,7 @@ class TableAuditor:
100
100
  self._raw = raw
101
101
  self._id: str = raw["table_id"]
102
102
  self._title: str = raw["title"]
103
- self._subtitle: str | None = raw.get("subtitle")
103
+ self._subtitles: list[str] = list(raw.get("subtitles", []))
104
104
  self._sheet: str = raw["sheet"]
105
105
 
106
106
  self._columns: list[str] = [
@@ -140,9 +140,9 @@ class TableAuditor:
140
140
  return self._title
141
141
 
142
142
  @property
143
- def subtitle(self) -> str | None:
144
- """Optional table subtitle or units label."""
145
- return self._subtitle
143
+ def subtitles(self) -> list[str]:
144
+ """Table subtitle lines."""
145
+ return list(self._subtitles)
146
146
 
147
147
  @property
148
148
  def sheet(self) -> str: