From 53c0047886cc0edd475b6cdf95a419d49c35179a Mon Sep 17 00:00:00 2001
From: Max <183308611+max938-coder@users.noreply.github.com>
Date: Sat, 4 Apr 2026 22:59:40 -0700
Subject: [PATCH 1/2] feat: add macaulay duration algorithm

---
 financial/macaulay_duration.py | 73 ++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 financial/macaulay_duration.py

diff --git a/financial/macaulay_duration.py b/financial/macaulay_duration.py
new file mode 100644
index 000000000000..32cd54f4712f
--- /dev/null
+++ b/financial/macaulay_duration.py
@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+def macaulay_duration(
+    face_value: float,
+    coupon_rate: float,
+    periods: int,
+    yield_rate: float
+) -> float:
+    """
+    Calculates the Macaulay Duration of a bond.
+
+    Reference:
+    https://www.investopedia.com/terms/m/macaulayduration.asp
+
+    Args:
+        face_value: The final payout amount of the bond.
+        coupon_rate: The annual interest rate paid by the bond.
+        periods: The number of years until the bond matures.
+        yield_rate: The current market interest rate used to discount future cash flows.
+
+    Returns:
+        The Macaulay Duration of the bond in years.
+
+    >>> round(macaulay_duration(1000.0, 0.05, 8, 0.04), 2)
+    6.83
+    >>> round(macaulay_duration(987435.34, 0.07, 5, 0.038), 2)
+    4.43
+    >>> round(macaulay_duration(3564.2, 0.023, 6, 0.071), 2)
+    5.62
+    >>> macaulay_duration(-1000.0, 0.05, 8, 0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: face_value must be > 0
+    >>> macaulay_duration(1000.0, -0.05, 8, 0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: coupon_rate must be >= 0
+    >>> macaulay_duration(1000.0, 0.05, 0, 0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: periods must be > 0
+    >>> macaulay_duration(1000.0, 0.05, 8, -0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: yield_rate must be > 0
+    """
+    if face_value <= 0:
+        raise ValueError("face_value must be > 0")
+    if coupon_rate < 0:
+        raise ValueError("coupon_rate must be >= 0")
+    if periods < 1:
+        raise ValueError("periods must be > 0")
+    if yield_rate <= 0:
+        raise ValueError("yield_rate must be > 0")
+
+    total_present_value: float = 0.0
+    total_time_weighted_value: float = 0.0
+
+    for period in range(1, periods + 1):
+        cash_flow: float = (face_value * coupon_rate) + (face_value if period == periods else 0)
+
+        time_weighted_value: float = (period * cash_flow) / pow(1 + yield_rate, period)
+        total_time_weighted_value += time_weighted_value
+
+        present_value: float = cash_flow / pow(1 + yield_rate, period)
+        total_present_value += present_value
+
+    return total_time_weighted_value / total_present_value
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

From f6d71033bb92cad67f377e5c7bc2f42781e6863c Mon Sep 17 00:00:00 2001
From: Max <183308611+max938-coder@users.noreply.github.com>
Date: Sat, 4 Apr 2026 23:21:10 -0700
Subject: [PATCH 2/2] formatting fixes in financial/macaulay_duration

---
 financial/macaulay_duration.py | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/financial/macaulay_duration.py b/financial/macaulay_duration.py
index 32cd54f4712f..ce559f57aad9 100644
--- a/financial/macaulay_duration.py
+++ b/financial/macaulay_duration.py
@@ -1,25 +1,26 @@
+"""
+Calculate the Macaulay Duration of a bond.
+Reference: https://www.investopedia.com/terms/m/macaulayduration.asp
+"""
+
 from __future__ import annotations
 
+
 def macaulay_duration(
     face_value: float,
     coupon_rate: float,
     periods: int,
-    yield_rate: float
+    yield_rate: float,
 ) -> float:
     """
     Calculates the Macaulay Duration of a bond.
 
-    Reference:
-    https://www.investopedia.com/terms/m/macaulayduration.asp
-
-    Args:
-        face_value: The final payout amount of the bond.
-        coupon_rate: The annual interest rate paid by the bond.
-        periods: The number of years until the bond matures.
-        yield_rate: The current market interest rate used to discount future cash flows.
-
-    Returns:
-        The Macaulay Duration of the bond in years.
+    :param face_value: The final payout amount of the bond.
+    :param coupon_rate: The annual interest rate paid by the bond.
+    :param periods: The number of years until the bond matures.
+    :param yield_rate: The current market interest rate used to discount
+                       future cash flows.
+    :return: The Macaulay Duration of the bond in years.
 
     >>> round(macaulay_duration(1000.0, 0.05, 8, 0.04), 2)
     6.83
@@ -57,7 +58,9 @@ def macaulay_duration(
     total_time_weighted_value: float = 0.0
 
     for period in range(1, periods + 1):
-        cash_flow: float = (face_value * coupon_rate) + (face_value if period == periods else 0)
+        cash_flow: float = face_value * coupon_rate + (
+            face_value if period == periods else 0
+        )
 
         time_weighted_value: float = (period * cash_flow) / pow(1 + yield_rate, period)
         total_time_weighted_value += time_weighted_value
@@ -67,6 +70,7 @@ def macaulay_duration(
 
     return total_time_weighted_value / total_present_value
 
+
 if __name__ == "__main__":
     import doctest