pyfirds package

Submodules

pyfirds.categories module

Some data types that are used as building blocks in the main ReferenceData classes.

class pyfirds.categories.BaseProduct(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

AGRI = 'Agricultural'

ENVR = 'Environmental'

FRGT = 'Freight'

FRTL = 'Fertilizer'

INDP = 'Industrial products'

INFL = 'Inflation'

MCEX = 'Multi Commodity Exotic'

METL = 'Metals'

NRGY = 'Energy'

OEST = 'Official economic statistics'

OTHC = 'Other C10 (as defined in Table 10.1 of Section 10 of Annex III to Commission Delegated Regulation supplementing Regulation (EU) No 600/2014 of the European Parliament and of the Council with regard to regulatory technical standards on transparency requirements for trading venues and investment firms in respect of bonds, structured finance products, emission allowances and derivatives)'

OTHR = 'Other'

PAPR = 'Paper'

POLY = 'Polypropylene'

class pyfirds.categories.DebtSeniority(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

JUND = 'junior'

MZZD = 'mezzanine'

SBOD = 'subordinated'

SNDB = 'senior'

class pyfirds.categories.DeliveryType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

CASH = 'cash'

OPTL = 'optional'

PHYS = 'physical'

class pyfirds.categories.FinalPriceType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

ARGM = 'Argus/McCloskey'

BLTC = 'Baltic'

EXOF = 'Exchange'

GBCL = 'GlobalCOAL'

IHSM = 'HIS McCloskey'

OTHR = 'Other'

PLAT = 'Platts'

class pyfirds.categories.FurtherSubProduct(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

ALUA = 'Aluminium Alloy'

ALUM = 'Aluminium'

BAKK = 'Bakken'

BDSL = 'Biodiesel'

BRNT = 'Brent'

BRNX = 'Brent NX'

BRWN = 'Raw Sugar'

BSLD = 'Base load'

CBLT = 'Cobalt'

CCOA = 'Cocoa'

CERE = 'CER'

CNDA = 'Canadian'

COND = 'Condensate'

COPR = 'Copper'

CORN = 'Maize'

DBCR = 'Dry bulk carriers'

DSEL = 'Diesel'

DUBA = 'Dubai'

ERUE = 'ERU'

ESPO = 'ESPO'

ETHA = 'Ethanol'

EUAA = 'EUAA'

EUAE = 'EUA'

FITR = 'Financial Transmission Rights'

FOIL = 'Fuel Oil'

FUEL = 'Fuel'

FWHT = 'Feed Wheat'

GASP = 'GASPOOL'

GOIL = 'Gasoil'

GOLD = 'Gold'

GSLN = 'Gasoline'

HEAT = 'Heating Oil'

IRON = 'Iron ore'

JTFL = 'Jet Fuel'

KERO = 'Kerosene'

LAMP = 'Lampante'

LEAD = 'Lead'

LLSO = 'Light Louisiana Sweet (LLS)'

LNGG = 'LNG'

MARS = 'MARS'

MOLY = 'Molybdenum'

MWHT = 'Milling Wheat'

NAPH = 'Naptha'

NASC = 'NASAAC'

NBPG = 'NBP'

NCGG = 'NCG'

NGLO = 'NGL'

NICK = 'Nickel'

OFFP = 'Off-peak'

OTHR = 'Other'

PKLD = 'Peak load'

PLDM = 'Palladium'

PTNM = 'Platinum'

RICE = 'Rice'

ROBU = 'Robusta Coffee'

RPSD = 'Rapeseed'

SLVR = 'Silver'

SOYB = 'Soybeans'

STEL = 'Steel'

TAPI = 'Tapis'

TINN = 'Tin'

TNKR = 'Tankers'

TTFG = 'TTF'

URAL = 'Urals'

WHSG = 'White Sugar'

WTIO = 'WTI'

ZINC = 'Zinc'

class pyfirds.categories.FxType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

FXCR = 'FX Cross Rates'

FXEM = 'FX Emerging Markets'

FXMJ = 'FX Majors'

class pyfirds.categories.IndexName(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

BBSW = 'BBSW'

BUBO = 'BUBOR'

CDOR = 'CDOR'

CIBO = 'CIBOR'

EONA = 'EONIA'

EONS = 'EONIA SWAP'

EUCH = 'EuroSwiss'

EURO = 'EURIBOR'

FUSW = 'Future SWAP'

GCFR = 'GCF REPO'

ISDA = 'ISDAFIX'

JIBA = 'JIBAR'

LIBI = 'LIBID'

LIBO = 'LIBOR'

MAAA = 'Muni AAA'

MOSP = 'MOSPRIM'

NIBO = 'NIBOR'

PFAN = 'Pfandbriefe'

PRBO = 'PRIBOR'

STBO = 'STIBOR'

SWAP = 'SWAP'

TIBO = 'TIBOR'

TLBO = 'TELBOR'

TREA = 'Treasury'

WIBO = 'WIBOR'

class pyfirds.categories.IndexTermUnit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

DAYS = 'days'

MNTH = 'month'

WEEK = 'week'

YEAR = 'year'

class pyfirds.categories.OptionExerciseStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

AMER = 'American'

ASIA = 'Asian'

BERM = 'Bermudan'

EURO = 'European'

OTHR = 'Other'

class pyfirds.categories.OptionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

CALL = 'call'

OTHR = 'other'

PUTO = 'put'

class pyfirds.categories.StrikePriceType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

BASIS_POINTS = 'basis_points'

MONETARY_VALUE = 'monetary_value'

NO_PRICE = 'no_price'

PERCENTAGE = 'percentage'

YIELD = 'yield'

class pyfirds.categories.SubProduct(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

AMMO = 'Ammonia'

CBRD = 'Containerboard'

COAL = 'Coal'

CRBR = 'Carbon related'

CSHP = 'Container ships'

CSTR = 'Construction'

DAPH = 'DAP (Diammonium Phosphate)'

DIRY = 'Dairy'

DIST = 'Distillates'

DLVR = 'Deliverable'

DRYF = 'Dry'

ELEC = 'Electricity'

EMIS = 'Emissions'

FRST = 'Forestry'

GRIN = 'Grain'

GROS = 'Grains and Oil Seeds'

INRG = 'Inter Energy'

LGHT = 'Light ends'

LSTK = 'Livestock'

MFTG = 'Manufacturing'

NDLV = 'Non-deliverable'

NGAS = 'Natural Gas'

NPRM = 'Non Precious'

NSPT = 'Newsprint'

OILP = 'Oil'

OOLI = 'Olive oil'

PLST = 'Plastic'

POTA = 'Potato'

PRME = 'Precious'

PTSH = 'Potash'

PULP = 'Pulp'

RCVP = 'Recovered paper'

RNNG = 'Renewable energy'

SEAF = 'Seafood'

SLPH = 'Sulphur'

SOFT = 'Softs'

UAAN = 'UAN (urea and ammonium nitrate)'

UREA = 'Urea'

WETF = 'Wet'

WTHR = 'Weather'

class pyfirds.categories.TransactionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

CRCK = 'Crack'

DIFF = 'Differential'

FUTR = 'Futures'

MINI = 'Minis'

OPTN = 'Options'

ORIT = 'Outright'

OTCT = 'OTC'

OTHR = 'Other'

SWAP = 'Swaps'

TAPO = 'TAPOS'

pyfirds.download module

exception pyfirds.download.BadChecksumError

Bases: Exception

An error raised when a downloaded file does not have the expected checksum.

class pyfirds.download.BaseFirdsSearcher

Bases: ABC

abstract search(from_date: date, to_date: date, file_type: FileType | None) → list[FirdsDoc]

Search the FIRDS database and return a list of download URLs.

Parameters:

• from_date – The start of the period to search. Can be a datetime object or a date object. In the latter case, the search period will run from the start of that date.

• to_date – The end of the period to search. Can be a datetime object or a date object. In the latter case, the search period will run to the end of that date.

• file_type – The query to search. Optional, but can be FULINS, DLTINS or FULCAN to search for full FIRDS records, delta files or cancellation files, respectively.

class pyfirds.download.EsmaFirdsSearcher(base_url: str = 'https://registers.esma.europa.eu/solr/esma_registers_firds_files/')

Bases: BaseFirdsSearcher

search(from_date: date, to_date: date, file_type: FileType | None) → list[FirdsDoc]

Search the FIRDS database and return a list of download URLs.

Parameters:

• from_date – The start of the period to search. Can be a datetime object or a date object. In the latter case, the search period will run from the start of that date.

• to_date – The end of the period to search. Can be a datetime object or a date object. In the latter case, the search period will run to the end of that date.

• file_type – The query to search. Optional, but can be FULINS, DLTINS or FULCAN to search for full FIRDS records, delta files or cancellation files, respectively.

class pyfirds.download.FcaFirdsSearcher(base_url: str = 'https://api.data.fca.org.uk/fca_data_firds_files')

Bases: BaseFirdsSearcher

search(from_date: date, to_date: date, file_type: FileType | None = None) → list[FirdsDoc]

Search the FIRDS database and return a list of download URLs.

Parameters:

• from_date – The start of the period to search. Can be a datetime object or a date object. In the latter case, the search period will run from the start of that date.

• to_date – The end of the period to search. Can be a datetime object or a date object. In the latter case, the search period will run to the end of that date.

• file_type – The query to search. Optional, but can be FULINS, DLTINS or FULCAN to search for full FIRDS records, delta files or cancellation files, respectively.

class pyfirds.download.FileType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The type of a FIRDS data file.

DLTINS = 'DLTINS'

FULCAN = 'FULCAN'

FULINS = 'FULINS'

class pyfirds.download.FirdsDoc(download_link: str, file_id: str, file_name: str, file_type: str, timestamp: datetime, checksum: str | None)

Bases: object

A dataclass representing a single document reference returned by searching a FIRDS database (ESMA or FCA).

checksum: str | None

MD5 checksum for the file, if present (should be present in ESMA data but not FCA data).

download_link: str

A URL to download the file from.

download_xml(to_dir: str, overwrite: bool = False, verify: bool = True, delete_zip: bool = True)

Download this file as an XML file to the specified directory.

Parameters:

• to_dir – The directory to download the file to. If no directory is specified, a temporary one is used.

• overwrite – Whether to overwrite an existing file if one already exists. Default is False.

• verify – Whether to verify the checksum of the downloaded zip file. Default is True.

• delete_zip – Whether to delete the zip file after its contents have been extracted. Default is True.

Returns:

The absolute path of the file’s location.

download_zip(to_dir: str, overwrite: bool = False, verify: bool = True)

Download this file as a zip file to the specified directory.

Parameters:

• to_dir – The directory to download the file to.

• overwrite – Whether to overwrite an existing file if one already exists. Default is False.

• verify – Whether to verify the checksum of the downloaded file. Default is True.

Returns:

The absolute path of the file’s location.

file_id: str

An ID for the file.

file_name: str

The name of the file.

file_type: str

The type of the file (FULINS/DLTINS/FULCAN).

classmethod from_esma_dict(d: dict[str, Any]) → FirdsDoc

classmethod from_fca_dict(d: dict[str, Any]) → FirdsDoc

timestamp: datetime

The timestamp of the document.

pyfirds.identifiers module

Classes representing certain types of identifier used in the FIRDS data.

exception pyfirds.identifiers.BadIdentifierException

Bases: Exception

exception pyfirds.identifiers.BadIsinError

Bases: BadIdentifierException

exception pyfirds.identifiers.BadLeiError

Bases: BadIdentifierException

class pyfirds.identifiers.ISIN(code: str, country_code: str = None, instrument_identifier: str = None, check_digit: int = None)

Bases: object

An International Securities Identification Number.

check_digit: int = None

Last digit of the ISIN, which is a check digit.

code: str

The ISIN as a string.

country_code: str = None

The first two digits of the ISIN, which form a country code.

instrument_identifier: str = None

Third to eleventh digits of the ISIN, which form an alphanumeric security identifier.

validate()

Perform some basic checks against the ISIN code to ensure it broadly looks okay (is the right length, etc), and throw an error otherwise. Does not check if the ISIN code has actually been issued.

verify_checksum() → bool

Verify that the ISIN’s check digit is valid.

class pyfirds.identifiers.LEI(code: str, lou_identifier: str = None, entity_identifier: str = None, check_digits: str = None)

Bases: object

A Legal Entity Identifier.

check_digits: str = None

The last two digits of the LEI, which are check digits.

code: str

The LEI code as a string.

entity_identifier: str = None

The fifth to eighteenth digits of the LEI, which identify the entity itself.

lou_identifier: str = None

The first four digits of the LEI, which identify the local operating unit (LOU) for the LEI.

validate()

Perform some basic checks against the LEI code to ensure it broadly looks okay (is the right length, etc), and throw an error otherwise. Does not check if the given LEI code has actually been issued.

verify_checksum() → bool

Verify that the LEI’s check digits are valid. The alphanumeric LEI code is converted to an integer by replacing alphabetical characters with corresponding numbers. If the resulting integer modulo 97 equals 1, the checksum is valid.

pyfirds.model module

class pyfirds.model.CommodityDerivativeAttributes(base_product: BaseProduct, sub_product: SubProduct | None, further_sub_product: FurtherSubProduct | None, transaction_type: TransactionType | None, final_price_type: FinalPriceType | None)

Bases: XmlParsed

Additional reference data for a commodity derivative instrument.

base_product: BaseProduct

The base product for the underlying asset class.

final_price_type: FinalPriceType | None

The final price type as specified by the trading venue.

classmethod from_xml(elem: Element) → CommodityDerivativeAttributes

Parse a DerivInstrmAttrbts/AsstClssSpcfcAttrbts/Cmmdty XML element from FIRDS into a CommodityDerivativeAttributes object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}Cmmdty or equivalent.

further_sub_product: FurtherSubProduct | None

The further sub-product (ie, sub-sub-product) for the underlying asset class.

sub_product: SubProduct | None

The sub-product for the underlying asset class.

transaction_type: TransactionType | None

The transaction type as specified by the trading venue.

class pyfirds.model.DebtAttributes(total_issued_amount: float, maturity_date: date | None, nominal_currency: str, nominal_value_per_unit: float, interest_rate: InterestRate, seniority: DebtSeniority | None)

Bases: XmlParsed

Reference data for bonds or other forms of securitised debt.

classmethod from_xml(elem: Element) → DebtAttributes

Create an instance of the class from an appropriate XML element.

interest_rate: InterestRate

Details of the interest rate applicable to the financial instrument.

maturity_date: date | None

The maturity date of the financial instrument. Only applies to debt instruments with defined maturity.

nominal_currency: str

The currency of the nominal value.

nominal_value_per_unit: float

The nominal value of each traded unit. If not available, the minimum traded amount is included. Amount is expressed in the nominal_currency.

seniority: DebtSeniority | None

The seniority of the financial instrument (senior, mezzanine, subordinated or junior).

total_issued_amount: float

The total issued nominal amount of the financial instrument. Amount is expressed in the nominal_currency.

class pyfirds.model.DerivativeAttributes(expiry_date: date | None, price_multiplier: float | None, underlying: DerivativeUnderlying | None, option_type: OptionType | None, strike_price: StrikePrice | None, option_exercise_style: OptionExerciseStyle | None, delivery_type: DeliveryType | None, commodity_attributes: CommodityDerivativeAttributes | None, ir_attributes: InterestRateDerivativeAttributes | None, fx_attributes: FxDerivativeAttributes | None)

Bases: XmlParsed

Reference data for a derivative instrument.

Note that some other types of instrument can also have derivative-related attributes, eg, some collective investment scheme (CFI code C) instruments.

commodity_attributes: CommodityDerivativeAttributes | None

If the instrument is a commodity derivative, certain commodity-related attributes.

delivery_type: DeliveryType | None

Whether the financial instrument is cash settled or physically settled or delivery type cannot be determined at time of execution.

expiry_date: date | None

Expiry date of the instrument.

classmethod from_xml(elem: Element) → DerivativeAttributes

Parse a DerivInstrmAttrbts XML element from FIRDS into a DerivativeAttributes object.

Parameters:

elem – The XML element to parse, as a etree._Element object.

fx_attributes: FxDerivativeAttributes | None

If the instrument is a foreign exchange derivative, certain FX-related attributes.

ir_attributes: InterestRateDerivativeAttributes | None

If the instrument is an interest rate derivative, certain IR-related attributes.

option_exercise_style: OptionExerciseStyle | None

Indication of whether the option may be exercised only at a fixed date (European and Asian style), a series of pre-specified dates (Bermudan) or at any time during the life of the contract (American style).

option_type: OptionType | None

If the derivative instrument is an option, whether it is a call or a put or whether it cannot be determined whether it is a call or a put at the time of execution.

price_multiplier: float | None

Number of units of the underlying instrument represented by a single derivative contract. For a future or option on an index, the amount per index point.

strike_price: StrikePrice | None

Predetermined price at which the holder will have to buy or sell the underlying instrument, or an indication that the price cannot be determined at the time of execution.

underlying: DerivativeUnderlying | None

Description of the underlying asset or basket of assets.

class pyfirds.model.DerivativeUnderlying(single: UnderlyingSingle | None, basket: UnderlyingBasket | None)

Bases: XmlParsed

Reference data for the asset underlying a derivative. The underlying may be a single issuer, instrument or index, or may be a basket of instruments or issuers. The relevant parameter will be populated and the rest will be None.

basket: UnderlyingBasket | None

Data for a basket of instruments or issuers underlying a derivative instrument, or None if the underlying is a single instrument, index or issuer.

classmethod from_xml(elem: [<cyfunction Element at 0x7364b8789ff0>]) → DerivativeUnderlying

Parse a DerivInstrmAttrbts/UndrlygInstrm XML element from FIRDS into a UnderlyingSingle or UnderlyingBasket object as appropriate.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}UndrlygInstrm or equivalent.

single: UnderlyingSingle | None

Data for a single instrument, index or issuer underlying a derivative instrument, or None if the underlying is a basket.

class pyfirds.model.FxDerivativeAttributes(notional_currency_2: str, fx_type: FxType)

Bases: XmlParsed

Additional reference data for a foreign exchange derivative instrument.

classmethod from_xml(elem: Element) → FxDerivativeAttributes

Parse a DerivInstrmAttrbts/AsstClssSpcfcAttrbts/FX XML element from FIRDS into a FxDerivativeAttributes object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}FX or equivalent.

fx_type: FxType

The type of underlying currency.

notional_currency_2: str

The second currency of the currency pair.

class pyfirds.model.Index(name: str | IndexName | None, isin: str | None, term: IndexTerm | None)

Bases: XmlParsed

An index or benchmark rate that is used in the reference data for certain financial instruments.

classmethod from_xml(elem: Element) → Index

Parse an IntrstRate/Fltg or DerivInstrmAttrbts/UndrlygInstrm/Sngl/Indx/Nm/RefRate/Nm XML element from FIRDS data into a Index object.

Parameters:

elem – The XML element to parse. The element should be of type FloatingInterestRate8 as defined in the FULINS XSD.

isin: str | None

The ISIN of the index or benchmark.

name: str | IndexName | None

The name of the index or benchmark. Should either be a IndexName object or a 25 character string.

term: IndexTerm | None

The term of the index or benchmark.

class pyfirds.model.IndexTerm(number: int, unit: IndexTermUnit)

Bases: XmlParsed

The term of an index or benchmark.

classmethod from_xml(elem: Element) → IndexTerm

Parse a Fltg/Term XML element from FIRDS data into a IndexTerm object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}Term or equivalent.

number: int

The number of weeks, months, etc (as determined by unit).

unit: IndexTermUnit

The unit of time in which the term is expressed (days, weeks, months or years).

class pyfirds.model.InterestRate(fixed_rate: float | None, benchmark: Index | None, spread: int | None)

Bases: XmlParsed

Data about the interest rate applicable to a debt instrument.

benchmark: Index | None

The benchmark or index of a floating rate instrument.

fixed_rate: float | None

The interest rate payable on a fixed rate instrument, expressed as a percentage (eg, 7.5 means 7.5% interest rate).

classmethod from_xml(elem: Element) → InterestRate

Parse an IntrstRate XML element from FIRDS data into an InterestRate object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}IntrstRate or equivalent.

property is_fixed: bool

Whether this interest rate is a fixed interest rate.

property is_floating: bool

Whether this interest rate is a floating interest rate.

spread: int | None

Spread of a floating rate instrument, expressed as an integer number of basis points.

validate()

Check that either a fixed rate or a floating rate is defined.

class pyfirds.model.InterestRateDerivativeAttributes(reference_rate: Index, notional_currency_2: str | None, fixed_rate_1: float | None, fixed_rate_2: float | None, floating_rate_2: Index | None)

Bases: XmlParsed

Additional reference data for an interest rate derivative instrument.

fixed_rate_1: float | None

The fixed rate of leg 1 of the trade, if applicable. Expressed as a percentage.

fixed_rate_2: float | None

The fixed rate of leg 2 of the trade, if applicable. Expressed as a percentage.

floating_rate_2: Index | None

The floating rate of leg 2 of the trade, if applicable.

classmethod from_xml(elem: Element) → InterestRateDerivativeAttributes

Parse a DerivInstrmAttrbts/AsstClssSpcfcAttrbts/Intrst XML element from FIRDS into a InterestRateDerivativeAttributes object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}Intrst or equivalent.

notional_currency_2: str | None

In the case of multi-currency or cross-currency swaps the currency in which leg 2 of the contract is denominated. For swaptions where the underlying swap is multi-currency, the currency in which leg 2 of the swap is denominated.

reference_rate: Index

The reference rate.

class pyfirds.model.ModifiedRecord(isin: str, full_name: str, cfi: str, is_commodities_derivative: bool, issuer_lei: str, fisn: str, trading_venue_attrs: TradingVenueAttributes, notional_currency: str, technical_attributes: TechnicalAttributes | None, debt_attributes: DebtAttributes | None, derivative_attributes: DerivativeAttributes | None)

Bases: ReferenceData

Modified reference data for a financial instrument. Supports all the same properties and methods as ReferenceData.

cfi: str

The Classification of Financial Instruments code (ISO 10962) of the financial instrument.

debt_attributes: DebtAttributes | None

If the instrument is a debt instrument, certain debt-related attributes.

derivative_attributes: DerivativeAttributes | None

If the instrument is a derivative, certain derivative-related attributes.

fisn: str

The Financial Instrument Short Name (ISO 18774) for the financial instrument.

full_name: str

The full name of the financial instrument. This should give a good indication of the issuer and the particulars of the instrument.

is_commodities_derivative: bool

Whether the financial instrument falls within the definition of a “commodities derivative” under Article 2(1)(30) of Regulation (EU) No 600/2014.

isin: str

The International Securities Indentifier Number (ISO 6166) of the financial instrument.

issuer_lei: str

The Legal Entity identifier (ISO 17442) for the issuer. In certain cases, eg derivative instruments issued by the trading venue, this field will be populated with the trading venue operator’s LEI.

notional_currency: str

The currency in which the notional is denominated. For an interest rate or currency derivative contract, this will be the notional currency of leg 1, or the currency 1, of the pair. In the case of swaptions where the underlying swap is single currency, this will be the notional currency of the underlying swap. For swaptions where the underlying is multi-currency, this will be the notional currency of leg 1 of the swap.

technical_attributes: TechnicalAttributes | None

Technical attributes of the financial instrument.

trading_venue_attrs: TradingVenueAttributes

Data relating to the trading or admission to trading of the financial instrument on a trading venue.

class pyfirds.model.NewRecord(isin: str, full_name: str, cfi: str, is_commodities_derivative: bool, issuer_lei: str, fisn: str, trading_venue_attrs: TradingVenueAttributes, notional_currency: str, technical_attributes: TechnicalAttributes | None, debt_attributes: DebtAttributes | None, derivative_attributes: DerivativeAttributes | None)

Bases: ReferenceData

Reference data for a newly added financial instrument. Supports all the same properties and methods as ReferenceData.

cfi: str

The Classification of Financial Instruments code (ISO 10962) of the financial instrument.

debt_attributes: DebtAttributes | None

If the instrument is a debt instrument, certain debt-related attributes.

derivative_attributes: DerivativeAttributes | None

If the instrument is a derivative, certain derivative-related attributes.

fisn: str

The Financial Instrument Short Name (ISO 18774) for the financial instrument.

full_name: str

The full name of the financial instrument. This should give a good indication of the issuer and the particulars of the instrument.

is_commodities_derivative: bool

Whether the financial instrument falls within the definition of a “commodities derivative” under Article 2(1)(30) of Regulation (EU) No 600/2014.

isin: str

The International Securities Indentifier Number (ISO 6166) of the financial instrument.

issuer_lei: str

The Legal Entity identifier (ISO 17442) for the issuer. In certain cases, eg derivative instruments issued by the trading venue, this field will be populated with the trading venue operator’s LEI.

notional_currency: str

The currency in which the notional is denominated. For an interest rate or currency derivative contract, this will be the notional currency of leg 1, or the currency 1, of the pair. In the case of swaptions where the underlying swap is single currency, this will be the notional currency of the underlying swap. For swaptions where the underlying is multi-currency, this will be the notional currency of leg 1 of the swap.

technical_attributes: TechnicalAttributes | None

Technical attributes of the financial instrument.

trading_venue_attrs: TradingVenueAttributes

Data relating to the trading or admission to trading of the financial instrument on a trading venue.

class pyfirds.model.PublicationPeriod(from_date: date, to_date: date | None)

Bases: XmlParsed

The period for which details on a financial instrument were published.

from_date: date

The date from which details on the financial instrument were published.

classmethod from_xml(elem: Element) → PublicationPeriod

Parse a PblctnPrd XML element from FIRDS data into a PublicationPeriod object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}PblctnPrd or equivalent.

to_date: date | None

The date to which details on the financial instrument were published.

class pyfirds.model.ReferenceData(isin: str, full_name: str, cfi: str, is_commodities_derivative: bool, issuer_lei: str, fisn: str, trading_venue_attrs: TradingVenueAttributes, notional_currency: str, technical_attributes: TechnicalAttributes | None, debt_attributes: DebtAttributes | None, derivative_attributes: DerivativeAttributes | None)

Bases: XmlParsed

A base class for financial instrument reference data.

cfi: str

The Classification of Financial Instruments code (ISO 10962) of the financial instrument.

debt_attributes: DebtAttributes | None

If the instrument is a debt instrument, certain debt-related attributes.

derivative_attributes: DerivativeAttributes | None

If the instrument is a derivative, certain derivative-related attributes.

fisn: str

The Financial Instrument Short Name (ISO 18774) for the financial instrument.

classmethod from_xml(elem: Element) → ReferenceData

Parse a RefData XML element from FIRDS into a ReferenceData object (or appropriate subclass).

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}RefData or an equivalent XML element which belongs to the document namespace in nsmap.

full_name: str

The full name of the financial instrument. This should give a good indication of the issuer and the particulars of the instrument.

is_commodities_derivative: bool

Whether the financial instrument falls within the definition of a “commodities derivative” under Article 2(1)(30) of Regulation (EU) No 600/2014.

isin: str

The International Securities Indentifier Number (ISO 6166) of the financial instrument.

issuer_lei: str

The Legal Entity identifier (ISO 17442) for the issuer. In certain cases, eg derivative instruments issued by the trading venue, this field will be populated with the trading venue operator’s LEI.

notional_currency: str

The currency in which the notional is denominated. For an interest rate or currency derivative contract, this will be the notional currency of leg 1, or the currency 1, of the pair. In the case of swaptions where the underlying swap is single currency, this will be the notional currency of the underlying swap. For swaptions where the underlying is multi-currency, this will be the notional currency of leg 1 of the swap.

technical_attributes: TechnicalAttributes | None

Technical attributes of the financial instrument.

trading_venue_attrs: TradingVenueAttributes

Data relating to the trading or admission to trading of the financial instrument on a trading venue.

property unique_id: str

A unique ID for the financial instrument reference data, consisting of its ISIN plus the MIC of the relevant trading venue (as the same ISIN can be reported by multiple trading venues). This identifier is not separately provided by the FIRDS data, but is generated from the isin and trading_venue_attrs.trading_venue attributes of the ReferenceData object, which are taken from the FIRDS data. The combination of ISIN and MIC is, however, apparently used by ESMA to identify records uniquely.

class pyfirds.model.StrikePrice(price_type: StrikePriceType, price: float | None, pending: bool, currency: str | None)

Bases: XmlParsed

The strike price of a derivative instrument.

currency: str | None

The currency in which the price is denominated (if appropriate).

classmethod from_xml(elem: Element) → StrikePrice

Parse a DerivInstrmAttrbts/StrkPric XML element from FIRDS into a StrikePrice object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}StrkPric or equivalent.

pending: bool

Whether the price is currently not available and is pending.

price: float | None

The actual price, expressed according to price_type. Will be None if no price is available.

price_type: StrikePriceType

How the price is expressed (as a monetary value, percentage, yield or basis points). Alternatively identifies if no price is available.

class pyfirds.model.TechnicalAttributes(relevant_competent_authority: str | None, publication_period: PublicationPeriod | None, relevant_trading_venue: str | None)

Bases: XmlParsed

The technical attributes of a financial instrument (ie, attributes relating to the submission of details of the financial instrument to FIRDS).

classmethod from_xml(elem: Element) → TechnicalAttributes

Parse a TechAttrbts XML element from FIRDS data into a TechnicalAttributes object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}TechAttrbts or equivalent.

publication_period: PublicationPeriod | None

The period for which these details on the financial instrument was published. NOTE: publication_period is optional as it does not appear in TerminatedRecord classes, but it should always appear in ReferenceData classes.

relevant_competent_authority: str | None

The relevant competent authority for the instrument.

relevant_trading_venue: str | None

The MIC of the trading venue that reported the record considered as the reference for the published data.

class pyfirds.model.TerminatedRecord(isin: str, full_name: str, cfi: str, is_commodities_derivative: bool, issuer_lei: str, fisn: str, trading_venue_attrs: TradingVenueAttributes, notional_currency: str, technical_attributes: TechnicalAttributes | None, debt_attributes: DebtAttributes | None, derivative_attributes: DerivativeAttributes | None)

Bases: ReferenceData

Reference data for a financial instrument that has ceased being traded on a trading venue. Supports all the same properties and methods as ReferenceData.

cfi: str

The Classification of Financial Instruments code (ISO 10962) of the financial instrument.

debt_attributes: DebtAttributes | None

If the instrument is a debt instrument, certain debt-related attributes.

derivative_attributes: DerivativeAttributes | None

If the instrument is a derivative, certain derivative-related attributes.

fisn: str

The Financial Instrument Short Name (ISO 18774) for the financial instrument.

full_name: str

The full name of the financial instrument. This should give a good indication of the issuer and the particulars of the instrument.

is_commodities_derivative: bool

Whether the financial instrument falls within the definition of a “commodities derivative” under Article 2(1)(30) of Regulation (EU) No 600/2014.

isin: str

The International Securities Indentifier Number (ISO 6166) of the financial instrument.

issuer_lei: str

The Legal Entity identifier (ISO 17442) for the issuer. In certain cases, eg derivative instruments issued by the trading venue, this field will be populated with the trading venue operator’s LEI.

notional_currency: str

The currency in which the notional is denominated. For an interest rate or currency derivative contract, this will be the notional currency of leg 1, or the currency 1, of the pair. In the case of swaptions where the underlying swap is single currency, this will be the notional currency of the underlying swap. For swaptions where the underlying is multi-currency, this will be the notional currency of leg 1 of the swap.

technical_attributes: TechnicalAttributes | None

Technical attributes of the financial instrument.

trading_venue_attrs: TradingVenueAttributes

Data relating to the trading or admission to trading of the financial instrument on a trading venue.

class pyfirds.model.TradingVenueAttributes(trading_venue: str, requested_admission: bool, approval_date: datetime | None, request_date: datetime | None, admission_or_first_trade_date: datetime | None, termination_date: datetime | None)

Bases: XmlParsed

Data relating to the trading or admission to trading of a financial instrument on a trading venue.

admission_or_first_trade_date: datetime | None

Date and time of the admission to trading on the trading venue or the date and time when the instrument was first traded or an order or quote was first received by the trading venue.

approval_date: datetime | None

Date and time the issuer has approved admission to trading or trading in its financial instruments on a trading venue.

classmethod from_xml(elem: Element) → TradingVenueAttributes

Parse a TradgVnRltAttrbts XML element from FIRDS into a TradingVenueAttributes object.

Parameters:

elem – The XML element to parse. The tag should be {urn:iso:std:iso:20022:tech:xsd:auth.017.001.02}TradgVnRltAttrbts or equivalent.

request_date: datetime | None

Date and time of the request for admission to trading on the trading venue.

requested_admission: bool

Whether the issuer has requested or approved the trading or admission to trading of their financial instruments on a trading venue.

termination_date: datetime | None

Date and time when the instrument ceases to be traded or admitted to trading on the trading venue.

trading_venue: str

The Market Identifier Code (ISO 20022) for the trading venue or systemic internaliser. A segment MIC is used where available; otherwise, an operating MIC is used.

class pyfirds.model.UnderlyingBasket(isin: list[str] | None, issuer_lei: list[str] | None)

Bases: object

Reference data for a basket of assets which underlie a derivative instrument.

isin: list[str] | None

A list of ISINs of the financial instruments in the basket.

issuer_lei: list[str] | None

A list of LEIs of issuers in the basket.

class pyfirds.model.UnderlyingSingle(isin: str | None, index: str | Index | None, issuer_lei: str | None)

Bases: object

Reference data for a single asset which underlies a derivative instrument.

index: str | Index | None

The ISIN, or an Index object, representing the underlying index.

isin: str | None

The ISIN of the underlying financial instrument. - For ADRs, GDRs and similar instruments, the ISIN code of the financial instrument on which those instruments are based. For convertible bonds, the ISIN code of the instrument in which the bond can be converted. - For derivatives or other instruments which have an underlying, the underlying instrument ISIN code, when the underlying is admitted to trading, or traded on a trading venue. Where the underlying is a stock dividend, then the ISIN code of the related share entitling the underlying dividend shall be provided. - For Credit Default Swaps, the ISIN of the reference obligation shall be provided.

issuer_lei: str | None

The LEI of the underlying issuer.

pyfirds.xml_utils module

class pyfirds.xml_utils.XmlParsed

Bases: ABC

A base class for objects which can be parsed from an XML element.

abstract classmethod from_xml(elem: Element) → XmlParsed

Create an instance of the class from an appropriate XML element.

pyfirds.xml_utils.iterparse(file: str, tag_localname_to_cls: dict[str, Type[X]]) → Generator[X, None, dict[str, int]]

Parse an XML file iteratively, creating and yielding a ReferenceData (or subclass) object from each relevant node, and deleting nodes as we finish with them, to preserve memory. :param file: Path to the XML file to parse. :param tag_localname_to_cls: A dict mapping each XML tag name (after the namespace bit) to the class to be generated

from it (which should be a subclass of BaseXmlParsed or otherwise have an appropriate from_xml class method).

Returns:

A dict specifying the number of XML elements of each given tag encountered.

pyfirds.xml_utils.optional(elem: Element | None, cls: Type[X]) → X | None

pyfirds.xml_utils.parse_bool(elem: Element | None, optional: bool = False) → bool | None

Parse a true or false value in the FIRDS data to a bool.

Parameters:

• elem – XML element which contains the text value to parse, namely “true” or “false” as used in FIRDS.

• optional – If True and elem is None, return None. Useful where the data is optional in FIRDS.

pyfirds.xml_utils.parse_date(elem: Element | None, optional: bool = False) → date | None

Parse a date string in the FIRDS data to a date object.

Parameters:

• elem – XML element which contains the text value to parse, in ISO 8601 date format as used in FIRDS.

• optional – If True and elem is None, return None. Useful where the data is optional in FIRDS.

pyfirds.xml_utils.parse_datetime(elem: Element | None, optional: bool = False) → datetime | None

Parse a timestamp string in the FIRDS data to a datetime object.

Parameters:

• elem – XML element which contains the text value to parse, in ISO 8601 date format as used in FIRDS.

• optional – If True and elem is None, return None. Useful where the data is optional in FIRDS.

pyfirds.xml_utils.text_or_none(elem: Element | None, wrapper: Callable[[str], T] | Type[Enum] | None = None) → T | Enum | str | None

A convenience function that takes an XML element or None, and returns the element’s text if it exists or None otherwise.

Parameters:

• elem – The XML element or None.

• wrapper – A function or enum.Enum subtype to be used to process the XML element’s text. If a function, it will be called with the text and the result will be returned. If an Enum subtype, a member of the subtype with a name corresponding to the text will be returned.

Module contents