alphadataforge 0.1.0__py3-none-any.whl

alphadataforge/__init__.py

@@ -0,0 +1,2 @@
+from .data.price import Price
+from .data.fundamental import Fundamentals

alphadataforge/config/endpoints.py

@@ -0,0 +1,52 @@
+class Endpoints:
+    """
+    Centralized configuration for API provider endpoints.
+    """
+    class AlphaVantage:
+        BASE_URL = "https://www.alphavantage.co/query"
+        
+        # Mappings for the `function` parameter in AlphaVantage
+        FUNCTIONS = {
+            "income": "INCOME_STATEMENT",
+            "balance": "BALANCE_SHEET",
+            "cashflow": "CASH_FLOW",
+            "shares_outstanding": "SHARES_OUTSTANDING",
+            "earnings": "EARNINGS",
+            "overview": "OVERVIEW",
+            "price_daily": "TIME_SERIES_DAILY",
+            "dividends": "DIVIDENDS",
+            "splits": "SPLITS"
+        }
+
+    class FMP:
+        BASE_URL = "https://financialmodelingprep.com/stable"
+        
+        # Paths appended to the FMP BASE_URL
+        PATHS = {
+            "income": "income-statement",
+            "balance": "balance-sheet-statement",
+            "cashflow": "cash-flow-statement",
+            "shares_float": "shares-float",
+            "profile": "profile",
+            "price_adjusted": "historical-price-eod/dividend-adjusted",
+            "price_raw": "historical-price-eod/full"
+        }
+
+    class Tiingo:
+        BASE_URL = "https://api.tiingo.com/tiingo/daily"
+
+    class StockFit:
+        BASE_URL = "https://api.stockfit.io/v1/api"
+        PATHS = {
+            "income": "financials/income-statement",
+            "balance": "financials/balance-sheet",
+            "cashflow": "financials/cash-flow-statement",
+            "growth": "financials/growth",
+            "scores": "financials/scores",
+            "key_metrics": "financials/key-metrics",
+            "as_reported": "financials/as-reported",
+            "details": "company/details",
+            "research_summary": "company/research-summary",
+            "price_history": "price/history",
+            "quote": "price/quote"
+        }

alphadataforge/config/settings.py

@@ -0,0 +1,18 @@
+import os
+from typing import Optional
+from dotenv import load_dotenv
+
+# Use override=True so that if the user updates .env while the Jupyter kernel is running,
+# and autoreload triggers, it will actually load the new API keys instead of keeping the old ones in os.environ.
+load_dotenv(override=True)
+
+class Settings:
+    """
+    Settings of the package
+    """
+    TIINGO_API_KEY: Optional[str] = os.getenv("TIINGO_API_KEY")
+    ALPHAVANTAGE_API_KEY: Optional[str] = os.getenv("ALPHAVANTAGE_API_KEY")
+    FMP_API_KEY: Optional[str] = os.getenv("FMP_API_KEY")
+    STOCKFIT_API_KEY: Optional[str] = os.getenv("STOCKFIT_API_KEY")
+
+config = Settings()

alphadataforge/core/base_fetcher.py

@@ -0,0 +1,357 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+from typing import Optional, List, Dict
+import random as rd
+import time
+from datetime import datetime
+import gzip
+import zlib
+import json
+
+import requests
+import requests_cache
+from requests.exceptions import RequestException, HTTPError, Timeout, ConnectionError
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception, before_sleep_log
+import concurrent.futures
+import tempfile
+import os
+
+from .exceptions import RateLimitExceededError
+
+cache_path = os.path.join(tempfile.gettempdir(), 'alphadataforge_cache')
+def _filter_responses(response):
+    # Don't cache AlphaVantage rate limit messages (which return HTTP 200)
+    if "Thank you for using Alpha Vantage!" in response.text:
+        return False
+    return True
+
+from ..utils.logger import setup_logger
+from ..utils.finance_math import backfill_adjusted_columns
+
+logger = setup_logger(__name__)
+
+def _is_retryable_exception(e: BaseException) -> bool:
+    """Determine if an exception should be retried."""
+    if isinstance(e, RateLimitExceededError):
+        return True
+    if isinstance(e, (Timeout, ConnectionError)):
+        return True
+    if isinstance(e, HTTPError):
+        # Retry only on 5xx (Server Error). Do not retry 400-404.
+        if e.response is not None and e.response.status_code >= 500:
+            return True
+        if e.response is not None and e.response.status_code == 429:
+            return True
+    return False
+
+class BaseDataFetcher(ABC):
+    """
+    Abstract Base Class for all data fetchers.
+    Acts as a contract ensuring all fetchers implement the fetch_single method.
+    """
+    
+    def __init__(self):
+        import sys
+        if "pytest" not in sys.modules and os.environ.get("DISABLE_REQUESTS_CACHE") != "1":
+            self.session = requests_cache.CachedSession(
+                cache_name=cache_path, 
+                backend='sqlite', 
+                expire_after=86400,
+                filter_fn=_filter_responses
+            )
+        else:
+            self.session = requests.Session()
+    
+    @abstractmethod
+    def fetch_single(
+        self, 
+        symbol: str, 
+        start_date: Optional[str] = None, 
+        end_date: Optional[str] = None, 
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch data for a single symbol.
+        Every provider must implement this method.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_info(self, symbol: str) -> dict:
+        """
+        Fetch company profile and basic information.
+        Must return a dictionary.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_financials(self, symbol: str, statement: str = "income", period: str = "annual") -> pd.DataFrame:
+        """
+        Fetch financial statements (income, balance, cashflow).
+        period: "annual" or "quarterly".
+        Must return a DataFrame with dates as the index.
+        """
+        pass
+    
+    def _validate_inputs(self, symbol: str, start_date: Optional[str] = None, end_date: Optional[str] = None):
+        """Validates standard inputs before fetching."""
+        if not symbol or not isinstance(symbol, str) or symbol.strip() == "":
+            raise ValueError("Symbol must be a non-empty string.")
+        
+        def validate_date(date_str, name):
+            if date_str:
+                try:
+                    return datetime.strptime(date_str, "%Y-%m-%d")
+                except ValueError:
+                    raise ValueError(f"{name} format must be YYYY-MM-DD, got: '{date_str}'")
+            return None
+            
+        start = validate_date(start_date, "start_date")
+        end = validate_date(end_date, "end_date")
+        
+        if start and end and start > end:
+            raise ValueError("start_date cannot be after end_date.")
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=2, max=30),
+        retry=retry_if_exception(_is_retryable_exception),
+        before_sleep=before_sleep_log(logger, log_level=20),  # 20 = INFO
+        reraise=True,
+    )
+    def _make_http_request(self, url: str, params: Optional[dict] = None, headers: Optional[dict] = None) -> dict:
+        """
+        Generic HTTP GET request helper with automatic retry.
+        Retries up to 3 times with exponential backoff for transient network errors.
+        Raises HTTPError for non-retryable server errors (4xx).
+        """
+        logger.debug("GET %s params=%s", url, list((params or {}).keys()))
+        
+        headers = headers or {}
+        # Force gzip/deflate to avoid unsupported Brotli (br) encoding
+        if "Accept-Encoding" not in headers:
+            headers["Accept-Encoding"] = "gzip, deflate"
+            
+        response = self.session.get(url, params=params, headers=headers, timeout=30)
+
+        # Raise specific error for rate-limiting so tenacity can retry it
+        if response.status_code == 429:
+            logger.warning("Rate limited (HTTP 429). Retrying after backoff...")
+            raise RateLimitExceededError(f"Rate limited by server (HTTP 429) for URL: {url}")
+
+        response.raise_for_status()
+        try:
+            # requests usually auto-decompresses; prefer response.json first
+            return response.json()
+        except ValueError as first_err:
+            raw = response.content or b""
+            enc = (response.headers.get("Content-Encoding") or "").lower()
+
+            try:
+                if "gzip" in enc or raw[:2] == b'\x1f\x8b':
+                    raw = gzip.decompress(raw)
+                elif "deflate" in enc:
+                    raw = zlib.decompress(raw)
+
+                # try UTF-8 decode + json parse
+                if isinstance(raw, bytes):
+                    raw = raw.decode("utf-8", errors="replace")
+
+                return json.loads(raw)
+            except Exception as second_err:
+                snippet = (raw[:200] if isinstance(raw, str) else repr(raw[:80]))
+                logger.error(
+                    "Failed to parse JSON response from %s (status=%s, encoding=%s). Snippet: %s",
+                    url, response.status_code, enc, snippet
+                )
+                raise ValueError(
+                    f"Invalid JSON response from API: {second_err or first_err}"
+                ) from second_err
+    
+    def _normalize_ohlcv(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Standardizes the DataFrame columns to Title Case (Open, High, Low, Close, Volume, Adj Close)
+        and ensures the index is a DatetimeIndex.
+        """
+        if df.empty:
+            return pd.DataFrame()
+            
+        # If all values are NaN (e.g. yfinance returning NaNs for invalid tickers in batch), return empty
+        if df.isna().all().all():
+            logger.warning("All values are NaN after fetch — returning empty DataFrame.")
+            return pd.DataFrame()
+
+        # Flatten MultiIndex columns (e.g., from new yfinance versions returning Price/Ticker)
+        if isinstance(df.columns, pd.MultiIndex):
+            # We assume level 0 is the metric (Close, High, etc.) and level 1 is the ticker
+            df.columns = df.columns.get_level_values(0)
+
+        # Title case mapping for common variants
+        col_mapping = {
+            'open': 'Open',
+            'high': 'High',
+            'low': 'Low',
+            'close': 'Close',
+            'volume': 'Volume',
+            'adjclose': 'Adj Close',
+            'adj_close': 'Adj Close',
+            'adjClose': 'Adj Close',
+            'adjOpen': 'Adj Open',
+            'adjHigh': 'Adj High',
+            'adjLow': 'Adj Low',
+            'adjVolume': 'Adj Volume',
+        }
+        df = df.rename(columns=col_mapping)
+        
+        # Ensure index is datetime and named 'Date'
+        if not isinstance(df.index, pd.DatetimeIndex):
+            try:
+                df.index = pd.to_datetime(df.index)
+            except Exception as e:
+                logger.warning(
+                    "Could not convert index to DatetimeIndex: %s. "
+                    "Falling back to pd.to_datetime with errors='coerce'.", e
+                )
+                df.index = pd.to_datetime(df.index, errors='coerce')
+        df.index.name = "Date"
+        
+        # Automatically backfill 'Adj Open', 'Adj High', 'Adj Low' if we only have 'Adj Close'
+        df = backfill_adjusted_columns(df)
+                
+        return df
+
+    def _normalize_financials(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Standardizes financial statement column names across different providers.
+        Targets: Net_Income, Total_Equity, Shares_Outstanding, Total_Revenue,
+                 Operating_Income, Free_Cash_Flow, Total_Assets, Total_Liabilities.
+        """
+        if df.empty:
+            return df
+            
+        # Common variations for fundamental metrics
+        col_mapping = {
+            # Net Income
+            'netIncome': 'Net_Income',
+            'Net Income': 'Net_Income',
+            'netIncomeLoss': 'Net_Income',
+            'net_income': 'Net_Income',
+            
+            # Total Equity
+            'totalStockholdersEquity': 'Total_Equity',
+            'stockholdersEquity': 'Total_Equity',
+            'Total Stockholder Equity': 'Total_Equity',
+            'Stockholders Equity': 'Total_Equity',
+            'totalEquity': 'Total_Equity',
+            'total_equity': 'Total_Equity',
+            'totalShareholderEquity': 'Total_Equity',
+            
+            # Shares Outstanding
+            'sharesOutstanding': 'Shares_Outstanding',
+            'commonStockSharesOutstanding': 'Shares_Outstanding',
+            'weightedAverageSharesOutstanding': 'Shares_Outstanding',
+            'Basic Average Shares': 'Shares_Outstanding',
+            'shares_outstanding': 'Shares_Outstanding',
+            'shares_outstanding_basic': 'Shares_Outstanding',
+            
+            # Total Revenue
+            'totalRevenue': 'Total_Revenue',
+            'Total Revenue': 'Total_Revenue',
+            'revenue': 'Total_Revenue',
+            
+            # Operating Income
+            'operatingIncome': 'Operating_Income',
+            'Operating Income': 'Operating_Income',
+            'operating_income': 'Operating_Income',
+            'ebit': 'Operating_Income',
+            'EBIT': 'Operating_Income',
+            
+            # Free Cash Flow
+            'freeCashFlow': 'Free_Cash_Flow',
+            'Free Cash Flow': 'Free_Cash_Flow',
+            'free_cash_flow': 'Free_Cash_Flow',
+            
+            # Total Assets
+            'totalAssets': 'Total_Assets',
+            'Total Assets': 'Total_Assets',
+            'total_assets': 'Total_Assets',
+            'assets': 'Total_Assets',
+            
+            # Total Liabilities
+            'totalLiabilities': 'Total_Liabilities',
+            'Total Liabilities': 'Total_Liabilities',
+            'Total Liabilities Net Minority Interest': 'Total_Liabilities',
+            'total_liabilities': 'Total_Liabilities',
+            'liabilities': 'Total_Liabilities'
+        }
+        
+        # Rename columns if they exist in mapping
+        df = df.rename(columns=col_mapping)
+        
+        # Deduplicate columns if multiple raw metrics mapped to the same standard column
+        if df.columns.duplicated().any():
+            df = df.loc[:, ~df.columns.duplicated(keep='first')]
+        
+        # Ensure index is datetime and named 'Date'
+        if not isinstance(df.index, pd.DatetimeIndex):
+            try:
+                # Some APIs return dates in index, some as a column. Assume index here.
+                df.index = pd.to_datetime(df.index)
+            except Exception:
+                pass
+        df.index.name = "Date"
+                
+        return df
+    
+    def fetch_multiple(
+        self, 
+        symbols: List[str], 
+        start_date: Optional[str] = None, 
+        end_date: Optional[str] = None,
+        max_workers: int = 5,
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch data for multiple tickers, returning a dictionary of DataFrames.
+        Symbols that fail are logged and excluded from the result.
+        Uses ThreadPoolExecutor for concurrent fetching to improve performance.
+        """
+        if not symbols:
+            return {}
+
+        results = {}
+
+        def _fetch_one(symbol):
+            try:
+                # Add random delay to prevent instantly hitting rate limits
+                time.sleep(rd.uniform(0.1, 0.5))
+                df = self.fetch_single(symbol, start_date, end_date, **kwargs)
+                return symbol, df, None
+            except Exception as e:
+                return symbol, None, e
+
+        logger.info(
+            "Batch fetching %d symbols concurrently (max_workers=%d)...", 
+            len(symbols), max_workers
+        )
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {executor.submit(_fetch_one, sym): sym for sym in symbols}
+            for future in concurrent.futures.as_completed(futures):
+                sym, df, err = future.result()
+                if err:
+                    logger.error("Failed to fetch %s — skipping. Error: %s", sym, err)
+                else:
+                    results[sym] = df
+
+        succeeded = len(results)
+        failed = len(symbols) - succeeded
+        if failed > 0:
+            logger.warning(
+                "fetch_multiple finished: %d/%d succeeded, %d failed.",
+                succeeded, len(symbols), failed,
+            )
+        else:
+            logger.info("fetch_multiple finished: all %d symbols succeeded.", succeeded)
+
+        return results

alphadataforge/core/exceptions.py

@@ -0,0 +1,19 @@
+class AlphaDataForgeError(Exception):
+    """Base class for all exceptions raised by the alphadataforge library."""
+    pass
+
+class ProviderConfigurationError(AlphaDataForgeError):
+    """Raised when a provider is improperly configured (e.g., missing API keys)."""
+    pass
+
+class RateLimitExceededError(AlphaDataForgeError):
+    """Raised when an API rate limit is exceeded (HTTP 429 or API notice)."""
+    pass
+
+class InvalidTickerError(AlphaDataForgeError):
+    """Raised when an API explicitly states the ticker is invalid or not found."""
+    pass
+
+class DataFetchError(AlphaDataForgeError):
+    """Raised when a general error occurs while fetching data from the API."""
+    pass

alphadataforge/data/fundamental.py

@@ -0,0 +1,107 @@
+import pandas as pd
+from typing import Optional, Dict, Any
+
+from ..providers.yfinance_fetcher import YFinanceFetcher
+from ..providers.fmp_fetcher import FMPFetcher
+from ..providers.alphavantage_fetcher import AlphaVantageFetcher
+from ..providers.stockfit_fetcher import StockFitFetcher
+from ..utils.logger import setup_logger
+from ..config.settings import config
+
+logger = setup_logger(__name__)
+
+class Fundamentals:
+    """
+    Facade for fetching fundamental data (company profile, financial statements)
+    across multiple providers (YFinance, FMP, AlphaVantage, StockFit).
+    """
+
+    @staticmethod
+    def _get_provider(provider_name: str):
+        provider_name = provider_name.lower()
+        if provider_name == "yfinance":
+            return YFinanceFetcher()
+        elif provider_name == "fmp":
+            return FMPFetcher()
+        elif provider_name == "alphavantage":
+            return AlphaVantageFetcher()
+        elif provider_name == "stockfit":
+            return StockFitFetcher()
+        else:
+            raise ValueError(f"Unsupported provider: '{provider_name}'. Choose 'yfinance', 'stockfit', 'alphavantage', or 'fmp'.")
+
+    @staticmethod
+    def get_info(symbol: str, provider: str = "yfinance") -> Dict[str, Any]:
+        """
+        Fetch company profile and basic information.
+        
+        Args:
+            symbol: Ticker symbol (e.g., "AAPL").
+            provider: "yfinance" (default), "stockfit", "fmp", or "alphavantage".
+            
+        Returns:
+            Dictionary containing company info (sector, industry, marketCap, etc.).
+        """
+        fetcher = Fundamentals._get_provider(provider)
+        return fetcher.fetch_info(symbol)
+
+    @staticmethod
+    def get_financials(
+        symbol: str, 
+        statement: str = "income", 
+        period: str = "annual", 
+        provider: str = "yfinance",
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch financial statements (Income, Balance Sheet, Cash Flow).
+        
+        Args:
+            symbol: Ticker symbol (e.g., "AAPL").
+            statement: "income", "balance", "cashflow", "growth", "scores", "shares_outstanding", "earnings", or "shares_float".
+            period: "annual" (default) or "quarterly".
+            provider: "yfinance" (default), "stockfit", "fmp", or "alphavantage".
+            **kwargs: Extra parameters passed to the provider (e.g. limit=100).
+            
+        Returns:
+            DataFrame with normalized columns (e.g., Net_Income, Total_Revenue)
+            and DatetimeIndex for the reporting periods.
+        """
+        fetcher = Fundamentals._get_provider(provider)
+        return fetcher.fetch_financials(symbol, statement=statement, period=period, **kwargs)
+
+    @staticmethod
+    def get_scores(symbol: str, provider: str = "stockfit") -> Dict[str, Any]:
+        """
+        Fetch Piotroski F-Score and financial health scores.
+        
+        Args:
+            symbol: Ticker symbol (e.g., "AAPL").
+            provider: "stockfit" (default).
+        """
+        fetcher = Fundamentals._get_provider(provider)
+        if hasattr(fetcher, "fetch_scores"):
+            return fetcher.fetch_scores(symbol)
+        raise NotImplementedError(f"Provider '{provider}' does not support get_scores.")
+
+    @staticmethod
+    def get_earnings_calendar(
+        horizon: str = "3month", 
+        symbol: Optional[str] = None,
+        provider: str = "alphavantage"
+    ) -> pd.DataFrame:
+        """
+        Fetch earnings calendar.
+        
+        Args:
+            horizon: '3month' (default), '6month', or '12month'.
+            symbol: Optional ticker symbol to fetch for specifically.
+            provider: Defaults to "alphavantage" (currently the only supported provider for this).
+            
+        Returns:
+            DataFrame containing the earnings calendar.
+        """
+        fetcher = Fundamentals._get_provider(provider)
+        if not hasattr(fetcher, 'fetch_earnings_calendar'):
+            raise NotImplementedError(f"Provider '{provider}' does not support get_earnings_calendar.")
+        return fetcher.fetch_earnings_calendar(horizon=horizon, symbol=symbol)