alphadataforge 0.1.0__py3-none-any.whl

alphadataforge/providers/tiingo_fetcher.py

@@ -0,0 +1,312 @@
+import pandas as pd
+import os
+from typing import Optional, List, Dict, Any
+from tiingo import TiingoClient
+from ..core.base_fetcher import BaseDataFetcher
+from ..core.exceptions import ProviderConfigurationError
+from ..config.settings import config
+from ..utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class TiingoFetcher(BaseDataFetcher):
+    """
+    Data fetcher for Tiingo API using the official tiingo-python client.
+    Supports: stock price, news, fundamentals, and crypto.
+
+    Requires TIINGO_API_KEY environment variable to be set.
+    Free tier: 500 requests/hr, EOD prices + news headlines.
+    """
+
+    def __init__(self, api_key: Optional[str] = None):
+        super().__init__()
+        self.api_key = api_key or config.TIINGO_API_KEY
+        self._client = None
+
+    @property
+    def client(self) -> TiingoClient:
+        if not self._client:
+            if not self.api_key:
+                raise ProviderConfigurationError(
+                    "TIINGO_API_KEY is not set. Please set it in your .env file or environment variables."
+                )
+            # Temporarily inject key to OS env for TiingoClient
+            os.environ['TIINGO_API_KEY'] = self.api_key
+            self._client = TiingoClient({'session': True})
+        return self._client
+        
+
+    # ------------------------------------------------------------------
+    # Required by BaseDataFetcher — fetches PRICE for 1 symbol
+    # ------------------------------------------------------------------
+    def fetch_single(
+        self,
+        symbol: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        frequency: str = "daily",
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch EOD price data for a single stock/ETF symbol.
+
+        Args:
+            symbol:     Ticker symbol, e.g. "AAPL"
+            start_date: "YYYY-MM-DD" (inclusive)
+            end_date:   "YYYY-MM-DD" (inclusive)
+            frequency:  "daily" | "weekly" | "monthly" | "annually" | "1min" | "5min" etc.
+            **kwargs:   Any extra params forwarded to TiingoClient.get_dataframe()
+        
+        Raises:
+            ValueError: If symbol or date inputs are invalid.
+            Exception: If Tiingo API call fails (network, auth, etc.)
+        """
+        logger.info("Fetching price for %s (%s)...", symbol, frequency)
+        self._validate_inputs(symbol, start_date, end_date)
+        
+        # Pop adjusted if present, since Tiingo returns adj natively
+        kwargs.pop("adjusted", None)
+        
+        df = self.client.get_dataframe(
+            tickers=symbol,
+            startDate=start_date,
+            endDate=end_date,
+            frequency=frequency,
+            **kwargs
+        )
+        
+        if df.empty:
+            logger.warning("Tiingo returned empty DataFrame for %s. Check if the ticker is valid.", symbol)
+
+        return self._normalize_ohlcv(df)
+
+    # ------------------------------------------------------------------
+    # Fetch price for multiple symbols at once
+    # ------------------------------------------------------------------
+    def fetch_multiple(
+        self,
+        symbols: List[str],
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        frequency: str = "daily",
+        metric_name: str = "adjClose",
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch price data for multiple symbols.
+        Uses tiingo's built-in batch method when metric_name is specified,
+        which is more efficient than looping.
+        
+        Symbols that fail or return empty data are logged and excluded.
+
+        Returns: {symbol: DataFrame}  (only successfully fetched symbols)
+        """
+        logger.info("Batch fetching %d symbols...", len(symbols))
+        if not symbols:
+            return {}
+
+        try:
+            combined: pd.DataFrame = self.client.get_dataframe(
+                symbols,
+                startDate=start_date,
+                endDate=end_date,
+                frequency=frequency,
+                metric_name=metric_name,
+                **kwargs
+            )
+        except Exception as e:
+            logger.error(
+                "Tiingo batch fetch failed entirely for %s symbols: %s. "
+                "Falling back to per-symbol fetch.", len(symbols), e
+            )
+            # Fallback: use base class loop so partial results are still returned
+            return super().fetch_multiple(
+                symbols, start_date=start_date, end_date=end_date,
+                frequency=frequency, **kwargs
+            )
+
+        # When passing a list, tiingo returns a DataFrame with symbol columns
+        results = {}
+        for sym in symbols:
+            if sym not in combined.columns:
+                logger.warning("Symbol %s not found in Tiingo batch result — excluding.", sym)
+                continue
+            normalized = self._normalize_ohlcv(combined[[sym]].rename(columns={sym: metric_name}))
+            if normalized.empty:
+                logger.warning("Symbol %s returned empty data — excluding.", sym)
+                continue
+            results[sym] = normalized
+
+        succeeded = len(results)
+        failed = len(symbols) - succeeded
+        if failed > 0:
+            logger.warning(
+                "Tiingo batch fetch finished: %d/%d succeeded, %d excluded.",
+                succeeded, len(symbols), failed,
+            )
+        else:
+            logger.info("Tiingo batch fetch finished: all %d symbols succeeded.", succeeded)
+
+        return results
+
+    # ------------------------------------------------------------------
+    #   News — curated financial news with ticker + tag filtering
+    # ------------------------------------------------------------------
+    def fetch_news(
+        self,
+        tickers: Optional[List[str]] = None,
+        tags: Optional[List[str]] = None,
+        sources: Optional[List[str]] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        limit: int = 100,
+    ) -> pd.DataFrame:
+        """
+        Fetch financial news articles from Tiingo.
+
+        Args:
+            tickers:    Filter by ticker symbols, e.g. ["AAPL", "GOOGL"]
+            tags:       Filter by topic tags, e.g. ["Earnings"]
+            sources:    Filter by news source domain, e.g. ["reuters.com"]
+            start_date: "YYYY-MM-DD"
+            end_date:   "YYYY-MM-DD"
+            limit:      Max number of articles to return
+
+        Returns:
+            DataFrame with columns: publishedDate, title, description, url, tickers, tags
+        
+        Raises:
+            Exception: If Tiingo news API call fails.
+        """
+        logger.info("Fetching news (tickers=%s, tags=%s)...", tickers, tags)
+        articles = self.client.get_news(
+            tickers=tickers,
+            tags=tags,
+            sources=sources,
+            startDate=start_date,
+            endDate=end_date,
+            limit=limit,
+        )
+
+        if not articles:
+            logger.warning("No news articles found for tickers=%s.", tickers)
+
+        return pd.DataFrame(articles)
+
+    # # ------------------------------------------------------------------
+    # # Fundamentals — daily (marketCap etc.) and quarterly statements
+    # # ------------------------------------------------------------------
+    # def fetch_fundamentals_daily(
+    #     self,
+    #     symbol: str,
+    #     start_date: Optional[str] = None,
+    #     end_date: Optional[str] = None,
+    # ) -> pd.DataFrame:
+    #     """
+    #     Fetch daily-updated fundamental metrics (e.g. marketCap, EV).
+    #     NOTE: Requires Tiingo paid plan.
+    #     """
+    #     logger.info("Fetching daily fundamentals for %s...", symbol)
+    #     data = self.client.get_fundamentals_daily(
+    #         symbol, startDate=start_date, endDate=end_date
+    #     )
+    #     return pd.DataFrame(data)
+
+    # def fetch_fundamentals_statements(
+    #     self,
+    #     symbol: str,
+    #     start_date: Optional[str] = None,
+    #     end_date: Optional[str] = None,
+    #     as_reported: bool = False,
+    # ) -> pd.DataFrame:
+    #     """
+    #     Fetch quarterly financial statements (income, balance sheet, cash flow).
+    #     NOTE: Requires Tiingo paid plan.
+
+    #     Args:
+    #         as_reported: If True, returns raw SEC-reported data (no corrections).
+    #     """
+    #     logger.info("Fetching quarterly statements for %s...", symbol)
+    #     data = self.client.get_fundamentals_statements(
+    #         symbol,
+    #         startDate=start_date,
+    #         endDate=end_date,
+    #         asReported=as_reported,
+    #     )
+    #     return pd.DataFrame(data)
+
+    # ------------------------------------------------------------------
+    #   Crypto — historical OHLCV for crypto pairs
+    # ------------------------------------------------------------------
+    def fetch_crypto(
+        self,
+        tickers: List[str],
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        resample_freq: str = "1Day",
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch historical cryptocurrency price data.
+
+        Args:
+            tickers:       Crypto pairs as a list, e.g. ["BTCUSD", "ETHUSD"]
+            start_date:    "YYYY-MM-DD"
+            end_date:      "YYYY-MM-DD"
+            resample_freq: e.g. "1Day", "1Hour", "30Min"
+
+        Returns: {ticker: DataFrame}  (only successfully fetched tickers)
+        
+        Raises:
+            Exception: If Tiingo crypto API call fails.
+        """
+        logger.info("Fetching crypto: %s...", tickers)
+        if not tickers:
+            return {}
+            
+        data = self.client.get_crypto_price_history(
+            tickers=tickers,
+            startDate=start_date,
+            endDate=end_date,
+            resampleFreq=resample_freq,
+        )
+
+        # Tiingo returns a list of dicts, each with 'ticker' and 'priceData'
+        result = {}
+        for item in data:
+            ticker = item.get('ticker', '<unknown>')
+            price_data = item.get('priceData', [])
+            if not price_data:
+                logger.warning("Crypto ticker '%s' has no priceData — skipping.", ticker)
+                continue
+            try:
+                df = pd.DataFrame(price_data)
+                normalized = self._normalize_ohlcv(df)
+                if normalized.empty:
+                    logger.warning("Crypto ticker '%s' normalized to empty — skipping.", ticker)
+                    continue
+                result[ticker] = normalized
+            except Exception as e:
+                logger.error("Failed to process crypto ticker '%s': %s — skipping.", ticker, e)
+
+        return result
+
+    def fetch_info(self, symbol: str) -> dict:
+        """
+        Fetch company profile via Tiingo.
+        """
+        logger.info("Fetching info for %s via Tiingo...", symbol)
+        self._validate_inputs(symbol)
+        try:
+            return self.client.get_ticker_metadata(symbol)
+        except Exception as e:
+            logger.warning("Failed to fetch info for %s from Tiingo: %s", symbol, e)
+            return {}
+
+    def fetch_financials(self, symbol: str, statement: str = "income", period: str = "annual") -> pd.DataFrame:
+        """
+        Tiingo does not provide full standardized financial statements in the free tier
+        (only basic daily fundamentals). Returning empty DataFrame.
+        """
+        logger.warning("Tiingo free tier does not support full %s statements. Returning empty.", statement)
+        return pd.DataFrame()

alphadataforge/providers/yfinance_fetcher.py

@@ -0,0 +1,282 @@
+import yfinance as yf
+import pandas as pd
+from typing import Optional, List, Dict
+from ..core.base_fetcher import BaseDataFetcher
+from ..utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class YFinanceFetcher(BaseDataFetcher):
+    """
+    Data fetcher for Yahoo Finance API using the yfinance library.
+    Inherits from BaseDataFetcher.
+
+    Supports: stock/ETF/crypto/forex price, news, and fundamentals.
+    All data is free with no API key required.
+    """
+
+    # ------------------------------------------------------------------
+    # Required by BaseDataFetcher — fetches PRICE for 1 symbol
+    # ------------------------------------------------------------------
+    def fetch_single(
+        self,
+        symbol: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        interval: str = "1d",
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch historical OHLCV price data for a single symbol.
+
+        Args:
+            symbol:     Ticker, e.g. "AAPL", "BTC-USD", "EURUSD=X", "^VIX"
+            start_date: "YYYY-MM-DD" (inclusive)
+            end_date:   "YYYY-MM-DD" (exclusive)
+            interval:   "1m","2m","5m","15m","30m","60m","90m","1h",
+                        "1d","5d","1wk","1mo","3mo"
+                        Note: intraday intervals only available for last 60 days
+            **kwargs:   Any extra yf.download() params (e.g. auto_adjust=False)
+        
+        Raises:
+            ValueError: If symbol or date inputs are invalid.
+            Exception: If yfinance download fails (network, invalid ticker, etc.)
+        """
+        logger.info("Fetching price for %s (%s)...", symbol, interval)
+        self._validate_inputs(symbol, start_date, end_date)
+        
+        # Pop adjusted if present, since yf.download doesn't accept it
+        kwargs.pop("adjusted", None)
+        
+        # Force auto_adjust=False to get raw Close and Adj Close separately
+        # This allows our backfill_adjusted_columns to generate full Adj OHLC
+        download_kwargs = {
+            "auto_adjust": False,
+            "multi_level_index": False
+        }
+        download_kwargs.update(kwargs)
+        
+        df = yf.download(
+            tickers=symbol,
+            start=start_date,
+            end=end_date,
+            interval=interval,
+            progress=False,
+            **download_kwargs
+        )
+        
+        if df.empty:
+            logger.warning("yfinance returned empty DataFrame for %s. Check if the ticker is valid.", symbol)
+
+        return self._normalize_ohlcv(df)
+
+    # ------------------------------------------------------------------
+    # Fetch price for multiple symbols at once (batch download)
+    # ------------------------------------------------------------------
+    def fetch_multiple(
+        self,
+        symbols: List[str],
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        interval: str = "1d",
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Batch fetch OHLCV price data for multiple symbols in a single API call.
+        More efficient than calling fetch_single() in a loop.
+        
+        Symbols that return empty or all-NaN data are logged and excluded.
+
+        Returns: {symbol: DataFrame}  (only successfully fetched symbols)
+        """
+        logger.info("Batch downloading %d symbols...", len(symbols))
+        # Add basic validation for empty list
+        if not symbols:
+            return {}
+            
+        kwargs['group_by'] = 'ticker'
+        
+        df = yf.download(
+            symbols,
+            start=start_date,
+            end=end_date,
+            interval=interval,
+            progress=False,
+            **kwargs
+        )
+            
+        # Single symbol: yfinance doesn't create a MultiIndex, return directly
+        if len(symbols) == 1:
+            normalized = self._normalize_ohlcv(df)
+            if normalized.empty:
+                logger.warning("Batch download returned no data for %s — excluding.", symbols[0])
+                return {}
+            return {symbols[0]: normalized}
+        
+        results = {}
+        for symbol in symbols:
+            if symbol not in df.columns:
+                logger.warning("Symbol %s not found in batch result — excluding.", symbol)
+                continue
+            normalized = self._normalize_ohlcv(df[symbol])
+            if normalized.empty:
+                logger.warning("Symbol %s returned empty data — excluding.", symbol)
+                continue
+            results[symbol] = normalized
+        
+        succeeded = len(results)
+        failed = len(symbols) - succeeded
+        if failed > 0:
+            logger.warning(
+                "Batch fetch finished: %d/%d succeeded, %d excluded.",
+                succeeded, len(symbols), failed,
+            )
+        else:
+            logger.info("Batch fetch finished: all %d symbols succeeded.", succeeded)
+
+        return results
+
+    # ------------------------------------------------------------------
+    # News — recent news articles for a given ticker
+    # ------------------------------------------------------------------
+    def fetch_news(
+        self,
+        symbol: str,
+        count: int = 10,
+    ) -> pd.DataFrame:
+        """
+        Fetch recent news articles for a given ticker from Yahoo Finance.
+
+        Args:
+            symbol: Ticker symbol, e.g. "AAPL"
+            count:  Max number of articles to return
+
+        Returns:
+            DataFrame with columns: title, publisher, link, providerPublishTime, type
+        
+        Raises:
+            Exception: If yfinance ticker lookup fails.
+        """
+        logger.info("Fetching news for %s...", symbol)
+        self._validate_inputs(symbol)
+        if not isinstance(count, int) or count <= 0:
+            raise ValueError(f"count must be a positive integer, got: {count!r}")
+        ticker = yf.Ticker(symbol)
+        articles = ticker.news
+        if not articles:
+            logger.warning("No news articles found for %s.", symbol)
+            return pd.DataFrame()
+        # Extract the 'content' dictionary which contains title, pubDate, etc.
+        valid_articles = [a['content'] for a in articles[:count] if 'content' in a]
+        df = pd.DataFrame(valid_articles)
+        
+        # Convert pubDate to datetime
+        if 'pubDate' in df.columns:
+            df['pubDate'] = pd.to_datetime(df['pubDate'])
+            
+        return df
+
+    # ------------------------------------------------------------------
+    # Fundamentals — summary info, financials, balance sheet, cash flow
+    # ------------------------------------------------------------------
+    def fetch_info(self, symbol: str) -> dict:
+        """
+        Fetch ticker metadata and key fundamental metrics (free-tier).
+        Includes: sector, industry, marketCap, trailingPE, forwardPE,
+                  dividendYield, 52-week high/low, beta, etc.
+
+        Returns: dict (use pd.Series(result) to convert if needed)
+        """
+        logger.info("Fetching info for %s...", symbol)
+        self._validate_inputs(symbol)
+        return yf.Ticker(symbol).info
+
+    def fetch_financials(
+        self,
+        symbol: str,
+        statement: str = "income",
+        period: str = "annual",
+    ) -> pd.DataFrame:
+        """
+        Fetch financial statements for a ticker.
+
+        Args:
+            symbol:    Ticker symbol
+            statement: "income" | "balance" | "cashflow"
+            period:    "annual" | "quarterly".
+
+        Returns: Normalized DataFrame with Dates as rows and metrics as columns
+        
+        Raises:
+            ValueError: If statement type is not recognized.
+        """
+        logger.info(
+            "Fetching %s statement for %s (%s)...",
+            statement, symbol, period,
+        )
+        self._validate_inputs(symbol)
+        ticker = yf.Ticker(symbol)
+        
+        quarterly = (period.lower() == "quarterly")
+
+        if statement == "income":
+            df = ticker.quarterly_income_stmt if quarterly else ticker.income_stmt
+        elif statement == "balance":
+            df = ticker.quarterly_balance_sheet if quarterly else ticker.balance_sheet
+        elif statement == "cashflow":
+            df = ticker.quarterly_cashflow if quarterly else ticker.cashflow
+        else:
+            raise ValueError(
+                f"Unknown statement type: '{statement}'. "
+                "Choose 'income', 'balance', or 'cashflow'."
+            )
+            
+        # yfinance returns dates as columns and metrics as rows. Transpose it.
+        df = df.T
+        
+        # Normalize columns (Net_Income, Total_Revenue, etc.)
+        return self._normalize_financials(df)
+
+    # ------------------------------------------------------------------
+    # Crypto & Forex — yfinance supports these natively, no extra setup
+    # ------------------------------------------------------------------
+    def fetch_crypto(
+        self,
+        symbols: List[str],
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        interval: str = "1d",
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch historical OHLCV data for crypto pairs.
+        Uses the same yfinance engine — just pass crypto symbols.
+
+        Args:
+            symbols: List of crypto pairs, e.g. ["BTC-USD", "ETH-USD", "SOL-USD"]
+
+        Returns: {symbol: DataFrame}
+        """
+        logger.info("Fetching crypto: %s...", symbols)
+        return self.fetch_multiple(symbols, start_date, end_date, interval, **kwargs)
+
+    def fetch_forex(
+        self,
+        pairs: List[str],
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        interval: str = "1d",
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch historical FX rate data.
+        Yahoo Finance forex symbol format: "EURUSD=X", "GBPUSD=X", "JPYUSD=X"
+
+        Args:
+            pairs: List of forex pair symbols, e.g. ["EURUSD=X", "GBPUSD=X"]
+
+        Returns: {symbol: DataFrame}
+        """
+        logger.info("Fetching forex: %s...", pairs)
+        return self.fetch_multiple(pairs, start_date, end_date, interval, **kwargs)