debt_optimizer.core.financial_calc module

class debt_optimizer.core.financial_calc.PaymentFrequency(value)[source]

Bases: Enum

Supported payment frequencies.

ONCE = 'once'
DAILY = 'daily'
WEEKLY = 'weekly'
BI_WEEKLY = 'bi-weekly'
SEMI_MONTHLY = 'semi-monthly'
MONTHLY = 'monthly'
QUARTERLY = 'quarterly'
SEMI_ANNUALLY = 'semi-annually'
ANNUALLY = 'annually'
class debt_optimizer.core.financial_calc.RecurrencePattern(frequency, start_date, end_date=None)[source]

Bases: object

Handles calculation and generation of recurring date patterns.

Supports all common recurrence frequencies including daily, weekly, bi-weekly, monthly, quarterly, semi-annually, and annually.

Parameters:

  • frequency (str)

  • start_date (date)

  • end_date (date | None)

__init__(frequency, start_date, end_date=None)[source]

Initialize a recurrence pattern.

Parameters:

  • frequency (str) – One of the supported frequency types from PaymentFrequency enum

  • start_date (date) – The date when this pattern begins

  • end_date (Optional[date]) – Optional end date for the pattern (None means no end)

get_dates(range_start, range_end)[source]

Generate all occurrence dates within the given date range.

Parameters:

  • range_start (date) – Start date of the range to generate dates for

  • range_end (date) – End date of the range to generate dates for

Return type:

List[date]

Returns:

List of dates on which the pattern occurs within the range

get_monthly_frequency()[source]

Calculate the monthly frequency (occurrences per month) of this pattern.

Return type:

float

Returns:

Float representing the average number of occurrences per month

__str__()[source]

Return a human-readable representation of the pattern.

Return type:

str

class debt_optimizer.core.financial_calc.Debt(name, balance, minimum_payment, interest_rate, due_date)[source]

Bases: object

Represents a debt with payment terms and current balance.

Parameters:
name: str
balance: float
minimum_payment: float
interest_rate: float
due_date: int
__post_init__()[source]

Validate debt parameters after initialization.

property monthly_interest_rate: float

Calculate monthly interest rate from annual rate.

calculate_interest_charge(balance)[source]

Calculate monthly interest charge on given balance.

Return type:

float

Parameters:

balance (float)

calculate_principal_payment(total_payment, balance)[source]

Calculate principal portion of a payment.

Return type:

float

Parameters:
calculate_months_to_payoff(payment_amount)[source]

Calculate months to pay off debt with fixed payment amount.

Return type:

float

Parameters:

payment_amount (float)

__init__(name, balance, minimum_payment, interest_rate, due_date)
Parameters:
Return type:

None

class debt_optimizer.core.financial_calc.Income(source, amount, frequency, start_date)[source]

Bases: object

Represents an income source with frequency and timing.

Parameters:
source: str
amount: float
frequency: str
start_date: date
__post_init__()[source]

Validate income parameters after initialization.

get_monthly_amount()[source]

Convert income to monthly equivalent amount.

Return type:

float

get_payment_dates(start_date, end_date)[source]

Generate list of payment dates within the given date range.

Return type:

List[date]

Parameters:
__init__(source, amount, frequency, start_date)
Parameters:
Return type:

None

class debt_optimizer.core.financial_calc.RecurringExpense(description, amount, frequency, due_date, start_date)[source]

Bases: object

Represents a recurring expense like subscriptions, fees, etc.

Parameters:
description: str
amount: float
frequency: str
due_date: int
start_date: date
__post_init__()[source]

Validate recurring expense parameters after initialization.

get_payment_dates(start_date, end_date)[source]

Generate list of payment dates within the given date range.

Return type:

List[date]

Parameters:
get_monthly_amount()[source]

Convert expense to monthly equivalent amount.

Return type:

float

__init__(description, amount, frequency, due_date, start_date)
Parameters:
Return type:

None

class debt_optimizer.core.financial_calc.FutureIncome(description, amount, start_date, frequency=None, end_date=None, date=None)[source]

Bases: object

Represents future income events - both one-time and recurring.

Can handle both one-time income events (bonuses, tax refunds) and recurring income patterns (raises, new income streams).

Parameters:

  • description (str)

  • amount (float)

  • start_date (date)

  • frequency (str | None)

  • end_date (date | None)

  • date (date | None)

description: str
amount: float
start_date: date
frequency: Optional[str] = None
end_date: Optional[date] = None
date: Optional[date] = None
__post_init__()[source]

Validate future income parameters after initialization.

is_recurring()[source]

Check if this is a recurring income event.

Return type:

bool

get_occurrences(range_start, range_end)[source]

Get all income occurrences within the specified date range.

Parameters:

  • range_start (date) – Start date of the range

  • range_end (date) – End date of the range

Return type:

List[Tuple[date, float]]

Returns:

List of tuples containing (date, amount) for each occurrence

get_total_amount_in_range(range_start, range_end)[source]

Calculate total income amount within the specified date range.

Parameters:

  • range_start (date) – Start date of the range

  • range_end (date) – End date of the range

Return type:

float

Returns:

Total amount of income in the date range

get_monthly_average()[source]

Calculate the average monthly income from this source.

Return type:

float

Returns:

Average monthly income amount

__str__()[source]

Return a human-readable representation of the income.

Return type:

str

__init__(description, amount, start_date, frequency=None, end_date=None, date=None)
Parameters:

  • description (str)

  • amount (float)

  • start_date (date)

  • frequency (str | None)

  • end_date (date | None)

  • date (date | None)

Return type:

None

class debt_optimizer.core.financial_calc.FutureExpense(description, amount, start_date, frequency=None, end_date=None, date=None)[source]

Bases: object

Represents future expense events - both one-time and recurring.

Can handle both one-time expense events (major purchases, repairs) and recurring expense patterns (new subscriptions, insurance increases).

Parameters:

  • description (str)

  • amount (float)

  • start_date (date)

  • frequency (str | None)

  • end_date (date | None)

  • date (date | None)

description: str
amount: float
start_date: date
frequency: Optional[str] = None
end_date: Optional[date] = None
date: Optional[date] = None
__post_init__()[source]

Validate future expense parameters after initialization.

is_recurring()[source]

Check if this is a recurring expense event.

Return type:

bool

get_occurrences(range_start, range_end)[source]

Get all expense occurrences within the specified date range.

Parameters:

  • range_start (date) – Start date of the range

  • range_end (date) – End date of the range

Return type:

List[Tuple[date, float]]

Returns:

List of tuples containing (date, amount) for each occurrence

get_total_amount_in_range(range_start, range_end)[source]

Calculate total expense amount within the specified date range.

Parameters:

  • range_start (date) – Start date of the range

  • range_end (date) – End date of the range

Return type:

float

Returns:

Total amount of expenses in the date range

get_monthly_average()[source]

Calculate the average monthly expense from this source.

Return type:

float

Returns:

Average monthly expense amount

__str__()[source]

Return a human-readable representation of the expense.

Return type:

str

__init__(description, amount, start_date, frequency=None, end_date=None, date=None)
Parameters:

  • description (str)

  • amount (float)

  • start_date (date)

  • frequency (str | None)

  • end_date (date | None)

  • date (date | None)

Return type:

None

debt_optimizer.core.financial_calc.calculate_monthly_payment(principal, annual_rate, months)[source]

Calculate monthly payment for a loan with fixed terms.

Return type:

float

Parameters:
debt_optimizer.core.financial_calc.calculate_total_monthly_income(income_sources)[source]

Calculate total monthly income from all sources.

Return type:

float

Parameters:

income_sources (List[Income])

debt_optimizer.core.financial_calc.generate_amortization_schedule(debt, payment_amount, start_date)[source]

Generate detailed amortization schedule for a debt.

Return type:

DataFrame

Parameters:
class debt_optimizer.core.financial_calc.DebtAnalyzer[source]

Bases: object

Utility class for analyzing debt scenarios.

static calculate_total_debt(debts)[source]

Calculate total debt balance.

Return type:

float

Parameters:

debts (List[Debt])

static calculate_total_minimum_payments(debts)[source]

Calculate total minimum payments across all debts.

Return type:

float

Parameters:

debts (List[Debt])

static calculate_weighted_average_rate(debts)[source]

Calculate weighted average interest rate across all debts.

Return type:

float

Parameters:

debts (List[Debt])

static rank_debts_by_avalanche(debts)[source]

Rank debts by interest rate (highest first) for avalanche method.

Return type:

List[Debt]

Parameters:

debts (List[Debt])

static rank_debts_by_snowball(debts)[source]

Rank debts by balance (lowest first) for snowball method.

Return type:

List[Debt]

Parameters:

debts (List[Debt])

static calculate_payoff_order_impact(debts, extra_payment, strategy='avalanche')[source]

Calculate impact of different payoff strategies.

Return type:

Dict[str, Any]

Parameters: