borsapy 0.4.0__py3-none-any.whl

borsapy/inflation.py

@@ -0,0 +1,166 @@
+"""Inflation class for TCMB inflation data - yfinance-like API."""
+
+from typing import Any
+
+import pandas as pd
+
+from borsapy._providers.tcmb import get_tcmb_provider
+
+
+class Inflation:
+    """
+    A yfinance-like interface for Turkish inflation data from TCMB.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> inf = bp.Inflation()
+
+        # Get latest inflation
+        >>> inf.latest()
+        {'date': '2024-11-01', 'yearly_inflation': 47.09, 'monthly_inflation': 2.24, ...}
+
+        # Get TÜFE history
+        >>> inf.tufe(limit=12)  # Last 12 months
+                        YearMonth  YearlyInflation  MonthlyInflation
+        Date
+        2024-11-01      11-2024             47.09              2.24
+        ...
+
+        # Calculate inflation
+        >>> inf.calculate(100000, "2020-01", "2024-01")
+        {'initial_value': 100000, 'final_value': 342515.0, 'total_change': 242.52, ...}
+    """
+
+    def __init__(self):
+        """Initialize an Inflation object."""
+        self._provider = get_tcmb_provider()
+
+    def latest(self, inflation_type: str = "tufe") -> dict[str, Any]:
+        """
+        Get the latest inflation data.
+
+        Args:
+            inflation_type: 'tufe' (CPI) or 'ufe' (PPI)
+
+        Returns:
+            Dictionary with latest inflation data:
+            - date: Date string (YYYY-MM-DD)
+            - year_month: Month-Year string
+            - yearly_inflation: Year-over-year inflation rate
+            - monthly_inflation: Month-over-month inflation rate
+            - type: Inflation type (TUFE or UFE)
+        """
+        return self._provider.get_latest(inflation_type)
+
+    def tufe(
+        self,
+        start: str | None = None,
+        end: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get TÜFE (Consumer Price Index) data.
+
+        Args:
+            start: Start date in YYYY-MM-DD format
+            end: End date in YYYY-MM-DD format
+            limit: Maximum number of records
+
+        Returns:
+            DataFrame with columns: YearMonth, YearlyInflation, MonthlyInflation.
+            Index is the Date.
+
+        Examples:
+            >>> inf = Inflation()
+            >>> inf.tufe(limit=6)  # Last 6 months
+            >>> inf.tufe(start="2023-01-01", end="2023-12-31")  # 2023 data
+        """
+        return self._provider.get_data("tufe", start, end, limit)
+
+    def ufe(
+        self,
+        start: str | None = None,
+        end: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get ÜFE (Producer Price Index) data.
+
+        Args:
+            start: Start date in YYYY-MM-DD format
+            end: End date in YYYY-MM-DD format
+            limit: Maximum number of records
+
+        Returns:
+            DataFrame with columns: YearMonth, YearlyInflation, MonthlyInflation.
+            Index is the Date.
+
+        Examples:
+            >>> inf = Inflation()
+            >>> inf.ufe(limit=6)  # Last 6 months
+            >>> inf.ufe(start="2023-01-01", end="2023-12-31")  # 2023 data
+        """
+        return self._provider.get_data("ufe", start, end, limit)
+
+    def calculate(
+        self,
+        amount: float,
+        start: str,
+        end: str,
+    ) -> dict[str, Any]:
+        """
+        Calculate inflation-adjusted value between two dates.
+
+        Uses TCMB's official inflation calculator API.
+
+        Args:
+            amount: Initial amount in TRY
+            start: Start date in YYYY-MM format (e.g., "2020-01")
+            end: End date in YYYY-MM format (e.g., "2024-01")
+
+        Returns:
+            Dictionary with:
+            - start_date: Start date
+            - end_date: End date
+            - initial_value: Initial amount
+            - final_value: Inflation-adjusted value
+            - total_years: Total years elapsed
+            - total_months: Total months elapsed
+            - total_change: Total percentage change
+            - avg_yearly_inflation: Average yearly inflation rate
+            - start_cpi: CPI at start date
+            - end_cpi: CPI at end date
+
+        Examples:
+            >>> inf = Inflation()
+            >>> result = inf.calculate(100000, "2020-01", "2024-01")
+            >>> print(f"100,000 TL in 2020 = {result['final_value']:,.0f} TL in 2024")
+            100,000 TL in 2020 = 342,515 TL in 2024
+        """
+        start_year, start_month = self._parse_year_month(start)
+        end_year, end_month = self._parse_year_month(end)
+
+        return self._provider.calculate_inflation(
+            start_year=start_year,
+            start_month=start_month,
+            end_year=end_year,
+            end_month=end_month,
+            basket_value=amount,
+        )
+
+    def _parse_year_month(self, date_str: str) -> tuple[int, int]:
+        """Parse YYYY-MM format to (year, month) tuple."""
+        try:
+            parts = date_str.split("-")
+            if len(parts) != 2:
+                raise ValueError(f"Invalid date format: {date_str}. Use YYYY-MM")
+            year = int(parts[0])
+            month = int(parts[1])
+            if not (1 <= month <= 12):
+                raise ValueError(f"Invalid month: {month}")
+            return year, month
+        except Exception as e:
+            raise ValueError(f"Could not parse date '{date_str}': {e}") from e
+
+    def __repr__(self) -> str:
+        return "Inflation()"

borsapy/market.py

@@ -0,0 +1,53 @@
+"""Market-level functions for BIST data."""
+
+import pandas as pd
+
+from borsapy._providers.kap import get_kap_provider
+
+
+def companies() -> pd.DataFrame:
+    """
+    Get list of all BIST companies.
+
+    Returns:
+        DataFrame with columns:
+        - ticker: Stock ticker code (e.g., "THYAO", "GARAN")
+        - name: Company name
+        - city: Company headquarters city
+
+    Examples:
+        >>> import borsapy as bp
+        >>> bp.companies()
+              ticker                                    name        city
+        0      ACSEL            ACIPAYAM SELULOZ SANAYI A.S.     DENIZLI
+        1      ADEL                  ADEL KALEMCILIK A.S.    ISTANBUL
+        ...
+    """
+    provider = get_kap_provider()
+    return provider.get_companies()
+
+
+def search_companies(query: str) -> pd.DataFrame:
+    """
+    Search BIST companies by name or ticker.
+
+    Args:
+        query: Search query (ticker code or company name)
+
+    Returns:
+        DataFrame with matching companies, sorted by relevance.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> bp.search_companies("THYAO")
+              ticker                                    name        city
+        0      THYAO          TURK HAVA YOLLARI A.O.    ISTANBUL
+
+        >>> bp.search_companies("banka")
+              ticker                                    name        city
+        0      GARAN              TURKIYE GARANTI BANKASI A.S.  ISTANBUL
+        1      AKBNK              AKBANK T.A.S.               ISTANBUL
+        ...
+    """
+    provider = get_kap_provider()
+    return provider.search(query)

borsapy/multi.py

@@ -0,0 +1,227 @@
+"""Multi-ticker functions and classes - yfinance-like API."""
+
+from datetime import datetime
+
+import pandas as pd
+
+from borsapy._providers.paratic import get_paratic_provider
+from borsapy.ticker import Ticker
+
+
+class Tickers:
+    """
+    Container for multiple Ticker objects.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> tickers = bp.Tickers("THYAO GARAN AKBNK")
+        >>> tickers.tickers["THYAO"].info
+        >>> tickers.symbols
+        ['THYAO', 'GARAN', 'AKBNK']
+
+        >>> tickers = bp.Tickers(["THYAO", "GARAN", "AKBNK"])
+        >>> for symbol, ticker in tickers:
+        ...     print(symbol, ticker.info['last'])
+    """
+
+    def __init__(self, symbols: str | list[str]):
+        """
+        Initialize Tickers with multiple symbols.
+
+        Args:
+            symbols: Space-separated string or list of symbols.
+                     Example: "THYAO GARAN AKBNK" or ["THYAO", "GARAN", "AKBNK"]
+        """
+        if isinstance(symbols, str):
+            self._symbols = [s.strip().upper() for s in symbols.split() if s.strip()]
+        else:
+            self._symbols = [s.strip().upper() for s in symbols if s.strip()]
+
+        self._tickers: dict[str, Ticker] = {}
+        for symbol in self._symbols:
+            self._tickers[symbol] = Ticker(symbol)
+
+    @property
+    def symbols(self) -> list[str]:
+        """Return list of symbols."""
+        return self._symbols.copy()
+
+    @property
+    def tickers(self) -> dict[str, Ticker]:
+        """Return dictionary of Ticker objects keyed by symbol."""
+        return self._tickers
+
+    def history(
+        self,
+        period: str = "1mo",
+        interval: str = "1d",
+        start: datetime | str | None = None,
+        end: datetime | str | None = None,
+        group_by: str = "column",
+    ) -> pd.DataFrame:
+        """
+        Get historical data for all tickers.
+
+        Args:
+            period: Data period (1d, 5d, 1mo, 3mo, 6mo, 1y, etc.)
+            interval: Data interval (1d, 1wk, 1mo)
+            start: Start date
+            end: End date
+            group_by: How to group columns ('column' or 'ticker')
+
+        Returns:
+            DataFrame with multi-level columns.
+        """
+        return download(
+            self._symbols,
+            period=period,
+            interval=interval,
+            start=start,
+            end=end,
+            group_by=group_by,
+        )
+
+    def __iter__(self):
+        """Iterate over (symbol, ticker) pairs."""
+        return iter(self._tickers.items())
+
+    def __len__(self) -> int:
+        """Return number of tickers."""
+        return len(self._tickers)
+
+    def __getitem__(self, symbol: str) -> Ticker:
+        """Get ticker by symbol."""
+        symbol = symbol.upper()
+        if symbol not in self._tickers:
+            raise KeyError(f"Symbol not found: {symbol}")
+        return self._tickers[symbol]
+
+    def __repr__(self) -> str:
+        return f"Tickers({self._symbols})"
+
+
+def download(
+    tickers: str | list[str],
+    period: str = "1mo",
+    interval: str = "1d",
+    start: datetime | str | None = None,
+    end: datetime | str | None = None,
+    group_by: str = "column",
+    progress: bool = True,
+) -> pd.DataFrame:
+    """
+    Download historical data for multiple tickers.
+
+    Similar to yfinance.download(), this function fetches OHLCV data
+    for multiple stocks and returns a DataFrame with multi-level columns.
+
+    Args:
+        tickers: Space-separated string or list of symbols.
+                 Example: "THYAO GARAN AKBNK" or ["THYAO", "GARAN"]
+        period: Data period. Valid values:
+                1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max.
+                Ignored if start is provided.
+        interval: Data interval. Valid values:
+                  1m, 5m, 15m, 30m, 1h, 1d, 1wk, 1mo.
+        start: Start date (string YYYY-MM-DD or datetime).
+        end: End date (string YYYY-MM-DD or datetime). Defaults to today.
+        group_by: How to group the output columns:
+                  - 'column': MultiIndex (Price, Symbol) - default
+                  - 'ticker': MultiIndex (Symbol, Price)
+        progress: Show progress (not implemented, for yfinance compatibility).
+
+    Returns:
+        DataFrame with OHLCV data.
+        - If single ticker: Simple columns (Open, High, Low, Close, Volume)
+        - If multiple tickers: MultiIndex columns based on group_by
+
+    Examples:
+        >>> import borsapy as bp
+
+        # Single ticker (returns simple DataFrame)
+        >>> bp.download("THYAO", period="1mo")
+                         Open    High     Low   Close    Volume
+        Date
+        2024-12-01    265.00  268.00  264.00  267.50  12345678
+
+        # Multiple tickers (returns MultiIndex DataFrame)
+        >>> bp.download(["THYAO", "GARAN"], period="1mo")
+                           Open                 High          ...
+                          THYAO   GARAN        THYAO   GARAN
+        Date
+        2024-12-01       265.00  45.50        268.00   46.20
+
+        # With date range
+        >>> bp.download("THYAO GARAN AKBNK", start="2024-01-01", end="2024-06-30")
+
+        # Group by ticker
+        >>> bp.download(["THYAO", "GARAN"], group_by="ticker")
+                          THYAO                      GARAN
+                           Open    High  Low Close   Open    High
+        Date
+        2024-12-01       265.00  268.00  ...        45.50   46.20
+    """
+    # Parse symbols
+    if isinstance(tickers, str):
+        symbols = [s.strip().upper() for s in tickers.split() if s.strip()]
+    else:
+        symbols = [s.strip().upper() for s in tickers if s.strip()]
+
+    if not symbols:
+        raise ValueError("No symbols provided")
+
+    # Parse dates
+    start_dt = _parse_date(start) if start else None
+    end_dt = _parse_date(end) if end else None
+
+    provider = get_paratic_provider()
+
+    # Fetch data for each symbol
+    data_frames: dict[str, pd.DataFrame] = {}
+    for symbol in symbols:
+        try:
+            df = provider.get_history(
+                symbol=symbol,
+                period=period,
+                interval=interval,
+                start=start_dt,
+                end=end_dt,
+            )
+            if not df.empty:
+                data_frames[symbol] = df
+        except Exception:
+            # Skip failed symbols silently (yfinance behavior)
+            continue
+
+    if not data_frames:
+        return pd.DataFrame()
+
+    # Single ticker - return simple DataFrame
+    if len(symbols) == 1 and len(data_frames) == 1:
+        return list(data_frames.values())[0]
+
+    # Multiple tickers - create MultiIndex DataFrame
+    if group_by == "ticker":
+        # Group by ticker first: (THYAO, Open), (THYAO, High), ...
+        result = pd.concat(data_frames, axis=1)
+        # result columns are already (symbol, price)
+    else:
+        # Group by column first: (Open, THYAO), (Open, GARAN), ...
+        result = pd.concat(data_frames, axis=1)
+        # Swap levels to get (price, symbol)
+        result = result.swaplevel(axis=1)
+        result = result.sort_index(axis=1, level=0)
+
+    return result
+
+
+def _parse_date(date: str | datetime) -> datetime:
+    """Parse a date string to datetime."""
+    if isinstance(date, datetime):
+        return date
+    for fmt in ["%Y-%m-%d", "%Y/%m/%d", "%d-%m-%Y", "%d/%m/%Y"]:
+        try:
+            return datetime.strptime(date, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"Could not parse date: {date}")