Skip to content

instruments

Instrument base classes, enums, and registry for the core domain model.

Modules:

  • base –

    Base classes and enumerations for financial instruments in the core domain model.

  • bonds –

    Bond instrument classes for the core domain model.

  • deposits –

    Deposit instrument classes for the core domain model.

  • equity –

    Equity instrument classes for the core domain model.

  • factory –

    Factory helpers for creating instrument instances with sensible defaults.

  • loans –

    Loan instrument classes for the core domain model.

  • other –

    Other off-balance-sheet and miscellaneous instrument classes for the core domain model.

  • registry –

    Registry for financial instrument types to support deserialization.

Classes:

  • BalanceSheetCategory –

    Enumeration for the category of the balance sheet an instrument is on.

  • BookType –

    Enumeration for different types of books.

  • CompositeInstrument –

    Composite class for financial instruments.

  • CreditRating –

    Enumeration of S&P credit ratings.

  • Instrument –

    Abstract base class for financial instruments.

  • InstrumentRegistry –

    Registry mapping type identifiers to instrument classes or factory callables.

  • Issuer –

    Class representing an issuer of financial instruments.

  • IssuerType –

    Enumeration of issuer types.

  • MeasurementBasis –

    IFRS 9 measurement category for financial instruments.

Functions:

BalanceSheetCategory

Bases: Enum

Enumeration for the category of the balance sheet an instrument is on.

BookType

Bases: Enum

Enumeration for different types of books.

Before a bank can calculate RWA for credit risk and RWA for market risk, it must follow the requirements of RBC25 to identify the instruments that are in the trading book. The banking book comprises all instruments that are not in the trading book and all other assets of the bank.

CompositeInstrument 

CompositeInstrument(
    name: str = "",
    book_type: BookType | None = None,
    credit_rating: CreditRating | None = None,
    issuer: Issuer | None = None,
    parent: Instrument | None = None,
)

Bases: Instrument

Composite class for financial instruments.

This class allows for the aggregation of multiple financial instruments into a single composite instrument. It can be used to represent a collection of assets, liabilities, or equities for a bank.

Methods:

  • accept –

    Accept a visitor by delegating to all contained instruments.

  • add –

    Add an instrument to the composite.

  • is_composite –

    Check if the instrument is composite.

  • remove –

    Remove an instrument from the composite.

  • repricing_date –

    Return the next repricing date for variable-rate instruments.

Attributes:

book_type property writable 

book_type: BookType | None

Get the book type of the instrument.

credit_rating property writable 

credit_rating: CreditRating

Get the instrument's credit rating.

issuer property writable 

issuer: Issuer

Get the instrument's issuer.

parent property writable 

parent: Instrument | None

Get the parent instrument.

accept 

accept(visitor: Visitor) -> None

Accept a visitor by delegating to all contained instruments.

add 

add(instrument: Instrument) -> None

Add an instrument to the composite.

is_composite 

is_composite() -> bool

Check if the instrument is composite.

remove 

remove(instrument: Instrument) -> None

Remove an instrument from the composite.

repricing_date 

repricing_date(as_of: date) -> date | None

Return the next repricing date for variable-rate instruments.

Returns None for fixed-rate instruments (repricing_frequency is None).

CreditRating

Bases: Enum

Enumeration of S&P credit ratings.

Methods:

  • is_investment_grade –

    Check if the credit rating is investment grade.

  • to_str –

    Get a custom string representation of the credit rating.

is_investment_grade 

is_investment_grade() -> bool

Check if the credit rating is investment grade.

to_str 

to_str() -> str

Get a custom string representation of the credit rating.

Instrument 

Instrument(
    name: str = "",
    book_type: BookType | None = None,
    credit_rating: CreditRating | None = None,
    issuer: Issuer | None = None,
    parent: Instrument | None = None,
    measurement_basis: MeasurementBasis | None = None,
    repricing_frequency: Period | None = None,
)

Bases: ABC

Abstract base class for financial instruments.

Subclasses declare applicable_rules — a frozenset of rule classes that the :class:RuleEngine should evaluate for positions holding this instrument. The default is an empty set (no rules apply).

Methods:

  • accept –

    Accept a visitor.

  • is_composite –

    Check if the instrument is composite.

  • repricing_date –

    Return the next repricing date for variable-rate instruments.

Attributes:

book_type property writable 

book_type: BookType | None

Get the book type of the instrument.

credit_rating property writable 

credit_rating: CreditRating

Get the instrument's credit rating.

issuer property writable 

issuer: Issuer

Get the instrument's issuer.

parent property writable 

parent: Instrument | None

Get the parent instrument.

accept abstractmethod 

accept(visitor: Visitor) -> None

Accept a visitor.

is_composite 

is_composite() -> bool

Check if the instrument is composite.

repricing_date 

repricing_date(as_of: date) -> date | None

Return the next repricing date for variable-rate instruments.

Returns None for fixed-rate instruments (repricing_frequency is None).

InstrumentRegistry 

InstrumentRegistry()

Registry mapping type identifiers to instrument classes or factory callables.

Allows decoupled deserialization: callers register concrete instrument types by a string key, then create instances by key without hard-coded imports.

Methods:

  • create –

    Create an instrument instance for the given type identifier.

  • register –

    Register an instrument class or factory under the given type identifier.

create 

create(type_id: str, **kwargs: object) -> Instrument

Create an instrument instance for the given type identifier.

Parameters:

  • type_id

    (str) –

    The string key previously registered via :meth:register.

  • **kwargs

    (object, default: {} ) –

    Keyword arguments forwarded to the instrument constructor.

Returns:

  • Instrument –

    A new instance of the registered instrument class.

Raises:

  • KeyError –

    If type_id has not been registered.

register 

register(
    type_id: str,
    cls: type[Instrument] | Callable[..., Instrument],
) -> None

Register an instrument class or factory under the given type identifier.

Parameters:

  • type_id

    (str) –

    A unique string key for the instrument type.

  • cls

    (type[Instrument] | Callable[..., Instrument]) –

    The concrete instrument class or a factory callable.

Issuer 

Issuer(
    name: str,
    issuer_type: IssuerType,
    credit_rating: CreditRating | None = None,
)

Class representing an issuer of financial instruments.

Methods:

  • is_bank –

    Check if the issuer is depositary institution or bank.

  • is_corporate –

    Check if the issuer is corporate.

  • is_individual –

    Check if the issuer is individual.

  • is_mdb –

    Check if the issuer is multilateral development bank (MDB).

  • is_pse –

    Check if the issuer is public sector entity (PSE).

  • is_securities_firm –

    Check if the issuer is securities firm.

  • is_sme –

    Check if the issuer is SME corporate.

  • is_sovereign –

    Check if the issuer is sovereign.

Attributes:

credit_rating property writable 

credit_rating: CreditRating

Get the issuer's credit rating.

is_bank 

is_bank() -> bool

Check if the issuer is depositary institution or bank.

is_corporate 

is_corporate() -> bool

Check if the issuer is corporate.

is_individual 

is_individual() -> bool

Check if the issuer is individual.

is_mdb 

is_mdb() -> bool

Check if the issuer is multilateral development bank (MDB).

is_pse 

is_pse() -> bool

Check if the issuer is public sector entity (PSE).

is_securities_firm 

is_securities_firm() -> bool

Check if the issuer is securities firm.

is_sme 

is_sme() -> bool

Check if the issuer is SME corporate.

is_sovereign 

is_sovereign() -> bool

Check if the issuer is sovereign.

IssuerType

Bases: Flag

Enumeration of issuer types.

Methods:

  • to_str –

    Get a custom string representation of the issuer type.

to_str 

to_str() -> str

Get a custom string representation of the issuer type.

MeasurementBasis

Bases: Enum

IFRS 9 measurement category for financial instruments.

default_instrument_registry 

default_instrument_registry() -> InstrumentRegistry

Return an InstrumentRegistry populated with all known instrument types.