quantlab.acquisition.base.SourceDescriptor#

class quantlab.acquisition.base.SourceDescriptor(vendor, display_name, symbol_batch_cls, config_factory, capabilities, required_env, raw_tier_refresh=None)[source]#

Bases: object

Everything the registry knows about one vendor.

Facts about the vendor as a whole (credential names, display name, the default acquisition class and config factory) are stated once here. Everything that differs by market, frequency or data type is stored in capabilities. Exactly one descriptor is registered per vendor.

Parameters:

vendorVendor: The vendor’s short name, for example "tiingo".
display_namestr: A human-readable name for listings.
symbol_batch_clstype[SymbolBatchAcquisition] or None: The default class that downloads from this vendor. A capability may name a different one. None for a vendor whose raw tier is not a symbol-batched download (Sharadar’s whole tables, Massive’s daily files and REST pages): its raw_tier_refresh and scripts download it, and download_symbols() refuses it.
config_factorycallable or None: The default function that builds an AcquisitionConfig for this vendor, usually a functools.partial over the shared config factory with vendor filled in; None exactly when symbol_batch_cls is.
capabilitiestuple of Capability: Every (market, frequency, data_type) combination the vendor serves. Must not be empty.
required_envtuple of str: Names of the environment variables that hold the vendor’s credentials. Never a value, and never anything derived from one. They are written out here rather than read from symbol_batch_cls so that a test can check the two against each other.
raw_tier_refreshRawTierRefresh or None, default None: The function that keeps the vendor’s raw tier current from its watermarks (quantlab.acquisition.refresh), which registry.refresh_raw_tier calls; None for a vendor the daily update does not keep current.

Notes

symbol_batch_cls is a direct class reference, not a dotted path resolved at runtime. The cost is that quantlab.acquisition.registry, which imports every vendor module to register its descriptor, imports every vendor’s client library. The annotation names the SymbolBatchAcquisition base class, so the top of this module imports no vendor module, and each descriptor can be defined beside the client it describes.

Examples

>>> from quantlab.acquisition.base import DataSourceRegistry
>>> source = DataSourceRegistry.get("tiingo")
>>> source.display_name
'Tiingo EOD'
>>> source.required_env
('TIINGO_API_KEY',)
>>> [(c.market, c.frequency) for c in source.capabilities]
[('us_equity', '1d')]

capabilities_for(market, frequency, data_type=None)[source]#

Return every capability matching (market, frequency, data_type).

With data_type=None, a vendor that serves two data types at one (market, frequency) returns both. convert() relies on seeing all of them, so it can refuse an ambiguous request instead of picking one.

Parameters:

marketMarket: The requested market, for example "us_equity".
frequencyFrequency: The requested frequency, for example "1d".
data_typestr or None, default None: The requested data type, or None to match any data type.

Returns:

tuple of Capability: The matching capabilities in declaration order, or () when none match.

Examples

>>> source = DataSourceRegistry.get("alpaca")
>>> [c.data_type for c in source.capabilities_for("us_equity", "tick")]
['quotes', 'trades']
>>> DataSourceRegistry.get("tiingo").capabilities_for("us_equity", "tick")
()

config_factory_for(market, frequency, data_type=None)[source]#

Return the AcquisitionConfig factory that serves a request.

Resolved by the same rule as symbol_batch_cls_for.

Parameters:

marketMarket: The requested market, for example "us_equity".
frequencyFrequency: The requested frequency, for example "1d".
data_typestr or None, default None: The requested data type, or None to match any data type.

Returns:

callable: The function that builds the download’s AcquisitionConfig.

Raises:

ValueError: If two matching capabilities name different factories. Pass data_type to disambiguate.

Examples

>>> source = DataSourceRegistry.get("tiingo")
>>> source.config_factory_for("us_equity", "1d") is source.config_factory
True

supports(market, frequency, data_type=None)[source]#

Return whether this source serves (market, frequency, data_type).

This is the yes/no form of capabilities_for, which holds the matching rule.

Parameters:

marketMarket: The requested market, for example "us_equity".
frequencyFrequency: The requested frequency, for example "1d".
data_typestr or None, default None: The requested data type, or None to match any data type.

Returns:

bool: True if at least one capability matches.

Examples

>>> source = DataSourceRegistry.get("alpaca")
>>> source.supports("us_equity", "tick")
True
>>> source.supports("us_equity", "tick", "quotes")
True
>>> DataSourceRegistry.get("tiingo").supports("us_equity", "tick")
False

symbol_batch_cls_for(market, frequency, data_type=None)[source]#

Return the SymbolBatchAcquisition subclass that serves a request.

This is the matching capability’s symbol_batch_cls when it names one, and the descriptor’s default otherwise.

Parameters:

marketMarket: The requested market, for example "us_equity".
frequencyFrequency: The requested frequency, for example "1d".
data_typestr or None, default None: The requested data type, or None to match any data type.

Returns:

type[SymbolBatchAcquisition] or None: The class to construct for the download; None when the vendor has no symbol-batched download.

Raises:

ValueError: If two matching capabilities name different classes. Pass data_type to disambiguate.

Examples

>>> source = DataSourceRegistry.get("wrds")
>>> source.symbol_batch_cls_for("us_equity", "1d").__name__
'WrdsCrspDailyAcquisition'
>>> source.symbol_batch_cls_for("us_equity", "tick", "nbbo").__name__
'WrdsTaqNbboAcquisition'