refi-calculator 0.8.0__py3-none-any.whl

refi_calculator/core/charts.py

@@ -0,0 +1,77 @@
+"""Shared chart helper utilities for refinance visualizations."""
+
+from __future__ import annotations
+
+MIN_LINEAR_TICKS = 2
+
+
+def build_month_ticks(max_month: int, max_ticks: int = 6) -> list[int]:
+    """Generate tick positions for month-based axes.
+
+    Args:
+        max_month: Latest month number to display on the axis.
+        max_ticks: Maximum number of tick marks to emit.
+
+    Returns:
+        A list of month values to use for axis ticks.
+    """
+    if max_month <= 0:
+        return [0]
+
+    tick_count = min(max_ticks, max_month + 1)
+    if tick_count <= 1:
+        return [max_month]
+
+    interval = max_month / (tick_count - 1)
+    ticks: list[int] = []
+    last = -1
+    for i in range(tick_count):
+        tick = int(round(i * interval))
+        if tick <= last:
+            tick = last + 1
+        tick = min(max_month, tick)
+        ticks.append(tick)
+        last = tick
+
+    if ticks[-1] != max_month:
+        ticks[-1] = max_month
+
+    return ticks
+
+
+def build_linear_ticks(min_value: float, max_value: float, max_ticks: int = 5) -> list[float]:
+    """Generate evenly spaced linear axis tick values.
+
+    Args:
+        min_value: Minimum value to include on the axis.
+        max_value: Maximum value to include on the axis.
+        max_ticks: Maximum number of ticks to produce.
+
+    Returns:
+        A list of axis values covering the requested range.
+    """
+    if max_ticks < MIN_LINEAR_TICKS:
+        return [min_value, max_value]
+
+    span = max_value - min_value
+    if span == 0:
+        expansion = abs(max_value) or 1.0
+        min_value -= expansion / 2
+        max_value += expansion / 2
+        span = max_value - min_value
+
+    step = span / (max_ticks - 1)
+    ticks = [min_value + step * i for i in range(max_ticks)]
+    ticks[-1] = max_value
+    return ticks
+
+
+__all__ = [
+    "MIN_LINEAR_TICKS",
+    "build_month_ticks",
+    "build_linear_ticks",
+]
+
+__description__ = """
+Shared chart utilities for all refinance-calculator interfaces.
+"""

refi_calculator/core/market/__init__.py

@@ -0,0 +1,11 @@
+"""Market data helpers for the refinance calculator core."""
+
+from __future__ import annotations
+
+from .fred import fetch_fred_series
+
+__all__ = ["fetch_fred_series"]
+
+__description__ = """
+Shared helpers for retrieving market data in core interfaces.
+"""

refi_calculator/core/market/constants.py

@@ -0,0 +1,24 @@
+"""Constants for market data processing in the ReFi calculator."""
+
+from __future__ import annotations
+
+MARKET_SERIES: list[tuple[str, str]] = [
+    ("30-Year", "MORTGAGE30US"),
+    ("15-Year", "MORTGAGE15US"),
+]
+
+MARKET_PERIOD_OPTIONS: list[tuple[str, str]] = [
+    ("1 Year", "12"),
+    ("2 Years", "24"),
+    ("5 Years", "60"),
+    ("All", "0"),
+]
+
+MARKET_DEFAULT_PERIOD = "12"
+
+
+__all__ = ["MARKET_SERIES", "MARKET_PERIOD_OPTIONS", "MARKET_DEFAULT_PERIOD"]
+
+__description__ = """
+Constants for market data processing in the ReFi calculator.
+"""

refi_calculator/core/market/fred.py

@@ -0,0 +1,62 @@
+"""FRED API helpers for borrowing-rate data."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+def fetch_fred_series(
+    series_id: str,
+    api_key: str,
+    limit: int | None = None,
+) -> list[tuple[str, float]]:
+    """Fetch a stationary FRED series and return (date, value) pairs.
+
+    Args:
+        series_id: FRED series identifier (e.g., "MORTGAGE30US").
+        api_key: Your FRED API key.
+        limit: Maximum number of observations to fetch. Defaults to the service limit.
+
+    Returns:
+        Observations sorted newest-first, (date, float value).
+    """
+    params: dict[str, str] = {
+        "series_id": series_id,
+        "api_key": api_key,
+        "file_type": "json",
+        "sort_order": "desc",
+    }
+    if limit:
+        params["limit"] = str(limit)
+
+    url = f"https://api.stlouisfed.org/fred/series/observations?{urllib.parse.urlencode(params)}"
+
+    try:
+        with urllib.request.urlopen(url, timeout=10) as resp:
+            payload = json.load(resp)
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError) as exc:
+        raise RuntimeError("Failed to fetch FRED series") from exc
+
+    observations = payload.get("observations", [])
+    results: list[tuple[str, float]] = []
+    for obs in observations:
+        date = obs.get("date")
+        value = obs.get("value")
+        if date is None or value is None or value == ".":
+            continue
+        try:
+            parsed = float(value)
+        except ValueError:
+            continue
+        results.append((date, parsed))
+    return results
+
+
+__all__ = ["fetch_fred_series"]
+
+__description__ = """
+Helpers for retrieving FRED economic series.
+"""

refi_calculator/core/models.py

@@ -0,0 +1,131 @@
+"""Loan and analysis data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class LoanParams:
+    """Parameters for a mortgage loan.
+
+    Attributes:
+        balance: Loan balance.
+        rate: Annual interest rate as a decimal.
+        term_years: Loan term in years.
+    """
+
+    balance: float
+    rate: float
+    term_years: float
+
+    @property
+    def monthly_rate(self) -> float:
+        """Monthly interest rate.
+
+        Returns:
+            Monthly interest rate as a decimal.
+        """
+        return self.rate / 12
+
+    @property
+    def num_payments(self) -> int:
+        """Total number of monthly payments.
+
+        Returns:
+            Total number of payments.
+        """
+        return int(self.term_years * 12)
+
+    @property
+    def monthly_payment(self) -> float:
+        """Monthly payment using the standard amortization formula.
+
+        Returns:
+            Monthly payment amount.
+        """
+        r = self.monthly_rate
+        n = self.num_payments
+        if r == 0:
+            return self.balance / n
+        return self.balance * (r * (1 + r) ** n) / ((1 + r) ** n - 1)
+
+    @property
+    def total_interest(self) -> float:
+        """Total interest paid over the life of the loan."""
+        return (self.monthly_payment * self.num_payments) - self.balance
+
+
+@dataclass
+class RefinanceAnalysis:
+    """Results of refinance breakeven analysis.
+
+    Attributes:
+        current_payment: Current monthly payment.
+        new_payment: New monthly payment.
+        monthly_savings: Monthly savings from refinancing.
+        simple_breakeven_months: Months to simple breakeven (nominal).
+        npv_breakeven_months: Months to NPV breakeven.
+        current_total_interest: Total interest of the current loan.
+        new_total_interest: Total interest of the new loan.
+        interest_delta: Interest difference between new and current loans.
+        five_year_npv: NPV of savings over five years.
+        cumulative_savings: Cumulative savings timeline.
+        current_after_tax_payment: Current payment after tax benefit.
+        new_after_tax_payment: New payment after tax benefit.
+        after_tax_monthly_savings: After-tax monthly savings.
+        after_tax_simple_breakeven_months: After-tax simple breakeven.
+        after_tax_npv_breakeven_months: After-tax NPV breakeven.
+        after_tax_npv: After-tax NPV of savings.
+        current_after_tax_total_interest: Current loan interest after tax.
+        new_after_tax_total_interest: New loan interest after tax.
+        after_tax_interest_delta: Interest delta after tax.
+        new_loan_balance: Balance of the new loan.
+        cash_out_amount: Cash out amount included in the refinance.
+        accelerated_months: Months to payoff when maintaining payment.
+        accelerated_total_interest: Total interest when accelerating payoff.
+        accelerated_interest_savings: Interest savings from acceleration.
+        accelerated_time_savings_months: Months saved by accelerating payoff.
+        current_total_cost_npv: NPV of the current loan total cost.
+        new_total_cost_npv: NPV of the new loan total cost.
+        total_cost_npv_advantage: NPV advantage of refinancing.
+    """
+
+    current_payment: float
+    new_payment: float
+    monthly_savings: float
+    simple_breakeven_months: float | None
+    npv_breakeven_months: int | None
+    current_total_interest: float
+    new_total_interest: float
+    interest_delta: float
+    five_year_npv: float
+    cumulative_savings: list[tuple[int, float, float]]
+    current_after_tax_payment: float
+    new_after_tax_payment: float
+    after_tax_monthly_savings: float
+    after_tax_simple_breakeven_months: float | None
+    after_tax_npv_breakeven_months: int | None
+    after_tax_npv: float
+    current_after_tax_total_interest: float
+    new_after_tax_total_interest: float
+    after_tax_interest_delta: float
+    new_loan_balance: float
+    cash_out_amount: float
+    accelerated_months: int | None
+    accelerated_total_interest: float | None
+    accelerated_interest_savings: float | None
+    accelerated_time_savings_months: int | None
+    current_total_cost_npv: float
+    new_total_cost_npv: float
+    total_cost_npv_advantage: float
+
+
+__all__ = [
+    "LoanParams",
+    "RefinanceAnalysis",
+]
+
+__description__ = """
+Data models for refinance calculation results.
+"""

refi_calculator/environment.py

@@ -0,0 +1,124 @@
+"""Utilities for loading environment variables from .env files."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from logging import getLogger
+from pathlib import Path
+
+logger = getLogger(__name__)
+
+
+def _strip_quotes(value: str) -> str:
+    """Remove matching wrapping quotes from a string.
+
+    Args:
+        value: The string to strip quotes from.
+
+    Returns:
+        The unquoted string.
+    """
+    if (value.startswith('"') and value.endswith('"')) or (
+        value.startswith("'") and value.endswith("'")
+    ):
+        return value[1:-1]
+
+    return value
+
+
+def _parse_dotenv_line(line: str) -> tuple[str, str] | None:
+    """Parse a single line from a .env file into a key/value pair.
+
+    Args:
+        line: The line to parse.
+
+    Returns:
+        A tuple of (key, value) if the line is valid, otherwise None.
+    """
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+
+    if stripped.startswith("export "):
+        stripped = stripped[len("export ") :].strip()
+
+    if "=" not in stripped:
+        logger.warning("Skipping malformed .env line: %s", line)
+        return None
+
+    key, value = stripped.split("=", 1)
+    key = key.strip()
+    value = _strip_quotes(value.strip())
+
+    if not key:
+        logger.warning("Skipping .env entry with missing key: %s", line)
+        return None
+
+    return key, value
+
+
+def _iter_lines(content: str) -> Iterable[str]:
+    """Yield lines from .env file content.
+
+    Args:
+        content: The content of the .env file.
+
+    Yields:
+        Lines from the content.
+    """
+    return (line for line in content.splitlines())
+
+
+def load_dotenv(
+    dotenv_path: Path | str | None = None,
+    *,
+    override_existing: bool = False,
+) -> dict[str, str]:
+    """Load environment variables from a .env file into the process environment.
+
+    Args:
+        dotenv_path: Path to the .env file. Defaults to ``Path.cwd() / ".env"``.
+        override_existing: Whether to overwrite existing environment variables.
+
+    Returns:
+        A mapping of keys that were set from the .env file to their values.
+
+    Raises:
+        OSError: If the .env file could not be read.
+    """
+    path = Path(dotenv_path) if dotenv_path is not None else Path.cwd() / ".env"
+    if not path.exists():
+        logger.debug("No .env file found at %s", path)
+        return {}
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        logger.exception("Failed to read .env file at %s", path)
+        raise
+
+    loaded: dict[str, str] = {}
+    for line in _iter_lines(content):
+        pair = _parse_dotenv_line(line)
+        if pair is None:
+            continue
+
+        key, value = pair
+        if override_existing or key not in os.environ:
+            os.environ[key] = value
+            loaded[key] = value
+        else:
+            logger.debug("Skipping existing environment variable %s", key)
+
+    logger.debug("Loaded %d environment variables from %s", len(loaded), path)
+    return loaded
+
+
+__all__ = [
+    "load_dotenv",
+]
+
+__description__ = """
+Utilities for loading environment variables from .env files.
+"""

refi_calculator/gui/__init__.py

@@ -0,0 +1,13 @@
+"""GUI helpers for the refinance calculator."""
+
+from __future__ import annotations
+
+from . import builders
+from .app import RefinanceCalculatorApp, main
+from .chart import SavingsChart
+
+__all__ = ["RefinanceCalculatorApp", "main", "SavingsChart", "builders"]
+
+__description__ = """
+Tkinter-based GUI exports for the refinance calculator.
+"""