money-warp 0.25.0

MoneyWarp – Bend time. Model cash.

MoneyWarp

Bend time. Model cash.

Development Stage Notice -- MoneyWarp is in active development (alpha). Core classes are stable and covered by 1200+ tests, but the API may evolve.

MoneyWarp is a Python library for working with the time value of money. It treats loans, annuities, and investments as cash flows through time -- and gives you the tools to warp them back and forth between present, future, and everything in between.

Features

• Time Machine (Warp) -- travel to any date and see loan state as of that moment
• PMT, NPV, IRR, MIRR -- core finance functions powered by scipy
• Loan tracking -- payments, fines, mora interest, grace periods
• High-precision Money -- Decimal arithmetic, never floats
• Amortization schedules -- French (Price) and SAC (Inverted Price)
• Flexible dates -- irregular due dates, smart month-end handling
• Type-safe interest rates -- explicit percentage handling, frequency conversions
• Installments and Settlements -- first-class repayment plan and payment allocation
• Tax module -- Brazilian IOF, grossup, pluggable tax strategy
• Timezone-aware -- UTC by default, configurable globally
• Marshmallow extension -- custom fields for serialization
• SQLAlchemy extension -- column types + loan/settlement bridge with SQL-queryable balance

Installation

pip install money-warp

With optional extensions:

pip install money-warp[marshmallow]   # Marshmallow fields
pip install money-warp[sa]            # SQLAlchemy types + bridge

Quick Start

from datetime import datetime, timezone
from money_warp import Money, InterestRate, Loan, generate_monthly_dates
from money_warp.tz import to_date

principal = Money("10000.00")
rate = InterestRate("5% a")  # 5% annually

start_date = datetime(2024, 1, 15, tzinfo=timezone.utc)
due_dates = [to_date(d) for d in generate_monthly_dates(start_date, 12)]

loan = Loan(principal, rate, due_dates)

schedule = loan.get_amortization_schedule()
print(f"Monthly payment: {schedule[0].payment_amount}")
print(f"Total interest: {schedule.total_interest}")

loan.record_payment(Money("856.07"), datetime(2024, 2, 1, tzinfo=timezone.utc))
print(f"Remaining balance: {loan.current_balance}")

Time Machine

Travel to any date and see the loan exactly as it was -- payments, interest, fines, everything filtered to that moment:

from money_warp import Warp, Loan, Money, InterestRate
from datetime import date, datetime

loan = Loan(Money("10000"), InterestRate("5% a"), [date(2024, 1, 15)])
loan.record_payment(Money("500"), datetime(2024, 1, 10))
loan.record_payment(Money("600"), datetime(2024, 2, 10))
loan.record_payment(Money("700"), datetime(2024, 3, 10))

# Warp to the past -- only payments made by that date are visible
with Warp(loan, datetime(2024, 1, 20)) as past_loan:
    print(f"Balance on Jan 20: {past_loan.current_balance}")

# Warp to the future
with Warp(loan, datetime(2025, 1, 1)) as future_loan:
    print(f"Balance in 2025: {future_loan.current_balance}")

# Original loan is unchanged
print(f"Present balance: {loan.current_balance}")

Documentation

Full guides, examples, and API reference at tomascorrea.github.io/money-warp.

• Quick Start
• Money and Precision
• Interest Rates
• Cash Flow Analysis
• Date Generation
• Time Machine
• Present Value and IRR
• Fines and Mora Interest
• Tax and IOF
• Timezone Handling
• Marshmallow Extension
• SQLAlchemy Extension
• API Reference

Contributing

Contributions are welcome! See the Contributing Guide for details.

License

MIT -- see LICENSE.