abaquant.marketdata.providers.sec¶

Import path: abaquant.marketdata.providers.sec

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

Purpose¶

SEC EDGAR/XBRL financial-statement provider with persistent JSON caching.

When to use it¶

This module belongs to the provider layer. Most users reach it through the market-data facades; custom integrations can implement or instantiate the documented contracts directly.

Public objects¶

class: SecCompanyFacts — Raw SEC Company Facts payload with resolved CIK provenance.
class: SecJsonCacheStore — Versioned, checksum-validated disk cache for SEC JSON payloads. * SecJsonCacheStore.ticker_mapping_path — Return the cache path for the SEC ticker-to-CIK mapping. * SecJsonCacheStore.company_facts_path — Return the cache path for one ticker’s Company Facts payload. * SecJsonCacheStore.load_ticker_mapping — Load the cached ticker-to-CIK mapping when present and fresh. * SecJsonCacheStore.save_ticker_mapping — Persist a normalized ticker-to-CIK mapping atomically. * SecJsonCacheStore.load_company_facts — Load a cached Company Facts payload when present and fresh. * SecJsonCacheStore.save_company_facts — Persist one Company Facts payload atomically. * SecJsonCacheStore.ticker_mapping_status — Return local ticker-mapping cache availability without network access. * SecJsonCacheStore.company_facts_status — Return local Company Facts cache availability without network access. * SecJsonCacheStore.remove_company_facts — Remove cached Company Facts payloads for one symbol.
class: SecXbrlProvider — Financial-statement provider backed by SEC EDGAR Company Facts. * SecXbrlProvider.company_facts — Return the SEC Company Facts payload for one ticker symbol. * SecXbrlProvider.sec_facts — Return the raw SEC Company Facts JSON payload for one symbol. * SecXbrlProvider.cik_for_symbol — Resolve a ticker symbol to a ten-digit SEC CIK using cache when possible. * SecXbrlProvider.income_statement — Return a normalized SEC-derived income-statement table. * SecXbrlProvider.balance_sheet — Return a normalized SEC-derived balance-sheet table. * SecXbrlProvider.cash_flow_statement — Return a normalized SEC-derived cash-flow statement table. * SecXbrlProvider.cache_status — Describe SEC raw-data cache availability without provider access. * SecXbrlProvider.clear_cache — Clear memory and disk Company Facts cache entries for one or all symbols.

Detailed reference¶

SEC EDGAR/XBRL financial-statement provider with persistent JSON caching.

Purpose¶

This module adapts the official SEC EDGAR JSON APIs into AbaQuant’s financial-statement provider interface. It resolves ticker symbols to CIKs, retrieves Company Facts data, caches raw SEC JSON payloads, and converts selected US-GAAP facts into canonical line-item labels consumed by the financial-statement and credit-proxy pipeline.

Conventions¶

The provider uses the SEC company_tickers.json file for symbol-to-CIK resolution and the companyfacts endpoint for extracted XBRL data. Statement DataFrames are indexed by AbaQuant’s provider-neutral line-item labels, such as "Total Assets" and "Net Income". Columns are SEC end dates sorted newest first. Disk cache entries are versioned and checksum-protected.

Scope and limitations¶

Only company-level, non-custom taxonomy facts exposed through the SEC Company Facts API are used. The provider does not parse individual filings, footnotes, custom company extensions, or management-adjusted non-GAAP measures. Missing facts remain missing rather than being imputed.

References

[1] U.S. Securities and Exchange Commission, EDGAR Application Programming: Interfaces and data.sec.gov Company Facts API documentation.

class abaquant.marketdata.providers.sec.SecCompanyFacts(symbol, cik, payload, retrieved_at_utc=None, provenance=None)¶

Bases: object

Raw SEC Company Facts payload with resolved CIK provenance.

Parameters:

symbol (str)
cik (str)
payload (dict[str, Any])
retrieved_at_utc (datetime | None)
provenance (DataProvenance | None)

symbol¶

Normalized ticker symbol used for CIK resolution.

Type:: str

cik¶

Ten-digit Central Index Key with leading zeros.

Type:: str

payload¶

JSON payload returned by the SEC Company Facts API.

Type:: dict[str, Any]

retrieved_at_utc¶

Retrieval or cache-write timestamp. None is allowed for deterministic in-memory fixtures that do not model retrieval time.

Type:: datetime | None, default=None

class abaquant.marketdata.providers.sec.SecJsonCacheStore(directory=None)¶

Bases: object

Versioned, checksum-validated disk cache for SEC JSON payloads.

The store persists the ticker-to-CIK mapping and per-company Company Facts payloads under one cache directory. Invalid, stale, or corrupt files are treated as cache misses so callers can safely fall back to a fresh SEC request.

Configure the root directory for SEC raw JSON cache files.

Parameters:: directory (str | Path | None)

property ticker_mapping_path: Path¶: Return the cache path for the SEC ticker-to-CIK mapping.

company_facts_path(symbol, cik)¶

Return the cache path for one ticker’s Company Facts payload.

Parameters:

symbol (str)
cik (str)

Return type:

Path

load_ticker_mapping(*, max_age_days=None)¶

Load the cached ticker-to-CIK mapping when present and fresh.

Parameters:: max_age_days (float | None)
Return type:: dict[str, str] | None

save_ticker_mapping(mapping)¶

Persist a normalized ticker-to-CIK mapping atomically.

Parameters:: mapping (dict[str, str])
Return type:: None

load_company_facts(symbol, cik, *, max_age_days=None)¶

Load a cached Company Facts payload when present and fresh.

Parameters:

symbol (str)
cik (str)
max_age_days (float | None)

Return type:

SecCompanyFacts | None

save_company_facts(facts)¶

Persist one Company Facts payload atomically.

Parameters:: facts (SecCompanyFacts)
Return type:: None

ticker_mapping_status(*, max_age_days=None)¶

Return local ticker-mapping cache availability without network access.

Parameters:: max_age_days (float | None)
Return type:: dict[str, object]

company_facts_status(symbol, cik=None, *, max_age_days=None)¶

Return local Company Facts cache availability without network access.

Parameters:

symbol (str)
cik (str | None)
max_age_days (float | None)

Return type:

dict[str, object]

remove_company_facts(symbol, cik=None)¶

Remove cached Company Facts payloads for one symbol.

Parameters:

symbol (str)
cik (str | None)

Return type:

None

class abaquant.marketdata.providers.sec.SecXbrlProvider(*, user_agent=None, cik_by_symbol=None, timeout_seconds=30.0, min_request_interval_seconds=0.11, cache_mode='memory', cache_directory=None, default_max_age_days=7.0)¶

Bases: object

Financial-statement provider backed by SEC EDGAR Company Facts.

Parameters:

user_agent (str | None, default=None) – Declared SEC request user agent. If omitted, the provider reads ABAQUANT_SEC_USER_AGENT and then falls back to a generic AbaQuant research user agent.
cik_by_symbol (dict[str, str] | None, default=None) – Optional preloaded symbol-to-CIK mapping used by deterministic tests or users who want to avoid the ticker lookup request.
timeout_seconds (float, default=30.0) – Request timeout for SEC JSON retrieval.
min_request_interval_seconds (float, default=0.11) – Minimum spacing between SEC requests. The default is slightly below the SEC fair-access maximum of 10 requests per second.
cache_mode ({'none', 'memory', 'disk'}, default='memory') – Raw SEC JSON cache policy. 'disk' persists ticker mappings and Company Facts payloads across Python sessions.
cache_directory (str | Path | None, default=None) – Root directory for persistent SEC raw JSON cache files. If omitted, ~/.cache/abaquant/sec is used.
default_max_age_days (float, default=7.0) – Default freshness threshold for cached SEC JSON payloads.

Create a provider without requesting SEC data.

company_facts(symbol, *, refresh_policy='if_stale', max_age_days=None)¶

Return the SEC Company Facts payload for one ticker symbol.

The method uses memory and optional disk cache before requesting the SEC endpoint. refresh_policy='cache_only' never performs a network request and fails if no eligible cached payload exists.

Parameters:

symbol (str)
refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])
max_age_days (float | None)

Return type:

SecCompanyFacts

sec_facts(symbol, *, refresh_policy='if_stale', max_age_days=None)¶

Return the raw SEC Company Facts JSON payload for one symbol.

Parameters:

symbol (str)
refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])
max_age_days (float | None)

Return type:

dict[str, Any]

cik_for_symbol(symbol, *, refresh_policy='if_stale', max_age_days=None)¶

Resolve a ticker symbol to a ten-digit SEC CIK using cache when possible.

Parameters:

symbol (str)
refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])
max_age_days (float | None)

Return type:

str

income_statement(symbol, *, period='annual', refresh_policy='if_stale', max_age_days=None)¶

Return a normalized SEC-derived income-statement table.

Parameters:

symbol (str)
period (Literal['annual', 'quarterly'])
refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])
max_age_days (float | None)

Return type:

DataFrame

balance_sheet(symbol, *, period='annual', refresh_policy='if_stale', max_age_days=None)¶

Return a normalized SEC-derived balance-sheet table.

Parameters:

symbol (str)
period (Literal['annual', 'quarterly'])
refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])
max_age_days (float | None)

Return type:

DataFrame

cash_flow_statement(symbol, *, period='annual', refresh_policy='if_stale', max_age_days=None)¶

Return a normalized SEC-derived cash-flow statement table.

Parameters:

symbol (str)
period (Literal['annual', 'quarterly'])
refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])
max_age_days (float | None)

Return type:

DataFrame

cache_status(symbol, *, max_age_days=None)¶

Describe SEC raw-data cache availability without provider access.

Parameters:

symbol (str)
max_age_days (float | None)

Return type:

dict[str, object]

clear_cache(symbol=None)¶

Clear memory and disk Company Facts cache entries for one or all symbols.

Parameters:: symbol (str | None)
Return type:: None