Quickstart Guide

Get up and running with Metric Engine in 5 minutes. This guide covers the essential features you need to start building financial applications with confidence.

Installation

pip install metric-engine

For development or documentation features:

pip install metric-engine[dev]  # Includes docs, testing tools
pip install metric-engine[babel]  # Adds international formatting

Core Concepts

Metric Engine revolves around type-safe financial values that carry their units and formatting policies. Think of it as supercharged numbers that know whether they represent money, percentages, or ratios.

Basic Financial Values

Creating Values

from metricengine import FV
from metricengine.units import Money, Percent, Ratio

# Create monetary amounts
revenue = FV(150000, Money)
cost = FV(90000, Money)

# Create percentages and ratios
tax_rate = FV(0.25, Percent)  # 25%
growth_rate = FV(0.15, Ratio)  # 15% as ratio (0.15)

print(revenue)      # $150,000.00
print(tax_rate)     # 25.00%
print(growth_rate)  # 0.15

Safe Arithmetic

All operations are null-safe and unit-aware:

# Standard calculations
gross_profit = revenue - cost
net_income = gross_profit * (1 - tax_rate)

print(f"Gross Profit: {gross_profit}")  # $60,000.00
print(f"Net Income: {net_income}")      # $45,000.00

# Handle missing data gracefully
incomplete_data = FV(None, Money)
safe_result = revenue + incomplete_data  # Returns None, doesn't crash
print(safe_result.is_none())            # True

Unit Safety

The type system prevents common errors:

# This works - same units
total_cost = cost + FV(5000, Money)

# This fails gracefully - mixed units
# mixed = revenue + tax_rate  # Would return None or raise based on policy

Working with Calculations

Built-in Calculation Engine

from metricengine import Engine

# Create an engine for calculations
engine = Engine()

# Define your data
context = {
    "sales": money(100000),
    "cost": money(65000),
    "operating_expenses": money(20000)
}

# Let the engine calculate dependencies
gross_profit = engine.calculate("profitability.gross_profit", context)
operating_margin = engine.calculate("profitability.operating_margin", context)

print(f"Gross Profit: {gross_profit}")      # $35,000.00
print(f"Operating Margin: {operating_margin}")  # 15.00%

Custom Calculations

Register your own business logic:

from metricengine import calc
from metricengine.units import Money, Ratio

@calc("monthly_revenue", depends_on=("annual_revenue",))
def monthly_revenue(annual_revenue: FV[Money]) -> FV[Money]:
    """Calculate monthly revenue from annual."""
    if annual_revenue.is_none():
        return FV.none().money()
    return (annual_revenue / 12).money()

# Use your calculation
context = {"annual_revenue": money(1200000)}
monthly = engine.calculate("monthly_revenue", context)
print(f"Monthly Revenue: {monthly}")  # $100,000.00

Policy-Driven Formatting

Control how values display across your application:

from metricengine.policy import Policy

# Create custom formatting policies
high_precision = Policy(decimal_places=4)
accounting_format = Policy(
    decimal_places=2,
    currency_symbol="$",
    negative_parentheses=True
)

# Apply policies to values
precise_rate = FV(0.123456, Ratio, policy=high_precision)
loss = FV(-5000, Money, policy=accounting_format)

print(precise_rate)  # 0.1235
print(loss)          # ($5,000.00)

Real-World Example: Financial Dashboard

Here’s a complete example calculating key business metrics:

from metricengine import Engine
from metricengine.factories import money, ratio

# Initialize engine and data
engine = Engine()

# Q1 Financial Data
financial_data = {
    "sales": money(850000),
    "cost_of_goods_sold": money(510000),
    "operating_expenses": money(180000),
    "interest_expense": money(15000),
    "tax_rate": ratio(0.21),
}

# Calculate key metrics using built-in calculations
metrics = {}
metrics["gross_profit"] = engine.calculate("profitability.gross_profit", financial_data)
metrics["gross_margin"] = engine.calculate("profitability.gross_margin", financial_data)
metrics["operating_profit"] = engine.calculate("profitability.operating_profit", financial_data)
metrics["operating_margin"] = engine.calculate("profitability.operating_margin", financial_data)

# Display results
print("Q1 Financial Summary")
print("=" * 30)
for name, value in metrics.items():
    print(f"{name.replace('_', ' ').title()}: {value}")

# Output:
# Q1 Financial Summary
# ==============================
# Gross Profit: $340,000.00
# Gross Margin: 40.00%
# Operating Profit: $160,000.00
# Operating Margin: 18.82%

Error Handling & Validation

Metric Engine handles edge cases gracefully:

# Division by zero
safe_ratio = money(100) / money(0)  # Returns None instead of crashing
print(safe_ratio.is_none())  # True

# Invalid input
invalid_amount = money("not_a_number")  # Returns None
print(invalid_amount.is_none())  # True

# Strict mode for validation
from metricengine.policy import Policy
strict_policy = Policy(arithmetic_strict=True)

# This would raise CalculationError instead of returning None
# risky_calc = FV(100, Money, policy=strict_policy) / FV(0, Money, policy=strict_policy)

Next Steps

Now that you’ve seen the basics, explore these areas:

πŸ“š Core Concepts

  • Financial Value - Deep dive into the core abstraction

  • Units - Money, Percent, Ratio, and Dimensionless types

  • Policy - Control formatting and behavior

πŸŽ“ Tutorials

πŸ”§ How-To Guides

πŸ—οΈ Architecture

Ready to build robust financial applications! πŸš€