decimo

A drop-in replacement for Python's decimal, written in Mojo.

⚠️ Development release. The API is settled enough to use, but the versions carry a timestamp: 0.14.0.devYYYYMMDDHHMMSS, where 0.14.0 is the version of the Mojo library the wheel packages. Wheels: macOS arm64 (14 and later), CPython 3.13 and 3.14. Everywhere else, build from source.

Change one import and your program keeps working:

# from decimal import Decimal, getcontext
from decimo import Decimal, getcontext

getcontext().prec = 50
print(Decimal(1) / Decimal(7))
# 0.14285714285714285714285714285714285714285714285714

The two libraries agree digit for digit. The test suite checks every operation against the standard library rather than against a table of expected strings, so "agrees with decimal" is a property that is measured, not a claim.

How fast is it?

The same benchmark file run against both libraries -- python/benchmarks/compare.py in the repository, which imports one or the other and runs identical code. Best of five, on an Apple M-series laptop:

decimo is faster once the numbers are large, and 20-25% behind on small ones. The small-number gap is not the arithmetic: measured against libmpdec directly, without an interpreter in the way, decimo is 2-4× faster at 9 digits and faster at every operation at 1000 digits. What is left is the cost of the Python call itself -- building the result object and converting the operands -- which CPython's decimal has had thirty years to shave. See the benchmarks.

What works

Everything a decimal program normally touches:

• all the operators, including //, %, divmod() and **
• getcontext().prec and getcontext().rounding, setcontext(), localcontext() (with keyword overrides), Context objects
• all the rounding modes: ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_DOWN, ROUND_UP, ROUND_CEILING, ROUND_FLOOR, exact for arithmetic, quantize, round() and to_integral_value()
• int(), float(), round(), math.floor/ceil/trunc, hash(), format()
• quantize, normalize, as_tuple, as_integer_ratio, compare, fma, sqrt, exp, ln, log10, scaleb, adjusted, copy_abs, copy_negate, copy_sign, same_quantum, to_eng_string, max, min
• the rest of the specification's surface: remainder_near, next_plus, next_minus, next_toward, shift, rotate, logical_and, logical_or, logical_xor, logical_invert, logb, compare_total, compare_total_mag, compare_signal, max_mag, min_mag, number_class, to_integral_exact, is_normal, is_subnormal, from_number
• the same coercion rules: int converts in arithmetic, float does not, and both convert in a comparison
• copy, deepcopy and pickle
• ZeroDivisionError where you expect it, and hashes that agree with int, float and decimal.Decimal

What does not

decimo refuses these rather than answering differently:

• NaN and infinity. decimo has no non-finite values. is_nan() and is_infinite() are always False.
• ROUND_05UP. Nothing implements it; setting it raises NotImplementedError.
• ** under a rounding mode other than ROUND_HALF_EVEN is computed nine digits wider and rounded once more, so the last digit can differ from decimal when the true value lies within 10^-9 relative of a rounding boundary. sqrt, exp, ln and log10 are always half to even, as they are in decimal, whatever the context says. Arithmetic, quantize and round() are exact under every mode.
• //, %, divmod() and remainder_near with a long quotient. decimal raises InvalidOperation when the integer quotient has more digits than the precision; decimo answers. The remainder is rounded to the context, as in decimal.
• Emin only reaches four methods. Exponents are unbounded, so Emin changes nothing except what next_plus(0), next_minus(0), is_subnormal() and number_class() say, where decimal's answers need a smallest exponent.
• Signals and traps. Context.flags and Context.traps exist and stay empty. Inexact, Rounded and the rest are importable but never raised.
• Emin / Emax. Exponents are unbounded, so nothing ever underflows to zero or overflows to infinity. A loop that waits for a term to become exactly zero will not stop; wait for the sum to stop changing instead.
• One context per process, not per thread.

DivisionByZero and InvalidOperation are aliases for ZeroDivisionError and ValueError, which is what decimo actually raises, so except clauses written against decimal still catch.

Installing

pip install decimo

Wheels are built for macOS arm64 (macOS 14 and later), for CPython 3.13 and 3.14. On anything else -- Linux included, until its build is verified -- build from source with pixi:

git clone https://github.com/forfudan/decimo && cd decimo
pixi run -e py314 release        # or py313; the wheel lands in python/dist/
pip install python/dist/*.whl

Links

• GitHub: https://github.com/forfudan/decimo
• Benchmarks: https://github.com/forfudan/decimo/blob/main/docs/benchmarks.md
• Changelog: https://github.com/forfudan/decimo/blob/main/docs/changelog.md
• Mojo library docs: https://github.com/forfudan/decimo/blob/main/docs/api.md