quantlab.universe.TiingoRosterFetcher#

class quantlab.universe.TiingoRosterFetcher[source]#

Bases: object

Base class for exchange-wide common-stock rosters built from Tiingo.

A roster here is the list of every stock ever listed on a set of exchanges, each with its listing and delisting dates. This class downloads Tiingo’s supported_tickers.csv directory, which lists every ticker the vendor has ever carried with those dates, and filters it down to one roster. Using the full directory rather than a feed of currently listed names keeps delisted names in the roster, which is what keeps the universe free of survivorship bias.

A subclass is data, not code: it sets EXCHANGE_FILTER, MIN_ROSTER_ROWS and CATEGORY (and optionally EXCLUDE_NON_COMMON_SECURITY_TYPES) and inherits fetch unchanged.

fetch filters on exact string tokens, so a vocabulary change in the vendor’s feed would yield zero rows without raising. MIN_ROSTER_ROWS turns that silent truncation into an error before the catalog can overwrite a good reference table with an empty one.

Examples

>>> class NyseUniverseFetcher(TiingoRosterFetcher):
...     EXCHANGE_FILTER = ("NYSE",)
...     MIN_ROSTER_ROWS = 1000
...     CATEGORY = "us_all"
>>> roster = NyseUniverseFetcher().fetch()  # downloads from Tiingo
>>> roster.columns
['symbol', 'start_date', 'end_date']

CATEGORY#: The catalog category this roster is stored under. Typed as the literal so an unknown token is a type error rather than a runtime surprise.

EXCHANGE_FILTER#: Exact exchange tokens kept by fetch.

EXCLUDE_NON_COMMON_SECURITY_TYPES = False#: When true, fetch also drops preferred shares and baby bonds (see _PREFERRED_SHARE_PATTERN and _BABY_BOND_PATTERN). Off by default so a roster’s contents never change unless its subclass opts in.

MIN_ROSTER_ROWS#: Minimum row count fetch accepts; fewer rows means the vendor’s token vocabulary drifted and the roster is refused.

fetch()[source]#

Download Tiingo’s ticker directory and return this roster as a frame.

The directory is filtered to EXCHANGE_FILTER, ASSET_TYPE and PRICE_CURRENCY; preferred shares and baby bonds are dropped when EXCLUDE_NON_COMMON_SECURITY_TYPES is set; and tickers that do not match TRADEABLE_TICKER_PATTERN are always dropped, because the acquisition layer would refuse to fetch them. The row-count floor is checked last, on the rows that will actually be persisted.

Returns:

pl.DataFrame: A frame with columns symbol, start_date and end_date, one row per exchange listing (a ticker that moved venue has two rows).

Raises:

ValueError: If fewer than MIN_ROSTER_ROWS rows survive the filter.

Examples

>>> roster = USEquityUniverseFetcher().fetch()  # downloads from Tiingo
>>> roster.columns
['symbol', 'start_date', 'end_date']