Part 3 — Calculations & Logging
In this part, you'll create a BudgetSummary model that automatically calculates budget utilization for each team per quarter — and logs the results in a rich, formatted report using LexLogger. This model lives in the Reports/ folder, the Load layer of your ETL pipeline. For a deep-dive into how CalculationModel works under the hood, see CalculationModel Internals.
Create Reports/BudgetSummary.py
In PyCharm, right-click the Reports/ folder → New → Python File → name it BudgetSummary:
from django.db import models
from lex.core.models.CalculationModel import CalculationModel
from lex.audit_logging.handlers.LexLogger import LexLogger
from Input.Team import Team
from Input.Expense import Expense
class BudgetSummary(CalculationModel):
"""Auto-calculated budget utilization per team per quarter."""
team = models.ForeignKey(Team, on_delete=models.CASCADE)
quarter = models.CharField(max_length=10)
# Calculated fields (populated by calculate())
total_expenses = models.DecimalField(
max_digits=12, decimal_places=2, default=0
)
remaining_budget = models.DecimalField(
max_digits=12, decimal_places=2, default=0
)
utilization_pct = models.DecimalField(
max_digits=5, decimal_places=2, default=0,
help_text="Budget utilization percentage",
)
expense_count = models.IntegerField(default=0)
is_over_budget = models.BooleanField(default=False)
def __str__(self):
return f"{self.team.name} — {self.quarter}"
def calculate(self):
"""
Calculate budget utilization for a team in a given quarter.
Called when the user clicks "Calculate" in the UI.
"""
logger = LexLogger()
# Query all expenses for this team and quarter
expenses = Expense.objects.filter(
employee__team=self.team,
quarter=self.quarter,
)
# Compute totals
self.total_expenses = expenses.aggregate(
total=models.Sum("amount")
)["total"] or 0
self.expense_count = expenses.count()
self.remaining_budget = self.team.budget - self.total_expenses
self.utilization_pct = (
(self.total_expenses / self.team.budget * 100)
if self.team.budget > 0
else 0
)
self.is_over_budget = self.total_expenses > self.team.budget
# ── Log the results ──
logger.add_heading(
f"Budget Report: {self.team.name} — {self.quarter}"
)
logger.add_table(
headers=["Metric", "Value"],
rows=[
["Total Expenses", f"€{self.total_expenses:,.2f}"],
["Team Budget", f"€{self.team.budget:,.2f}"],
["Remaining", f"€{self.remaining_budget:,.2f}"],
["Utilization", f"{self.utilization_pct:.1f}%"],
["# of Expenses", str(self.expense_count)],
],
)
# Breakdown by category
category_data = (
expenses.values("category")
.annotate(total=models.Sum("amount"))
.order_by("-total")
)
if category_data:
logger.add_heading("Breakdown by Category", level=2)
logger.add_table(
headers=["Category", "Amount"],
rows=[
[row["category"], f"€{row['total']:,.2f}"]
for row in category_data
],
)
# Over-budget warning
if self.is_over_budget:
logger.add_text(
f"⚠️ OVER BUDGET by €{abs(self.remaining_budget):,.2f}!"
)
logger.log()Notice how the import paths work: BudgetSummary lives in Reports/, while Team and Expense are in Input/ — so we import them with from Input.Team import Team.
Let's break down what's happening:
Part | What It Does |
|---|---|
| Inherits the calculate button and state machine |
| Your business logic — just compute and assign |
| Builds a rich Markdown report |
| Saves the report — visible in the calculation logs panel |
Notice what you don't need to write: no state management (
is_calculatedis automatic), no error handling (framework catches exceptions), noself.save()(framework saves aftercalculate()returns).
Update model_structure.yaml
Add the BudgetSummary to your sidebar configuration:
model_structure:
Teams & People:
team: null
employee: null
Expenses:
expense: null
Reports:
budgetsummary: null
Data Import:
teamupload: null
employeeupload: null
expenseupload: null
model_styling:
Teams & People:
name: "👥 Teams & People"
Expenses:
name: "💶 Expenses"
Reports:
name: "📊 Reports"
Data Import:
name: "📥 Data Import"
untracked_models:
teamupload: null
employeeupload: null
expenseupload: nullApply to the Database
Select "Init" from the run configuration dropdown in PyCharm → click ▶️.
Terminal alternative
Linux / macOS:set -a; source .env; set +a lex InitWindows PowerShell:
lex Init
Try It Out
- Select "Start" in PyCharm → click ▶️
- Navigate to Reports → BudgetSummary in the frontend
- Create a new record: select a team and enter a quarter (e.g., "Q1 2026")
- Click the Calculate button ▶️
You should see:
- The
is_calculatedfield transitions:NOT_CALCULATED→IN_PROGRESS→SUCCESS - The calculated fields fill in automatically
- The Calculation Log panel shows your formatted report
How the State Machine Works
stateDiagram-v2
[*] --> NOT_CALCULATED : Record created
NOT_CALCULATED --> IN_PROGRESS : "Calculate" clicked
IN_PROGRESS --> SUCCESS : calculate completed
IN_PROGRESS --> ERROR : Exception raised
ERROR --> IN_PROGRESS : Retry
SUCCESS --> IN_PROGRESS : RecalculateIf your calculate() method throws an exception, the framework sets is_calculated = ERROR, stores the error message, and the user can retry. For more details, see Calculations.
In production, large calculations can be dispatched to Celery workers for parallel processing. During development, everything runs synchronously.
Checkpoint
At this point you have:
- A
BudgetSummarymodel inReports/that calculates on demand - Rich calculation logs with tables and formatting
- Automatic state management (no boilerplate)
- An updated sidebar with a "Reports" group
Your project now follows the full ETL pattern:
TeamBudget/
├── Upload/ ← Extract
├── Input/ ← Transform
└── Reports/ ← LoadNext up: Part 4 — Validation & Permissions.
Was this helpful?
Your feedback shapes what we write next.
