Alpha Vantage¶
Construct AlphaVantageClient directly or with from_env, then call methods on its
namespaced attributes. The namespace classes below document those methods.
Client¶
persistra.data.alphavantage.client.AlphaVantageClient
¶
A synchronous client for supported Alpha Vantage primary datasets.
_transport = transport
instance-attribute
¶
securities = SecuritiesNamespace(context)
instance-attribute
¶
quotes = QuotesNamespace(context)
instance-attribute
¶
indices = IndicesNamespace(context)
instance-attribute
¶
options = OptionsNamespace(context)
instance-attribute
¶
fx = PairNamespace(context, crypto=False)
instance-attribute
¶
crypto = PairNamespace(context, crypto=True)
instance-attribute
¶
commodities = CommoditiesNamespace(context)
instance-attribute
¶
economics = EconomicsNamespace(context)
instance-attribute
¶
reference = ReferenceNamespace(context)
instance-attribute
¶
__init__(api_key: str, *, base_url: str = 'https://www.alphavantage.co/query', cache_directory: str | Path | None = None, requests_per_minute: float = 150, timeout: float = 30, strict_schema: bool = False, cache_ages: Mapping[str, timedelta | None] | None = None, session: SessionLike | None = None, limiter: TokenRateLimiter | None = None) -> None
¶
close() -> None
¶
Close the client and its Persistra-owned HTTP session.
__enter__() -> Self
¶
__exit__(*_args: object) -> None
¶
from_env(*, base_url: str = 'https://www.alphavantage.co/query', cache_directory: str | Path | None = None, requests_per_minute: float = 150, timeout: float = 30, strict_schema: bool = False, cache_ages: Mapping[str, timedelta | None] | None = None, session: SessionLike | None = None, limiter: TokenRateLimiter | None = None) -> Self
classmethod
¶
Create a client from the Persistra Alpha Vantage API-key variable.
Security bars¶
persistra.data.alphavantage.securities.SecuritiesNamespace
¶
Acquire equity, ETF, and mutual-fund price bars.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
bars(symbol: str, *, kind: InstrumentKind, interval: str = 'daily', adjusted: bool = False, extended_hours: bool = False, outputsize: str = 'compact', month: str | None = None, entitlement: EntitlementMode = EntitlementMode.HISTORICAL, refresh: bool = False, offline: bool = False) -> BarSet
¶
Acquire one validated security bar result.
iter_intraday_months(symbol: str, months: list[str] | tuple[str, ...], *, kind: InstrumentKind, interval: str = '5min', adjusted: bool = False, extended_hours: bool = False, entitlement: EntitlementMode = EntitlementMode.HISTORICAL, refresh: bool = False, offline: bool = False) -> Iterator[BarSet]
¶
Yield one validated intraday result for each explicit provider month.
Quotes and top of book¶
persistra.data.alphavantage.quotes.QuotesNamespace
¶
Acquire latest, bulk, and top-of-book market observations.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
latest(symbol: str, *, kind: InstrumentKind = InstrumentKind.EQUITY, entitlement: EntitlementMode = EntitlementMode.HISTORICAL, refresh: bool = False, offline: bool = False) -> QuoteSet
¶
Acquire one latest quote.
bulk(symbols: list[str] | tuple[str, ...], *, kind: InstrumentKind = InstrumentKind.EQUITY, refresh: bool = False, offline: bool = False) -> QuoteSet
¶
Acquire sequential provider-sized quote chunks as one result.
top_of_book(symbols: list[str] | tuple[str, ...], *, kind: InstrumentKind = InstrumentKind.EQUITY, refresh: bool = False, offline: bool = False) -> TopOfBookSet
¶
Acquire sequential provider-sized top-of-book chunks as one result.
_bulk(operation: str, symbols: list[str] | tuple[str, ...], *, kind: InstrumentKind, refresh: bool, offline: bool, top_of_book: bool) -> QuoteSet | TopOfBookSet
¶
Indices¶
persistra.data.alphavantage.indices.IndicesNamespace
¶
Acquire market-index bars and the provider index catalog.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
bars(symbol: str, *, interval: str = 'daily', refresh: bool = False, offline: bool = False) -> BarSet
¶
Acquire daily, weekly, or monthly index bars.
catalog(*, refresh: bool = False, offline: bool = False) -> IndexCatalogResult
¶
Acquire the provider market-index catalog.
Historical options¶
persistra.data.alphavantage.options.OptionsNamespace
¶
Acquire historical option-chain observations.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
historical_chain(symbol: str, *, date: date | str | None = None, kind: InstrumentKind = InstrumentKind.EQUITY, refresh: bool = False, offline: bool = False) -> OptionChain
¶
Acquire one historical option chain without an underlying quote.
iter_historical_chains(symbol: str, *, start: date | str, end: date | str, kind: InstrumentKind = InstrumentKind.EQUITY, refresh: bool = False, offline: bool = False) -> Iterator[OptionChain]
¶
Yield successful chains for each calendar date in an inclusive range.
Fiat and crypto pairs¶
The client exposes separate instances of the same pair namespace as client.fx and
client.crypto.
persistra.data.alphavantage.pairs.PairNamespace
¶
Acquire explicit fiat or crypto pair observations.
_context = context
instance-attribute
¶
_crypto = crypto
instance-attribute
¶
__init__(context: AdapterContext, *, crypto: bool) -> None
¶
rate(base: str, quote: str, *, refresh: bool = False, offline: bool = False) -> ExchangeRateQuote
¶
Acquire one current exchange-rate quote.
bars(base: str, quote: str, *, interval: str = 'daily', outputsize: str = 'compact', refresh: bool = False, offline: bool = False) -> BarSet
¶
Acquire one native pair bar series.
Commodities¶
persistra.data.alphavantage.commodities.CommoditiesNamespace
¶
Acquire commodity spot quotes and scalar series.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
spot(metal: str, *, refresh: bool = False, offline: bool = False) -> CommoditySpotQuote
¶
Acquire one current gold or silver spot quote.
series(commodity: str, *, frequency: str, metal: str | None = None, refresh: bool = False, offline: bool = False) -> SeriesSet
¶
Acquire one native commodity scalar series.
Economics¶
persistra.data.alphavantage.economics.EconomicsNamespace
¶
Acquire primary economic and interest-rate series.
Reference data¶
persistra.data.alphavantage.reference.ReferenceNamespace
¶
Acquire provider search matches and market status.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
search(keywords: str, *, refresh: bool = False, offline: bool = False) -> InstrumentSearchResult
¶
Search provider symbols without inferring canonical identity.
market_status(*, refresh: bool = False, offline: bool = False) -> MarketStatusResult
¶
Acquire market status without inferring exchange calendars.
Transport and rate limiting¶
Most applications should use the configured client. These classes are public for custom transport setup, controlled tests, and integration diagnostics.
persistra.data.alphavantage.transport.TokenRateLimiter
¶
A thread-safe request-token limiter with a smoothed default burst.
rate = requests_per_minute / 60
instance-attribute
¶
capacity = capacity
instance-attribute
¶
_tokens = capacity
instance-attribute
¶
_updated = clock()
instance-attribute
¶
_clock = clock
instance-attribute
¶
_delay = delay
instance-attribute
¶
_lock = threading.Lock()
instance-attribute
¶
__init__(requests_per_minute: float = 150, *, capacity: float = 1, clock: Callable[[], float] = time.monotonic, delay: Callable[[float], None] = time.sleep) -> None
¶
acquire() -> None
¶
Wait until one request token is available.
persistra.data.alphavantage.transport.AlphaVantageTransport
¶
Rate-controlled transport with cache, retry, and envelope classification.
api_key = api_key
instance-attribute
¶
base_url = base_url
instance-attribute
¶
session = session if session is not None else cast('SessionLike', owned_session)
instance-attribute
¶
_owned_session = owned_session
instance-attribute
¶
_closed = False
instance-attribute
¶
cache = cache
instance-attribute
¶
limiter = limiter or TokenRateLimiter()
instance-attribute
¶
timeout = timeout
instance-attribute
¶
clock = clock or (lambda: datetime.now(UTC))
instance-attribute
¶
delay = delay
instance-attribute
¶
random_source = random_source
instance-attribute
¶
retries = retries
instance-attribute
¶
__init__(api_key: str, *, base_url: str = 'https://www.alphavantage.co/query', session: SessionLike | None = None, cache: RawResponseCache | None = None, limiter: TokenRateLimiter | None = None, timeout: float = 30, clock: Callable[[], datetime] | None = None, delay: Callable[[float], None] = time.sleep, random_source: Callable[[], float] = random.random, retries: int = 3) -> None
¶
close() -> None
¶
Close the transport and its Persistra-owned HTTP session.
request(operation: str, parameters: dict[str, Any], *, cache_age: timedelta | None = timedelta(hours=24), refresh: bool = False, offline: bool = False) -> RawResponse
¶
Return classified raw bytes for one provider operation.