API guide

The public API has one root package and eight first-layer domain packages. Import shared language from fuggers_py. Import domain objects from the domain package that owns them.

from fuggers_py import Currency, Date, InstrumentId, Price
from fuggers_py.bonds import FixedBondBuilder
from fuggers_py.curves import CurveSpec, YieldCurve
from fuggers_py.portfolio import Portfolio

The root package is for shared words used across the library. It does not export domain tools such as BondPricer or YieldCurve. Those stay under fuggers_py.bonds and fuggers_py.curves.

First-Layer Packages

  • curves: built curve objects, curve identity, curve shape choices, calibration inputs, and calibration reports.

  • vol_surfaces: volatility surface snapshots, points on those surfaces, and surface source interfaces.

  • bonds: bond instruments, bond quotes, bond pricing, bond risk, bond spreads, bond yields, reference records, and YAS-style bond analytics.

  • rates: swaps, basis swaps, FRAs, government bond futures, rates options, rate quotes, overnight fixing storage, and rates risk.

  • inflation: CPI history, inflation index conventions, reference CPI, index-ratio helpers, inflation swaps, and inflation analytics.

  • credit: CDS instruments, CDS quotes, CDS pricing, CDS risk, and bond-CDS basis analytics.

  • funding: repo trades, repo quotes, haircut quotes, carry, implied repo, financing cost, and specialness helpers.

  • portfolio: holdings, portfolio containers, analytics, benchmark comparison, contribution, bucketing, ETF workflows, liquidity, and stress.

Root Exports

The root exports the first-layer packages plus shared types and conventions.

Export

What it represents

Notes

__version__

Installed package version.

String.

curves, vol_surfaces, bonds, rates, inflation, credit, funding, portfolio

Public first-layer packages.

Use these package names for domain imports.

Date

Library date value.

Use for valuation dates, settlement dates, maturity dates, and fixing dates.

YearMonth

Calendar month value.

Use for monthly CPI observations and futures delivery months.

Currency

Currency code.

Common examples are Currency.USD, Currency.EUR, and Currency.GBP.

Frequency

Payment or coupon frequency.

Used by schedules, bonds, swaps, and CDS premium legs.

Compounding

How a rate compounds.

Used by yield and breakeven helpers.

Price

Typed price value.

Prices are usually percent-of-par unless a function says it needs a cash amount.

Yield

Typed yield value.

Raw yield inputs are decimals, so 0.05 means 5%.

Spread

Typed spread value.

Raw spread inputs are decimals, so 0.001 means 10 basis points.

InstrumentId

Identifier for one instrument.

Used by quotes, trades, reference records, and holdings.

CurveId

Identifier for one curve.

Used when several curves are stored or passed together.

PortfolioId

Identifier for one portfolio.

Used by portfolio containers and outputs.

Tenor

Term such as 3M, 5Y, or 30Y.

Use Tenor.parse("5Y") for string input.

DayCountConvention

Rule for turning dates into year fractions.

Used by cash-flow, yield, swap, repo, and CDS calculations.

BusinessDayConvention

Rule for moving dates that fall on non-business days.

Used by schedules and settlement rules.

CalendarId

Calendar name.

Identifies which business-day calendar a schedule or settlement rule uses.

SettlementAdjustment

Settlement date adjustment rule.

Used by settlement and schedule helpers.

YieldCalculationRules

Bond yield convention bundle.

Use presets such as YieldCalculationRules.us_treasury().

BondType, IssuerType

Bond classification enums.

Also available from fuggers_py.bonds.

PayReceive

Direction of a fixed leg, floating leg, or swap side.

Values describe whether the holder pays or receives that leg.

OptionType

Call or put option direction.

Used by bond options and rates options.

USD_CPI_U_NSA

Built-in US CPI-U NSA inflation convention.

Also available from fuggers_py.inflation.

IndexConventions, OvernightCompounding

Floating-rate and overnight index conventions.

Also available from fuggers_py.rates.

Input And Output Conventions

  • Dates are Date values unless a loader reads text from disk.

  • Rates, yields, spreads, recovery rates, haircuts, and volatilities are raw decimals unless the symbol name ends in _bps or _pct.

  • A raw decimal rate of 0.05 means 5%.

  • One basis point is 0.0001.

  • Prices are usually percent-of-par. A price of 99.5 means 99.5% of face.

  • Cash amounts are currency-unit decimals.

  • Quote records usually contain instrument_id, optional as_of, optional source, and optional bid, ask, and mid.

Boundary Rules

  • Use first-layer package imports in user code.

  • Do not import from package roots that start with _.

  • portfolio may combine objects from the other public packages.

  • Other public packages should not depend on portfolio.

  • Curve objects live in curves; quoted instruments and quote records live in the package that owns the instrument.

  • Volatility surface records live in vol_surfaces; option products and pricers live with the domain that owns those products.

If you are new to the repo, read Project Status first. The API surface is broad and usable, but the project is still pre-1.0. Implementation-only modules are documented in Developer internal modules, not in this API guide.