borsapy.index

  1"""Index class for market index data - yfinance-like API."""
  2
  3from datetime import datetime
  4from typing import Any
  5
  6import pandas as pd
  7
  8from borsapy._providers.bist_index import get_bist_index_provider
  9from borsapy._providers.tradingview import get_tradingview_provider
 10from borsapy.technical import TechnicalMixin
 11
 12# Known market indices with their names
 13INDICES = {
 14    # Main indices
 15    "XU100": "BIST 100",
 16    "XU050": "BIST 50",
 17    "XU030": "BIST 30",
 18    "XUTUM": "BIST Tüm",
 19    # Participation (Katılım) indices
 20    "XKTUM": "BIST Katılım Tüm",
 21    "XK100": "BIST Katılım 100",
 22    "XK050": "BIST Katılım 50",
 23    "XK030": "BIST Katılım 30",
 24    "XKTMT": "BIST Katılım Model Portföy",
 25    # Sector indices
 26    "XBANK": "BIST Banka",
 27    "XUSIN": "BIST Sınai",
 28    "XUMAL": "BIST Mali",
 29    "XHOLD": "BIST Holding ve Yatırım",
 30    "XUTEK": "BIST Teknoloji",
 31    "XGIDA": "BIST Gıda",
 32    "XTRZM": "BIST Turizm",
 33    "XULAS": "BIST Ulaştırma",
 34    "XSGRT": "BIST Sigorta",
 35    "XMANA": "BIST Metal Ana",
 36    "XKMYA": "BIST Kimya",
 37    "XMADN": "BIST Maden",
 38    "XELKT": "BIST Elektrik",
 39    "XTEKS": "BIST Tekstil",
 40    "XILTM": "BIST İletişim",
 41    # Thematic indices
 42    "XSRDK": "BIST Sürdürülebilirlik",
 43    "XKURY": "BIST Kurumsal Yönetim",
 44    "XYLDZ": "BIST Yıldız",
 45    "XBANA": "BIST Banka Dışı Likit 10",
 46    "XSPOR": "BIST Spor",
 47    "XGMYO": "BIST GYO",
 48    "XTUMY": "BIST Tüm-100",
 49    "XYORT": "BIST Yatırım Ortaklıkları",
 50    "XSDNZ": "BIST Seçme Divident",
 51}
 52
 53
 54class Index(TechnicalMixin):
 55    """
 56    A yfinance-like interface for Turkish market indices.
 57
 58    Examples:
 59        >>> import borsapy as bp
 60        >>> xu100 = bp.Index("XU100")
 61        >>> xu100.info
 62        {'symbol': 'XU100', 'name': 'BIST 100', 'last': 9500.5, ...}
 63        >>> xu100.history(period="1mo")
 64                         Open      High       Low     Close      Volume
 65        Date
 66        2024-12-01    9400.00  9550.00  9380.00  9500.50  1234567890
 67        ...
 68
 69        # Available indices
 70        >>> bp.indices()
 71        ['XU100', 'XU050', 'XU030', 'XBANK', ...]
 72    """
 73
 74    def __init__(self, symbol: str):
 75        """
 76        Initialize an Index object.
 77
 78        Args:
 79            symbol: Index symbol (e.g., "XU100", "XU030", "XBANK").
 80        """
 81        self._symbol = symbol.upper()
 82        self._tradingview = get_tradingview_provider()
 83        self._bist_index = get_bist_index_provider()
 84        self._info_cache: dict[str, Any] | None = None
 85        self._components_cache: list[dict[str, Any]] | None = None
 86
 87    @property
 88    def symbol(self) -> str:
 89        """Return the index symbol."""
 90        return self._symbol
 91
 92    @property
 93    def info(self) -> dict[str, Any]:
 94        """
 95        Get current index information.
 96
 97        Returns:
 98            Dictionary with index data:
 99            - symbol: Index symbol
100            - name: Index full name
101            - last: Current value
102            - open: Opening value
103            - high: Day high
104            - low: Day low
105            - close: Previous close
106            - change: Value change
107            - change_percent: Percent change
108            - update_time: Last update timestamp
109        """
110        if self._info_cache is None:
111            # Use TradingView API to get quote (same endpoint works for indices)
112            quote = self._tradingview.get_quote(self._symbol)
113            quote["name"] = INDICES.get(self._symbol, self._symbol)
114            quote["type"] = "index"
115            self._info_cache = quote
116        return self._info_cache
117
118    @property
119    def components(self) -> list[dict[str, Any]]:
120        """
121        Get constituent stocks of this index.
122
123        Returns:
124            List of component dicts with 'symbol' and 'name' keys.
125            Empty list if index components are not available.
126
127        Examples:
128            >>> import borsapy as bp
129            >>> xu030 = bp.Index("XU030")
130            >>> xu030.components
131            [{'symbol': 'AKBNK', 'name': 'AKBANK'}, ...]
132            >>> len(xu030.components)
133            30
134        """
135        if self._components_cache is None:
136            self._components_cache = self._bist_index.get_components(self._symbol)
137        return self._components_cache
138
139    @property
140    def component_symbols(self) -> list[str]:
141        """
142        Get just the ticker symbols of constituent stocks.
143
144        Returns:
145            List of stock symbols.
146
147        Examples:
148            >>> import borsapy as bp
149            >>> xu030 = bp.Index("XU030")
150            >>> xu030.component_symbols
151            ['AKBNK', 'AKSA', 'AKSEN', ...]
152        """
153        return [c["symbol"] for c in self.components]
154
155    def history(
156        self,
157        period: str = "1mo",
158        interval: str = "1d",
159        start: datetime | str | None = None,
160        end: datetime | str | None = None,
161    ) -> pd.DataFrame:
162        """
163        Get historical index data.
164
165        Args:
166            period: How much data to fetch. Valid periods:
167                    1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, ytd, max.
168                    Ignored if start is provided.
169            interval: Data interval. Valid intervals:
170                      1m, 5m, 15m, 30m, 1h, 1d, 1wk, 1mo.
171            start: Start date (string or datetime).
172            end: End date (string or datetime). Defaults to today.
173
174        Returns:
175            DataFrame with columns: Open, High, Low, Close, Volume.
176            Index is the Date.
177
178        Examples:
179            >>> idx = Index("XU100")
180            >>> idx.history(period="1mo")  # Last month
181            >>> idx.history(period="1y")  # Last year
182            >>> idx.history(start="2024-01-01", end="2024-06-30")
183        """
184        # Parse dates
185        start_dt = self._parse_date(start) if start else None
186        end_dt = self._parse_date(end) if end else None
187
188        # Use TradingView provider (same API works for indices)
189        return self._tradingview.get_history(
190            symbol=self._symbol,
191            period=period,
192            interval=interval,
193            start=start_dt,
194            end=end_dt,
195        )
196
197    def _parse_date(self, date: str | datetime) -> datetime:
198        """Parse a date string to datetime."""
199        if isinstance(date, datetime):
200            return date
201        for fmt in ["%Y-%m-%d", "%Y/%m/%d", "%d-%m-%Y", "%d/%m/%Y"]:
202            try:
203                return datetime.strptime(date, fmt)
204            except ValueError:
205                continue
206        raise ValueError(f"Could not parse date: {date}")
207
208    def _get_ta_symbol_info(self) -> tuple[str, str]:
209        """Get TradingView symbol and screener for TA signals.
210
211        Returns:
212            Tuple of (tv_symbol, screener) for TradingView Scanner API.
213        """
214        return (f"BIST:{self._symbol}", "turkey")
215
216    def scan(
217        self,
218        condition: str,
219        period: str = "3mo",
220        interval: str = "1d",
221    ) -> "pd.DataFrame":
222        """Scan index components for technical conditions.
223
224        Convenience method for scanning all stocks in this index.
225
226        Args:
227            condition: Condition string (e.g., "rsi < 30", "price > sma_50")
228            period: Historical data period for indicator calculation
229            interval: Data interval
230
231        Returns:
232            DataFrame with matching symbols and their data
233
234        Examples:
235            >>> import borsapy as bp
236            >>> xu030 = bp.Index("XU030")
237            >>> xu030.scan("rsi < 30")
238            >>> xu030.scan("price > sma_50 and rsi > 50")
239            >>> xu030.scan("sma_20 crosses_above sma_50")
240        """
241        from borsapy.scanner import scan
242
243        return scan(self.component_symbols, condition, period, interval)
244
245    def __repr__(self) -> str:
246        return f"Index('{self._symbol}')"
247
248
249def indices(detailed: bool = False) -> list[str] | list[dict[str, Any]]:
250    """
251    Get list of available market indices.
252
253    Args:
254        detailed: If True, return list of dicts with symbol, name, and count.
255                  If False (default), return just the symbol list.
256
257    Returns:
258        List of index symbols, or list of dicts if detailed=True.
259
260    Examples:
261        >>> import borsapy as bp
262        >>> bp.indices()
263        ['XU100', 'XU050', 'XU030', 'XBANK', 'XUSIN', ...]
264        >>> bp.indices(detailed=True)
265        [{'symbol': 'XU100', 'name': 'BIST 100', 'count': 100}, ...]
266    """
267    if not detailed:
268        return list(INDICES.keys())
269
270    # Get component counts from provider
271    provider = get_bist_index_provider()
272    available = provider.get_available_indices()
273
274    # Create lookup for counts
275    count_map = {item["symbol"]: item["count"] for item in available}
276
277    result = []
278    for symbol, name in INDICES.items():
279        result.append({
280            "symbol": symbol,
281            "name": name,
282            "count": count_map.get(symbol, 0),
283        })
284    return result
285
286
287def all_indices() -> list[dict[str, Any]]:
288    """
289    Get all indices from BIST with component counts.
290
291    This returns all 79 indices available in the BIST data,
292    not just the commonly used ones in indices().
293
294    Returns:
295        List of dicts with 'symbol', 'name', and 'count' keys.
296
297    Examples:
298        >>> import borsapy as bp
299        >>> bp.all_indices()
300        [{'symbol': 'X030C', 'name': 'BIST 30 Capped', 'count': 30}, ...]
301    """
302    provider = get_bist_index_provider()
303    return provider.get_available_indices()
304
305
306def index(symbol: str) -> Index:
307    """
308    Get an Index object for the given symbol.
309
310    This is a convenience function that creates an Index object.
311
312    Args:
313        symbol: Index symbol (e.g., "XU100", "XBANK").
314
315    Returns:
316        Index object.
317
318    Examples:
319        >>> import borsapy as bp
320        >>> xu100 = bp.index("XU100")
321        >>> xu100.history(period="1mo")
322    """
323    return Index(symbol)