eqlx-bankmath 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,11 @@
1
+ """Deterministic arithmetic for bank products in Türkiye, exact to the kuruş.
2
+
3
+ The library computes; it does not quote prices or give advice. Rates, levies and conventions are
4
+ inputs, and every result says which conventions produced it.
5
+ """
6
+
7
+ from .errors import InputError
8
+
9
+ __version__ = "0.1.0"
10
+
11
+ __all__ = ["InputError", "__version__"]
eqlx_bankmath/adat.py ADDED
@@ -0,0 +1,132 @@
1
+ """Interest on a balance that changes from day to day (the "adat" or interest-number method).
2
+
3
+ Overdrafts, revolving lines and current accounts do not have instalments: the balance moves with
4
+ every transaction. Interest is computed from interest numbers,
5
+
6
+ interest number (adat) = balance x days the balance stood
7
+ interest = sum of interest numbers x annual rate / year basis (rate as a fraction)
8
+
9
+ which is the same as charging simple interest on each day's closing balance. No law fixes the
10
+ divisor, the value-date rule or the rounding; they come from the contract and from bank practice,
11
+ so each is an explicit argument here and is echoed in the result.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import datetime as dt
17
+ from collections.abc import Sequence
18
+ from dataclasses import dataclass
19
+ from decimal import Decimal
20
+ from typing import Any
21
+
22
+ from .daycount import parse_date
23
+ from .errors import InputError
24
+ from .money import ZERO, Number, as_float, dec, money, rate, whole
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class Stretch:
29
+ """A balance and the number of days it stood."""
30
+
31
+ balance: Decimal
32
+ days: int
33
+ start: dt.date | None = None
34
+
35
+ @property
36
+ def number(self) -> Decimal:
37
+ return self.balance * self.days
38
+
39
+
40
+ def stretches_from_movements(
41
+ opening_balance: Number,
42
+ movements: Sequence[tuple[dt.date | str, Number]],
43
+ period_start: dt.date | str,
44
+ period_end: dt.date | str,
45
+ *,
46
+ count_end_day: bool = False,
47
+ ) -> list[Stretch]:
48
+ """Turn dated movements into balance stretches over a period.
49
+
50
+ ``movements`` are (value date, amount): positive amounts increase the debt, negative reduce it.
51
+ A movement counts from its value date. The period runs from ``period_start`` up to
52
+ ``period_end``; with ``count_end_day`` the end day itself also bears interest (some contracts
53
+ count both the first and the last day).
54
+ """
55
+ start, end = parse_date(period_start, "period_start"), parse_date(period_end, "period_end")
56
+ if end < start:
57
+ raise InputError("the period ends before it starts")
58
+ last_day = end + dt.timedelta(days=1) if count_end_day else end
59
+ items = sorted((parse_date(d, "value date"), dec(a, "amount")) for d, a in movements)
60
+ if any(d < start or d > end for d, _ in items):
61
+ raise InputError("a movement lies outside the period")
62
+ balance = dec(opening_balance, "opening_balance")
63
+ out: list[Stretch] = []
64
+ cursor = start
65
+ for day, amount in items:
66
+ if day > cursor:
67
+ out.append(Stretch(balance, (day - cursor).days, cursor))
68
+ cursor = day
69
+ balance += amount
70
+ if last_day > cursor:
71
+ out.append(Stretch(balance, (last_day - cursor).days, cursor))
72
+ return out
73
+
74
+
75
+ def interest(
76
+ stretches: Sequence[Stretch | tuple[Number, int]],
77
+ annual_rate: Number,
78
+ *,
79
+ year_basis: int = 360,
80
+ kkdf: Number = 0,
81
+ bsmv: Number = 0,
82
+ debit_only: bool = True,
83
+ ) -> dict[str, Any]:
84
+ """Interest on a varying balance for one accrual period, with its levies.
85
+
86
+ ``annual_rate`` is a fraction per year (0.60 for 60 %); for a monthly rate pass ``rate x 12``
87
+ with ``year_basis=360``, which is the usual reading of "monthly rate x days / 30".
88
+ With ``debit_only`` (the default) days with a zero or credit balance bear no interest.
89
+ Interest is rounded once, on the total for the period.
90
+ """
91
+ r = rate(annual_rate, "annual_rate")
92
+ basis = whole(year_basis, "year_basis", minimum=1)
93
+ if basis not in (360, 365, 366):
94
+ raise InputError("year_basis must be 360, 365 or 366")
95
+ k, b = rate(kkdf, "kkdf", maximum=1), rate(bsmv, "bsmv", maximum=1)
96
+ rows = []
97
+ total_number = ZERO
98
+ total_days = 0
99
+ for s in stretches:
100
+ st = s if isinstance(s, Stretch) else Stretch(dec(s[0], "balance"), whole(s[1], "days"))
101
+ if st.days < 0:
102
+ raise InputError("days must not be negative")
103
+ counted = st.balance if (st.balance > 0 or not debit_only) else ZERO
104
+ number = counted * st.days
105
+ total_number += number
106
+ total_days += st.days
107
+ rows.append(
108
+ {
109
+ "from": st.start.isoformat() if st.start else None,
110
+ "balance": as_float(st.balance),
111
+ "days": st.days,
112
+ "interest_number": as_float(number),
113
+ }
114
+ )
115
+ amount = money(total_number * r / basis)
116
+ kk, bs = money(amount * k), money(amount * b)
117
+ return {
118
+ "interest": as_float(amount),
119
+ "kkdf": as_float(kk),
120
+ "bsmv": as_float(bs),
121
+ "total": as_float(amount + kk + bs),
122
+ "interest_numbers": as_float(total_number),
123
+ "days": total_days,
124
+ "average_balance": as_float(money(total_number / total_days)) if total_days else 0.0,
125
+ "stretches": rows,
126
+ "conventions": {
127
+ "formula": f"sum(balance x days) x annual rate / {basis}",
128
+ "year_basis": basis,
129
+ "rounding": "interest rounded half-up to 0.01 once per period; each levy rounded separately",
130
+ "credit_balances": "ignored" if debit_only else "counted",
131
+ },
132
+ }