metricengine.policy

Policy configuration for Metric Engine calculations.

metricengine.policy.default_quantizer_factory(decimal_places)

Exact, fast quantizer for given dp: e.g., dp=2 -> Decimal(‘0.01’).

Return type:

Decimal

class metricengine.policy.DisplayPolicy(locale='en_ZA', currency='ZAR', currency_style='standard', use_grouping=True, min_int=None, min_frac=None, max_frac=None, compact=None, percent_scale='ratio', percent_style='standard', negative_parens=False, fallback_locale='en_US')

Bases: object

Immutable configuration for locale-aware formatting.

This policy controls how financial values are formatted for display, including currency symbols, number formatting, and locale-specific conventions.

locale: str = 'en_ZA'

currency: str = 'ZAR'

currency_style: str = 'standard'

use_grouping: bool = True

min_int: Optional[int] = None

min_frac: Optional[int] = None

max_frac: Optional[int] = None

compact: Optional[str] = None

percent_scale: str = 'ratio'

percent_style: str = 'standard'

negative_parens: bool = False

fallback_locale: str = 'en_US'

class metricengine.policy.Policy(decimal_places=2, rounding='ROUND_HALF_UP', none_text='—', percent_display='percent', cap_percentage_at=<factory>, percent_style='percent', quantizer_factory=<function default_quantizer_factory>, negative_sales_is_none=True, compare_none_as_minus_infinity=False, arithmetic_strict=False, thousands_sep=True, currency_symbol=None, currency_position='prefix', negative_parentheses=False, locale=None, display=None)

Bases: object

Immutable configuration for financial calculations and formatting.

decimal_places: int = 2

rounding: str = 'ROUND_HALF_UP'

none_text: str = '—'

percent_display: Literal['ratio', 'percent'] = 'percent'

cap_percentage_at: Optional[Decimal]

percent_style: str = 'percent'

quantizer_factory()

Exact, fast quantizer for given dp: e.g., dp=2 -> Decimal(‘0.01’).

Return type:

Decimal

negative_sales_is_none: bool = True

compare_none_as_minus_infinity: bool = False

arithmetic_strict: bool = False

thousands_sep: bool = True

currency_symbol: Optional[str] = None

currency_position: Literal['prefix', 'suffix'] = 'prefix'

negative_parentheses: bool = False

locale: Optional[str] = None

display: Optional[DisplayPolicy] = None

quantize(d)

Quantize according to policy. Supports arbitrary step sizes (e.g., 0.5) by rounding to nearest step.

Return type:

Decimal

format_decimal(d, unit)

Format a decimal with thousands separators, currency, and negative style.

This method is deprecated and will delegate to the built-in formatter for backward compatibility.

Return type:

str

format_percent(ratio_value)

Render ratio (0..1) as percent text. Always clamp to cap_percentage_at if provided.

Return type:

str

Policy Classes

class metricengine.policy.Policy(decimal_places=2, rounding='ROUND_HALF_UP', none_text='—', percent_display='percent', cap_percentage_at=<factory>, percent_style='percent', quantizer_factory=<function default_quantizer_factory>, negative_sales_is_none=True, compare_none_as_minus_infinity=False, arithmetic_strict=False, thousands_sep=True, currency_symbol=None, currency_position='prefix', negative_parentheses=False, locale=None, display=None)

Bases: object

Immutable configuration for financial calculations and formatting.

decimal_places: int = 2

rounding: str = 'ROUND_HALF_UP'

none_text: str = '—'

percent_display: Literal['ratio', 'percent'] = 'percent'

cap_percentage_at: Optional[Decimal]

percent_style: str = 'percent'

quantizer_factory()

Exact, fast quantizer for given dp: e.g., dp=2 -> Decimal(‘0.01’).

Return type:

Decimal

negative_sales_is_none: bool = True

compare_none_as_minus_infinity: bool = False

arithmetic_strict: bool = False

thousands_sep: bool = True

currency_symbol: Optional[str] = None

currency_position: Literal['prefix', 'suffix'] = 'prefix'

negative_parentheses: bool = False

locale: Optional[str] = None

display: Optional[DisplayPolicy] = None

quantize(d)

Quantize according to policy. Supports arbitrary step sizes (e.g., 0.5) by rounding to nearest step.

Return type:

Decimal

format_decimal(d, unit)

Format a decimal with thousands separators, currency, and negative style.

This method is deprecated and will delegate to the built-in formatter for backward compatibility.

Return type:

str

format_percent(ratio_value)

Render ratio (0..1) as percent text. Always clamp to cap_percentage_at if provided.

Return type:

str

__init__(decimal_places=2, rounding='ROUND_HALF_UP', none_text='—', percent_display='percent', cap_percentage_at=<factory>, percent_style='percent', quantizer_factory=<function default_quantizer_factory>, negative_sales_is_none=True, compare_none_as_minus_infinity=False, arithmetic_strict=False, thousands_sep=True, currency_symbol=None, currency_position='prefix', negative_parentheses=False, locale=None, display=None)

Policy Functions