alphadataforge 0.1.0__py3-none-any.whl

alphadataforge/data/price.py

@@ -0,0 +1,207 @@
+from typing import Optional, Dict, Any, Union, List, Literal
+import pandas as pd
+import concurrent.futures
+import logging
+
+logger = logging.getLogger(__name__)
+
+from ..providers.yfinance_fetcher import YFinanceFetcher
+from ..providers.tiingo_fetcher import TiingoFetcher
+from ..providers.alphavantage_fetcher import AlphaVantageFetcher
+from ..providers.fmp_fetcher import FMPFetcher
+from ..providers.hybrid_fetcher import HybridFetcher
+from ..providers.stockfit_fetcher import StockFitFetcher
+
+class Price:
+    """
+    Unified Facade API for fetching price data.
+    Hides provider-specific complexity from the caller.
+    """
+    
+    @staticmethod
+    def get(
+        symbols: Union[str, List[str]], 
+        start_date: Optional[str] = None, 
+        end_date: Optional[str] = None,
+        provider: Literal["yfinance", "tiingo", "alphavantage", "fmp", "hybrid_av_tiingo", "stockfit"] = "yfinance",
+        provider_params: Optional[Dict[str, Any]] = None
+    ) -> Union[pd.DataFrame, Dict[str, pd.DataFrame]]:
+        """
+        Fetch historical end-of-day (EOD) price data for one or more symbols.
+
+        Args:
+            symbols (Union[str, List[str]]): 
+                A single ticker symbol (e.g., 'AAPL') or a list of symbols (e.g., ['AAPL', 'MSFT']).
+            start_date (Optional[str], optional): 
+                Start date in 'YYYY-MM-DD' format. Defaults to None.
+            end_date (Optional[str], optional): 
+                End date in 'YYYY-MM-DD' format. Defaults to None.
+            provider (Literal["yfinance", "tiingo", "alphavantage", "fmp", "hybrid_av_tiingo", "stockfit"], optional): 
+                The data provider to use. Defaults to "yfinance".
+            provider_params (Optional[Dict[str, Any]], optional): 
+                Additional parameters passed directly to the specific provider's fetcher.
+                
+                **Supported `provider_params` by provider:**
+                
+                *   **All Providers:**
+                    *   `adjusted` (bool): If True, returns fully adjusted prices (Splits & Dividends). Default is False.
+                    
+                *   **yfinance:**
+                    *   `interval` (str): Data interval (e.g., "1d", "1wk", "1mo").
+                    *   `prepost` (bool): Include Pre and Post market data.
+                    
+                *   **tiingo:**
+                    *   `resampleFreq` (str): Resample frequency (e.g., "daily", "weekly", "monthly").
+                    
+                *   **alphavantage:**
+                    *   `outputsize` (str): "compact" (last 100 data points) or "full" (20+ years). Default is "compact".
+
+                *   **fmp:**
+                    *   `outputsize` (str): "full" (all history).
+                
+                *   **stockfit:**
+                    *   `resolution` (str): "1d", "1wk", "1mo".
+                
+        Returns:
+            Union[pd.DataFrame, Dict[str, pd.DataFrame]]: 
+                - If `symbols` is a single string, returns a pandas DataFrame.
+                - If `symbols` is a list, returns a dictionary mapping symbols to DataFrames.
+                
+        Examples:
+            >>> from alphadataforge.data.price import Price
+            >>> # 1. Default (yfinance)
+            >>> df = Price.get("AAPL", start_date="2023-01-01")
+            >>> 
+            >>> # 2. Using FMP with adjusted prices
+            >>> df_fmp = Price.get("MSFT", provider="fmp", provider_params={"adjusted": True})
+            >>> 
+            >>> # 3. Using StockFit
+            >>> df_stockfit = Price.get("NVDA", provider="stockfit", start_date="2023-01-01")
+        """
+        
+        # Prevent error if no params are passed
+        provider_params = provider_params or {}
+        
+        # 1. Route to the correct provider
+        if provider == "yfinance":
+            fetcher = YFinanceFetcher()
+        elif provider == "tiingo":
+            fetcher = TiingoFetcher()
+        elif provider == "alphavantage":
+            fetcher = AlphaVantageFetcher()
+        elif provider == "fmp":
+            fetcher = FMPFetcher()
+        elif provider == "hybrid_av_tiingo":
+            fetcher = HybridFetcher()
+        elif provider == "stockfit":
+            fetcher = StockFitFetcher()
+        else:
+            raise ValueError(f"Unsupported provider: '{provider}'. Choose 'yfinance', 'tiingo', 'alphavantage', 'fmp', 'hybrid_av_tiingo', or 'stockfit'.")
+            
+        # 2. fetch price data (check whether list or string)
+        if isinstance(symbols, list):
+            result = fetcher.fetch_multiple(symbols, start_date, end_date, **provider_params)
+        else:
+            result = fetcher.fetch_single(symbols, start_date, end_date, **provider_params)
+        
+        # 3. Return to caller
+        return result
+
+    @staticmethod
+    def compare(
+        symbol: str, 
+        start_date: Optional[str] = None, 
+        end_date: Optional[str] = None,
+        providers: Optional[List[str]] = None,
+        provider_params: Optional[Dict[str, Any]] = None,
+        custom_data: Optional[Dict[str, pd.DataFrame]] = None
+    ) -> pd.DataFrame:
+        """
+        Fetch historical price data from multiple providers concurrently and combine them 
+        into a single MultiIndex DataFrame for easy comparison.
+        
+        Args:
+            custom_data: Optional dictionary mapping provider names to custom pandas DataFrames.
+                         These will be merged alongside the API-fetched data.
+        """
+        if providers is None:
+            providers = ["yfinance", "tiingo", "alphavantage", "fmp", "hybrid_av_tiingo"]
+            
+        provider_params = provider_params or {}
+        
+        def fetch_for_provider(p):
+            try:
+                return p, Price.get(
+                    symbols=symbol,
+                    start_date=start_date,
+                    end_date=end_date,
+                    provider=p,
+                    provider_params=provider_params
+                )
+            except Exception as e:
+                logger.error(f"Failed to fetch from {p} for comparison: {type(e).__name__} {e}")
+                return p, pd.DataFrame()
+
+        results = {}
+        with concurrent.futures.ThreadPoolExecutor(max_workers=len(providers)) as executor:
+            futures = [executor.submit(fetch_for_provider, p) for p in providers]
+            for future in concurrent.futures.as_completed(futures):
+                p, df = future.result()
+                if not df.empty:
+                    if df.index.tz is not None:
+                        df.index = df.index.tz_localize(None)
+                    results[p] = df
+
+        if custom_data:
+            for p, df in custom_data.items():
+                if not df.empty:
+                    if df.index.tz is not None:
+                        df.index = df.index.tz_localize(None)
+                    results[p] = df
+
+        if not results:
+            return pd.DataFrame()
+
+        # Combine into MultiIndex DataFrame
+        # pd.concat(results, axis=1) creates MultiIndex where level 0 is the dictionary key (provider)
+        multi_df = pd.concat(results, axis=1)
+        return multi_df
+
+    @staticmethod
+    def consensus(
+        symbol: str, 
+        start_date: Optional[str] = None, 
+        end_date: Optional[str] = None,
+        providers: Optional[List[str]] = None,
+        provider_params: Optional[Dict[str, Any]] = None,
+        custom_data: Optional[Dict[str, pd.DataFrame]] = None,
+        method: Literal["mean", "median"] = "median"
+    ) -> pd.DataFrame:
+        """
+        Fetch from multiple providers and return a single consensus DataFrame 
+        by calculating the mean or median across all available providers.
+        """
+        multi_df = Price.compare(symbol, start_date, end_date, providers, provider_params, custom_data)
+        
+        if multi_df.empty:
+            return pd.DataFrame()
+            
+        # Filter out non-numeric columns (like 'symbol' strings)
+        numeric_df = multi_df.select_dtypes(include='number')
+        
+        # Group by level 1 (the column names like 'Close', 'Adj Close') and aggregate
+        # Using .T.groupby() to avoid deprecated axis=1
+        if method == "mean":
+            consensus_df = numeric_df.T.groupby(level=1).mean().T
+        elif method == "median":
+            consensus_df = numeric_df.T.groupby(level=1).median().T
+        else:
+            raise ValueError("Method must be 'mean' or 'median'")
+            
+        # Sort columns to maintain standard OHLCV order
+        standard_cols = ['Open', 'High', 'Low', 'Close', 'Volume', 'Adj Open', 'Adj High', 'Adj Low', 'Adj Close', 'Adj Volume']
+        existing_cols = [c for c in standard_cols if c in consensus_df.columns]
+        other_cols = [c for c in consensus_df.columns if c not in standard_cols]
+        consensus_df = consensus_df[existing_cols + other_cols]
+        
+        return consensus_df

alphadataforge/providers/alphavantage_fetcher.py

@@ -0,0 +1,328 @@
+import pandas as pd
+from typing import Optional, List, Dict
+
+import time
+import threading
+from ..utils.finance_math import calculate_adjusted_prices
+
+from ..core.base_fetcher import BaseDataFetcher
+from ..core.exceptions import ProviderConfigurationError, RateLimitExceededError, InvalidTickerError
+from ..config.settings import config
+from ..config.endpoints import Endpoints
+from ..utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class AlphaVantageFetcher(BaseDataFetcher):
+    """
+    Data fetcher for Alpha Vantage using direct HTTP requests.
+    Supports: EOD stock price.
+    
+    Requires ALPHAVANTAGE_API_KEY environment variable.
+    Free tier: 25 requests/day.
+    """
+    
+    # Class-level lock to ensure only one thread makes an AlphaVantage request at a time
+    _rate_limit_lock = threading.Lock()
+
+    def __init__(self, api_key: Optional[str] = None):
+        super().__init__()
+        self.api_key = api_key or config.ALPHAVANTAGE_API_KEY
+        self.base_url = Endpoints.AlphaVantage.BASE_URL
+
+    def _require_api_key(self) -> None:
+        if not self.api_key:
+            raise ProviderConfigurationError(
+                "ALPHAVANTAGE_API_KEY is not set. Please set it in your .env file or environment variables."
+            )
+
+    def _make_request(self, **params) -> dict:
+        """
+        Executes HTTP GET request to Alpha Vantage API.
+        Raises ValueError for API-level errors (bad symbol, etc.).
+        Raises RuntimeError for rate-limit / information notices.
+        """
+        # AlphaVantage Free Tier allows max 1 request/second.
+        # Add automatic delay and thread lock to prevent concurrent rate limit hits.
+        with self._rate_limit_lock:
+            time.sleep(1.2)
+            
+            self._require_api_key()
+            params['apikey'] = self.api_key
+            data = self._make_http_request(self.base_url, params=params)
+        
+        
+        # Alpha Vantage returns an error message in the JSON payload instead of HTTP status sometimes
+        if "Error Message" in data:
+            raise InvalidTickerError(f"AlphaVantage API Error: {data['Error Message']}")
+        if "Information" in data:
+            raise RateLimitExceededError(
+                f"AlphaVantage rate limit or notice: {data['Information']}"
+            )
+        return data
+
+    def _parse_response(self, raw_json: dict, time_series_key: str) -> pd.DataFrame:
+        """
+        Parses Alpha Vantage JSON response into a Pandas DataFrame.
+        Raises KeyError if the expected time series key is missing from the response.
+        """
+        if time_series_key not in raw_json:
+            logger.warning(
+                "Expected key '%s' not found in API response. "
+                "Available keys: %s", time_series_key, list(raw_json.keys())
+            )
+            return pd.DataFrame()
+            
+        time_series_data = raw_json[time_series_key]
+        
+        # Convert dictionary to DataFrame
+        df = pd.DataFrame.from_dict(time_series_data, orient='index')
+        
+        # Alpha Vantage returns columns like "1. open", "2. high", etc.
+        # We clean them to match standard mappings ("open", "high", etc.)
+        # so that _normalize_ohlcv can capitalize them.
+        rename_map = {
+            '1. open': 'open',
+            '2. high': 'high',
+            '3. low': 'low',
+            '4. close': 'close',
+            '5. volume': 'volume',
+            '5. adjusted close': 'adjClose',
+            '6. volume': 'volume',  # Adjusted daily uses 6 for volume
+        }
+        df.rename(columns=rename_map, inplace=True)
+        
+        # Convert types from string to float
+        for col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors='coerce')
+            
+        return df
+
+    # ------------------------------------------------------------------
+    # Required by BaseDataFetcher — fetches PRICE for 1 symbol
+    # ------------------------------------------------------------------
+    def fetch_single(
+        self,
+        symbol: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        outputsize: str = "compact",  # "compact" (100 days) or "full" (20 years)
+        adjusted: bool = False,
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch EOD price data for a single stock/ETF symbol from Alpha Vantage.
+        
+        Raises:
+            ValueError: If symbol is invalid or API returns an error.
+            RuntimeError: If rate limit is exceeded.
+            RequestException: If network request fails after retries.
+        """
+        logger.info("Fetching price for %s (size=%s, adjusted=%s)...", symbol, outputsize, adjusted)
+        self._validate_inputs(symbol, start_date, end_date)
+        
+        # TIME_SERIES_DAILY_ADJUSTED is a premium endpoint now.
+        # We always use TIME_SERIES_DAILY and manually adjust it using DIVIDENDS/SPLITS.
+        function = Endpoints.AlphaVantage.FUNCTIONS["price_daily"]
+        time_series_key = "Time Series (Daily)"
+        
+        # --- Step 1: Fetch price data (will raise on failure) ---
+        raw_json = self._make_request(
+            function=function,
+            symbol=symbol,
+            outputsize=outputsize
+        )
+        df = self._parse_response(raw_json, time_series_key)
+        if df.empty:
+            logger.warning("_parse_response returned empty for %s (key='%s').", symbol, time_series_key)
+        
+        # Alpha Vantage doesn't let us filter by date in the API call directly
+        # We must filter it locally in pandas
+        if not df.empty:
+            df.index = pd.to_datetime(df.index)
+            if start_date:
+                df = df[df.index >= pd.to_datetime(start_date)]
+            if end_date:
+                df = df[df.index <= pd.to_datetime(end_date)]
+
+        # --- Step 2: Fetch Dividends & Splits (separate try/except) ---
+        if adjusted and not df.empty:
+
+            div_df = pd.DataFrame(columns=['Dividend'])
+            split_df = pd.DataFrame(columns=['SplitFactor'])
+
+            # --- 2a: Dividends ---
+            try:
+                logger.info("Fetching DIVIDENDS for %s...", symbol)
+                raw_json = self._make_request(function=Endpoints.AlphaVantage.FUNCTIONS["dividends"], symbol=symbol)
+                div_data = raw_json.get("data", [])
+                if div_data:
+                    div_df = pd.DataFrame(div_data)
+                    div_df['Dividend'] = pd.to_numeric(div_df['amount'], errors='coerce')
+                    div_df.index = pd.to_datetime(div_df['ex_dividend_date'])
+            except Exception as e:
+                logger.warning(
+                    "Could not fetch dividends for %s: %s. "
+                    "Proceeding without dividend adjustment.", symbol, e
+                )
+
+            # --- 2b: Splits ---
+            try:
+                logger.info("Fetching SPLITS for %s...", symbol)
+                raw_json = self._make_request(function=Endpoints.AlphaVantage.FUNCTIONS["splits"], symbol=symbol)
+                split_data = raw_json.get("data", [])
+                if split_data:
+                    split_df = pd.DataFrame(split_data)
+                    split_df['SplitFactor'] = pd.to_numeric(split_df['split_factor'], errors='coerce')
+                    split_df.index = pd.to_datetime(split_df['effective_date'])
+            except Exception as e:
+                logger.warning(
+                    "Could not fetch splits for %s: %s. "
+                    "Proceeding without split adjustment.", symbol, e
+                )
+
+            # --- 2c: Apply adjustment ---
+            df = self._normalize_ohlcv(df)
+            df = calculate_adjusted_prices(df, div_df, split_df)
+                    
+        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,
+        outputsize: str = "compact",
+        adjusted: bool = False,
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch price data for multiple symbols concurrently using ThreadPoolExecutor.
+        """
+        calls_per_symbol = 3 if adjusted else 1
+        total_calls = len(symbols) * calls_per_symbol
+        if total_calls > 25:
+            logger.warning(
+                "AlphaVantage quota warning: Fetching %d symbols (adjusted=%s) requires %d API calls. "
+                "The free tier limits you to 25 requests per day. This operation may fail.",
+                len(symbols), adjusted, total_calls
+            )
+        # Delegate to BaseDataFetcher.fetch_multiple which handles per-symbol
+        # error isolation and logging automatically.
+        return super().fetch_multiple(
+            symbols,
+            start_date=start_date,
+            end_date=end_date,
+            outputsize=outputsize,
+            adjusted=adjusted,
+            **kwargs
+        )
+
+    # ------------------------------------------------------------------
+    # Fetch fundamental data
+    # ------------------------------------------------------------------
+    def fetch_fundamental(self, symbol: str, function: str = "OVERVIEW") -> dict:
+        """
+        Fetch fundamental data from Alpha Vantage.
+        Supported functions: OVERVIEW, INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW, EARNINGS, etc.
+        
+        Raises:
+            InvalidTickerError: If symbol is invalid or API returns an error.
+            RateLimitExceededError: If rate limit is exceeded.
+        """
+        logger.info("Fetching %s for %s...", function, symbol)
+        self._validate_inputs(symbol)
+        
+        raw_json = self._make_request(
+            function=function,
+            symbol=symbol
+        )
+        return raw_json
+
+    def fetch_info(self, symbol: str) -> dict:
+        """
+        Fetch company profile (fundamentals like sector, industry, mktCap).
+        """
+        logger.info("Fetching info for %s via AlphaVantage...", symbol)
+        return self.fetch_fundamental(symbol, function=Endpoints.AlphaVantage.FUNCTIONS["overview"])
+
+    def fetch_financials(self, symbol: str, statement: str = "income", period: str = "annual") -> pd.DataFrame:
+        """
+        Fetch financial statements from AlphaVantage.
+        """
+        logger.info("Fetching %s statement for %s (%s) via AlphaVantage...", statement, symbol, period)
+        
+        endpoint_map = Endpoints.AlphaVantage.FUNCTIONS
+        valid_statements = {"income", "balance", "cashflow", "shares_outstanding", "earnings"}
+        
+        if statement not in valid_statements:
+            raise ValueError(f"Unknown statement type: '{statement}'. Choose 'income', 'balance', 'cashflow', 'shares_outstanding', or 'earnings'.")
+            
+        function = endpoint_map[statement]
+        raw_json = self.fetch_fundamental(symbol, function=function)
+        
+        # AlphaVantage uses different keys for different endpoints
+        if statement == "shares_outstanding":
+            # SHARES_OUTSTANDING uses a flat "data" list
+            reports = raw_json.get("data", [])
+        else:
+            if statement == "earnings":
+                report_key = "quarterlyEarnings" if period.lower() == "quarterly" else "annualEarnings"
+            else:
+                report_key = "quarterlyReports" if period.lower() == "quarterly" else "annualReports"
+            reports = raw_json.get(report_key, [])
+            
+        if not reports:
+            logger.warning("No %s financial data found for %s in AlphaVantage.", period, symbol)
+            return pd.DataFrame()
+            
+        df = pd.DataFrame(reports)
+        
+        # fiscalDateEnding or date is the index
+        if 'fiscalDateEnding' in df.columns:
+            df.index = pd.to_datetime(df['fiscalDateEnding'])
+            df = df.drop(columns=['fiscalDateEnding'])
+        elif 'date' in df.columns:
+            df.index = pd.to_datetime(df['date'])
+            df = df.drop(columns=['date'])
+            
+        return self._normalize_financials(df)
+
+    def fetch_earnings_calendar(self, horizon: str = "3month", symbol: Optional[str] = None) -> pd.DataFrame:
+        """
+        Fetch earnings calendar.
+        horizon: '3month', '6month', or '12month'
+        symbol: Optional specific symbol to fetch for.
+        """
+        logger.info("Fetching earnings calendar (horizon=%s) via AlphaVantage...", horizon)
+        
+        # AlphaVantage Free Tier allows max 1 request/second.
+        time.sleep(1.2)
+        
+        # This endpoint returns CSV directly, so we use pandas read_csv instead of _make_request
+        url = f"{self.base_url}?function=EARNINGS_CALENDAR&horizon={horizon}&apikey={self.api_key}"
+        if symbol:
+            url += f"&symbol={symbol}"
+            
+        try:
+            df = pd.read_csv(url)
+            # Check for API rate limit (AlphaVantage returns JSON error if rate limited, which breaks read_csv, or returns a 1-row DataFrame with the error)
+            if not df.empty and len(df.columns) == 1 and "Thank you for using Alpha Vantage!" in str(df.iloc[0, 0]):
+                raise RateLimitExceededError(f"AlphaVantage rate limit or notice: {df.iloc[0, 0]}")
+            
+            # The CSV columns are: symbol, name, reportDate, fiscalDateEnding, estimate, currency
+            if 'reportDate' in df.columns:
+                df['reportDate'] = pd.to_datetime(df['reportDate'], errors='coerce')
+            if 'fiscalDateEnding' in df.columns:
+                df['fiscalDateEnding'] = pd.to_datetime(df['fiscalDateEnding'], errors='coerce')
+                
+            return df
+        except Exception as e:
+            if isinstance(e, RateLimitExceededError):
+                raise
+            logger.error("Failed to fetch earnings calendar: %s", e)
+            return pd.DataFrame()