I just checked my bond portfolio and realized it’s been a while since I looked at the risks hiding in plain sight.

A lot of beginners think bonds are simple, but most miss that interest rate swings can hit hard when you least expect it.

Bond duration can help.

Professionals use Python to measure Macaulay Duration and see exactly how risky their bond holdings are before anything blindsides them.

By reading today’s newsletter, you’ll get Python code to calculate bond duration and interest rate risk for any bond in your portfolio.

Let's go!

What every successful bond investor needs to know

Macaulay Duration is a measure of a bond’s interest rate sensitivity, defining the weighted average time to receive all payments. It tells you how much your bond investment responds to rate movements and the timing of your cash flows.

Understanding how this metric developed puts its importance into perspective.

Macaulay Duration was introduced by Frederick Macaulay in 1938 as a tool for quantifying interest rate risk in bonds. Over time, it became standard in fixed income analytics for traders, asset managers, and institutions. Duration’s impact grew as bond markets matured and investors needed a clear handle on risk.

Modern fixed income professionals rely on Macaulay Duration to build portfolios tailored to specific timelines and risk profiles.

Portfolio managers use duration matching to immunize liabilities and avoid unexpected losses from rate hikes. Analysts look at duration stats when screening bond ETFs and constructing ladders for predictable cash flows.

Let's see how it works with Python.

Imports and setup

We use QuantLib to model fixed income securities and calculate analytics, datetime to handle dates, and pandas to organize the results. I use a 30 year Apple corporate bond for the example. You can find this bond here: https://www.bondsupermart.com/bsm/bond-factsheet/US037833AT77

1import QuantLib as ql
2import datetime
3import pandas as pd

Specify bond terms and dates

This block prepares the calendar and evaluation date for bond pricing operations using QuantLib.

1today_date = datetime.date.today()
2calendar = ql.UnitedStates(ql.UnitedStates.GovernmentBond)
3ql.Settings.instance().evaluationDate = ql.Date(today_date.day, today_date.month, today_date.year)

This code tells QuantLib which calendar and market conventions to use for all date calculations. By setting the evaluation date to today, we tell the framework to reflect current market conditions when pricing and analyzing the bond.

1coupon_rate = 0.0445
2maturity_years = 30
3latest_price = 92.097
4issue_date = ql.Date(6, 5, 2014)
5maturity_date = calendar.advance(issue_date, ql.Period(maturity_years, ql.Years))
6
7frequency = ql.Semiannual
8day_count = ql.ActualActual(ql.ActualActual.ISDA)
9face_value = 100

We set the annual coupon, how often interest payments occur, and when the bond matures. We use QuantLib’s scheduling features to automatically determine when all future payments fall based on market conventions in the US for Treasury bonds.

Next, we build the bond’s payment schedule and constructs a QuantLib bond object that will be used for pricing and risk calculations.

1schedule = ql.Schedule(
2    issue_date,
3    maturity_date,
4    ql.Period(frequency),
5    calendar,
6    ql.Following,
7    ql.Following,
8    ql.DateGeneration.Backward,
9    False
10)
11
12fixed_rate_bond = ql.FixedRateBond(
13    0,
14    face_value,
15    schedule,
16    [coupon_rate],
17    day_count
18)

The payment schedule arranges all future cashflows based on the coupon and maturity. We create a plain vanilla fixed-rate bond using QuantLib, providing all the contract terms and conventions so that pricing and yield calculations stay accurate.

Calculate yield and duration

This block calculates the bond’s yield to maturity and its risk to changes in interest rates by finding the Macaulay duration.

1ytm_guess = coupon_rate
2compounding = ql.Compounded
3ytm = (coupon_rate + 0.01)
4bond_price = latest_price
5bond_yield = fixed_rate_bond.bondYield(
6    bond_price,
7    day_count,
8    compounding,
9    frequency
10)
11
12macaulay_duration = ql.BondFunctions.duration(
13    fixed_rate_bond,
14    bond_yield,
15    day_count,
16    compounding,
17    frequency,
18    ql.Duration.Macaulay
19)

Here, we use QuantLib to solve for the bond’s yield, which expresses the annualized return if held to maturity at today’s market price. We also get a practical summary statistic called duration, which tells us how sensitive the bond price is to moves in yields. Both are key numbers for anyone analyzing fixed income.

This block displays the price, calculated yield to maturity, and Macaulay duration in a neat table using pandas.

1pd.DataFrame({
2    "Bond Price": [bond_price],
3    "Yield to Maturity": [bond_yield],
4    "Macaulay Duration (Years)": [macaulay_duration]
5})

We organize our results in a pandas DataFrame, giving us a clean, useful summary of all the main analytics. This format makes it easy to review, export, or compare results for this bond or others.

As of writing, the price is 92.097, the yield is 5.11%, and Macaulay Duration is 12.48. The price and yield line up perfectly to the public information.

Your next steps

You’ve now got a repeatable way to calculate bond yield and duration using QuantLib. Next, swap in different coupon rates or maturity dates up top and see how your results shift.

Try tweaking latest_price and watch the yield and duration numbers adjust—this is how you really learn bond math in practice.