`fuggers_py.inflation`¶

fuggers_py.inflation is the public home for CPI history, reference CPI, index ratios, inflation swaps, inflation swap pricing, and simple inflation analytics.

Use one-layer imports from fuggers_py.inflation.

from decimal import Decimal

from fuggers_py import Date, YearMonth
from fuggers_py.inflation import (
    InMemoryInflationFixingSource,
    InflationFixing,
    USD_CPI_U_NSA,
    reference_cpi,
)

fixings = InMemoryInflationFixingSource(
    [
        InflationFixing("CPURNSA", YearMonth(2026, 1), Decimal("320.000")),
        InflationFixing("CPURNSA", YearMonth(2026, 2), Decimal("321.000")),
    ]
)

value = reference_cpi(
    settlement_date=Date.from_ymd(2026, 4, 1),
    convention=USD_CPI_U_NSA,
    fixing_source=fixings,
)

print(value)  # Decimal("320.000")

Core Rules¶

CPI fixings are monthly index levels. They are not daily rates.
CPI fixing months use YearMonth.
Rates use raw decimal form unless this page says otherwise. Decimal("0.025") means 2.5%.
Treasury auction coupon rates are different: TreasuryAuctionedTipsRow stores the Treasury percentage value. 1.625 means 1.625%, and tips_bond_from_treasury_auction_row() divides it by 100 when it builds a TipsBond.
Reference CPI turns monthly CPI fixings into a daily value.
An index ratio is settlement reference CPI / base-date reference CPI.
Swap PV signs follow the swap side. A pay-fixed swap has a negative fixed-leg sign and a positive inflation-leg sign. A receive-fixed swap is the opposite.
Standard coupon inflation swaps currently support USD CPI-U / CPURNSA only.
Parser functions take text or already parsed payloads. Loader functions read a local file and then call the matching parser.

Conventions¶

`InflationInterpolation`¶

InflationInterpolation names how monthly CPI fixings become daily reference CPI values.

MONTHLY uses one monthly CPI fixing for the whole settlement month.
LINEAR uses two monthly CPI fixings and moves from the first value toward the second value day by day.
FLAT is an enum value, but reference_cpi() does not support it yet. Passing it raises UnsupportedInflationInterpolation.

`InflationConvention`¶

InflationConvention describes an inflation index. It tells the library which CPI source to use, which currency the index belongs to, how many months of lag to apply, and which interpolation rule to use.

The constructor cleans common inputs:

name is stripped.
family and index_source are uppercased.
observation_lag_months is converted to int.
aliases are stripped, uppercased, deduplicated, and kept in order.
A negative observation lag raises InvalidObservationLag.

Useful method:

lookup_names() returns the source name and aliases that fixing lookup should try, in order.

InflationIndexDefinition is an alias for InflationConvention.

from fuggers_py.inflation import USD_CPI_U_NSA

print(USD_CPI_U_NSA.name)                    # "USD CPI-U NSA"
print(USD_CPI_U_NSA.index_source)            # "CPURNSA"
print(USD_CPI_U_NSA.observation_lag_months)  # 3
print(USD_CPI_U_NSA.lookup_names())
# ("CPURNSA", "CPI-U", "CPI-U NSA", "US CPI-U", "US CPI-U NSA")

from fuggers_py import Currency
from fuggers_py.inflation import InflationConvention, InflationInterpolation

custom = InflationConvention(
    name="Example CPI",
    family="example_cpi",
    currency=Currency.USD,
    index_source="example",
    observation_lag_months="2",
    interpolation_method=InflationInterpolation.MONTHLY,
    aliases=(" example-alt ", "EXAMPLE-ALT"),
)

print(custom.family)                  # "EXAMPLE_CPI"
print(custom.index_source)            # "EXAMPLE"
print(custom.observation_lag_months)  # 2
print(custom.lookup_names())          # ("EXAMPLE", "EXAMPLE-ALT")

`USD_CPI_U_NSA`¶

USD_CPI_U_NSA is the built-in convention for US CPI-U, not seasonally adjusted. It uses:

currency USD
source name CPURNSA
three-month observation lag
linear daily interpolation
aliases such as CPI-U and US CPI-U NSA

Use it when pricing or referencing US CPI-linked instruments.

Errors¶

Inflation errors inherit from InflationError.

InflationError is the base class for inflation-specific failures.
InvalidObservationLag is raised when a convention has a negative lag. It stores observation_lag_months.
MissingInflationFixing is raised when reference CPI needs a monthly CPI fixing that the source cannot return. It stores index_name, requested_date, and observation_months.
UnsupportedInflationInterpolation is raised when reference_cpi() receives an interpolation method it does not implement. It stores interpolation_method.

from dataclasses import replace

from fuggers_py import Date
from fuggers_py.inflation import (
    InMemoryInflationFixingSource,
    InflationInterpolation,
    InvalidObservationLag,
    MissingInflationFixing,
    UnsupportedInflationInterpolation,
    USD_CPI_U_NSA,
    reference_cpi,
)

empty_source = InMemoryInflationFixingSource()

try:
    reference_cpi(Date.from_ymd(2026, 4, 1), USD_CPI_U_NSA, empty_source)
except MissingInflationFixing as error:
    print(error.index_name)            # "CPURNSA"
    print(error.observation_months)    # missing lagged months

try:
    replace(USD_CPI_U_NSA, observation_lag_months=-1)
except InvalidObservationLag as error:
    print(error.observation_lag_months)  # -1

flat_convention = replace(
    USD_CPI_U_NSA,
    interpolation_method=InflationInterpolation.FLAT,
)

try:
    reference_cpi(Date.from_ymd(2026, 4, 1), flat_convention, empty_source)
except UnsupportedInflationInterpolation as error:
    print(error.interpolation_method)  # FLAT

CPI Fixings And Sources¶

`InflationFixing`¶

InflationFixing is one published monthly CPI value for one index.

Fields:

index_name: source name such as CPURNSA
observation_month: the month the CPI value belongs to
value: the CPI index level

The constructor cleans inputs:

index_name is stripped and uppercased.
observation_month is parsed into YearMonth.
value is parsed into Decimal.

from fuggers_py.inflation import InflationFixing

fixing = InflationFixing(
    index_name=" cpurnsa ",
    observation_month="2026-01",
    value="320.000",
)

print(fixing.index_name)         # "CPURNSA"
print(fixing.observation_month)  # 2026-01
print(fixing.value)              # Decimal("320.000")

`InMemoryInflationFixingSource`¶

InMemoryInflationFixingSource stores CPI fixings in memory. Use it for examples, tests, and small local datasets.

The source stores fixings by (index_name, observation_month). Later fixings with the same key replace earlier ones.

Useful methods and fields:

fixings is the stored dictionary.
add_inflation_fixing(fixing) stores a fixing and returns the source, so calls can be chained.
get_inflation_fixing(index_name, observation_month) returns the matching InflationFixing or None. It strips and uppercases index_name and parses observation_month.

from fuggers_py.inflation import InMemoryInflationFixingSource, InflationFixing

source = InMemoryInflationFixingSource()
source.add_inflation_fixing(InflationFixing("CPURNSA", "2026-01", "320.000"))
source.add_inflation_fixing(InflationFixing("CPURNSA", "2026-02", "321.000"))

jan = source.get_inflation_fixing(" cpurnsa ", "2026-01")
print(jan.value)  # Decimal("320.000")

CPI parsers and loaders¶

Use parsers when you already have text or decoded JSON. Use loaders when the data is in a local file.

parse_monthly_cpi_fixings_csv(text, index_name="CPURNSA") parses normalized CSV rows.
parse_monthly_cpi_fixings_json(payload, index_name="CPURNSA") parses normalized JSON rows. The payload can be a JSON string, bytes, a list of row dicts, or a dict with rows under data, observations, or fixings.
load_monthly_cpi_fixings_csv(path, index_name="CPURNSA") reads a CSV file and calls parse_monthly_cpi_fixings_csv().
load_monthly_cpi_fixings_json(path, index_name="CPURNSA") reads a JSON file and calls parse_monthly_cpi_fixings_json().
parse_bls_cpi_json(payload, index_name="CPURNSA") parses BLS-style CPI JSON. It skips annual M13 rows and keeps monthly M01 to M12 rows.
parse_fred_cpi_csv(text, index_name="CPURNSA") parses a FRED monthly CSV. It uses the date column and the first non-date value column.
treasury_cpi_source_from_fixings(fixings) wraps parsed fixings in an InMemoryInflationFixingSource.

Normalized CPI rows can use these month fields:

observation_month
month
date
reference_month

Normalized CPI rows can use these value fields:

value
cpi
reference_cpi
index_level
cpurnsa

from pathlib import Path

from fuggers_py.inflation import (
    load_monthly_cpi_fixings_csv,
    load_monthly_cpi_fixings_json,
    parse_fred_cpi_csv,
    parse_monthly_cpi_fixings_csv,
    parse_monthly_cpi_fixings_json,
    treasury_cpi_source_from_fixings,
)

csv_text = """
observation_month,value
2026-01,320.000
2026-02,321.000
"""

fixings = parse_monthly_cpi_fixings_csv(csv_text)
source = treasury_cpi_source_from_fixings(fixings)
print(source.get_inflation_fixing("CPURNSA", "2026-02").value)

fred_text = """
DATE,CPURNSA
2026-01-01,320.000
2026-02-01,321.000
"""

fred_fixings = parse_fred_cpi_csv(fred_text)
print(fred_fixings[0].observation_month)

path = Path("/tmp/fuggers_py_cpi_fixings.csv")
path.write_text(csv_text)
loaded = load_monthly_cpi_fixings_csv(path)
print(len(loaded))  # 2

json_payload = {
    "fixings": [
        {"observation_month": "2026-01", "value": "320.000"},
        {"observation_month": "2026-02", "value": "321.000"},
    ]
}

json_fixings = parse_monthly_cpi_fixings_json(json_payload)
print(json_fixings[1].value)  # Decimal("321.000")

json_path = Path("/tmp/fuggers_py_cpi_fixings.json")
json_path.write_text('{"fixings": [{"observation_month": "2026-01", "value": "320.000"}]}')
json_loaded = load_monthly_cpi_fixings_json(json_path)
print(len(json_loaded))  # 1

from fuggers_py.inflation import parse_bls_cpi_json

payload = {
    "Results": {
        "series": [
            {
                "data": [
                    {"year": "2026", "period": "M02", "value": "321.000"},
                    {"year": "2026", "period": "M13", "value": "ignored"},
                ]
            }
        ]
    }
}

fixings = parse_bls_cpi_json(payload)
print(fixings[0].observation_month)  # 2026-02

Reference CPI And Index Ratios¶

`reference_cpi`¶

reference_cpi(settlement_date, convention, fixing_source) returns the CPI value used on a daily settlement date.

The function first applies the convention’s observation lag. With the built-in US CPI convention, an April 2026 settlement uses January and February 2026 CPI because the lag is three months.

Behavior by interpolation method:

MONTHLY: needs one lagged monthly fixing and returns that value for the whole settlement month.
LINEAR: needs two lagged monthly fixings. On day 1 it returns the first fixing. After day 1 it moves from the first fixing toward the second fixing using (day of month - 1) / days in settlement month.
Other methods raise UnsupportedInflationInterpolation.

The fixing source can be an object with get_inflation_fixing(index_name, observation_month). It can also be a market data snapshot that exposes an inflation_fixing_source.

from fuggers_py import Date
from fuggers_py.inflation import (
    InMemoryInflationFixingSource,
    InflationFixing,
    USD_CPI_U_NSA,
    reference_cpi,
)

source = InMemoryInflationFixingSource(
    [
        InflationFixing("CPURNSA", "2026-01", "320.000"),
        InflationFixing("CPURNSA", "2026-02", "321.000"),
    ]
)

start_value = reference_cpi(Date.from_ymd(2026, 4, 1), USD_CPI_U_NSA, source)
mid_month_value = reference_cpi(Date.from_ymd(2026, 4, 16), USD_CPI_U_NSA, source)

print(start_value)      # Decimal("320.000")
print(mid_month_value)  # moves toward Decimal("321.000")

`reference_index_ratio`¶

reference_index_ratio(settlement_date, base_date, convention, fixing_source) returns:

reference_cpi(settlement_date) / reference_cpi(base_date)

Use it when you need the inflation uplift from one date to another.

from fuggers_py import Date
from fuggers_py.inflation import (
    InMemoryInflationFixingSource,
    InflationFixing,
    USD_CPI_U_NSA,
    reference_index_ratio,
)

source = InMemoryInflationFixingSource(
    [
        InflationFixing("CPURNSA", "2026-01", "320.000"),
        InflationFixing("CPURNSA", "2026-02", "321.000"),
        InflationFixing("CPURNSA", "2026-03", "322.000"),
        InflationFixing("CPURNSA", "2026-04", "323.000"),
    ]
)

ratio = reference_index_ratio(
    settlement_date=Date.from_ymd(2026, 6, 1),
    base_date=Date.from_ymd(2026, 4, 1),
    convention=USD_CPI_U_NSA,
    fixing_source=source,
)

print(ratio)

`InflationProjection`¶

InflationProjection is a small interface for objects that can forecast reference CPI directly.

The public protocol method is:

reference_cpi(date, convention) -> Decimal

InflationSwapPricer.reference_cpi() also accepts projection objects with projected_reference_cpi(date), get_reference_cpi(date, convention), or get_inflation_fixing(index_name, observation_month). This lets the pricer work with both forecast curves and fixing sources.

from decimal import Decimal

from fuggers_py.inflation import USD_CPI_U_NSA

class FlatCpiProjection:
    def reference_cpi(self, date, convention):
        return Decimal("325.000")

projection = FlatCpiProjection()
print(projection.reference_cpi(None, USD_CPI_U_NSA))

Treasury TIPS Reference Data¶

`TreasuryAuctionedTipsRow`¶

TreasuryAuctionedTipsRow stores the Treasury auction fields needed to build a TIPS bond.

Fields:

cusip
security_type
security_term
issue_date
dated_date
maturity_date
coupon_rate
original_issue_date
ref_cpi_on_issue_date
ref_cpi_on_dated_date
original_security_term

Constructor behavior:

cusip is stripped and uppercased.
security_type, security_term, and original_security_term are stripped.
coupon_rate is parsed into Decimal.
coupon_rate is a Treasury percentage value. Pass 1.625 for 1.625%, not 0.01625.

Treasury parsers and loaders¶

parse_treasury_auctioned_tips_csv(text) parses Treasury auction rows from CSV text and keeps only TIPS rows.
parse_treasury_auctioned_tips_json(payload) parses Treasury auction rows from JSON text, bytes, a list of rows, or a dict with rows under data, securities, or auctioned.
load_treasury_auctioned_tips_csv(path) reads a CSV file and calls parse_treasury_auctioned_tips_csv().
load_treasury_auctioned_tips_json(path) reads a JSON file and calls parse_treasury_auctioned_tips_json().

A row is treated as TIPS when it contains a reference CPI field or text such as TIPS, inflation protected, or inflation-protected.

`tips_bond_from_treasury_auction_row`¶

tips_bond_from_treasury_auction_row(row, fixing_source=None, identifiers=None) converts a parsed Treasury row into fuggers_py.bonds.TipsBond.

Important behavior:

dated_date is required. If it is missing, the function raises ValueError.
The function uses USD_CPI_U_NSA.
The row coupon rate is divided by 100 before it is passed to TipsBond.
If identifiers is not supplied, the function builds a preview bond and then replaces its CUSIP with the Treasury row CUSIP.

from pathlib import Path

from fuggers_py.inflation import (
    load_treasury_auctioned_tips_csv,
    load_treasury_auctioned_tips_json,
    parse_treasury_auctioned_tips_csv,
    parse_treasury_auctioned_tips_json,
    tips_bond_from_treasury_auction_row,
)

csv_text = """
CUSIP,SecurityType,SecurityTerm,IssueDate,DatedDate,MaturityDate,InterestRate,RefCPIOnDatedDate
91282CGK1,TIPS,10-Year,2026-01-15,2026-01-15,2036-01-15,1.625,320.000
"""

rows = parse_treasury_auctioned_tips_csv(csv_text)
row = rows[0]

print(row.cusip)        # "91282CGK1"
print(row.coupon_rate)  # Decimal("1.625"), meaning 1.625%

bond = tips_bond_from_treasury_auction_row(row)
print(bond.maturity_date())

csv_path = Path("/tmp/fuggers_py_tips_rows.csv")
csv_path.write_text(csv_text)
csv_loaded = load_treasury_auctioned_tips_csv(csv_path)
print(csv_loaded[0].maturity_date)

json_rows = {
    "data": [
        {
            "cusip": "91282CGK1",
            "securityType": "TIPS",
            "securityTerm": "10-Year",
            "issueDate": "2026-01-15",
            "datedDate": "2026-01-15",
            "maturityDate": "2036-01-15",
            "interestRate": "1.625",
            "refCpiOnDatedDate": "320.000",
        }
    ]
}

json_parsed = parse_treasury_auctioned_tips_json(json_rows)
print(json_parsed[0].cusip)

json_path = Path("/tmp/fuggers_py_tips_rows.json")
json_path.write_text(
    '[{"cusip": "91282CGK1", "securityType": "TIPS", "securityTerm": "10-Year", '
    '"issueDate": "2026-01-15", "datedDate": "2026-01-15", '
    '"maturityDate": "2036-01-15", "interestRate": "1.625", '
    '"refCpiOnDatedDate": "320.000"}]'
)
json_loaded = load_treasury_auctioned_tips_json(json_path)
print(json_loaded[0].coupon_rate)

Inflation Swaps¶

Shared swap rules¶

Inflation swaps use two legs:

The fixed leg pays the fixed swap rate.
The inflation leg pays the realized inflation change.

pay_receive names the fixed leg side:

PAY means pay fixed and receive inflation.
RECEIVE means receive fixed and pay inflation.

The helper methods make that sign rule visible:

fixed_leg_sign() returns the sign for fixed-leg PV.
inflation_leg_sign() returns the opposite sign for inflation-leg PV.

`ZeroCouponInflationSwap`¶

ZeroCouponInflationSwap represents one fixed payment and one inflation payment at maturity.

Constructor behavior:

notional and fixed_rate are parsed into Decimal.
pay_receive, currency, payment_calendar, business_day_convention, and instrument_id are parsed from strings when needed.
If effective_date is missing, it is set to the payment calendar settlement date two business days after trade_date.
inflation_convention is required.
maturity_date must be after effective_date.
notional must be positive.
currency must match inflation_convention.currency.

Useful methods and properties:

new(...) is the keyword-only constructor helper.
payment_date() adjusts maturity_date by the payment calendar and business day rule.
kind returns "inflation.swap.zero_coupon".
fixed_leg_sign() returns the fixed-leg sign.
inflation_leg_sign() returns the inflation-leg sign.
fixed_leg_year_fraction() returns Decimal(1).
index_initial_date() returns effective_date.
index_final_date() returns maturity_date.

from decimal import Decimal

from fuggers_py import Date
from fuggers_py.inflation import USD_CPI_U_NSA, ZeroCouponInflationSwap

swap = ZeroCouponInflationSwap.new(
    trade_date=Date.from_ymd(2026, 1, 2),
    effective_date=Date.from_ymd(2026, 1, 6),
    maturity_date=Date.from_ymd(2031, 1, 6),
    notional=Decimal("1000000"),
    fixed_rate=Decimal("0.025"),
    pay_receive="PAY",
    inflation_convention=USD_CPI_U_NSA,
)

print(swap.kind)
print(swap.payment_date())
print(swap.fixed_leg_sign())
print(swap.inflation_leg_sign())

`StandardCouponInflationSwap`¶

StandardCouponInflationSwap represents a coupon inflation swap. It has a fixed coupon period schedule and an inflation period schedule.

Constructor behavior:

notional and fixed_rate are parsed into Decimal.
pay_receive, currency, fixed_day_count_convention, and instrument_id are parsed from strings when needed.
If effective_date is missing, it is set to the schedule calendar settlement date two business days after trade_date.
If normalize_effective_date_to_reference_month_start=True, the effective date is moved to the adjusted first day of its month.
If inflation_schedule is missing, it uses the fixed schedule.
Fixed and inflation period overrides are stored as tuples.
inflation_convention is required.
maturity_date must be after effective_date.
notional must be positive.
currency must match inflation_convention.currency.
The first release supports only USD CPI-U / CPURNSA.
Fixed and inflation schedules must have the same number of periods.
Fixed and inflation period start dates, end dates, and payment dates must match.
The schedule must start on effective_date and end on maturity_date.

Useful methods and properties:

new(...) is the keyword-only constructor helper.
fixed_leg_sign() returns the fixed-leg sign.
inflation_leg_sign() returns the inflation-leg sign.
fixed_periods() returns fixed accrual periods. If fixed periods were passed to new(..., fixed_periods=...), it returns those.
inflation_periods() returns inflation accrual periods. If inflation periods were passed to new(..., inflation_periods=...), it returns those.
payment_dates() returns the fixed period payment dates.
kind returns "inflation.swap.standard_coupon".

from decimal import Decimal

from fuggers_py import Date
from fuggers_py.inflation import USD_CPI_U_NSA, StandardCouponInflationSwap

swap = StandardCouponInflationSwap.new(
    trade_date=Date.from_ymd(2026, 1, 2),
    effective_date=Date.from_ymd(2026, 1, 6),
    maturity_date=Date.from_ymd(2027, 1, 6),
    notional=Decimal("1000000"),
    fixed_rate=Decimal("0.025"),
    pay_receive="RECEIVE",
    inflation_convention=USD_CPI_U_NSA,
    normalize_effective_date_to_reference_month_start=False,
)

print(swap.kind)
print(swap.payment_dates())
print(swap.fixed_periods()[0].year_fraction)
print(swap.inflation_periods()[0].start_date)

Inflation Swap Pricing¶

Curve and projection inputs¶

InflationSwapPricer can price with explicit curves or with a curves bundle.

A discount curve must provide:

reference_date
spec.day_count
discount_factor_at(tenor)

The pricer turns a payment date into a tenor using the curve reference date and day count, then asks the curve for the discount factor.

An inflation projection can provide one of these:

projected_reference_cpi(date)
reference_cpi(date, convention)
get_reference_cpi(date, convention)
get_inflation_fixing(index_name, observation_month)

If the projection only provides monthly fixings, the pricer calls reference_cpi() to turn those fixings into daily reference CPI.

`InflationSwapPricer`¶

InflationSwapPricer prices zero-coupon and standard coupon inflation swaps.

Useful methods:

fixed_leg_pv(swap, curves=None, discount_curve=None) returns fixed-leg PV.
inflation_leg_pv(swap, curves=None, discount_curve=None, inflation_projection=None) returns inflation-leg PV.
pv(swap, curves=None, discount_curve=None, inflation_projection=None) returns fixed-leg PV plus inflation-leg PV.
par_fixed_rate(swap, curves=None, discount_curve=None, inflation_projection=None) returns the fixed rate that makes the swap PV zero.
pv01(swap, curves=None, discount_curve=None, bump=Decimal("0.0001")) returns the signed value of a one-basis-point fixed-rate bump. A basis point is 0.0001.
fixed_leg_annuity(swap, curves=None, discount_curve=None) returns the fixed leg’s discounted notional times year fraction.
reference_cpi(swap, date, curves=None, inflation_projection=None) returns the projection’s reference CPI for a date.
price(swap, curves=None, discount_curve=None, inflation_projection=None) returns a pricing result record.

from decimal import Decimal

from fuggers_py import Date
from fuggers_py.inflation import (
    InflationSwapPricer,
    USD_CPI_U_NSA,
    ZeroCouponInflationSwap,
)


class FlatDiscountCurve:
    reference_date = Date.from_ymd(2026, 1, 2)
    spec = type("Spec", (), {"day_count": "ACT/365F"})()

    def discount_factor_at(self, tenor):
        return Decimal("0.950000")


class SimpleCpiProjection:
    def reference_cpi(self, date, convention):
        if date.year() < 2031:
            return Decimal("320.000")
        return Decimal("360.000")


swap = ZeroCouponInflationSwap.new(
    trade_date=Date.from_ymd(2026, 1, 2),
    effective_date=Date.from_ymd(2026, 1, 6),
    maturity_date=Date.from_ymd(2031, 1, 6),
    notional=Decimal("1000000"),
    fixed_rate=Decimal("0.025"),
    pay_receive="PAY",
    inflation_convention=USD_CPI_U_NSA,
)

pricer = InflationSwapPricer()
discount_curve = FlatDiscountCurve()
projection = SimpleCpiProjection()

print(pricer.fixed_leg_annuity(swap, discount_curve=discount_curve))
print(pricer.fixed_leg_pv(swap, discount_curve=discount_curve))
print(pricer.inflation_leg_pv(swap, discount_curve=discount_curve, inflation_projection=projection))
print(pricer.pv(swap, discount_curve=discount_curve, inflation_projection=projection))
print(pricer.par_fixed_rate(swap, discount_curve=discount_curve, inflation_projection=projection))
print(pricer.pv01(swap, discount_curve=discount_curve))
print(pricer.reference_cpi(swap, swap.index_final_date(), inflation_projection=projection))

result = pricer.price(swap, discount_curve=discount_curve, inflation_projection=projection)
print(result.present_value)
print(result.par_fixed_rate)

`ZeroCouponInflationSwapPricingResult`¶

ZeroCouponInflationSwapPricingResult is returned by price() for a zero-coupon inflation swap.

Fields:

par_fixed_rate: raw decimal fixed rate that makes PV zero
present_value: fixed-leg PV plus inflation-leg PV
fixed_leg_pv
inflation_leg_pv
pv01: signed value of a one-basis-point fixed-rate bump
index_initial: starting reference CPI
index_final: final reference CPI
payment_date
discount_factor
fixed_leg_annuity

result = pricer.price(swap, discount_curve=discount_curve, inflation_projection=projection)

print(result.index_initial)
print(result.index_final)
print(result.discount_factor)
print(result.present_value)

`StandardCouponInflationSwapPeriodPricing`¶

StandardCouponInflationSwapPeriodPricing stores one priced coupon period.

Fields:

start_date
end_date
payment_date
year_fraction
index_initial
index_final
inflation_rate: (index_final / index_initial) - 1
fixed_cashflow
inflation_cashflow
discount_factor
fixed_leg_pv
inflation_leg_pv

The numeric fields are parsed into Decimal.

`StandardCouponInflationSwapPricingResult`¶

StandardCouponInflationSwapPricingResult is returned by price() for a standard coupon inflation swap.

Fields:

par_fixed_rate: raw decimal fixed rate that makes PV zero
present_value: fixed-leg PV plus inflation-leg PV
fixed_leg_pv
inflation_leg_pv
pv01: signed value of a one-basis-point fixed-rate bump
fixed_leg_annuity
periods: tuple of StandardCouponInflationSwapPeriodPricing

Numeric fields are parsed into Decimal, and periods is stored as a tuple.

from decimal import Decimal

from fuggers_py import Date
from fuggers_py.inflation import (
    InflationSwapPricer,
    StandardCouponInflationSwap,
    USD_CPI_U_NSA,
)


class FlatDiscountCurve:
    reference_date = Date.from_ymd(2026, 1, 2)
    spec = type("Spec", (), {"day_count": "ACT/365F"})()

    def discount_factor_at(self, tenor):
        return Decimal("0.980000")


class SimpleCpiProjection:
    def reference_cpi(self, date, convention):
        if date.year() == 2026:
            return Decimal("320.000")
        return Decimal("328.000")


standard_swap = StandardCouponInflationSwap.new(
    trade_date=Date.from_ymd(2026, 1, 2),
    effective_date=Date.from_ymd(2026, 1, 6),
    maturity_date=Date.from_ymd(2027, 1, 6),
    notional=Decimal("1000000"),
    fixed_rate=Decimal("0.025"),
    pay_receive="PAY",
    inflation_convention=USD_CPI_U_NSA,
    normalize_effective_date_to_reference_month_start=False,
)

standard_result = InflationSwapPricer().price(
    standard_swap,
    discount_curve=FlatDiscountCurve(),
    inflation_projection=SimpleCpiProjection(),
)

print(standard_result.present_value)
for period in standard_result.periods:
    print(period.start_date, period.end_date, period.inflation_rate)

Inflation Analytics¶

Analytics helpers compare nominal yields, real yields, and inflation swap rates. All rates are raw decimals.

`breakeven_inflation_rate`¶

breakeven_inflation_rate(nominal_yield=..., real_yield=..., compounding=...) returns the inflation rate implied by a nominal yield and a real yield.

With continuous compounding, it returns nominal_yield - real_yield.
With other compounding, it returns (1 + nominal_yield) / (1 + real_yield) - 1.
Nominal and real yields must be greater than -1.

`nominal_real_yield_basis`¶

nominal_real_yield_basis(nominal_yield=..., real_yield=..., compounding=...) returns the nominal-real basis.

With continuous compounding, it returns nominal_yield - real_yield.
With other compounding, it calls breakeven_inflation_rate().

`nominal_real_yield_spread`¶

nominal_real_yield_spread(...) is an alias for nominal_real_yield_basis(...).

`linker_swap_parity_check`¶

linker_swap_parity_check(nominal_yield=..., real_yield=..., inflation_swap_rate=..., compounding=...) compares a linker breakeven with an inflation swap rate.

It returns LinkerSwapParityCheck.

`LinkerSwapParityCheck`¶

LinkerSwapParityCheck stores:

nominal_yield
real_yield
linker_breakeven
swap_breakeven
parity_gap

parity_gap is linker_breakeven - swap_breakeven. Numeric fields are parsed into Decimal.

from decimal import Decimal

from fuggers_py import Compounding
from fuggers_py.inflation import (
    breakeven_inflation_rate,
    linker_swap_parity_check,
    nominal_real_yield_basis,
    nominal_real_yield_spread,
)

breakeven = breakeven_inflation_rate(
    nominal_yield=Decimal("0.045"),
    real_yield=Decimal("0.018"),
    compounding=Compounding.ANNUAL,
)

basis = nominal_real_yield_basis(
    nominal_yield=Decimal("0.045"),
    real_yield=Decimal("0.018"),
)

spread = nominal_real_yield_spread(
    nominal_yield=Decimal("0.045"),
    real_yield=Decimal("0.018"),
)

check = linker_swap_parity_check(
    nominal_yield=Decimal("0.045"),
    real_yield=Decimal("0.018"),
    inflation_swap_rate=Decimal("0.026"),
)

print(breakeven)
print(basis)
print(spread)
print(check.parity_gap)

Boundaries¶

TIPS instruments and TIPS bond pricing live in fuggers_py.bonds.
Nominal and real curve objects live in fuggers_py.curves.
Rates instruments live in fuggers_py.rates.
Portfolio inflation exposure is aggregated in fuggers_py.portfolio.

Export Reference¶

Public inflation products, pricing, and reference helpers.

class fuggers_py.inflation.InMemoryInflationFixingSource(fixings=None)¶

Deterministic in-memory inflation fixing source.

Parameters:: fixings (dict[tuple[str, YearMonth], InflationFixing])

class fuggers_py.inflation.InflationConvention(name, family, currency, index_source, observation_lag_months, interpolation_method=InflationInterpolation.MONTHLY, publication_style=None, aliases=(), notes=None)¶

Generic inflation-index definition used by reference-index helpers.

Parameters:

name (str)
family (str)
currency (Currency)
index_source (str)
observation_lag_months (int)
interpolation_method (InflationInterpolation)
publication_style (str | None)
aliases (tuple[str, ...])
notes (str | None)

lookup_names()¶

Return the ordered source names accepted when resolving fixings.

Return type:: tuple[str, ...]

exception fuggers_py.inflation.InflationError¶

Base exception for inflation-convention and reference-index failures.

Return type:: None

class fuggers_py.inflation.InflationFixing(index_name, observation_month, value)¶

Monthly inflation fixing keyed by index and observation month.

Parameters:

index_name (str)
observation_month (YearMonth)
value (Decimal)

fuggers_py.inflation.InflationIndexDefinition¶: alias of InflationConvention

class fuggers_py.inflation.InflationInterpolation(value)¶: Interpolation convention for inflation fixings.

class fuggers_py.inflation.InflationProjection(*args, **kwargs)¶: Shared interface for direct reference-index forecasts.

class fuggers_py.inflation.InflationSwapPricer¶

Price zero-coupon and standard coupon inflation swaps.

exception fuggers_py.inflation.InvalidObservationLag(observation_lag_months)¶

Raised when an inflation convention carries an invalid observation lag.

Parameters:: observation_lag_months (int)
Return type:: None

class fuggers_py.inflation.LinkerSwapParityCheck(nominal_yield, real_yield, linker_breakeven, swap_breakeven, parity_gap)¶

Compare linker-implied breakeven inflation against an inflation swap rate.

Parameters:

nominal_yield (Decimal)
real_yield (Decimal)
linker_breakeven (Decimal)
swap_breakeven (Decimal)
parity_gap (Decimal)

exception fuggers_py.inflation.MissingInflationFixing(index_name, requested_date, observation_months)¶

Raised when required monthly inflation fixings are not available.

Parameters:

index_name (str)
requested_date (Date)
observation_months (tuple[YearMonth, ...])

Return type:

None

class fuggers_py.inflation.StandardCouponInflationSwap(trade_date=<factory>, maturity_date=<factory>, notional=Decimal('100'), fixed_rate=Decimal('0'), pay_receive=PayReceive.PAY, inflation_convention=InflationConvention(name='USD CPI-U NSA', family='CPI_U', currency=<Currency.USD: 'USD'>, index_source='CPURNSA', observation_lag_months=3, interpolation_method=<InflationInterpolation.LINEAR: 'LINEAR'>, publication_style='NSA', aliases=('CPI-U', 'CPI-U NSA', 'US CPI-U', 'US CPI-U NSA'), notes='US Consumer Price Index for All Urban Consumers, Not Seasonally Adjusted. Reference CPI uses the third preceding month with linear daily interpolation.'), effective_date=None, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, schedule=<factory>, inflation_schedule=None, fixed_day_count_convention=DayCountConvention.<bound method DayCountConvention.name of <DayCountConvention.ACT_365_FIXED: 'ACT_365_FIXED'>>, normalize_effective_date_to_reference_month_start=True, fixed_periods_override=(), inflation_periods_override=(), instrument_id=None)¶

Schedule-driven standard coupon inflation swap.

Parameters:

trade_date (Date)
maturity_date (Date)
notional (Decimal)
fixed_rate (Decimal)
pay_receive (PayReceive | str)
inflation_convention (InflationConvention)
effective_date (Date | None)
currency (Currency | str)
schedule (ScheduleDefinition)
inflation_schedule (ScheduleDefinition | None)
fixed_day_count_convention (DayCountConvention | str)
normalize_effective_date_to_reference_month_start (bool)
fixed_periods_override (tuple[AccrualPeriod, ...])
inflation_periods_override (tuple[AccrualPeriod, ...])
instrument_id (InstrumentId | None)

class fuggers_py.inflation.StandardCouponInflationSwapPeriodPricing(start_date, end_date, payment_date, year_fraction, index_initial, index_final, inflation_rate, fixed_cashflow, inflation_cashflow, discount_factor, fixed_leg_pv, inflation_leg_pv)¶

Parameters:

start_date (Date)
end_date (Date)
payment_date (Date)
year_fraction (Decimal)
index_initial (Decimal)
index_final (Decimal)
inflation_rate (Decimal)
fixed_cashflow (Decimal)
inflation_cashflow (Decimal)
discount_factor (Decimal)
fixed_leg_pv (Decimal)
inflation_leg_pv (Decimal)

class fuggers_py.inflation.StandardCouponInflationSwapPricingResult(par_fixed_rate, present_value, fixed_leg_pv, inflation_leg_pv, pv01, fixed_leg_annuity, periods)¶

Parameters:

par_fixed_rate (Decimal)
present_value (Decimal)
fixed_leg_pv (Decimal)
inflation_leg_pv (Decimal)
pv01 (Decimal)
fixed_leg_annuity (Decimal)
periods (tuple[StandardCouponInflationSwapPeriodPricing, ...])

class fuggers_py.inflation.TreasuryAuctionedTipsRow(cusip, security_type, security_term, issue_date, dated_date, maturity_date, coupon_rate, original_issue_date=None, ref_cpi_on_issue_date=None, ref_cpi_on_dated_date=None, original_security_term=None)¶

Subset of Treasury auctioned-security TIPS metadata used by the library.

Parameters:

cusip (str)
security_type (str)
security_term (str)
issue_date (Date)
dated_date (Date | None)
maturity_date (Date)
coupon_rate (Decimal)
original_issue_date (Date | None)
ref_cpi_on_issue_date (Decimal | None)
ref_cpi_on_dated_date (Decimal | None)
original_security_term (str | None)

exception fuggers_py.inflation.UnsupportedInflationInterpolation(interpolation_method)¶

Raised when reference-index resolution does not support the convention.

Parameters:: interpolation_method (object)
Return type:: None

class fuggers_py.inflation.ZeroCouponInflationSwap(trade_date=<factory>, maturity_date=<factory>, notional=Decimal('100'), fixed_rate=Decimal('0'), pay_receive=PayReceive.PAY, inflation_convention=InflationConvention(name='USD CPI-U NSA', family='CPI_U', currency=<Currency.USD: 'USD'>, index_source='CPURNSA', observation_lag_months=3, interpolation_method=<InflationInterpolation.LINEAR: 'LINEAR'>, publication_style='NSA', aliases=('CPI-U', 'CPI-U NSA', 'US CPI-U', 'US CPI-U NSA'), notes='US Consumer Price Index for All Urban Consumers, Not Seasonally Adjusted. Reference CPI uses the third preceding month with linear daily interpolation.'), effective_date=None, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, payment_calendar=CalendarId(value='SIFMA'), business_day_convention=BusinessDayConvention.MODIFIED_FOLLOWING, instrument_id=None)¶

Single-payment zero-coupon inflation swap.

Parameters:

trade_date (Date)
maturity_date (Date)
notional (Decimal)
fixed_rate (Decimal)
pay_receive (PayReceive | str)
inflation_convention (InflationConvention)
effective_date (Date | None)
currency (Currency | str)
payment_calendar (CalendarId | str)
business_day_convention (BusinessDayConvention | str)
instrument_id (InstrumentId | None)

class fuggers_py.inflation.ZeroCouponInflationSwapPricingResult(par_fixed_rate, present_value, fixed_leg_pv, inflation_leg_pv, pv01, index_initial, index_final, payment_date, discount_factor, fixed_leg_annuity)¶

Parameters:

par_fixed_rate (Decimal)
present_value (Decimal)
fixed_leg_pv (Decimal)
inflation_leg_pv (Decimal)
pv01 (Decimal)
index_initial (Decimal)
index_final (Decimal)
payment_date (Date)
discount_factor (Decimal)
fixed_leg_annuity (Decimal)

fuggers_py.inflation.breakeven_inflation_rate(*, nominal_yield, real_yield, compounding=Compounding.ANNUAL)¶

Return the breakeven inflation rate implied by nominal and real yields.

Return type:

Decimal

Parameters:

nominal_yield (object)
real_yield (object)
compounding (Compounding)

fuggers_py.inflation.linker_swap_parity_check(*, nominal_yield, real_yield, inflation_swap_rate, compounding=Compounding.ANNUAL)¶

Return a simple linker-versus-swap parity comparison.

Return type:

LinkerSwapParityCheck

Parameters:

nominal_yield (object)
real_yield (object)
inflation_swap_rate (object)
compounding (Compounding)

fuggers_py.inflation.load_monthly_cpi_fixings_csv(path, *, index_name='CPURNSA')¶

Load normalized monthly CPI CSV rows from disk.

Return type:

tuple[InflationFixing, ...]

Parameters:

path (str | Path)
index_name (str)

fuggers_py.inflation.load_monthly_cpi_fixings_json(path, *, index_name='CPURNSA')¶

Load normalized monthly CPI JSON rows from disk.

Return type:

tuple[InflationFixing, ...]

Parameters:

path (str | Path)
index_name (str)

fuggers_py.inflation.load_treasury_auctioned_tips_csv(path)¶

Load Treasury auctioned-security TIPS rows from CSV on disk.

Return type:: tuple[TreasuryAuctionedTipsRow, ...]
Parameters:: path (str | Path)

fuggers_py.inflation.load_treasury_auctioned_tips_json(path)¶

Load Treasury auctioned-security TIPS rows from JSON on disk.

Return type:: tuple[TreasuryAuctionedTipsRow, ...]
Parameters:: path (str | Path)

fuggers_py.inflation.nominal_real_yield_basis(*, nominal_yield, real_yield, compounding=Compounding.CONTINUOUS)¶

Return the nominal-minus-real yield basis.

Return type:

Decimal

Parameters:

nominal_yield (object)
real_yield (object)
compounding (Compounding)

fuggers_py.inflation.nominal_real_yield_spread(*, nominal_yield, real_yield, compounding=Compounding.CONTINUOUS)¶

Alias for the nominal-minus-real yield basis.

Return type:

Decimal

Parameters:

nominal_yield (object)
real_yield (object)
compounding (Compounding)

fuggers_py.inflation.parse_bls_cpi_json(payload, *, index_name='CPURNSA')¶

Parse monthly BLS CPI-U JSON content into InflationFixing records.

Return type:

tuple[InflationFixing, ...]

Parameters:

payload (str | bytes | dict[str, Any] | list[dict[str, Any]])
index_name (str)

fuggers_py.inflation.parse_fred_cpi_csv(text, *, index_name='CPURNSA')¶

Parse a FRED monthly CPI CSV export into InflationFixing records.

Return type:

tuple[InflationFixing, ...]

Parameters:

text (str)
index_name (str)

fuggers_py.inflation.parse_monthly_cpi_fixings_csv(text, *, index_name='CPURNSA')¶

Parse normalized monthly CPI CSV rows into InflationFixing records.

Return type:

tuple[InflationFixing, ...]

Parameters:

text (str)
index_name (str)

fuggers_py.inflation.parse_monthly_cpi_fixings_json(payload, *, index_name='CPURNSA')¶

Parse normalized monthly CPI JSON rows into InflationFixing records.

Return type:

tuple[InflationFixing, ...]

Parameters:

payload (str | bytes | list[dict[str, Any]] | dict[str, Any])
index_name (str)

fuggers_py.inflation.parse_treasury_auctioned_tips_csv(text)¶

Parse Treasury auctioned-security CSV rows and retain TIPS records only.

Return type:: tuple[TreasuryAuctionedTipsRow, ...]
Parameters:: text (str)

fuggers_py.inflation.parse_treasury_auctioned_tips_json(payload)¶

Parse Treasury auctioned-security JSON rows and retain TIPS records only.

Return type:: tuple[TreasuryAuctionedTipsRow, ...]
Parameters:: payload (str | bytes | list[dict[str, Any]] | dict[str, Any])

fuggers_py.inflation.reference_cpi(settlement_date, convention, fixing_source)¶

Return the daily reference CPI implied by monthly published fixings.

Return type:

Decimal

Parameters:

settlement_date (Date)
convention (InflationConvention)
fixing_source (object)

fuggers_py.inflation.reference_index_ratio(settlement_date, base_date, convention, fixing_source)¶

Return the ratio of reference CPI at settlement and base dates.

Return type:

Decimal

Parameters:

settlement_date (Date)
base_date (Date)
convention (InflationConvention)
fixing_source (object)

fuggers_py.inflation.tips_bond_from_treasury_auction_row(row, *, fixing_source=None, identifiers=None)¶

Convert a parsed Treasury TIPS row into a TipsBond.

Return type:

TipsBond

Parameters:

row (TreasuryAuctionedTipsRow)
fixing_source (object | None)
identifiers (object | None)

fuggers_py.inflation.treasury_cpi_source_from_fixings(fixings)¶

Build an in-memory inflation fixing source from parsed CPI history.

Return type:: InMemoryInflationFixingSource
Parameters:: fixings (tuple[InflationFixing, ...] | list[InflationFixing])

fuggers_py.inflation¶

Core Rules¶

Conventions¶

InflationInterpolation¶

InflationConvention¶

USD_CPI_U_NSA¶

Errors¶

CPI Fixings And Sources¶

InflationFixing¶

InMemoryInflationFixingSource¶

CPI parsers and loaders¶

Reference CPI And Index Ratios¶

reference_cpi¶

reference_index_ratio¶

InflationProjection¶

Treasury TIPS Reference Data¶

TreasuryAuctionedTipsRow¶

Treasury parsers and loaders¶

tips_bond_from_treasury_auction_row¶

Inflation Swaps¶

Shared swap rules¶

ZeroCouponInflationSwap¶

StandardCouponInflationSwap¶

Inflation Swap Pricing¶

Curve and projection inputs¶

InflationSwapPricer¶

ZeroCouponInflationSwapPricingResult¶

StandardCouponInflationSwapPeriodPricing¶

StandardCouponInflationSwapPricingResult¶

Inflation Analytics¶

breakeven_inflation_rate¶

nominal_real_yield_basis¶

nominal_real_yield_spread¶

linker_swap_parity_check¶

LinkerSwapParityCheck¶

Boundaries¶

Export Reference¶

`fuggers_py.inflation`¶

`InflationInterpolation`¶

`InflationConvention`¶

`USD_CPI_U_NSA`¶

`InflationFixing`¶

`InMemoryInflationFixingSource`¶

`reference_cpi`¶

`reference_index_ratio`¶

`InflationProjection`¶

`TreasuryAuctionedTipsRow`¶

`tips_bond_from_treasury_auction_row`¶

`ZeroCouponInflationSwap`¶

`StandardCouponInflationSwap`¶

`InflationSwapPricer`¶

`ZeroCouponInflationSwapPricingResult`¶

`StandardCouponInflationSwapPeriodPricing`¶

`StandardCouponInflationSwapPricingResult`¶

`breakeven_inflation_rate`¶

`nominal_real_yield_basis`¶

`nominal_real_yield_spread`¶

`linker_swap_parity_check`¶

`LinkerSwapParityCheck`¶