borsapy 0.4.0__py3-none-any.whl

borsapy/__init__.py

@@ -0,0 +1,134 @@
+"""
+borsapy - Turkish Financial Markets Data Library
+
+A yfinance-like API for BIST stocks, forex, crypto, funds, and economic data.
+
+Examples:
+    >>> import borsapy as bp
+
+    # Get stock data
+    >>> stock = bp.Ticker("THYAO")
+    >>> stock.info  # Real-time quote
+    >>> stock.history(period="1mo")  # OHLCV data
+    >>> stock.balance_sheet  # Financial statements
+
+    # Get forex/commodity data
+    >>> usd = bp.FX("USD")
+    >>> usd.current  # Current rate
+    >>> usd.history(period="1mo")  # Historical data
+    >>> usd.bank_rates  # Bank exchange rates
+    >>> usd.bank_rate("akbank")  # Single bank rate
+    >>> bp.banks()  # List supported banks
+    >>> gold = bp.FX("gram-altin")
+
+    # List all BIST companies
+    >>> bp.companies()
+    >>> bp.search_companies("banka")
+
+    # Get crypto data
+    >>> btc = bp.Crypto("BTCTRY")
+    >>> btc.current  # Current price
+    >>> btc.history(period="1mo")  # Historical OHLCV
+    >>> bp.crypto_pairs()  # List available pairs
+
+    # Get fund data
+    >>> fund = bp.Fund("AAK")
+    >>> fund.info  # Fund details
+    >>> fund.history(period="1mo")  # Price history
+
+    # Get inflation data
+    >>> inf = bp.Inflation()
+    >>> inf.latest()  # Latest TÜFE data
+    >>> inf.calculate(100000, "2020-01", "2024-01")  # Inflation calculation
+
+    # Economic calendar
+    >>> cal = bp.EconomicCalendar()
+    >>> cal.events(period="1w")  # This week's events
+    >>> cal.today()  # Today's events
+    >>> bp.economic_calendar(country="TR", importance="high")
+
+    # Government bonds
+    >>> bp.bonds()  # All bond yields
+    >>> bond = bp.Bond("10Y")
+    >>> bond.yield_rate  # Current 10Y yield
+    >>> bp.risk_free_rate()  # For DCF calculations
+
+    # Stock screener
+    >>> bp.screen_stocks(template="high_dividend")
+    >>> bp.screen_stocks(market_cap_min=1000, pe_max=15)
+    >>> screener = bp.Screener()
+    >>> screener.add_filter("dividend_yield", min=3).run()
+"""
+
+from borsapy.bond import Bond, bonds, risk_free_rate
+from borsapy.calendar import EconomicCalendar, economic_calendar
+from borsapy.crypto import Crypto, crypto_pairs
+from borsapy.exceptions import (
+    APIError,
+    AuthenticationError,
+    BorsapyError,
+    DataNotAvailableError,
+    InvalidIntervalError,
+    InvalidPeriodError,
+    RateLimitError,
+    TickerNotFoundError,
+)
+from borsapy.fund import Fund, compare_funds, screen_funds, search_funds
+from borsapy.fx import FX, banks, metal_institutions
+from borsapy.index import Index, all_indices, index, indices
+from borsapy.inflation import Inflation
+from borsapy.market import companies, search_companies
+from borsapy.multi import Tickers, download
+from borsapy.screener import Screener, screen_stocks, screener_criteria, sectors, stock_indices
+from borsapy.ticker import Ticker
+from borsapy.viop import VIOP
+
+__version__ = "0.4.0"
+__author__ = "Said Surucu"
+
+__all__ = [
+    # Main classes
+    "Ticker",
+    "Tickers",
+    "FX",
+    "Crypto",
+    "Fund",
+    "Index",
+    "Inflation",
+    "VIOP",
+    "Bond",
+    "EconomicCalendar",
+    "Screener",
+    # Market functions
+    "companies",
+    "search_companies",
+    "banks",
+    "metal_institutions",
+    "crypto_pairs",
+    "search_funds",
+    "screen_funds",
+    "compare_funds",
+    "download",
+    "index",
+    "indices",
+    "all_indices",
+    # Bond functions
+    "bonds",
+    "risk_free_rate",
+    # Calendar functions
+    "economic_calendar",
+    # Screener functions
+    "screen_stocks",
+    "screener_criteria",
+    "sectors",
+    "stock_indices",
+    # Exceptions
+    "BorsapyError",
+    "TickerNotFoundError",
+    "DataNotAvailableError",
+    "APIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InvalidPeriodError",
+    "InvalidIntervalError",
+]

borsapy/_models/__init__.py

@@ -0,0 +1 @@
+"""Data models for borsapy."""

borsapy/_providers/__init__.py

@@ -0,0 +1,5 @@
+"""Data providers for borsapy."""
+
+from borsapy._providers.base import BaseProvider
+
+__all__ = ["BaseProvider"]

borsapy/_providers/base.py

@@ -0,0 +1,94 @@
+"""Base provider class for all data providers."""
+
+from typing import Any
+
+import httpx
+
+from borsapy.cache import Cache, get_cache
+
+
+class BaseProvider:
+    """Base class for all data providers."""
+
+    DEFAULT_HEADERS = {
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        "Accept": "application/json, text/plain, */*",
+        "Accept-Language": "tr-TR,tr;q=0.9,en-US;q=0.8,en;q=0.7",
+    }
+
+    def __init__(
+        self,
+        timeout: float = 30.0,
+        cache: Cache | None = None,
+    ):
+        """
+        Initialize the provider.
+
+        Args:
+            timeout: HTTP request timeout in seconds.
+            cache: Cache instance to use. If None, uses global cache.
+        """
+        self._client = httpx.Client(timeout=timeout, headers=self.DEFAULT_HEADERS)
+        self._cache = cache or get_cache()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def _get(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """
+        Make a GET request.
+
+        Args:
+            url: Request URL.
+            params: Query parameters.
+            headers: Request headers.
+
+        Returns:
+            HTTP response.
+        """
+        response = self._client.get(url, params=params, headers=headers)
+        response.raise_for_status()
+        return response
+
+    def _post(
+        self,
+        url: str,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """
+        Make a POST request.
+
+        Args:
+            url: Request URL.
+            data: Form data.
+            json: JSON data.
+            headers: Request headers.
+
+        Returns:
+            HTTP response.
+        """
+        response = self._client.post(url, data=data, json=json, headers=headers)
+        response.raise_for_status()
+        return response
+
+    def _cache_get(self, key: str) -> Any | None:
+        """Get a value from cache."""
+        return self._cache.get(key)
+
+    def _cache_set(self, key: str, value: Any, ttl: int) -> None:
+        """Set a value in cache."""
+        self._cache.set(key, value, ttl)

borsapy/_providers/bist_index.py

@@ -0,0 +1,150 @@
+"""BIST index constituent provider - downloads index components from BIST CSV."""
+
+from io import StringIO
+from typing import Any
+
+import pandas as pd
+
+from borsapy._providers.base import BaseProvider
+from borsapy.cache import TTL
+
+# BIST index components CSV URL
+INDEX_COMPONENTS_URL = "https://www.borsaistanbul.com/datum/hisse_endeks_ds.csv"
+
+# Singleton instance
+_provider: "BistIndexProvider | None" = None
+
+
+def get_bist_index_provider() -> "BistIndexProvider":
+    """Get or create the singleton BistIndexProvider instance."""
+    global _provider
+    if _provider is None:
+        _provider = BistIndexProvider()
+    return _provider
+
+
+class BistIndexProvider(BaseProvider):
+    """Provider for BIST index constituents from official CSV file."""
+
+    def __init__(self):
+        super().__init__(timeout=30.0)
+        self._df_cache: pd.DataFrame | None = None
+
+    def _download_components(self) -> pd.DataFrame | None:
+        """Download and cache the components CSV."""
+        if self._df_cache is not None:
+            return self._df_cache
+
+        # Check memory cache first
+        cache_key = "bist:index:components:all"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            self._df_cache = cached
+            return cached
+
+        try:
+            response = self._get(INDEX_COMPONENTS_URL)
+            df = pd.read_csv(StringIO(response.text), sep=";")
+            # Skip header row (has English column names)
+            df = df.iloc[1:]
+            # Clean up symbol codes (remove .E suffix)
+            df["symbol"] = df["BILESEN KODU"].str.replace(r"\.E$", "", regex=True)
+            df["name"] = df["BULTEN_ADI"]
+            df["index_code"] = df["ENDEKS KODU"]
+            df["index_name"] = df["ENDEKS ADI"]
+
+            self._df_cache = df
+            self._cache_set(cache_key, df, TTL.COMPANY_LIST)
+            return df
+        except Exception:
+            return None
+
+    def get_components(self, symbol: str) -> list[dict[str, Any]]:
+        """
+        Get constituent stocks for an index.
+
+        Args:
+            symbol: Index symbol (e.g., "XU100", "XU030", "XKTUM").
+
+        Returns:
+            List of component dicts with 'symbol' and 'name' keys.
+            Empty list if index not found or fetch fails.
+
+        Examples:
+            >>> provider = get_bist_index_provider()
+            >>> provider.get_components("XU030")
+            [{'symbol': 'AKBNK', 'name': 'AKBANK'}, ...]
+        """
+        symbol = symbol.upper()
+
+        df = self._download_components()
+        if df is None:
+            return []
+
+        # Filter by index code
+        mask = df["index_code"] == symbol
+        components = df[mask][["symbol", "name"]].to_dict("records")
+
+        return components
+
+    def get_available_indices(self) -> list[dict[str, Any]]:
+        """
+        Get list of all indices with component counts.
+
+        Returns:
+            List of dicts with 'symbol', 'name', and 'count' keys.
+        """
+        df = self._download_components()
+        if df is None:
+            return []
+
+        # Group by index code
+        grouped = df.groupby(["index_code", "index_name"]).size().reset_index(name="count")
+        indices = [
+            {"symbol": row["index_code"], "name": row["index_name"], "count": row["count"]}
+            for _, row in grouped.iterrows()
+        ]
+
+        return sorted(indices, key=lambda x: x["symbol"])
+
+    def is_in_index(self, ticker: str, index_symbol: str) -> bool:
+        """
+        Check if a stock is in a specific index.
+
+        Args:
+            ticker: Stock symbol (e.g., "THYAO").
+            index_symbol: Index symbol (e.g., "XU030").
+
+        Returns:
+            True if stock is in the index.
+        """
+        ticker = ticker.upper()
+        index_symbol = index_symbol.upper()
+
+        df = self._download_components()
+        if df is None:
+            return False
+
+        mask = (df["symbol"] == ticker) & (df["index_code"] == index_symbol)
+        return mask.any()
+
+    def get_indices_for_ticker(self, ticker: str) -> list[str]:
+        """
+        Get all indices that contain a specific stock.
+
+        Args:
+            ticker: Stock symbol (e.g., "THYAO").
+
+        Returns:
+            List of index symbols that contain this stock.
+        """
+        ticker = ticker.upper()
+
+        df = self._download_components()
+        if df is None:
+            return []
+
+        mask = df["symbol"] == ticker
+        indices = df[mask]["index_code"].unique().tolist()
+
+        return sorted(indices)

borsapy/_providers/btcturk.py

@@ -0,0 +1,230 @@
+"""BtcTurk provider for cryptocurrency data."""
+
+from datetime import datetime, timedelta
+from typing import Any
+
+import pandas as pd
+
+from borsapy._providers.base import BaseProvider
+from borsapy.cache import TTL
+from borsapy.exceptions import APIError, DataNotAvailableError
+
+
+class BtcTurkProvider(BaseProvider):
+    """
+    Provider for cryptocurrency data from BtcTurk.
+
+    Provides:
+    - Real-time ticker data for crypto pairs
+    - Historical OHLC data
+    """
+
+    BASE_URL = "https://api.btcturk.com/api/v2"
+    GRAPH_API_URL = "https://graph-api.btcturk.com"
+
+    # Resolution mapping (minutes)
+    RESOLUTION_MAP = {
+        "1m": 1,
+        "5m": 5,
+        "15m": 15,
+        "30m": 30,
+        "1h": 60,
+        "4h": 240,
+        "1d": 1440,
+        "1wk": 10080,
+    }
+
+    def get_ticker(self, pair: str) -> dict[str, Any]:
+        """
+        Get current ticker data for a crypto pair.
+
+        Args:
+            pair: Trading pair (e.g., "BTCTRY", "ETHTRY", "BTCUSDT")
+
+        Returns:
+            Dictionary with ticker data.
+        """
+        pair = pair.upper()
+
+        cache_key = f"btcturk:ticker:{pair}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            url = f"{self.BASE_URL}/ticker"
+            params = {"pairSymbol": pair}
+
+            response = self._client.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+
+            if not data.get("success", False):
+                raise APIError(f"API error: {data.get('message', 'Unknown')}")
+
+            ticker_data = data.get("data", [])
+            if not ticker_data:
+                raise DataNotAvailableError(f"No data for pair: {pair}")
+
+            ticker = ticker_data[0] if isinstance(ticker_data, list) else ticker_data
+
+            result = {
+                "symbol": ticker.get("pair"),
+                "last": float(ticker.get("last", 0)),
+                "open": float(ticker.get("open", 0)),
+                "high": float(ticker.get("high", 0)),
+                "low": float(ticker.get("low", 0)),
+                "bid": float(ticker.get("bid", 0)),
+                "ask": float(ticker.get("ask", 0)),
+                "volume": float(ticker.get("volume", 0)),
+                "change": float(ticker.get("daily", 0)),
+                "change_percent": float(ticker.get("dailyPercent", 0)),
+                "timestamp": ticker.get("timestamp"),
+            }
+
+            self._cache_set(cache_key, result, TTL.REALTIME_PRICE)
+            return result
+
+        except Exception as e:
+            raise APIError(f"Failed to fetch ticker for {pair}: {e}") from e
+
+    def get_history(
+        self,
+        pair: str,
+        period: str = "1mo",
+        interval: str = "1d",
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get historical OHLC data for a crypto pair.
+
+        Args:
+            pair: Trading pair (e.g., "BTCTRY", "ETHTRY")
+            period: Data period (1d, 5d, 1mo, 3mo, 6mo, 1y)
+            interval: Data interval (1m, 5m, 15m, 30m, 1h, 4h, 1d, 1wk)
+            start: Start date
+            end: End date
+
+        Returns:
+            DataFrame with OHLCV data.
+        """
+        pair = pair.upper()
+
+        # Calculate time range
+        end_dt = end or datetime.now()
+        if start:
+            start_dt = start
+        else:
+            days = {"1d": 1, "5d": 5, "1mo": 30, "3mo": 90, "6mo": 180, "1y": 365}.get(period, 30)
+            start_dt = end_dt - timedelta(days=days)
+
+        from_ts = int(start_dt.timestamp())
+        to_ts = int(end_dt.timestamp())
+
+        cache_key = f"btcturk:history:{pair}:{interval}:{from_ts}:{to_ts}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            # Get resolution in minutes
+            resolution = self.RESOLUTION_MAP.get(interval, 1440)
+
+            url = f"{self.GRAPH_API_URL}/v1/klines/history"
+            params = {
+                "symbol": pair,
+                "resolution": resolution,
+                "from": from_ts,
+                "to": to_ts,
+            }
+
+            response = self._client.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+
+            # Graph API returns TradingView format
+            status = data.get("s", "error")
+            if status != "ok":
+                raise DataNotAvailableError(f"No data available for {pair}")
+
+            # Parse TradingView format
+            timestamps = data.get("t", [])
+            opens = data.get("o", [])
+            highs = data.get("h", [])
+            lows = data.get("l", [])
+            closes = data.get("c", [])
+            volumes = data.get("v", [])
+
+            records = []
+            for i in range(len(timestamps)):
+                records.append(
+                    {
+                        "Date": datetime.fromtimestamp(timestamps[i]),
+                        "Open": float(opens[i]) if i < len(opens) else 0.0,
+                        "High": float(highs[i]) if i < len(highs) else 0.0,
+                        "Low": float(lows[i]) if i < len(lows) else 0.0,
+                        "Close": float(closes[i]) if i < len(closes) else 0.0,
+                        "Volume": float(volumes[i]) if i < len(volumes) else 0.0,
+                    }
+                )
+
+            df = pd.DataFrame(records)
+            if not df.empty:
+                df.set_index("Date", inplace=True)
+                df.sort_index(inplace=True)
+
+            self._cache_set(cache_key, df, TTL.OHLCV_HISTORY)
+            return df
+
+        except Exception as e:
+            raise APIError(f"Failed to fetch history for {pair}: {e}") from e
+
+    def get_pairs(self, quote: str = "TRY") -> list[str]:
+        """
+        Get list of available trading pairs.
+
+        Args:
+            quote: Quote currency filter (TRY, USDT, BTC)
+
+        Returns:
+            List of trading pair symbols.
+        """
+        cache_key = f"btcturk:pairs:{quote}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            url = f"{self.BASE_URL}/ticker"
+            response = self._client.get(url)
+            response.raise_for_status()
+            data = response.json()
+
+            if not data.get("success", False):
+                return []
+
+            pairs = []
+            quote_upper = quote.upper()
+            for ticker in data.get("data", []):
+                pair = ticker.get("pair", "")
+                if pair.endswith(quote_upper):
+                    pairs.append(pair)
+
+            self._cache_set(cache_key, pairs, TTL.COMPANY_LIST)
+            return pairs
+
+        except Exception:
+            return []
+
+
+# Singleton
+_provider: BtcTurkProvider | None = None
+
+
+def get_btcturk_provider() -> BtcTurkProvider:
+    """Get singleton provider instance."""
+    global _provider
+    if _provider is None:
+        _provider = BtcTurkProvider()
+    return _provider