equity-aggregator 0.1.1__py3-none-any.whl → 0.1.5__py3-none-any.whl

equity_aggregator/schemas/feeds/stock_analysis_feed_data.py

@@ -0,0 +1,107 @@
+# feeds/stock_analysis_feed_data.py
+
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from .feed_validators import required
+
+
+@required("name", "symbol")
+class StockAnalysisFeedData(BaseModel):
+    """
+    Represents a single Stock Analysis feed record, transforming and normalising
+    incoming fields to match the RawEquity model's expected attributes.
+
+    Args:
+        name (str): Company name, mapped from "n".
+        symbol (str): Equity symbol, mapped from "s".
+        cusip (str | None): CUSIP identifier, passed through unchanged.
+        isin (str | None): ISIN identifier, passed through unchanged.
+        market_cap (Decimal | None): Market capitalisation, mapped from "marketCap".
+        last_price (Decimal | None): Last known price, mapped from "price".
+        market_volume (Decimal | None): Trading volume, mapped from "volume".
+        trailing_pe (Decimal | None): Price-to-earnings ratio, mapped from "peRatio".
+        sector (str | None): Sector classification, mapped from "sector".
+        industry (str | None): Industry classification, mapped from "industry".
+        revenue (Decimal | None): Total revenue, mapped from "revenue".
+        free_cash_flow (Decimal | None): Free cash flow, mapped from "fcf".
+        return_on_equity (Decimal | None): Return on equity, mapped from "roe".
+        return_on_assets (Decimal | None): Return on assets, mapped from "roa".
+        ebitda (Decimal | None): EBITDA, mapped from "ebitda".
+
+    Returns:
+        StockAnalysisFeedData: An instance with fields normalised for RawEquity
+            validation.
+    """
+
+    # Fields exactly match RawEquity's signature
+    name: str
+    symbol: str
+    cusip: str | None
+    isin: str | None
+    market_cap: Decimal | None
+    last_price: Decimal | None
+    market_volume: Decimal | None
+    trailing_pe: Decimal | None
+    sector: str | None
+    industry: str | None
+    revenue: Decimal | None
+    free_cash_flow: Decimal | None
+    return_on_equity: Decimal | None
+    return_on_assets: Decimal | None
+    ebitda: Decimal | None
+
+    @model_validator(mode="before")
+    def _normalise_fields(self: dict[str, object]) -> dict[str, object]:
+        """
+        Normalise a raw Stock Analysis feed record into the flat schema expected
+        by RawEquity.
+
+        Args:
+            self (dict[str, object]): Raw payload containing Stock Analysis feed data.
+
+        Returns:
+            dict[str, object]: A new dictionary with renamed keys suitable for the
+                RawEquity schema.
+        """
+        return {
+            # s → RawEquity.symbol
+            "symbol": self.get("s"),
+            # n → RawEquity.name
+            "name": self.get("n"),
+            # cusip → RawEquity.cusip
+            "cusip": self.get("cusip"),
+            # isin → RawEquity.isin
+            "isin": self.get("isin"),
+            # no CIK, FIGI, MICS or currency in Stock Analysis feed, so omitting
+            # marketCap → RawEquity.market_cap
+            "market_cap": self.get("marketCap"),
+            # price → RawEquity.last_price
+            "last_price": self.get("price"),
+            # volume → RawEquity.market_volume
+            "market_volume": self.get("volume"),
+            # peRatio → RawEquity.trailing_pe
+            "trailing_pe": self.get("peRatio"),
+            # sector → RawEquity.sector
+            "sector": self.get("sector"),
+            # industry → RawEquity.industry
+            "industry": self.get("industry"),
+            # revenue → RawEquity.revenue
+            "revenue": self.get("revenue"),
+            # fcf → RawEquity.free_cash_flow
+            "free_cash_flow": self.get("fcf"),
+            # roe → RawEquity.return_on_equity
+            "return_on_equity": self.get("roe"),
+            # roa → RawEquity.return_on_assets
+            "return_on_assets": self.get("roa"),
+            # ebitda → RawEquity.ebitda
+            "ebitda": self.get("ebitda"),
+        }
+
+    model_config = ConfigDict(
+        # ignore extra fields in incoming Stock Analysis raw data feed
+        extra="ignore",
+        # defer strict type validation to RawEquity
+        strict=False,
+    )

equity_aggregator/schemas/feeds/tradingview_feed_data.py

@@ -0,0 +1,144 @@
+# feeds/tradingview_feed_data.py
+
+from decimal import Decimal, InvalidOperation
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from .feed_validators import required
+
+
+@required("name", "symbol")
+class TradingViewFeedData(BaseModel):
+    """
+    TradingViewFeedData represents a single record from the TradingView feed,
+    normalising and transforming incoming fields to align with the RawEquity model.
+
+    Args:
+        name (str): The equity name.
+        symbol (str): The equity symbol.
+        currency (str | None): The trading currency.
+        ...: Additional fields are mapped and normalised from the TradingView feed.
+
+    Returns:
+        TradingViewFeedData: Instance with fields normalised for RawEquity validation.
+    """
+
+    # Fields exactly match RawEquity's signature
+    name: str
+    symbol: str
+    currency: str | None
+    last_price: Decimal | None
+    market_cap: Decimal | None
+    market_volume: Decimal | None
+    dividend_yield: Decimal | None
+    shares_outstanding: Decimal | None
+    revenue: Decimal | None
+    ebitda: Decimal | None
+    trailing_pe: Decimal | None
+    price_to_book: Decimal | None
+    trailing_eps: Decimal | None
+    return_on_equity: Decimal | None
+    return_on_assets: Decimal | None
+    sector: str | None
+    industry: str | None
+
+    @model_validator(mode="before")
+    def _normalise_fields(self: dict[str, object]) -> dict[str, object]:
+        """
+        Normalise a raw TradingView feed record into the flat schema expected
+        by RawEquity.
+
+        TradingView provides data in an array format where field 'd' contains
+        19 elements, each at a specific index position corresponding to a
+        particular metric.
+
+        Args:
+            self (dict[str, object]): Raw payload containing TradingView feed data.
+
+        Returns:
+            dict[str, object]: A new dictionary with renamed keys suitable for the
+                RawEquity schema.
+        """
+        # Extract the data array
+        d = self.get("d", [])
+
+        return {
+            # d[0] → RawEquity.symbol (ticker)
+            "symbol": _extract_field(d, 0),
+            # d[1] → RawEquity.name (company name)
+            "name": _extract_field(d, 1),
+            # no ISIN, CUSIP, CIK, FIGI or MICS in TradingView feed,
+            # so omitting from model
+            # d[3] → RawEquity.currency
+            "currency": _extract_field(d, 3),
+            # d[4] → RawEquity.last_price (close price)
+            "last_price": _extract_field(d, 4),
+            # d[5] → RawEquity.market_cap
+            "market_cap": _extract_field(d, 5),
+            # d[6] → RawEquity.market_volume
+            "market_volume": _extract_field(d, 6),
+            # d[7] → RawEquity.dividend_yield (already in decimal format)
+            "dividend_yield": _extract_field(d, 7),
+            # d[9] → RawEquity.shares_outstanding
+            "shares_outstanding": _extract_field(d, 9),
+            # d[10] → RawEquity.revenue
+            "revenue": _extract_field(d, 10),
+            # d[11] → RawEquity.ebitda
+            "ebitda": _extract_field(d, 11),
+            # d[12] → RawEquity.trailing_pe
+            "trailing_pe": _extract_field(d, 12),
+            # d[13] → RawEquity.price_to_book
+            "price_to_book": _extract_field(d, 13),
+            # d[14] → RawEquity.trailing_eps
+            "trailing_eps": _extract_field(d, 14),
+            # d[15] → RawEquity.return_on_equity (convert from percentage to decimal)
+            "return_on_equity": _convert_percentage_to_decimal(_extract_field(d, 15)),
+            # d[16] → RawEquity.return_on_assets (convert from percentage to decimal)
+            "return_on_assets": _convert_percentage_to_decimal(_extract_field(d, 16)),
+            # d[17] → RawEquity.sector
+            "sector": _extract_field(d, 17),
+            # d[18] → RawEquity.industry
+            "industry": _extract_field(d, 18),
+        }
+
+    model_config = ConfigDict(
+        # ignore extra fields in incoming TradingView raw data feed
+        extra="ignore",
+        # defer strict type validation to RawEquity
+        strict=False,
+    )
+
+
+def _extract_field(data_array: list | None, index: int) -> object | None:
+    """
+    Safely extract a field from a data array at the given index.
+
+    Args:
+        data_array (list | None): The array containing field data.
+        index (int): The index position to extract.
+
+    Returns:
+        object | None: The field value at the index, or None if unavailable.
+    """
+    if not data_array or len(data_array) <= index:
+        return None
+    return data_array[index]
+
+
+def _convert_percentage_to_decimal(value: float | None) -> Decimal | None:
+    """
+    Convert a percentage value to decimal representation.
+
+    Args:
+        value (float | None): The percentage value (e.g., 20.6 for 20.6%).
+
+    Returns:
+        Decimal | None: The decimal representation (e.g., 0.206), or None if
+            input is None.
+    """
+    if value is None:
+        return None
+    try:
+        return Decimal(str(value)) / Decimal("100")
+    except (ValueError, TypeError, InvalidOperation):
+        return None

equity_aggregator/schemas/feeds/xetra_feed_data.py

@@ -51,7 +51,7 @@ class XetraFeedData(BaseModel):
         """
         return {
             "name": self.get("name"),
-            # wkn → maps to RawEquity.symbol
+            # wkn → RawEquity.symbol
             "symbol": self.get("wkn"),
             "isin": self.get("isin"),
             # no CUSIP, CIK or FIGI in Xetra feed, so omitting from model

equity_aggregator/schemas/feeds/yfinance_feed_data.py

@@ -62,6 +62,13 @@ class YFinanceFeedData(BaseModel):
         """
         Normalise a raw YFinance feed record into the flat schema expected by RawEquity.
 
+        This validator supports both Yahoo Finance endpoints:
+        - quote_summary_primary_url (i.e. '/v10/finance/quoteSummary/')
+        - quote_summary_fallback_url (i.e. '/v7/finance/quote')
+
+        Note:
+            The fallback endpoint lacks many financial metrics.
+
         Args:
             self (dict[str, object]): Raw payload containing YFinance feed data.
 
@@ -70,68 +77,73 @@ class YFinanceFeedData(BaseModel):
                 RawEquity schema.
         """
         return {
-            # longName/shortName → maps to RawEquity.name (camel-case for Quote Summary)
+            # longName/shortName → RawEquity.name
             "name": self.get("longName") or self.get("shortName"),
-            # underlyingSymbol → maps to RawEquity.symbol
+            # underlyingSymbol or symbol → RawEquity.symbol
             "symbol": self.get("underlyingSymbol") or self.get("symbol"),
             # no ISIN, CUSIP, CIK, FIGI or MICS in YFinance feed, so omitting from model
             "currency": self.get("currency"),
-            # currentPrice → maps to RawEquity.last_price
-            "last_price": self.get("currentPrice"),
-            # marketCap → maps to RawEquity.market_cap
+            # currentPrice or regularMarketPrice
+            # → RawEquity.last_price
+            "last_price": self.get("currentPrice") or self.get("regularMarketPrice"),
+            # marketCap → RawEquity.market_cap
             "market_cap": self.get("marketCap"),
-            # fiftyTwoWeekLow → maps to RawEquity.fifty_two_week_min
+            # fiftyTwoWeekLow → RawEquity.fifty_two_week_min
             "fifty_two_week_min": self.get("fiftyTwoWeekLow"),
-            # fiftyTwoWeekHigh → maps to RawEquity.fifty_two_week_max
+            # fiftyTwoWeekHigh → RawEquity.fifty_two_week_max
             "fifty_two_week_max": self.get("fiftyTwoWeekHigh"),
-            # dividendYield → maps to RawEquity.dividend_yield
+            # dividendYield → RawEquity.dividend_yield
             "dividend_yield": self.get("dividendYield"),
-            # volume → maps to RawEquity.market_volume
-            "market_volume": self.get("volume"),
-            # heldInsiders → maps to RawEquity.held_insiders
+            # volume or regularMarketVolume → RawEquity.market_volume
+            "market_volume": self.get("volume") or self.get("regularMarketVolume"),
+            # heldPercentInsiders → RawEquity.held_insiders
             "held_insiders": self.get("heldPercentInsiders"),
-            # heldInstitutions → maps to RawEquity.held_institutions
+            # heldPercentInstitutions → RawEquity.held_institutions
             "held_institutions": self.get("heldPercentInstitutions"),
-            # shortPercentOfFloat → maps to RawEquity.short_interest
+            # shortPercentOfFloat → RawEquity.short_interest
             "short_interest": self.get("shortPercentOfFloat"),
-            # floatShares → maps to RawEquity.share_float
+            # floatShares → RawEquity.share_float
             "share_float": self.get("floatShares"),
-            # sharesOutstanding → maps to RawEquity.shares_outstanding
+            # sharesOutstanding → RawEquity.shares_outstanding
             "shares_outstanding": self.get("sharesOutstanding"),
-            # revenuePerShare → maps to RawEquity.revenue_per_share
+            # revenuePerShare → RawEquity.revenue_per_share
             "revenue_per_share": self.get("revenuePerShare"),
-            # profitMargins → maps to RawEquity.profit_margin
+            # profitMargins → RawEquity.profit_margin
             "profit_margin": self.get("profitMargins"),
-            # grossMargins → maps to RawEquity.gross_margin
+            # grossMargins → RawEquity.gross_margin
             "gross_margin": self.get("grossMargins"),
-            # operatingMargins → maps to RawEquity.operating_margin
+            # operatingMargins → RawEquity.operating_margin
             "operating_margin": self.get("operatingMargins"),
-            # freeCashflow → maps to RawEquity.free_cash_flow
+            # freeCashflow → RawEquity.free_cash_flow
             "free_cash_flow": self.get("freeCashflow"),
-            # operatingCashflow → maps to RawEquity.operating_cash_flow
+            # operatingCashflow → RawEquity.operating_cash_flow
             "operating_cash_flow": self.get("operatingCashflow"),
-            # returnOnEquity → maps to RawEquity.return_on_equity
+            # returnOnEquity → RawEquity.return_on_equity
             "return_on_equity": self.get("returnOnEquity"),
-            # returnOnAssets → maps to RawEquity.return_on_assets
+            # returnOnAssets → RawEquity.return_on_assets
             "return_on_assets": self.get("returnOnAssets"),
-            # no one year performance, so omitting from model
-            # totalDebt → maps to RawEquity.total_debt
+            # 52WeekChange or fiftyTwoWeekChangePercent → RawEquity.performance_1_year
+            "performance_1_year": self.get("52WeekChange")
+            or self.get("fiftyTwoWeekChangePercent"),
+            # totalDebt → RawEquity.total_debt
             "total_debt": self.get("totalDebt"),
-            # totalRevenue → maps to RawEquity.revenue
+            # totalRevenue → RawEquity.revenue
             "revenue": self.get("totalRevenue"),
-            # ebitda → maps to RawEquity.ebitda
+            # ebitda → RawEquity.ebitda
             "ebitda": self.get("ebitda"),
-            # trailingPE → maps to RawEquity.trailing_pe
+            # trailingPE → RawEquity.trailing_pe
             "trailing_pe": self.get("trailingPE"),
-            # PriceToBook → maps to RawEquity.price_to_book
+            # priceToBook → RawEquity.price_to_book
             "price_to_book": self.get("priceToBook"),
-            # trailingEps → maps to RawEquity.trailing_eps
-            "trailing_eps": self.get("trailingEps"),
-            # recommendationKey → maps to RawEquity.analyst_rating
-            "analyst_rating": self.get("recommendationKey"),
-            # industry → maps to RawEquity.industry
+            # trailingEps or epsTrailingTwelveMonths → RawEquity.trailing_eps
+            "trailing_eps": self.get("trailingEps")
+            or self.get("epsTrailingTwelveMonths"),
+            # recommendationKey or averageAnalystRating → RawEquity.analyst_rating
+            "analyst_rating": self.get("recommendationKey")
+            or self.get("averageAnalystRating"),
+            # industry → RawEquity.industry
             "industry": self.get("industry"),
-            # sector → maps to RawEquity.sector
+            # sector → RawEquity.sector
             "sector": self.get("sector"),
         }
 

equity_aggregator/schemas/raw.py

@@ -13,6 +13,7 @@ from .types import (
     CUSIPStrOpt,
     FIGIStrOpt,
     ISINStrOpt,
+    LEIStrOpt,
     MICListOpt,
     SignedDecOpt,
     UnsignedDecOpt,
@@ -30,7 +31,7 @@ class RawEquity(BaseModel):
     Fields:
       - name: name of the equity
       - symbol: equity symbol
-      - isin, cusip, cik, share_class_figi: equity identifiers
+      - isin, cusip, cik, lei, share_class_figi: equity identifiers
       - mics: list of Market Identifier Codes (MICs)
       - currency: currency code (ISO-4217)
       - last_price: last known price of the equity
@@ -74,6 +75,7 @@ class RawEquity(BaseModel):
     isin: ISINStrOpt = None
     cusip: CUSIPStrOpt = None
     cik: CIKStrOpt = None
+    lei: LEIStrOpt = None
     share_class_figi: FIGIStrOpt = None
 
     # financial data, optional
@@ -91,7 +93,7 @@ class RawEquity(BaseModel):
     short_interest: UnsignedDecOpt = None
     share_float: UnsignedDecOpt = None
     shares_outstanding: UnsignedDecOpt = None
-    revenue_per_share: UnsignedDecOpt = None
+    revenue_per_share: SignedDecOpt = None
     profit_margin: SignedDecOpt = None
     gross_margin: SignedDecOpt = None
     operating_margin: SignedDecOpt = None
@@ -101,7 +103,7 @@ class RawEquity(BaseModel):
     return_on_assets: SignedDecOpt = None
     performance_1_year: SignedDecOpt = None
     total_debt: UnsignedDecOpt = None
-    revenue: UnsignedDecOpt = None
+    revenue: SignedDecOpt = None
     ebitda: SignedDecOpt = None
     trailing_pe: SignedDecOpt = None
     price_to_book: SignedDecOpt = None

equity_aggregator/schemas/types.py

@@ -13,6 +13,7 @@ from .validators import (
     to_cusip,
     to_figi,
     to_isin,
+    to_lei,
     to_mic,
     to_signed_decimal,
     to_unsigned_decimal,
@@ -56,6 +57,12 @@ CIKStrOpt = Annotated[
     BeforeValidator(to_cik),
 ]
 
+# Valid LEI must be exactly 20 characters: 18 alphanumeric + 2 check digits.
+LEIStrOpt = Annotated[
+    str | None,
+    BeforeValidator(to_lei),
+]
+
 # Valid FIGI must be exactly 12 characters and consist of uppercase letters and digits.
 FIGIStrOpt = Annotated[
     str | None,

equity_aggregator/schemas/validators.py

@@ -61,8 +61,7 @@ def to_signed_decimal(
 ) -> Decimal | None:
     """
     Converts a numeric string to a Decimal, accepting both EU and US formats.
-    Rejects negative values and returns None for invalid input. Raises a ValueError
-    with a field-specific message if conversion fails.
+    Returns None for invalid input.
 
     Args:
         value: The input value to convert, expected as a string or number.
@@ -70,18 +69,11 @@ def to_signed_decimal(
 
     Returns:
         Decimal or None: The converted Decimal value, or None if input is invalid.
-
-    Raises:
-        ValueError: If the input cannot be converted to Decimal, with field name in
-            the error message.
     """
     text = _parse_numeric_text(value)
     if text is None:
         return None
-    try:
-        return Decimal(text)
-    except (InvalidOperation, ValueError):
-        raise ValueError(f"invalid {info.field_name}: {value!r}") from None
+    return Decimal(text)
 
 
 def to_unsigned_decimal(
@@ -178,29 +170,29 @@ def to_cik(value: str | float | Decimal | None) -> str | None:
 
     - Accepts None or blank input and returns None.
     - Strips, collapses whitespace, and uppercases using to_upper (safe for digits).
-    - Ensures the result is exactly 10 digits.
+    - Accepts 1-10 digit input and left-pads with zeros to 10 digits.
 
     Args:
         value (str | float | Decimal | None): The input CIK value.
-        info (cs.ValidationInfo): Validation context with field metadata.
 
     Returns:
         str | None: The normalised 10-digit CIK, or None if input is blank.
 
     Raises:
-        ValueError: If the value does not match the CIK specification.
+        ValueError: If the value is not 1-10 digits.
     """
     cik = to_upper(value)
 
-    cik_pattern = re.compile(r"^[0-9]{10}$")
+    cik_pattern = r"^[0-9]{1,10}$"
+    cik_length = 10
 
     if cik is None:
         return None
 
-    if not cik_pattern.fullmatch(cik):
+    if not re.fullmatch(cik_pattern, cik):
         raise ValueError(f"invalid CIK code: {value!r}")
 
-    return cik
+    return cik.zfill(cik_length)
 
 
 def to_figi(value: str | float | Decimal | None) -> str | None:
@@ -265,6 +257,38 @@ def to_mic(value: str | float | Decimal | None) -> str | None:
     return mic
 
 
+def to_lei(value: str | float | Decimal | None) -> str | None:
+    """
+    Normalises and validates an LEI (Legal Entity Identifier, ISO 17442).
+
+    - Accepts None or blank input and returns None.
+    - Normalises input using to_upper (removes punctuation, collapses spaces,
+      converts to uppercase).
+    - Validates that the result matches the ISO-17442 20-character pattern:
+      18 alphanumeric characters followed by 2 check digits.
+
+    Args:
+        value (str | float | Decimal | None): The input LEI code.
+
+    Returns:
+        str | None: The normalised LEI code, or None if input is blank.
+
+    Raises:
+        ValueError: If the value does not match the LEI format.
+    """
+    lei = to_upper(value)
+
+    lei_pattern = r"^[A-Z0-9]{18}[0-9]{2}$"
+
+    if lei is None:
+        return None
+
+    if not re.fullmatch(lei_pattern, lei):
+        raise ValueError(f"invalid LEI code: {value!r}")
+
+    return lei
+
+
 def to_currency(value: str | float | Decimal | None) -> str | None:
     """
     Normalises and validates a currency code to ISO-4217 format (AAA).
@@ -323,25 +347,55 @@ def to_analyst_rating(value: str | float | Decimal | None) -> str | None:
 
 def _parse_numeric_text(value: str | float | Decimal | None) -> str | None:
     """
-    Normalises numeric text.
+    Normalises numeric text for Decimal conversion, rejecting invalid values.
+
+    - Returns None for None, blank input, or non-finite floats (NaN, Infinity).
+    - Uses Decimal parsing to validate strings, automatically rejecting
+      non-numeric text such as "n/a", "null", or "infinity".
+    - Normalises separators (e.g., "1,234.56" → "1234.56") before validation.
+    - Removes leading '+' for uniformity.
 
     Args:
-        value (str | float | Decimal): The value to normalise. Can be a string,
-            float, Decimal, or None.
+        value: The input value to normalise, expected as a string, float, Decimal,
+            or None.
 
     Returns:
-        str | None: The normalised numeric string, or None if input is None or blank.
-
-    - Returns None for None or blank input.
-    - Removes leading '+'.
-    - Delegates separator handling to _convert_separators.
+        str | None: The normalised numeric string ready for Decimal conversion,
+        or None if the input is invalid or non-finite.
     """
-    text = str(value).strip() if value is not None else ""
+    # Reject None or non-finite floats
+    if value is None or (
+        isinstance(value, float) and not -float("inf") < value < float("inf")
+    ):
+        return None
+
+    text = str(value).strip().lstrip("+")
     if not text:
         return None
 
-    text = text.lstrip("+")
-    return _convert_separators(text)
+    # Normalise separators and validate as a finite decimal
+    normalised_text = _convert_separators(text)
+    return normalised_text if _is_finite_decimal(normalised_text) else None
+
+
+def _is_finite_decimal(text: str) -> bool:
+    """
+    Validates whether a string represents a valid, finite decimal number.
+
+    - Returns True if the string can be converted to a finite Decimal.
+    - Returns False for non-numeric text (e.g., "n/a", "null").
+    - Returns False for non-finite values (e.g., "Infinity", "NaN").
+
+    Args:
+        text (str): The string to validate as a decimal number.
+
+    Returns:
+        bool: True if the string is a valid finite decimal, False otherwise.
+    """
+    try:
+        return Decimal(text).is_finite()
+    except InvalidOperation:
+        return False
 
 
 def _convert_separators(text: str) -> str:

equity_aggregator/storage/data_store.py

@@ -2,7 +2,7 @@
 
 import logging
 import sqlite3
-from collections.abc import Iterable, Iterator
+from collections.abc import Callable, Iterable, Iterator
 
 from equity_aggregator.schemas import CanonicalEquity
 
@@ -62,7 +62,9 @@ def _init_canonical_equities_table(conn: sqlite3.Connection) -> None:
     )
 
 
-def load_canonical_equities(refresh_fn: callable = None) -> list[CanonicalEquity]:
+def load_canonical_equities(
+    refresh_fn: Callable | None = None,
+) -> list[CanonicalEquity]:
     """
     Loads and rehydrates all CanonicalEquity objects from the database.
 
@@ -71,7 +73,7 @@ def load_canonical_equities(refresh_fn: callable = None) -> list[CanonicalEquity
     returns a list of CanonicalEquity instances.
 
     Args:
-        refresh_fn (callable, optional): Function to refresh database if stale.
+        refresh_fn (Callable | None, optional): Function to refresh database if stale.
 
     Returns:
         list[CanonicalEquity]: List of all rehydrated CanonicalEquity objects.