Formatting Reference

Quick reference for Metric Engine’s formatting capabilities.

Installation

# Basic installation
pip install metric-engine

# With Babel for internationalization
pip install "metric-engine[babel]"

Quick Start

from metricengine.factories import money, percent
from metricengine.policy import DisplayPolicy

# Create values
amount = money(1234.56)
rate = percent(12.5, input="percent")

# Format with policy
policy = DisplayPolicy(locale="en_US", currency="USD")
print(amount.format(policy))  # $1,234.56
print(rate.format(policy))    # 12.50%

DisplayPolicy Parameters

Parameter	Type	Default	Description
`locale`	str	“en_US”	Locale code (e.g., “en_US”, “de_DE”)
`currency`	str	“USD”	Currency code (e.g., “USD”, “EUR”, “JPY”)
`max_frac`	int	2	Maximum decimal places
`min_frac`	int	0	Minimum decimal places
`use_grouping`	bool	True	Use thousands separators
`currency_style`	str	“standard”	“standard” or “accounting”
`negative_parens`	bool	False	Use parentheses for negatives
`percent_scale`	str	“percent”	“percent” or “ratio”
`compact`	str	None	“short” or “long” (Babel only)
`fallback_locale`	str	“en_US”	Fallback if locale fails

Common Locale Examples

# United States
DisplayPolicy(locale="en_US", currency="USD")
# Output: $1,234.56

# Germany
DisplayPolicy(locale="de_DE", currency="EUR")
# Output: 1.234,56 €

# Japan
DisplayPolicy(locale="ja_JP", currency="JPY", max_frac=0)
# Output: ¥1,235

# United Kingdom
DisplayPolicy(locale="en_GB", currency="GBP")
# Output: £1,234.56

# France
DisplayPolicy(locale="fr_FR", currency="EUR")
# Output: 1 234,56 €

Formatter Classes

get_formatter()

Factory function that returns the best available formatter:

from metricengine.formatters.base import get_formatter

formatter = get_formatter()
# Returns BabelFormatter if Babel is available, else BuiltinFormatter

BabelFormatter

Full-featured formatter with Babel integration:

from metricengine.formatters.babel_adapter import BabelFormatter

try:
    formatter = BabelFormatter()
except BabelUnavailable:
    # Babel not installed
    pass

Methods:

money(amount, unit, display_policy) - Format currency
number(value, display_policy) - Format plain numbers
percent(ratio_or_percent, display_policy) - Format percentages

BuiltinFormatter

Fallback formatter without external dependencies:

from metricengine.formatters.base import BuiltinFormatter

formatter = BuiltinFormatter()
# Same interface as BabelFormatter but basic formatting

Value Factory Functions

from metricengine.factories import money, percent, ratio

# Money values
usd_amount = money(1234.56)                    # Defaults to USD
eur_amount = money(1234.56, currency="EUR")    # Specify currency

# Percentages
percent_input = percent(25, input="percent")   # 25%
ratio_input = percent(0.25, input="ratio")    # 25% from 0.25 ratio

# Plain ratios
growth_ratio = ratio(0.15)                     # 0.15 (15% growth)

Formatting Methods

Direct Formatting

# Using the format() method
amount = money(1234.56)
policy = DisplayPolicy(locale="en_US", currency="USD")
result = amount.format(policy)

Formatter Interface

from metricengine.formatters.base import get_formatter
from decimal import Decimal

formatter = get_formatter()
policy = DisplayPolicy(locale="en_US", currency="USD")

# Format different types
money_result = formatter.money(Decimal("1234.56"), None, policy)
number_result = formatter.number(Decimal("1234.56"), policy)
percent_result = formatter.percent(Decimal("0.1556"), policy)

Accounting Style

For financial reports with parentheses for negatives:

policy = DisplayPolicy(
    locale="en_US",
    currency="USD",
    currency_style="accounting",
    negative_parens=True
)

profit = money(1000)
loss = money(-1000)

print(profit.format(policy))  # $1,000.00
print(loss.format(policy))    # ($1,000.00)

Error Handling

from metricengine.formatters.base import BabelUnavailable

try:
    from metricengine.formatters.babel_adapter import BabelFormatter
    formatter = BabelFormatter()
except BabelUnavailable:
    print("Babel not available, using builtin formatter")
    from metricengine.formatters.base import BuiltinFormatter
    formatter = BuiltinFormatter()

Supported Currencies

Common currency codes (with Babel):

Code	Currency	Symbol
USD	US Dollar	$
EUR	Euro	€
GBP	British Pound	£
JPY	Japanese Yen	¥
CAD	Canadian Dollar	C$
AUD	Australian Dollar	A$
CHF	Swiss Franc	CHF
CNY	Chinese Yuan	¥

Supported Locales

Common locale codes:

Code	Language/Region
en_US	English (United States)
en_GB	English (United Kingdom)
de_DE	German (Germany)
fr_FR	French (France)
es_ES	Spanish (Spain)
it_IT	Italian (Italy)
ja_JP	Japanese (Japan)
zh_CN	Chinese (Simplified)
pt_BR	Portuguese (Brazil)
ru_RU	Russian (Russia)

Performance Tips

Cache DisplayPolicy instances:

# Good
policy = DisplayPolicy(locale="en_US", currency="USD")
for amount in amounts:
    result = amount.format(policy)

Cache formatter instances:

# Good
formatter = get_formatter()
for amount in amounts:
    result = formatter.money(amount, None, policy)

Reuse policies across similar values:

# Good
usd_policy = DisplayPolicy(locale="en_US", currency="USD")
eur_policy = DisplayPolicy(locale="de_DE", currency="EUR")

Common Patterns

Multi-locale Application

class LocaleFormatter:
    def __init__(self):
        self.policies = {
            'us': DisplayPolicy(locale="en_US", currency="USD"),
            'de': DisplayPolicy(locale="de_DE", currency="EUR"),
            'jp': DisplayPolicy(locale="ja_JP", currency="JPY", max_frac=0),
        }

    def format_for_region(self, amount, region='us'):
        policy = self.policies.get(region, self.policies['us'])
        return amount.format(policy)

Financial Reports

def format_financial_report(data, locale="en_US"):
    policy = DisplayPolicy(
        locale=locale,
        currency="USD",
        currency_style="accounting",
        negative_parens=True,
        max_frac=2
    )

    return {
        'revenue': data['revenue'].format(policy),
        'expenses': data['expenses'].format(policy),
        'profit': (data['revenue'] - data['expenses']).format(policy)
    }

User Preferences

def create_user_policy(user_prefs):
    return DisplayPolicy(
        locale=user_prefs.get('locale', 'en_US'),
        currency=user_prefs.get('currency', 'USD'),
        max_frac=user_prefs.get('decimal_places', 2),
        use_grouping=user_prefs.get('use_grouping', True),
        negative_parens=user_prefs.get('accounting_style', False)
    )

Troubleshooting

Babel not found:

pip install "metric-engine[babel]"

Invalid locale:

# Use fallback_locale in DisplayPolicy
policy = DisplayPolicy(
    locale="invalid_locale",
    fallback_locale="en_US"
)

Currency not displaying:

Check that currency code is valid (ISO 4217)
Verify locale supports the currency
Use currency_style="standard" for basic symbol display

Decimal places not working:

Set both max_frac and min_frac for exact control
Some currencies (like JPY) don’t use decimal places

Grouping not working:

Ensure use_grouping=True in DisplayPolicy
Check that locale supports grouping separators