abaquant.marketdata.financials.facade

Import path: abaquant.marketdata.financials.facade

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

Purpose

Small public facade for cached financial statement retrieval.

When to use it

This module participates in the financial-statement pipeline: provider response, normalization, cache/repository coordination, canonical line-item resolution, and analytical input construction.

Public objects

  • class: FinancialStatements — Public financial-statement facade with source-aware repositories. * FinancialStatements.snapshot — Return one repository-managed statement snapshot. * FinancialStatements.refresh — Refresh a period when forced or when its cache is stale. * FinancialStatements.cache_status — Describe cache availability without a provider request. * FinancialStatements.clear_cache — Remove selected cache entries from memory and disk. * FinancialStatements.sec_company_facts — Return raw SEC Company Facts with attached provenance metadata. * FinancialStatements.sec_facts — Return raw SEC Company Facts JSON for the configured SEC source. * FinancialStatements.sec_cache_status — Describe SEC raw-data cache availability without a provider request. * FinancialStatements.clear_sec_cache — Clear SEC raw Company Facts cache entries for this ticker when supported. * FinancialStatements.income_statement — Return a defensive copy of the normalized income statement. * FinancialStatements.balance_sheet — Return a defensive copy of the normalized balance sheet. * FinancialStatements.cash_flow_statement — Return a defensive copy of the normalized cash-flow statement. * FinancialStatements.get_line_item_details — Return a resolved line item with provider-label provenance. * FinancialStatements.get_line_item — Return a resolved scalar value or ‘’None’’ when unavailable. * FinancialStatements.credit_inputs — Build grouped credit-analysis inputs from one snapshot. * FinancialStatements.visualize — Return a figure for the latest column of one cached statement table. * FinancialStatements.total_debt — Return the latest resolved ‘total_debt’ statement value. * FinancialStatements.total_equity — Return the latest resolved ‘total_equity’ statement value. * FinancialStatements.current_assets — Return the latest resolved ‘current_assets’ statement value. * FinancialStatements.inventory — Return the latest resolved ‘inventory’ statement value. * FinancialStatements.current_liabilities — Return the latest resolved ‘current_liabilities’ statement value. * FinancialStatements.cash_and_cash_equivalents — Return the latest resolved ‘cash_and_cash_equivalents’ statement value. * FinancialStatements.ebit — Return the latest resolved ‘ebit’ statement value. * FinancialStatements.ebitda — Return the latest resolved ‘ebitda’ statement value. * FinancialStatements.interest_expense — Return the latest resolved ‘interest_expense’ statement value. * FinancialStatements.operating_cash_flow — Return the latest resolved ‘operating_cash_flow’ statement value. * FinancialStatements.total_assets — Return the latest resolved ‘total_assets’ statement value. * FinancialStatements.total_liabilities — Return the latest resolved ‘total_liabilities’ statement value. * FinancialStatements.retained_earnings — Return the latest resolved ‘retained_earnings’ statement value. * FinancialStatements.revenue — Return the latest resolved ‘revenue’ statement value. * FinancialStatements.net_income — Return the latest resolved ‘net_income’ statement value. * FinancialStatements.long_term_debt — Return the latest resolved ‘long_term_debt’ statement value. * FinancialStatements.shares_outstanding — Return the latest resolved ‘shares_outstanding’ statement value. * FinancialStatements.gross_profit — Return the latest resolved ‘gross_profit’ statement value.

Detailed reference

Small public facade for cached financial statement retrieval.

class abaquant.marketdata.financials.facade.FinancialStatements(ticker, repository=None, *, repositories=None, default_source=None)

Bases: object

Public financial-statement facade with source-aware repositories.

The facade keeps user-facing calls stable while delegating retrieval and caching to one repository per configured source. A ticker can therefore use Yahoo for quotes and SEC XBRL for fundamentals without mixing provider responsibilities.

Attach one or more statement repositories to the presentation facade.

Parameters:
snapshot(*, period='annual', refresh_policy='if_stale', max_age_days=None, source=None)

Return one repository-managed statement snapshot.

Parameters:

  • period (Literal['annual', 'quarterly'])

  • refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])

  • max_age_days (float | None)

  • source (str | None)

refresh(*, period='annual', force=False, source=None)

Refresh a period when forced or when its cache is stale.

Parameters:

  • period (Literal['annual', 'quarterly'])

  • force (bool)

  • source (str | None)

cache_status(*, period='annual', source=None)

Describe cache availability without a provider request.

Parameters:

source (str | None)

clear_cache(*, period=None, source=None)

Remove selected cache entries from memory and disk.

Parameters:

source (str | None)

sec_company_facts(*, source='sec', refresh_policy='if_stale', max_age_days=None)

Return raw SEC Company Facts with attached provenance metadata.

Returns:

Immutable wrapper exposing payload and provenance.

Return type:

SecCompanyFacts

Parameters:

  • source (str)

  • refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])

  • max_age_days (float | None)

sec_facts(*, source='sec', refresh_policy='if_stale', max_age_days=None)

Return raw SEC Company Facts JSON for the configured SEC source.

The SEC provider honors the same refresh policies used by normalized statement snapshots. With disk caching enabled, repeated Python sessions can reuse cached Company Facts payloads without a new SEC request.

Parameters:

  • source (str)

  • refresh_policy (Literal['cache_only', 'if_missing', 'if_stale', 'refresh'])

  • max_age_days (float | None)

sec_cache_status(*, source='sec', max_age_days=None)

Describe SEC raw-data cache availability without a provider request.

Parameters:

  • source (str)

  • max_age_days (float | None)

clear_sec_cache(*, source='sec')

Clear SEC raw Company Facts cache entries for this ticker when supported.

Parameters:

source (str)

income_statement(*, period='annual', **kwargs)

Return a defensive copy of the normalized income statement.

balance_sheet(*, period='annual', **kwargs)

Return a defensive copy of the normalized balance sheet.

cash_flow_statement(*, period='annual', **kwargs)

Return a defensive copy of the normalized cash-flow statement.

get_line_item_details(canonical_name, *, period='annual', **kwargs)

Return a resolved line item with provider-label provenance.

get_line_item(canonical_name, *, period='annual', **kwargs)

Return a resolved scalar value or None when unavailable.

credit_inputs(*, period='annual', **kwargs)

Build grouped credit-analysis inputs from one snapshot.

visualize(*, statement='balance_sheet', period='annual', backend=None, theme=None, save_path=None, filename=None, **kwargs)

Return a figure for the latest column of one cached statement table.

Parameters:

  • statement (str)

  • period (Literal['annual', 'quarterly'])

  • backend (str | None)

total_debt(*, period='annual', **kwargs)

Return the latest resolved total_debt statement value.

total_equity(*, period='annual', **kwargs)

Return the latest resolved total_equity statement value.

current_assets(*, period='annual', **kwargs)

Return the latest resolved current_assets statement value.

inventory(*, period='annual', **kwargs)

Return the latest resolved inventory statement value.

current_liabilities(*, period='annual', **kwargs)

Return the latest resolved current_liabilities statement value.

cash_and_cash_equivalents(*, period='annual', **kwargs)

Return the latest resolved cash_and_cash_equivalents statement value.

ebit(*, period='annual', **kwargs)

Return the latest resolved ebit statement value.

ebitda(*, period='annual', **kwargs)

Return the latest resolved ebitda statement value.

interest_expense(*, period='annual', **kwargs)

Return the latest resolved interest_expense statement value.

operating_cash_flow(*, period='annual', **kwargs)

Return the latest resolved operating_cash_flow statement value.

total_assets(*, period='annual', **kwargs)

Return the latest resolved total_assets statement value.

total_liabilities(*, period='annual', **kwargs)

Return the latest resolved total_liabilities statement value.

retained_earnings(*, period='annual', **kwargs)

Return the latest resolved retained_earnings statement value.

revenue(*, period='annual', **kwargs)

Return the latest resolved revenue statement value.

net_income(*, period='annual', **kwargs)

Return the latest resolved net_income statement value.

long_term_debt(*, period='annual', **kwargs)

Return the latest resolved long_term_debt statement value.

shares_outstanding(*, period='annual', **kwargs)

Return the latest resolved shares_outstanding statement value.

gross_profit(*, period='annual', **kwargs)

Return the latest resolved gross_profit statement value.