abaquant.marketdata.ticker¶

Import path: abaquant.marketdata.ticker

Domain: Provider-neutral market-data facades, normalized records, caching, and analytics.

Purpose¶

Lazy single-ticker applied market-data interface.

When to use it¶

Use this package to retrieve or inject quotes, price history, option chains, and financial statements while preserving a stable analytical interface.

Public objects¶

function: get_ticker — Create a lazy applied interface for one normalized ticker symbol.
class: MarketTicker — Lazy market-data facade with immutable identity and mutable session state. * MarketTicker.spot — Return the latest available spot-like quote supplied by the configured provider. * MarketTicker.dividend_yield — Return the provider dividend yield or the documented fallback. * MarketTicker.visualize — Return a market-price history figure for this ticker.
class: TickerHistory — Historical-price and realized-volatility namespace for a market ticker. * TickerHistory.prices — Return the normalized price data required by this interface. * TickerHistory.realized_volatility — Estimate trailing historical realized volatility from ticker prices.
class: TickerOptionAnalytics — Listed-option retrieval and model-analytics namespace for one ticker. * TickerOptionAnalytics.expirations — Return the available listed option expiration dates. * TickerOptionAnalytics.chain — Return a normalized listed option chain for one expiration. * TickerOptionAnalytics.analytics — Return listed-option-chain analytics for one expiration. * TickerOptionAnalytics.bsm — Price a European option under Black–Scholes–Merton using applied ticker inputs. * TickerOptionAnalytics.greeks — Return the model sensitivities implemented by this model. * TickerOptionAnalytics.listed_implied_volatility — Retrieve the listed implied volatility of the nearest available contract. * TickerOptionAnalytics.solve_implied_volatility — Solve the inverse Black–Scholes–Merton problem for implied volatility. * TickerOptionAnalytics.compare_models — Compare the option prices generated by the available pricing models.
class: TickerFundamentalData — Lazy fundamental-statement retrieval namespace for one ticker. * TickerFundamentalData.info — Return provider metadata normalized to a plain Python dictionary.
class: TickerCreditMetrics — Manual fundamental credit-proxy namespace for one ticker. * TickerCreditMetrics.assess — Evaluate manually supplied fundamentals for the ticker. * TickerCreditMetrics.assess_from_financials — Build provider-fed credit inputs from cached statements and assess them. * TickerCreditMetrics.proxy_metrics — Return flat manual credit-proxy metrics for convenient inspection. * TickerCreditMetrics.synthetic_score — Return the 0–100 heuristic synthetic credit-proxy score. * TickerCreditMetrics.altman_z_score — Return the traditional public-company Altman Z-score when available. * TickerCreditMetrics.piotroski_f_score — Return the complete nine-signal Piotroski F-score when available.

Detailed reference¶

Lazy single-ticker applied market-data interface.

Purpose¶

The module provides a MarketTicker object with namespaces for spot quotes, price history, listed options, and delegation to pure option-pricing functions.

Conventions¶

Symbols are normalized to uppercase. Volatility is always explicit: a decimal input, realized historical volatility, or listed implied volatility. Rates and yields are decimal annual quantities; maturity is in years.

Scope and limitations¶

No market request occurs at object construction. Provider values can be missing or stale, and model outputs are not investment recommendations.

References

[ 1 ] Black, F., and M. Scholes (1973), “The Pricing of Options and Corporate Liabilities”; Merton, R. C. (1973), “Theory of Rational Option Pricing”.

abaquant.marketdata.ticker.get_ticker(symbol, provider='yahoo', *, fundamentals_provider=None, sec_user_agent=None, sec_cik_by_symbol=None, financial_cache='memory', cache_directory=None)¶

Create a lazy applied interface for one normalized ticker symbol.

Parameters:

symbol (str) – Ticker symbol to normalize and query.
provider (str | MarketDataProvider, default='yahoo') – Provider name or object satisfying the market-data provider protocol.
fundamentals_provider (str | FinancialStatementProvider | None, default=None) – Optional provider used only for financial statements and credit-input construction. Use "sec" to retrieve SEC EDGAR/XBRL Company Facts while retaining the main provider for quotes, history, and options.
sec_user_agent (str | None, default=None) – Declared SEC request user agent when fundamentals_provider="sec". If omitted, the SEC provider reads ABAQUANT_SEC_USER_AGENT.
sec_cik_by_symbol (dict[str, str] | None, default=None) – Optional symbol-to-CIK mapping used by the SEC provider to avoid ticker lookup requests.
financial_cache ({'none', 'memory', 'disk'}, default='memory') – Financial-statement cache mode. Disk mode persists normalized statement snapshots between Python sessions.
cache_directory (str | None, default=None) – Optional directory used when financial_cache='disk'.

Returns:

Lazy ticker object. Constructing it does not fetch remote data.

Return type:

MarketTicker

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

class abaquant.marketdata.ticker.MarketTicker(identity, provider, configuration, session=None, financial_statement_provider=None)¶

Bases: object

Lazy market-data facade with immutable identity and mutable session state.

identity and configuration never change after construction. The separate session owns cache state, avoiding frozen-object mutation.

Create a ticker facade without making a provider request.

Parameters:

identity (TickerIdentity)
provider (MarketDataProvider)
configuration (TickerConfiguration)
session (TickerSession | None)
financial_statement_provider (FinancialStatementProvider | None)

spot()¶

Return the latest available spot-like quote supplied by the configured provider.

Returns:: Computed spot as a scalar in the units implied by the input values.
Return type:: float

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

dividend_yield(default=0.0)¶

Return the provider dividend yield or the documented fallback.

Parameters:: default (float, default=0.0) – Fallback value used when the provider does not expose a usable value.
Returns:: Computed dividend yield as a dimensionless decimal quantity.
Return type:: float

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

visualize(*, period='1y', start=None, end=None, auto_adjust=True, backend=None, theme=None, save_path=None, filename=None)¶

Return a market-price history figure for this ticker.

The method fetches history lazily through history.prices and returns a figure without invoking the backend display function.

Parameters:

period (str | None)
start (str | None)
end (str | None)
auto_adjust (bool)
backend (str | None)

class abaquant.marketdata.ticker.TickerHistory(ticker)¶

Bases: object

Historical-price and realized-volatility namespace for a market ticker.

Parameters:: ticker (MarketTicker)

ticker¶

Ticker facade supplying the normalized symbol and market-data provider.

Type:: MarketTicker

Notes

prices retrieves only historical data. realized_volatility derives annualized volatility from those prices and does not retrieve option-chain implied volatility.

prices(*, period='1y', start=None, end=None, auto_adjust=True)¶

Return the normalized price data required by this interface.

Parameters:

period (str | None, default='1y') – Provider history period label, such as "1y", when explicit dates are not supplied.
start (str | None, default=None) – Optional inclusive history start date.
end (str | None, default=None) – Optional exclusive or provider-defined history end date.
auto_adjust (bool, default=True) – Whether provider-adjusted price history is requested.

Returns:

Tabular result with the index, column schema, units, and missing-value treatment defined by the module convention.

Return type:

pandas.DataFrame

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

realized_volatility(*, period='1y', window=21, annualize=252)¶

Estimate trailing historical realized volatility from ticker prices.

Parameters:

period (str, default='1y') – Provider history period label, such as "1y", when explicit dates are not supplied.
window (int, default=21) – Rolling observation window length used for realized volatility.
annualize (int, default=252) – Annualization factor or flag accepted by the volatility routine.

Returns:

Computed realized volatility as a dimensionless decimal quantity.

Return type:

float

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

class abaquant.marketdata.ticker.TickerOptionAnalytics(ticker)¶

Bases: object

Listed-option retrieval and model-analytics namespace for one ticker.

Parameters:: ticker (MarketTicker)

ticker¶

Applied ticker object that owns this listed-options namespace.

Type:: MarketTicker

Notes

Construction is lazy where documented: provider data are requested only by retrieval methods, not by object creation.

expirations()¶

Return the available listed option expiration dates.

Returns:: Available labels in the order supplied by the provider or defined by the implementation.
Return type:: list[str]

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

chain(expiry, option_type=None)¶

Return a normalized listed option chain for one expiration.

Parameters:

expiry (str) – Option expiry date in ISO YYYY-MM-DD form.
option_type (OptionType | None, default=None) – Option type label, normally "call" or "put".

Returns:

Tabular result with the index, column schema, units, and missing-value treatment defined by the module convention.

Return type:

pandas.DataFrame

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

analytics(expiry)¶

Return listed-option-chain analytics for one expiration.

Parameters:: expiry (str) – Option expiry date in ISO YYYY-MM-DD form. The underlying raw chain is retrieved once and then reused by the returned analytics object.
Returns:: Provider-independent analytics object exposing IV smile, IV surface, skew, term structure, rich/cheap, open-interest, and visualization methods.
Return type:: OptionChainAnalytics

bsm(*, strike, risk_free_rate, maturity=None, expiry=None, volatility=None, option_type='call', dividend_yield=None)¶

Price a European option under Black–Scholes–Merton using applied ticker inputs.

Parameters:

strike (float) – Option strike price in the same currency units as the underlying.
risk_free_rate (float) – Annual risk-free rate in decimal units.
maturity (float | None, default=None) – Time to option expiry in years.
expiry (str | None, default=None) – Option expiry date in ISO YYYY-MM-DD form.
volatility (VolatilityInput, default=None) – Volatility input: a positive annualized decimal number, "realized", or "market" as documented by the applied interface.
option_type (OptionType, default='call') – Option type label, normally "call" or "put".
dividend_yield (float | None, default=None) – Continuous dividend yield in decimal annual units.

Returns:

Computed bsm as a scalar in the units implied by the input values.

Return type:

float

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

greeks(*, strike, risk_free_rate, maturity=None, expiry=None, volatility=None, option_type='call', dividend_yield=None)¶

Return the model sensitivities implemented by this model.

Parameters:

strike (float) – Option strike price in the same currency units as the underlying.
risk_free_rate (float) – Annual risk-free rate in decimal units.
maturity (float | None, default=None) – Time to option expiry in years.
expiry (str | None, default=None) – Option expiry date in ISO YYYY-MM-DD form.
volatility (VolatilityInput, default=None) – Volatility input: a positive annualized decimal number, "realized", or "market" as documented by the applied interface.
option_type (OptionType, default='call') – Option type label, normally "call" or "put".
dividend_yield (float | None, default=None) – Continuous dividend yield in decimal annual units.

Returns:

Named outputs of the greeks calculation.

Return type:

dict[str, float]

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

listed_implied_volatility(*, strike, expiry, option_type='call')¶

Retrieve the listed implied volatility of the nearest available contract.

Parameters:

strike (float) – Option strike price in the same currency units as the underlying.
expiry (str) – Option expiry date in ISO YYYY-MM-DD form.
option_type (OptionType, default='call') – Option type label, normally "call" or "put".

Returns:

Computed listed implied volatility as a dimensionless decimal quantity.

Return type:

float

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

solve_implied_volatility(*, market_price, strike, maturity=None, expiry=None, risk_free_rate=0.0, option_type='call', dividend_yield=None)¶

Solve the inverse Black–Scholes–Merton problem for implied volatility.

Parameters:

market_price (float) – Observed option premium in the same currency units as spot and strike.
strike (float) – Option strike price in the same currency units as the underlying.
maturity (float | None, default=None) – Time to option expiry in years.
expiry (str | None, default=None) – Option expiry date in ISO YYYY-MM-DD form.
risk_free_rate (float, default=0.0) – Annual risk-free rate in decimal units.
option_type (OptionType, default='call') – Option type label, normally "call" or "put".
dividend_yield (float | None, default=None) – Continuous dividend yield in decimal annual units.

Returns:

Computed solve implied volatility as a dimensionless decimal quantity.

Return type:

float

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

compare_models(*, strike, risk_free_rate, maturity=None, expiry=None, volatility=None, dividend_yield=None)¶

Compare the option prices generated by the available pricing models.

Parameters:

strike (float) – Option strike price in the same currency units as the underlying.
risk_free_rate (float) – Annual risk-free rate in decimal units.
maturity (float | None, default=None) – Time to option expiry in years.
expiry (str | None, default=None) – Option expiry date in ISO YYYY-MM-DD form.
volatility (VolatilityInput, default=None) – Volatility input: a positive annualized decimal number, "realized", or "market" as documented by the applied interface.
dividend_yield (float | None, default=None) – Continuous dividend yield in decimal annual units.

Returns:

Named outputs of the compare models calculation.

Return type:

dict[str, dict[str, float]]

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

class abaquant.marketdata.ticker.TickerFundamentalData(ticker)¶

Bases: object

Lazy fundamental-statement retrieval namespace for one ticker.

Parameters:: ticker (MarketTicker)

ticker¶

Applied ticker object that owns this fundamentals namespace.

Type:: MarketTicker

Notes

Construction is lazy where documented: provider data are requested only by retrieval methods, not by object creation.

info()¶

Return provider metadata normalized to a plain Python dictionary.

Returns:: Named outputs of the info calculation.
Return type:: dict

Notes

The applied layer normalizes provider data but cannot guarantee provider completeness, timeliness, or accuracy.

class abaquant.marketdata.ticker.TickerCreditMetrics(ticker)¶

Bases: object

Manual fundamental credit-proxy namespace for one ticker.

This namespace deliberately does not request fundamental statements from a provider in Phase 3. Callers create CreditAnalysisInputs from reconciled manual inputs and then evaluate it against the ticker. This keeps accounting definitions, reporting dates, and currency choices explicit.

Parameters:: ticker (MarketTicker)

ticker¶

Applied ticker object used only to associate a manual assessment with a normalized symbol. No provider call is made by this namespace.

Type:: MarketTicker

Notes

The reported synthetic score is a heuristic credit proxy, not a rating, default probability, CDS spread, or investment recommendation.

assess(inputs)¶

Evaluate manually supplied fundamentals for the ticker.

Parameters:: inputs (CreditAnalysisInputs) – Manual, internally consistent statement and market-value inputs. The object should use one currency, one consolidation perimeter, and comparable reporting periods.
Returns:: Full transparent assessment containing ratios, Altman Z-score, Piotroski signals, earnings and leverage diagnostics, a normalized synthetic proxy score, and mandatory limitations.
Return type:: CreditProxyAssessment

Notes

This method does not call the configured market-data provider.

assess_from_financials(*, period='annual', **kwargs)¶

Build provider-fed credit inputs from cached statements and assess them.

Parameters:

period ({"annual", "quarterly"}, default="annual") – Statement frequency used to construct the input bundle.
**kwargs (object) – Cache controls accepted by ticker.financials.credit_inputs.

Returns:

Transparent fundamental credit-proxy assessment.

Return type:

CreditProxyAssessment

Notes

This method may retrieve one three-statement snapshot when no allowed cache is available. It reuses the existing pure credit-risk model.

proxy_metrics(inputs)¶

Return flat manual credit-proxy metrics for convenient inspection.

Parameters:: inputs (CreditAnalysisInputs) – Manual fundamental inputs used by assess().
Returns:: Flat mapping with debt-to-equity, liquidity, coverage, cash-flow, Altman, Piotroski, earnings, leverage, and synthetic proxy fields. Missing required inputs are represented by None; they are never inferred from market data.
Return type:: dict[str, object]

synthetic_score(inputs)¶

Return the 0–100 heuristic synthetic credit-proxy score.

Parameters:: inputs (CreditAnalysisInputs) – Manual fundamental inputs used by assess().
Returns:: Coverage-normalized proxy score, or None when no score component can be computed. The value is not an agency rating or default probability.
Return type:: float or None

altman_z_score(inputs)¶

Return the traditional public-company Altman Z-score when available.

Parameters:: inputs (CreditAnalysisInputs) – Manual inputs including current assets, current liabilities, total assets, retained earnings, EBIT, market equity value, total liabilities, and revenue.
Returns:: Traditional five-factor Altman Z-score, or None if one or more required values are unavailable. This formulation is not a generic model for financial companies or every private issuer.
Return type:: float or None

piotroski_f_score(inputs)¶

Return the complete nine-signal Piotroski F-score when available.

Parameters:: inputs (CreditAnalysisInputs) – Manual current and prior-period accounting inputs. All nine signal inputs are required; partial F-scores are not reported.
Returns:: Integer from 0 through 9, or None when any required current or prior-period signal input is unavailable.
Return type:: int or None