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

equity_aggregator/adapters/data_sources/enrichment_feeds/yfinance/transport.py

@@ -0,0 +1,191 @@
+# yfinance/transport.py
+
+import asyncio
+import logging
+from collections.abc import Callable
+
+import httpx
+
+from equity_aggregator.adapters.data_sources._utils import make_client
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+# Type aliases
+OnResetFn = Callable[[], None]
+ClientFactory = Callable[[], httpx.AsyncClient]
+
+
+class HttpTransport:
+    """
+    Manages HTTP client lifecycle with automatic recovery on transport errors.
+
+    When a request fails due to transport errors (connection failures, protocol
+    errors, timeouts), the transport resets the client and retries. Uses
+    optimistic concurrency: if another task already reset the client, the retry
+    is "free" (doesn't consume budget).
+
+    Args:
+        client (httpx.AsyncClient | None): Optional pre-configured HTTP client.
+        on_reset (OnResetFn | None): Optional callback invoked after client reset.
+        client_factory (ClientFactory | None): Optional factory function to create
+            new clients during reset. Defaults to make_client.
+
+    Returns:
+        None
+    """
+
+    __slots__ = ("_client", "_client_factory", "_lock", "_on_reset", "_ready")
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient | None = None,
+        on_reset: OnResetFn | None = None,
+        *,
+        client_factory: ClientFactory | None = None,
+    ) -> None:
+        """
+        Initialise HttpTransport with optional client and reset callback.
+
+        Args:
+            client (httpx.AsyncClient | None): Optional pre-configured HTTP client.
+            on_reset (OnResetFn | None): Optional callback invoked after client reset.
+            client_factory (ClientFactory | None): Optional factory function to create
+                new clients during reset. Defaults to make_client.
+
+        Returns:
+            None
+        """
+        self._client_factory: ClientFactory = client_factory or make_client
+        self._client: httpx.AsyncClient = client or self._client_factory()
+        self._lock: asyncio.Lock = asyncio.Lock()
+        self._ready: asyncio.Event = asyncio.Event()
+        self._ready.set()
+        self._on_reset: OnResetFn | None = on_reset
+
+    async def aclose(self) -> None:
+        """
+        Close the underlying HTTP client.
+
+        Args:
+            None
+
+        Returns:
+            None
+        """
+        async with self._lock:
+            client = self._client
+        await client.aclose()
+
+    async def get(
+        self,
+        url: str,
+        params: dict[str, str],
+        *,
+        retries_remaining: int = 3,
+    ) -> httpx.Response:
+        """
+        Perform GET request with automatic client recovery on connection errors.
+
+        Uses optimistic retry: if the client was already reset by another task,
+        retries without consuming the retry budget. Only failures on a fresh
+        client decrement the budget.
+
+        Args:
+            url (str): The absolute URL to request.
+            params (dict[str, str]): Query parameters for the request.
+            retries_remaining (int): Number of retries left for fresh client failures.
+
+        Returns:
+            httpx.Response: The HTTP response.
+
+        Raises:
+            LookupError: If all retry attempts fail due to connection errors.
+        """
+        if retries_remaining <= 0:
+            raise LookupError("Connection failed after retries") from None
+
+        await self._ready.wait()
+
+        async with self._lock:
+            client, client_id = self._client, id(self._client)
+
+        try:
+            return await client.get(url, params=params)
+
+        except (httpx.TransportError, RuntimeError):
+            # Check if client was already reset by another task (returns True if stale)
+            was_stale = await self._handle_connection_error(client_id)
+
+            # Free retry if stale, otherwise decrement retry budget
+            next_retries = retries_remaining if was_stale else retries_remaining - 1
+
+            # Recursively retry request with updated retry budget
+            return await self.get(url, params, retries_remaining=next_retries)
+
+    async def _handle_connection_error(self, failed_client_id: int) -> bool:
+        """
+        Handle connection error, resetting client if necessary.
+
+        Checks if another task already reset the client (stale client).
+        If not, this task triggers the reset.
+
+        Args:
+            failed_client_id (int): The id() of the client that failed.
+
+        Returns:
+            bool: True if client was already reset (free retry),
+                  False if this task reset it (counts against budget).
+        """
+        async with self._lock:
+            already_reset = failed_client_id != id(self._client)
+
+        if already_reset:
+            return True
+
+        logger.debug(
+            "CLIENT_RESET: Transport error encountered, resetting YFinance client",
+        )
+        await self._reset()
+        return False
+
+    async def _reset(self) -> None:
+        """
+        Reset the HTTP client instance.
+
+        Creates a new client, verifies it can connect, then replaces the
+        old client. Invokes the on_reset callback if configured.
+
+        Args:
+            None
+
+        Returns:
+            None
+
+        Raises:
+            Exception: If new client creation or health check fails.
+        """
+        async with self._lock:
+            # Save old client before replacement, blocking new requests until ready
+            old_client = self._client
+            self._ready.clear()
+
+            try:
+                # Create and verify new client with health check
+                new_client = self._client_factory()
+                await new_client.get("https://finance.yahoo.com", timeout=5.0)
+
+            except Exception:
+                # Restore ready state if health check fails
+                self._ready.set()
+                raise
+
+            # Atomically swap in new client and unblock requests
+            self._client = new_client
+            self._ready.set()
+
+        # Clean up old client outside lock to avoid blocking
+        await old_client.aclose()
+
+        # Notify listeners of client reset
+        if self._on_reset is not None:
+            self._on_reset()

equity_aggregator/adapters/data_sources/enrichment_feeds/yfinance/yfinance.py

@@ -0,0 +1,413 @@
+# yfinance/yfinance.py
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from equity_aggregator.schemas import YFinanceFeedData
+from equity_aggregator.storage import (
+    load_cache_entry,
+    save_cache_entry,
+)
+
+from .api import (
+    get_quote_summary,
+    search_quotes,
+)
+from .config import FeedConfig
+from .ranking import filter_equities, rank_symbols
+from .session import YFSession
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def open_yfinance_feed(
+    *,
+    config: FeedConfig | None = None,
+) -> AsyncIterator["YFinanceFeed"]:
+    """
+    Context manager to create and close a YFinanceFeed.
+
+    Args:
+        config: Custom feed configuration; defaults to FeedConfig().
+
+    Yields:
+        YFinanceFeed with active session.
+    """
+    config = config or FeedConfig()
+    session = YFSession(config)
+    try:
+        yield YFinanceFeed(session)
+    finally:
+        await session.aclose()
+
+
+class YFinanceFeed:
+    """
+    Async Yahoo Finance feed with caching and fuzzy lookup.
+
+    Provides fetch_equity() to retrieve equity data by symbol, name, ISIN or CUSIP.
+
+    Attributes:
+        model: YFinanceFeedData schema class.
+        default_min_score: Default minimum fuzzy matching score threshold.
+    """
+
+    __slots__ = ("_session",)
+
+    model = YFinanceFeedData
+    default_min_score = 160
+
+    def __init__(self, session: YFSession) -> None:
+        """
+        Initialise with an active YFSession.
+
+        Args:
+            session: The Yahoo Finance HTTP session.
+        """
+        self._session = session
+
+    async def fetch_equity(
+        self,
+        *,
+        symbol: str,
+        name: str,
+        isin: str | None = None,
+        cusip: str | None = None,
+        **kwargs: object,
+    ) -> dict:
+        """
+        Fetch enriched equity data using symbol, name, ISIN, or CUSIP.
+
+        Steps:
+            1. Check cache for existing entry
+            2. Resolve candidate symbols via identifiers or search
+            3. Fetch and validate quote summary for first viable candidate
+            4. Cache and return result
+
+        Args:
+            symbol: Ticker symbol of the equity.
+            name: Full name of the equity.
+            isin: ISIN identifier, if available.
+            cusip: CUSIP identifier, if available.
+            **kwargs: Additional identifiers (ignored by Yahoo Finance).
+
+        Returns:
+            Enriched equity data.
+
+        Raises:
+            LookupError: If no matching equity data is found.
+        """
+        if record := load_cache_entry("yfinance_equities", symbol):
+            return record
+
+        try:
+            candidates = await self._resolve_candidates(
+                symbol=symbol,
+                name=name,
+                isin=isin,
+                cusip=cusip,
+            )
+
+            data = await self._fetch_first_valid_quote(candidates)
+
+            save_cache_entry("yfinance_equities", symbol, data)
+            return data
+
+        except LookupError:
+            raise LookupError(f"No enrichment data found for {symbol}.") from None
+
+    async def _resolve_candidates(
+        self,
+        *,
+        symbol: str,
+        name: str,
+        isin: str | None,
+        cusip: str | None,
+    ) -> list[str]:
+        """
+        Resolve candidate symbols using full fallback chain.
+
+        Resolution order:
+            1. ISIN lookup (if provided)
+            2. CUSIP lookup (if provided)
+            3. Name/symbol search (fallback)
+
+        Args:
+            symbol: Expected ticker symbol.
+            name: Expected company name.
+            isin: ISIN identifier or None.
+            cusip: CUSIP identifier or None.
+
+        Returns:
+            Ranked candidate symbols (best first).
+
+        Raises:
+            LookupError: If all resolution strategies fail.
+        """
+        identifiers = _build_identifier_sequence(isin, cusip)
+
+        for identifier in identifiers:
+            candidates = await self._resolve_by_identifier_safe(
+                identifier=identifier,
+                expected_name=name,
+                expected_symbol=symbol,
+            )
+            if candidates:
+                return candidates
+
+        return await self._resolve_by_search_terms(
+            query=name or symbol,
+            expected_name=name,
+            expected_symbol=symbol,
+        )
+
+    async def _resolve_by_identifier_safe(
+        self,
+        *,
+        identifier: str,
+        expected_name: str,
+        expected_symbol: str,
+    ) -> list[str]:
+        """
+        Attempt identifier resolution, returning empty list on failure.
+
+        Args:
+            identifier: ISIN or CUSIP to search.
+            expected_name: Expected company name.
+            expected_symbol: Expected ticker symbol.
+
+        Returns:
+            Ranked symbols or empty list on any failure.
+        """
+        try:
+            return await self._resolve_by_identifier(
+                identifier=identifier,
+                expected_name=expected_name,
+                expected_symbol=expected_symbol,
+            )
+        except LookupError:
+            return []
+
+    async def _resolve_by_identifier(
+        self,
+        *,
+        identifier: str,
+        expected_name: str,
+        expected_symbol: str,
+    ) -> list[str]:
+        """
+        Search by ISIN/CUSIP and return ranked candidate symbols.
+
+        Args:
+            identifier: ISIN or CUSIP to search.
+            expected_name: Expected company name for ranking.
+            expected_symbol: Expected ticker symbol for ranking.
+
+        Returns:
+            Ranked symbols (best first).
+
+        Raises:
+            LookupError: If search returns no results or no viable candidates.
+        """
+        quotes = await search_quotes(self._session, identifier)
+
+        if not quotes:
+            raise LookupError("Quote Search endpoint returned no results")
+
+        viable = filter_equities(quotes)
+
+        if not viable:
+            raise LookupError("No viable candidates found")
+
+        min_score = _select_identifier_min_score(len(viable), self.default_min_score)
+
+        return rank_symbols(
+            viable,
+            expected_name=expected_name,
+            expected_symbol=expected_symbol,
+            min_score=min_score,
+        )
+
+    async def _resolve_by_search_terms(
+        self,
+        *,
+        query: str,
+        expected_name: str,
+        expected_symbol: str,
+    ) -> list[str]:
+        """
+        Search by query and return ranked candidate symbols.
+
+        Tries query first, then expected_symbol if they differ.
+
+        Args:
+            query: Primary search query (typically company name or symbol).
+            expected_name: Expected company name for ranking.
+            expected_symbol: Expected ticker symbol for ranking and fallback search.
+
+        Returns:
+            Ranked symbols (best first).
+
+        Raises:
+            LookupError: If no viable candidates found.
+        """
+        terms = _build_search_terms(query, expected_symbol)
+
+        for term in terms:
+            quotes = await search_quotes(self._session, term)
+
+            if not quotes:
+                continue
+
+            ranked = _rank_viable_candidates(
+                quotes,
+                expected_name=expected_name,
+                expected_symbol=expected_symbol,
+                min_score=self.default_min_score,
+            )
+
+            if ranked:
+                return ranked
+
+        raise LookupError("No symbol candidates found")
+
+    async def _fetch_first_valid_quote(self, symbols: list[str]) -> dict:
+        """
+        Fetch and validate quote summary for first viable symbol.
+
+        Args:
+            symbols: Ranked candidate symbols to try.
+
+        Returns:
+            Validated quote summary data.
+
+        Raises:
+            LookupError: If all candidates fail validation.
+        """
+        for symbol in symbols:
+            data = await get_quote_summary(
+                self._session,
+                symbol,
+                modules=self._session.config.modules,
+            )
+            try:
+                return _validate_quote_summary(data, symbol)
+            except LookupError:
+                continue
+
+        raise LookupError("All candidates failed validation")
+
+
+def _build_identifier_sequence(
+    isin: str | None,
+    cusip: str | None,
+) -> tuple[str, ...]:
+    """
+    Return non-None identifiers in resolution priority order.
+
+    Args:
+        isin: ISIN identifier or None.
+        cusip: CUSIP identifier or None.
+
+    Returns:
+        Tuple of identifiers with None values filtered out.
+    """
+    return tuple(filter(None, (isin, cusip)))
+
+
+def _build_search_terms(query: str, symbol: str) -> tuple[str, ...]:
+    """
+    Return deduplicated search terms in priority order.
+
+    Args:
+        query: Primary search query (typically company name or symbol).
+        symbol: Ticker symbol (fallback search term).
+
+    Returns:
+        Tuple of unique search terms, query first.
+    """
+    return tuple(dict.fromkeys((query, symbol)))
+
+
+def _select_identifier_min_score(viable_count: int, default_min_score: int) -> int:
+    """
+    Select fuzzy match threshold based on result count.
+
+    Single-result identifier lookups use a reduced threshold (120) since
+    ISIN/CUSIP identifiers are globally unique. Multiple results use the
+    default threshold for stricter ranking.
+
+    Args:
+        viable_count: Number of viable candidates.
+        default_min_score: Default minimum score threshold.
+
+    Returns:
+        Minimum score threshold.
+    """
+    return 120 if viable_count == 1 else default_min_score
+
+
+def _validate_quote_summary(data: dict | None, symbol: str) -> dict:
+    """
+    Validate quote summary meets EQUITY criteria.
+
+    Checks:
+        1. Data is not empty
+        2. quoteType is "EQUITY"
+        3. longName or shortName is present
+
+    Args:
+        data: Quote summary data or None.
+        symbol: Symbol for error messages.
+
+    Returns:
+        Validated data dict.
+
+    Raises:
+        LookupError: If any validation check fails.
+    """
+    if not data:
+        raise LookupError(f"Quote summary returned no data for {symbol}")
+
+    quote_type = data.get("quoteType")
+    if quote_type != "EQUITY":
+        raise LookupError(
+            f"Symbol {symbol} has quoteType '{quote_type}', expected 'EQUITY'",
+        )
+
+    if not data.get("longName") and not data.get("shortName"):
+        raise LookupError(f"Symbol {symbol} has no company name")
+
+    return data
+
+
+def _rank_viable_candidates(
+    quotes: list[dict],
+    expected_name: str,
+    expected_symbol: str,
+    min_score: int,
+) -> list[str]:
+    """
+    Filter and rank quote candidates by fuzzy match quality.
+
+    Args:
+        quotes: Raw quotes from search API.
+        expected_name: Expected company name.
+        expected_symbol: Expected ticker symbol.
+        min_score: Minimum fuzzy score threshold.
+
+    Returns:
+        Ranked symbols (best first), empty if none viable.
+    """
+    viable = filter_equities(quotes)
+    if not viable:
+        return []
+
+    return rank_symbols(
+        viable,
+        expected_name=expected_name,
+        expected_symbol=expected_symbol,
+        min_score=min_score,
+    )

equity_aggregator/adapters/data_sources/reference_lookup/exchange_rate_api.py

@@ -30,9 +30,9 @@ async def retrieve_conversion_rates(
         dict[str, Decimal]: Mapping of currency codes to their Decimal conversion rates.
 
     Raises:
-        EnvironmentError: If the API key is missing.
+        OSError: If the API key is missing.
         httpx.HTTPError: For network or HTTP status errors.
-        Exception: For API-level failures or invalid responses.
+        ValueError: For API-level failures or invalid responses.
 
     Notes:
         Uses a cache to avoid unnecessary API calls. Cache is refreshed every 24 hours.
@@ -40,11 +40,8 @@ async def retrieve_conversion_rates(
     cached = load_cache(cache_key)
 
     if cached is not None:
-        logger.debug("Loaded exchange rates from cache.")
         return cached
 
-    logger.info("Fetching exchange rates from ExchangeRateApi API.")
-
     # fetch from API and validate
     api_key = _get_api_key()
     url = _build_url(api_key)
@@ -60,8 +57,7 @@ async def retrieve_conversion_rates(
         logger.info("Saved exchange rates to cache.")
         return rates
 
-    # If any error occurs on the request, treat it as fatal and exit
-    except Exception as error:
+    except (httpx.HTTPError, ValueError) as error:
         logger.fatal(
             "Fatal error while fetching exchange rates: %s",
             error,
@@ -84,7 +80,6 @@ def _get_api_key() -> str:
     if not key:
         logger.error("EXCHANGE_RATE_API_KEY environment variable is not set.")
         raise OSError("EXCHANGE_RATE_API_KEY environment variable is not set.")
-    logger.debug("Exchange Rate API key loaded from environment.")
     return key
 
 
@@ -150,8 +145,6 @@ async def _fetch_and_validate(client: httpx.AsyncClient, url: str) -> dict:
         logger.error(f"Unexpected error while fetching exchange rates: {e}")
         raise
 
-    logger.debug("Exchange rates response received and parsed.")
-
     _assert_success(payload)
     return payload
 
@@ -173,7 +166,7 @@ def _convert_rate(key: str, rate: float) -> tuple[str, Decimal]:
 
 def _assert_success(payload: dict) -> None:
     """
-    Checks if the API response indicates success; raises an Exception otherwise.
+    Checks if the API response indicates success; raises a ValueError otherwise.
 
     Args:
         payload (dict): The response payload from the Exchange Rate API. Must contain
@@ -181,7 +174,7 @@ def _assert_success(payload: dict) -> None:
             describing the error.
 
     Raises:
-        Exception: If the 'result' key is not 'success', raises an Exception with the
+        ValueError: If the 'result' key is not 'success', raises a ValueError with the
             error type from the payload or 'Unknown error' if not provided.
 
     Returns:
@@ -192,4 +185,4 @@ def _assert_success(payload: dict) -> None:
 
         logger.error(f"Exchange Rate API error: {error}")
 
-        raise Exception(f"Exchange Rate API error: {error}")
+        raise ValueError(f"Exchange Rate API error: {error}")