# Why decimal.Decimal Is Used Over float for Financial Data Precision in Python

> Learn why Python's decimal Decimal is crucial for financial data precision, preventing errors common with float in market calculations and valuations.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: best-practices
- Published: 2026-07-26

---

**Python's `decimal.Decimal` is used instead of `float` in financial applications to eliminate binary floating-point representation errors that can corrupt market capitalization calculations, valuation ratios, and cross-source data validation.**

The ai-berkshire repository implements a strict `Decimal`-first architecture across its financial analysis tools. By mandating exact decimal arithmetic, the codebase prevents the microscopic rounding drifts inherent to IEEE-754 binary floats—drifts that compound disastrously when calculating billions of dollars in market cap or verifying PE ratios against third-party data sources.

## The Binary Float Problem in Financial Calculations

Python's built-in `float` type stores numbers in binary IEEE-754 format, which cannot represent common decimal fractions precisely. This creates *floating-point drift* where basic arithmetic yields unexpected results:

```python
>>> 0.1 + 0.2 == 0.3
False
>>> 0.1 + 0.2
0.30000000000000004

```

For financial software, these invisible errors multiply across chains of operations. When calculating market capitalization as `price × shares outstanding`, a microscopic binary rounding error in the price field can produce a valuation discrepancy of millions of dollars at scale. The ai-berkshire codebase eliminates this risk by standardizing on `decimal.Decimal` for all monetary values.

## Decimal Implementation in ai-berkshire

The repository centralizes decimal handling in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), enforcing consistent precision and rounding rules across the entire calculation pipeline.

### Exact Conversion with the exact() Function

The `exact()` utility at lines 31-38 in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) converts all incoming numeric data to `Decimal` while avoiding the classic `float` trap:

```python
from decimal import Decimal, Context, ROUND_HALF_EVEN

_CTX = Context(prec=28, rounding=ROUND_HALF_EVEN)

def exact(value) -> Decimal:
    """Convert any numeric to an exact Decimal, avoiding float traps."""
    if isinstance(value, Decimal):
        return value
    if isinstance(value, float):
        return Decimal(str(value))
    return Decimal(str(value))

```

Passing `float` values through `str()` before `Decimal` instantiation preserves the literal decimal representation rather than the imprecise binary float value. This ensures that `0.1` remains exactly `0.1`, not `0.10000000000000000555`.

### Controlled Precision Context

Lines 27-29 establish a module-level context with 28-digit precision and banker's rounding (`ROUND_HALF_EVEN`):

```python
_CTX = Context(prec=28, rounding=ROUND_HALF_EVEN)

```

All arithmetic operations in the repository use this `_CTX` explicitly, guaranteeing deterministic results across different platforms and Python versions. The 28-digit precision accommodates large-scale calculations (e.g., trillions of shares) without losing significant digits.

### Market Cap and Valuation Verification

The verification functions at lines 61-90 in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) demonstrate the architectural commitment to decimal precision. The `verify_market_cap()` function performs exact multiplication of price and shares, then compares against reported market cap values with strict tolerance checks:

```python
def verify_market_cap(price, shares, reported_cap, currency=""):
    p = exact(price)
    s = exact(shares)
    r = exact(reported_cap)
    
    calculated = _CTX.multiply(p, s)
    # Validation logic proceeds with exact values...

```

This pattern ensures that `verify_valuation()` and related functions compute PE, PB, and ROE ratios without floating-point artifacts corrupting the output.

## Data Ingestion with Decimal

In [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py), the repository ingests A-share (Chinese equity) data by immediately wrapping price and market-cap strings with `Decimal` before any mathematical operations. This creates a *precision firewall* at the data boundary—once converted to `Decimal`, values cannot be contaminated by float arithmetic downstream. The [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) module inherits this same decimal discipline when auditing generated research reports.

## Practical Code Examples

The following patterns from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) demonstrate production-grade decimal handling:

**Setting up the precision context and conversion utilities:**

```python
from decimal import Decimal, Context, ROUND_HALF_EVEN

_CTX = Context(prec=28, rounding=ROUND_HALF_EVEN)

def exact(value) -> Decimal:
    """Convert any numeric to an exact Decimal, avoiding float traps."""
    if isinstance(value, Decimal):
        return value
    if isinstance(value, float):
        return Decimal(str(value))
    return Decimal(str(value))

```

**Verifying market capitalization with exact arithmetic:**

```python
def verify_market_cap(price, shares, reported_cap, currency=""):
    p = exact(price)
    s = exact(shares)
    r = exact(reported_cap)

    calculated = _CTX.multiply(p, s)
    deviation = abs(float(calculated - r) / float(r)) * 100 if r != 0 else 0

    print(f"Price: {p} {currency}")
    print(f"Shares: {s}")
    print(f"Calculated cap: {calculated}")
    print(f"Reported cap:   {r}")
    print(f"Deviation: {deviation:.2f}%")
    return deviation

# Example usage

verify_market_cap(price="510", shares="9.11e9", reported_cap="4.65e12", currency="HKD")

```

**Calculating valuation ratios without floating-point drift:**

```python
def valuation_ratios(price, eps=None, bvps=None, fcf_per_share=None):
    p = exact(price)
    results = {}

    if eps:
        e = exact(eps)
        pe = _CTX.divide(p, e)
        results["PE"] = float(pe)
        print(f"PE = {p} / {e} = {pe:.2f}")

    if bvps:
        b = exact(bvps)
        pb = _CTX.divide(p, b)
        results["PB"] = float(pb)
        print(f"PB = {p} / {b} = {pb:.2f}")

    if fcf_per_share:
        f = exact(fcf_per_share)
        pfcf = _CTX.divide(p, f)
        results["P/FCF"] = float(pfcf)
        print(f"P/FCF = {p} / {f} = {pfcf:.2f}")

    return results

# Example usage

valuation_ratios(price="510", eps="23.5", bvps="120", fcf_per_share="18")

```

## Benefits of Decimal Over float for Financial Data

The architectural decision to standardize on `decimal.Decimal` provides concrete advantages over IEEE-754 `float`:

- **Exact base-10 representation**: `Decimal` stores numbers as base-10 significand/exponent pairs, eliminating the binary approximation errors that plague `float` when representing currency values like `0.01` or `0.05`.

- **Deterministic rounding**: The explicit `ROUND_HALF_EVEN` context in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) ensures that rounding behavior is consistent across platforms, satisfying financial auditing requirements that ambiguous `float` rounding cannot meet.

- **Cross-source validation integrity**: When `verify_market_cap()` compares calculated versus reported values, exact decimal arithmetic prevents tiny drifts from triggering false validation warnings, reducing noise in automated data quality checks.

- **Safe large-scale arithmetic**: With 28 digits of precision, the codebase safely handles calculations involving billions of shares and trillions in market capitalization without losing significance—operations that would degrade precision with `float`.

## Summary

- The ai-berkshire repository mandates `decimal.Decimal` for all financial calculations to eliminate IEEE-754 binary floating-point errors.
- The `exact()` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) converts inputs via `Decimal(str(value))` to preserve literal decimal values and avoid float contamination.
- A module-level `Context(prec=28, rounding=ROUND_HALF_EVEN)` ensures deterministic, high-precision arithmetic across market cap verification and valuation ratio calculations.
- Data ingestion modules like [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py) wrap raw price strings immediately in `Decimal`, creating a precision firewall at the system boundary.
- This architecture guarantees that cross-source validation, PE/PB calculations, and market cap checks remain mathematically exact and auditable.

## Frequently Asked Questions

### Why can't I use float for financial calculations in Python?

IEEE-754 binary floats cannot represent most decimal fractions exactly, leading to representation errors like `0.1 + 0.2 != 0.3`. In financial software, these errors compound across multiplication and division operations, potentially producing incorrect valuations, misleading ratios, and failed validation checks when comparing against external data sources.

### How does ai-berkshire handle float-to-Decimal conversion?

The repository uses the `exact()` helper in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (lines 31-38) which converts floats to strings before instantiating `Decimal`. This `Decimal(str(value))` pattern captures the literal decimal representation displayed to users rather than the underlying imprecise binary value, ensuring `0.1` remains exactly `0.1` in calculations.

### What rounding mode does ai-berkshire use for Decimal arithmetic?

The codebase configures a global `decimal.Context` with `rounding=ROUND_HALF_EVEN` (banker's rounding) at lines 27-29 in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). This is the industry standard for financial calculations, rounding to the nearest even number when the value is exactly halfway between two options, minimizing cumulative rounding bias over large datasets.

### Does using Decimal impact performance compared to float?

`decimal.Decimal` operations are slower than hardware-accelerated `float` arithmetic because they are implemented in software with arbitrary precision. However, for financial validation tasks in ai-berkshire—such as verifying market caps or calculating valuation ratios—the precision guarantee outweighs the performance cost, as these calculations are not performed in tight loops requiring microsecond latency.