Code refactoring

Author: andrewmurphy353

.pylintrc

@@ -0,0 +1,4 @@
+[MESSAGES CONTROL]
+# R0902: Too many instance attributes
+# W0107: Unnecessary pass statement
+disable = R0902,W0107,

MANIFEST.in

@@ -1,5 +1,4 @@
-include CONTRIBUTING.md
-include HISTORY.md
+include CHANGELOG.md
 include LICENSE
 include README.md
 

Makefile

@@ -2,9 +2,15 @@
 
 
 # Rebuild the virtual environment if corrupted or outdated
+# [`uv pip install -e .` installs curo in editable mode]
 rebuild-venv:
 	rm -rf .venv
 	rm uv.lock
 	uv venv
 	uv pip install .
+	uv pip install -e .
 	uv lock
+
+
+all-tests:
+	uv run pytest tests/ -v -s

curo/__init__.py

@@ -1,4 +1,24 @@
-"""Top-level package for Curo Python."""
+"""
+Curo - a feature-rich library for performing simple to advanced 
+instalment credit financial calculations.
+"""
 
-__author__ = """Andrew Murphy"""
-__email__ = 'curocalculator@gmail.com'
+__author__ = "Andrew Murphy"
+__email__ = "curocalculator@gmail.com"
+
+# Declare top-level shortcuts
+# from calculator import Calculator
+# from daycount.us_30_360 import US30360
+# from daycount.us_30u_360 import US30U360
+# from daycount.us_appendix_j import USAppendixJ
+# from series import SeriesAdvance, SeriesPayment, SeriesCharge
+
+# __all__ = [
+#     "Calculator",
+#     "US30360",
+#     "US30U360",
+#     "USAppendixJ",
+#     "SeriesAdvance",
+#     "SeriesPayment",
+#     "SeriesCharge",
+# ]

curo/calculator.py

@@ -0,0 +1,250 @@
+"""
+Docstring for calculator
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional
+import pandas as pd
+from scipy.optimize import root_scalar
+from daycount.convention import Convention
+from daycount.us_appendix_j import USAppendixJ
+from series import Series, SeriesAdvance, SeriesPayment, SeriesCharge
+from enums import DayCountOrigin
+from utils import gauss_round
+
+@dataclass
+class Calculator:
+    """_summary_
+
+    Raises:
+        ValueError: _description_
+
+    Returns:
+        _type_: _description_
+    """
+    precision: int = 2
+    profile: Optional[pd.DataFrame] = None
+    series: List[Series] = None
+
+
+    def __post_init__(self):
+        if not 0 <= self.precision <= 4:
+            raise ValueError("Precision must be between 0 and 4")
+        self.series = self.series or []
+        self._is_bespoke_profile = self.profile is not None
+        if self._is_bespoke_profile:
+            self._validate_profile()
+
+
+    def _validate_profile(self):
+        if self.profile is None:
+            return
+        if not {'post_date', 'value_date', 'amount',
+                'is_known', 'weighting', 'label'
+                }.issubset(self.profile.columns):
+            raise ValueError("Profile DataFrame missing required columns")
+        if self.profile['weighting'].le(0).any():
+            raise ValueError("Weighting must be > 0")
+        if (self.profile['value_date'] < self.profile['post_date']).any():
+            raise ValueError("value_date must be on or after post_date")
+        advances = self.profile[self.profile['amount'] < 0]
+        if len(advances) == 0:
+            raise ValueError("At least one advance required")
+        payments = self.profile[self.profile['amount'] > 0]
+        if len(payments) == 0:
+            raise ValueError("At least one payment required")
+        unknowns = self.profile[~self.profile['is_known']]
+        if len(unknowns) > 1:
+            raise ValueError("Only one unknown value or rate allowed")
+
+
+    def add(self, series: Series):
+        """_summary_
+
+        Args:
+            series (Series): _description_
+
+        Raises:
+            ValueError: _description_
+        """
+        if self._is_bespoke_profile:
+            raise ValueError("Cannot add series with a bespoke profile")
+        if series.value is not None:
+            series.value = gauss_round(series.value, self.precision)
+        self.series.append(series)
+
+
+    def _build_profile(self, start_date: Optional[pd.Timestamp] = None) -> pd.DataFrame:
+        start_date = start_date or pd.Timestamp.now(tz='UTC')
+        cash_flows = pd.DataFrame()
+        prev_end_date = None
+        for s in self.series:
+            cf = s.to_cash_flows(start_date, prev_end_date)
+            if isinstance(s, SeriesAdvance):
+                cf['amount'] = -abs(cf['amount'])  # Advances are negative
+            elif isinstance(s, SeriesPayment):
+                cf['is_interest_capitalised'] = s.is_interest_capitalised
+            elif isinstance(s, SeriesCharge):
+                cf['is_charge'] = True
+            cash_flows = pd.concat([cash_flows, cf], ignore_index=True)
+            prev_end_date = cash_flows['post_date'].iloc[-1]
+        self._validate_profile()
+        return cash_flows
+
+
+    def solve_value(
+        self,
+        day_count: Convention,
+        interest_rate: float,
+        start_date: Optional[pd.Timestamp] = None,
+        root_guess: float = 0.1
+    ) -> float:
+        """_summary_
+
+        Args:
+            day_count (Convention): _description_
+            interest_rate (float): _description_
+            start_date (Optional[pd.Timestamp], optional): _description_. Defaults to None.
+            root_guess (float, optional): _description_. Defaults to 0.1.
+
+        Raises:
+            ValueError: _description_
+
+        Returns:
+            float: _description_
+        """
+        if self.profile is None and not self._is_bespoke_profile:
+            self.profile = self._build_profile(start_date)
+        cash_flows = self._assign_factors(self.profile, day_count)
+        if isinstance(day_count, USAppendixJ):
+            interest_rate /= day_count.time_period.periods_in_year
+
+        def nfv_function(guess: float) -> float:
+            updated_cash_flows = self._update_unknowns(cash_flows, guess)
+            return self._calculate_nfv(updated_cash_flows, day_count, interest_rate)
+
+        result = root_scalar(nfv_function, bracket=[-1e6, 1e6], x0=root_guess)
+        if not result.converged:
+            raise ValueError("Failed to solve for value")
+
+        value = gauss_round(result.root, self.precision)
+        self.profile = self._update_unknowns(cash_flows, value)
+
+        if not day_count.use_xirr_method:
+            self.profile = self._amortise_interest(self.profile, interest_rate)
+
+        return value
+
+
+    def solve_rate(
+        self,
+        day_count: Convention,
+        start_date: Optional[pd.Timestamp] = None,
+        root_guess: float = 0.1
+    ) -> float:
+        """_summary_
+
+        Args:
+            day_count (Convention): _description_
+            start_date (Optional[pd.Timestamp], optional): _description_. Defaults to None.
+            root_guess (float, optional): _description_. Defaults to 0.1.
+
+        Raises:
+            ValueError: _description_
+
+        Returns:
+            float: _description_
+        """
+        if self.profile is None and not self._is_bespoke_profile:
+            self.profile = self._build_profile(start_date)
+
+        cash_flows = self._assign_factors(self.profile, day_count)
+
+        def nfv_function(rate: float) -> float:
+            return self._calculate_nfv(cash_flows, day_count, rate)
+
+        result = root_scalar(nfv_function, bracket=[-0.99, 10.0], x0=root_guess)
+        if not result.converged:
+            raise ValueError("Failed to solve for rate")
+
+        rate = result.root
+        if isinstance(day_count, USAppendixJ):
+            rate *= day_count.time_period.periods_in_year
+
+        if not day_count.use_xirr_method:
+            self.profile = self._amortise_interest(self.profile, rate)
+
+        return gauss_round(rate, self.precision)
+
+
+    def _assign_factors(self, cash_flows: pd.DataFrame, day_count: Convention) -> pd.DataFrame:
+        cash_flows = cash_flows.copy()
+        if day_count.day_count_origin == DayCountOrigin.DRAWDOWN:
+            start_date = cash_flows['post_date'].iloc[0]
+            cash_flows['factor'] = cash_flows['post_date'].apply(
+                lambda d: day_count.compute_factor(start_date, d)
+            )
+        else:
+            cash_flows['prev_date'] = cash_flows['post_date'].shift(1)
+            cash_flows.loc[0, 'prev_date'] = cash_flows.loc[0, 'post_date']
+            cash_flows['factor'] = cash_flows.apply(
+                lambda row: day_count.compute_factor(row['prev_date'], row['post_date']),
+                axis=1
+            )
+            cash_flows = cash_flows.drop(columns=['prev_date'])
+        return cash_flows
+
+
+    def _calculate_nfv(self, cash_flows: pd.DataFrame, day_count: Convention, rate: float) -> float:
+        final_date = cash_flows['post_date'].iloc[-1]
+        capital_balance = 0.0
+        accrued_interest = 0.0
+
+        for _, row in cash_flows.iterrows():
+            if row.get('is_charge', False) and not day_count.include_non_financing_flows:
+                continue
+            factor = day_count.compute_factor(row['post_date'], final_date)
+            amount = row['amount'] or 0.0
+            if isinstance(day_count, USAppendixJ):
+                fractional = factor.fractional_adjustment or 0.0
+                fv = amount * (1 + fractional * rate) * (1 + rate) ** factor.principal_factor
+            else:
+                fv = amount * (1 + rate) ** factor.total_factor
+
+            if row.get('is_payment', False) and row.get('is_interest_capitalised', False):
+                capital_balance += accrued_interest + fv
+                accrued_interest = 0.0
+            else:
+                accrued_interest += fv * rate * factor.total_factor
+                capital_balance += fv
+
+        return capital_balance
+
+
+    def _update_unknowns(self, cash_flows: pd.DataFrame, value: float) -> pd.DataFrame:
+        cash_flows = cash_flows.copy()
+        mask = ~cash_flows['is_known']
+        cash_flows.loc[mask, 'amount'] = value * cash_flows.loc[mask, 'weighting']
+        cash_flows.loc[mask, 'is_known'] = True
+        return cash_flows
+
+
+    def _amortise_interest(self, cash_flows: pd.DataFrame, rate: float) -> pd.DataFrame:
+        cash_flows = cash_flows.copy()
+        capital_balance = 0.0
+        cash_flows['interest'] = 0.0
+
+        for i, row in cash_flows.iterrows():
+            if row.get('is_charge', False):
+                continue
+            factor = cash_flows['factor'].iloc[i]
+            period_interest = capital_balance * rate * factor.total_factor
+            if row.get('is_payment', False):
+                if row.get('is_interest_capitalised', False):
+                    capital_balance += period_interest + row['amount']
+                else:
+                    capital_balance += row['amount']
+                cash_flows.loc[i, 'interest'] = period_interest
+            else:
+                capital_balance += period_interest + row['amount']
+        return cash_flows