borsapy 0.4.0__py3-none-any.whl

borsapy/_providers/viop.py

@@ -0,0 +1,204 @@
+"""VİOP provider for derivatives data via İş Yatırım HTML scraping."""
+
+import pandas as pd
+from bs4 import BeautifulSoup
+
+from borsapy._providers.base import BaseProvider
+from borsapy.cache import TTL
+from borsapy.exceptions import APIError
+
+# Singleton instance
+_viop_provider: "ViOpProvider | None" = None
+
+
+def get_viop_provider() -> "ViOpProvider":
+    """Get singleton VİOP provider instance."""
+    global _viop_provider
+    if _viop_provider is None:
+        _viop_provider = ViOpProvider()
+    return _viop_provider
+
+
+class ViOpProvider(BaseProvider):
+    """
+    Provider for VİOP (Vadeli İşlem ve Opsiyon Piyasası) data.
+
+    Data source: İş Yatırım VİOP page (HTML scraping)
+    Note: Data is delayed by ~15 minutes (Matriks source)
+    """
+
+    URL = "https://www.isyatirim.com.tr/tr-tr/analiz/Sayfalar/viop.aspx"
+
+    # Table section identifiers (Turkish)
+    SECTIONS = {
+        "stock_futures": "Pay Vadeli İşlem Ana Pazarı",
+        "index_futures": "Endeks Vadeli İşlem Ana Pazarı",
+        "currency_futures": "Döviz Vadeli İşlem Ana Pazarı",
+        "commodity_futures": "Kıymetli Madenler Vadeli İşlem Ana Pazarı",
+        "stock_options": "Pay Opsiyon Ana Pazarı",
+        "index_options": "Endeks Opsiyon Ana Pazarı",
+    }
+
+    def _fetch_page(self) -> BeautifulSoup:
+        """Fetch and parse VİOP page."""
+        cache_key = "viop:page"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            response = self._get(self.URL)
+            soup = BeautifulSoup(response.text, "html.parser")
+            self._cache_set(cache_key, soup, TTL.VIOP)
+            return soup
+        except Exception as e:
+            raise APIError(f"Failed to fetch VİOP page: {e}") from e
+
+    def _parse_table(self, soup: BeautifulSoup, section_name: str) -> pd.DataFrame:
+        """Parse a VİOP table section."""
+        # Find accordion with the section name
+        accordion = None
+        for a_tag in soup.find_all("a"):
+            if a_tag.get_text(strip=True) == section_name:
+                accordion = a_tag.find_parent("div", class_="accordion-item")
+                break
+
+        if accordion is None:
+            return pd.DataFrame()
+
+        # Find table within accordion
+        table = accordion.find("table")
+        if table is None:
+            return pd.DataFrame()
+
+        rows = []
+        for tr in table.find_all("tr"):
+            tds = tr.find_all("td")
+            if len(tds) >= 5:
+                # Extract contract code from title attribute
+                first_td = tds[0]
+                title = first_td.get("title", "")
+                contract_code = ""
+                if "|" in title:
+                    contract_code = title.split("|")[0].strip()
+
+                contract_name = first_td.get_text(strip=True)
+                price = self._parse_number(tds[1].get_text(strip=True))
+                change = self._parse_number(tds[2].get_text(strip=True))
+                volume_tl = self._parse_number(tds[3].get_text(strip=True))
+                volume_qty = self._parse_number(tds[4].get_text(strip=True))
+
+                rows.append({
+                    "code": contract_code,
+                    "contract": contract_name,
+                    "price": price,
+                    "change": change,
+                    "volume_tl": volume_tl,
+                    "volume_qty": volume_qty,
+                })
+
+        if not rows:
+            return pd.DataFrame()
+
+        return pd.DataFrame(rows)
+
+    def _parse_number(self, text: str) -> float | None:
+        """Parse Turkish number format (1.234,56 -> 1234.56)."""
+        if not text:
+            return None
+        try:
+            # Remove thousand separator (.) and convert decimal separator (,) to (.)
+            cleaned = text.replace(".", "").replace(",", ".")
+            return float(cleaned)
+        except (ValueError, TypeError):
+            return None
+
+    def get_futures(self, category: str = "all") -> pd.DataFrame:
+        """
+        Get futures contracts.
+
+        Args:
+            category: Filter by category:
+                - "all": All futures
+                - "stock": Stock futures (Pay Vadeli)
+                - "index": Index futures (Endeks Vadeli)
+                - "currency": Currency futures (Döviz Vadeli)
+                - "commodity": Commodity futures (Kıymetli Madenler)
+
+        Returns:
+            DataFrame with columns: code, contract, price, change, volume_tl, volume_qty
+        """
+        soup = self._fetch_page()
+
+        category_map = {
+            "stock": ["stock_futures"],
+            "index": ["index_futures"],
+            "currency": ["currency_futures"],
+            "commodity": ["commodity_futures"],
+            "all": ["stock_futures", "index_futures", "currency_futures", "commodity_futures"],
+        }
+
+        sections = category_map.get(category, category_map["all"])
+        dfs = []
+
+        for section_key in sections:
+            section_name = self.SECTIONS.get(section_key)
+            if section_name:
+                df = self._parse_table(soup, section_name)
+                if not df.empty:
+                    df["category"] = section_key.replace("_futures", "")
+                    dfs.append(df)
+
+        if not dfs:
+            return pd.DataFrame(columns=["code", "contract", "price", "change", "volume_tl", "volume_qty", "category"])
+
+        return pd.concat(dfs, ignore_index=True)
+
+    def get_options(self, category: str = "all") -> pd.DataFrame:
+        """
+        Get options contracts.
+
+        Args:
+            category: Filter by category:
+                - "all": All options
+                - "stock": Stock options (Pay Opsiyon)
+                - "index": Index options (Endeks Opsiyon)
+
+        Returns:
+            DataFrame with columns: code, contract, price, change, volume_tl, volume_qty
+        """
+        soup = self._fetch_page()
+
+        category_map = {
+            "stock": ["stock_options"],
+            "index": ["index_options"],
+            "all": ["stock_options", "index_options"],
+        }
+
+        sections = category_map.get(category, category_map["all"])
+        dfs = []
+
+        for section_key in sections:
+            section_name = self.SECTIONS.get(section_key)
+            if section_name:
+                df = self._parse_table(soup, section_name)
+                if not df.empty:
+                    df["category"] = section_key.replace("_options", "")
+                    dfs.append(df)
+
+        if not dfs:
+            return pd.DataFrame(columns=["code", "contract", "price", "change", "volume_tl", "volume_qty", "category"])
+
+        return pd.concat(dfs, ignore_index=True)
+
+    def get_all(self) -> dict[str, pd.DataFrame]:
+        """
+        Get all VİOP data.
+
+        Returns:
+            Dictionary with 'futures' and 'options' DataFrames.
+        """
+        return {
+            "futures": self.get_futures("all"),
+            "options": self.get_options("all"),
+        }

borsapy/bond.py

@@ -0,0 +1,162 @@
+"""Bond class for Turkish government bond yields - yfinance-like API."""
+
+from typing import Any
+
+import pandas as pd
+
+from borsapy._providers.dovizcom_tahvil import get_tahvil_provider
+
+
+class Bond:
+    """
+    A yfinance-like interface for Turkish government bond data.
+
+    Data source: doviz.com/tahvil
+
+    Examples:
+        >>> import borsapy as bp
+        >>> bond = bp.Bond("10Y")
+        >>> bond.yield_rate  # Current yield (e.g., 28.03)
+        28.03
+        >>> bond.yield_decimal  # As decimal (e.g., 0.2803)
+        0.2803
+        >>> bond.change_pct  # Daily change percentage
+        1.5
+
+        >>> bp.bonds()  # Get all bond yields
+                  name maturity   yield  change  change_pct
+        0  2 Yıllık Tahvil       2Y   26.42    0.40        1.54
+        1  5 Yıllık Tahvil       5Y   27.15    0.35        1.31
+        2 10 Yıllık Tahvil      10Y   28.03    0.42        1.52
+    """
+
+    # Valid maturities
+    MATURITIES = ["2Y", "5Y", "10Y"]
+
+    def __init__(self, maturity: str):
+        """
+        Initialize a Bond object.
+
+        Args:
+            maturity: Bond maturity (2Y, 5Y, 10Y).
+        """
+        self._maturity = maturity.upper()
+        self._provider = get_tahvil_provider()
+        self._data_cache: dict[str, Any] | None = None
+
+    @property
+    def maturity(self) -> str:
+        """Return the bond maturity."""
+        return self._maturity
+
+    @property
+    def _data(self) -> dict[str, Any]:
+        """Get bond data (cached)."""
+        if self._data_cache is None:
+            self._data_cache = self._provider.get_bond(self._maturity)
+        return self._data_cache
+
+    @property
+    def name(self) -> str:
+        """Return the bond name."""
+        return self._data.get("name", "")
+
+    @property
+    def yield_rate(self) -> float | None:
+        """
+        Return the current yield as percentage.
+
+        Returns:
+            Yield rate as percentage (e.g., 28.03 for 28.03%).
+        """
+        return self._data.get("yield")
+
+    @property
+    def yield_decimal(self) -> float | None:
+        """
+        Return the current yield as decimal.
+
+        Returns:
+            Yield rate as decimal (e.g., 0.2803 for 28.03%).
+            Useful for financial calculations.
+        """
+        return self._data.get("yield_decimal")
+
+    @property
+    def change(self) -> float | None:
+        """Return the absolute change in yield."""
+        return self._data.get("change")
+
+    @property
+    def change_pct(self) -> float | None:
+        """Return the percentage change in yield."""
+        return self._data.get("change_pct")
+
+    @property
+    def info(self) -> dict[str, Any]:
+        """
+        Return all bond information.
+
+        Returns:
+            Dictionary with name, maturity, yield, change, etc.
+        """
+        return self._data.copy()
+
+    def __repr__(self) -> str:
+        return f"Bond('{self._maturity}')"
+
+
+def bonds() -> pd.DataFrame:
+    """
+    Get all Turkish government bond yields.
+
+    Returns:
+        DataFrame with columns: name, maturity, yield, change, change_pct.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> bp.bonds()
+                      name maturity   yield  change  change_pct
+        0  2 Yıllık Tahvil       2Y   26.42    0.40        1.54
+        1  5 Yıllık Tahvil       5Y   27.15    0.35        1.31
+        2 10 Yıllık Tahvil      10Y   28.03    0.42        1.52
+    """
+    provider = get_tahvil_provider()
+    data = provider.get_bond_yields()
+
+    if not data:
+        return pd.DataFrame(columns=["name", "maturity", "yield", "change", "change_pct"])
+
+    df = pd.DataFrame(data)
+
+    # Select and rename columns
+    columns = {
+        "name": "name",
+        "maturity": "maturity",
+        "yield": "yield",
+        "change": "change",
+        "change_pct": "change_pct",
+    }
+
+    df = df[[c for c in columns.keys() if c in df.columns]]
+    df = df.rename(columns=columns)
+
+    return df
+
+
+def risk_free_rate() -> float | None:
+    """
+    Get the risk-free rate for Turkish market (10Y bond yield).
+
+    Returns:
+        10-year government bond yield as decimal.
+        Useful for CAPM and DCF calculations.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> rfr = bp.risk_free_rate()
+        >>> rfr
+        0.2803
+    """
+    provider = get_tahvil_provider()
+    return provider.get_10y_yield()

borsapy/cache.py

@@ -0,0 +1,86 @@
+"""TTL-based in-memory cache for borsapy."""
+
+import time
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class CacheEntry(Generic[T]):
+    """A single cache entry with value and expiration time."""
+
+    value: T
+    expires_at: float
+
+
+@dataclass
+class Cache:
+    """Thread-safe TTL-based in-memory cache."""
+
+    _store: dict[str, CacheEntry] = field(default_factory=dict)
+    _lock: Lock = field(default_factory=Lock)
+
+    def get(self, key: str) -> Any | None:
+        """Get a value from cache if it exists and hasn't expired."""
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if time.time() > entry.expires_at:
+                del self._store[key]
+                return None
+            return entry.value
+
+    def set(self, key: str, value: Any, ttl_seconds: int) -> None:
+        """Set a value in cache with TTL in seconds."""
+        with self._lock:
+            self._store[key] = CacheEntry(value=value, expires_at=time.time() + ttl_seconds)
+
+    def delete(self, key: str) -> bool:
+        """Delete a key from cache. Returns True if key existed."""
+        with self._lock:
+            if key in self._store:
+                del self._store[key]
+                return True
+            return False
+
+    def clear(self) -> None:
+        """Clear all entries from cache."""
+        with self._lock:
+            self._store.clear()
+
+    def cleanup(self) -> int:
+        """Remove expired entries. Returns number of entries removed."""
+        with self._lock:
+            now = time.time()
+            expired_keys = [k for k, v in self._store.items() if now > v.expires_at]
+            for key in expired_keys:
+                del self._store[key]
+            return len(expired_keys)
+
+
+# TTL values in seconds
+class TTL:
+    """Standard TTL values for different data types."""
+
+    REALTIME_PRICE = 60  # 1 minute
+    OHLCV_HISTORY = 3600  # 1 hour
+    COMPANY_INFO = 3600  # 1 hour
+    FINANCIAL_STATEMENTS = 86400  # 24 hours
+    FX_RATES = 300  # 5 minutes
+    COMPANY_LIST = 86400  # 24 hours
+    FUND_DATA = 3600  # 1 hour
+    INFLATION_DATA = 86400  # 24 hours
+    VIOP = 300  # 5 minutes (delayed data)
+
+
+# Global cache instance
+_cache = Cache()
+
+
+def get_cache() -> Cache:
+    """Get the global cache instance."""
+    return _cache