borsapy 0.4.0__py3-none-any.whl

borsapy/calendar.py

@@ -0,0 +1,272 @@
+"""EconomicCalendar class for economic events - yfinance-like API."""
+
+from datetime import datetime, timedelta
+from typing import Any
+
+import pandas as pd
+
+from borsapy._providers.dovizcom_calendar import get_calendar_provider
+
+
+class EconomicCalendar:
+    """
+    A yfinance-like interface for economic calendar data.
+
+    Data source: doviz.com
+
+    Examples:
+        >>> import borsapy as bp
+        >>> cal = bp.EconomicCalendar()
+        >>> cal.events(period="1w")  # This week's events
+                         Date      Time Country  Importance              Event Actual Forecast Previous
+        0 2024-01-15  10:00:00  Türkiye        high  Enflasyon (YoY)  64.77%   65.00%   61.98%
+        ...
+
+        >>> cal.today()  # Today's events
+        >>> cal.events(country="TR", importance="high")  # High importance TR events
+    """
+
+    # Valid country codes
+    COUNTRIES = ["TR", "US", "EU", "DE", "GB", "JP", "CN", "FR", "IT", "CA", "AU", "CH"]
+
+    def __init__(self):
+        """Initialize EconomicCalendar."""
+        self._provider = get_calendar_provider()
+
+    def events(
+        self,
+        period: str = "1w",
+        start: datetime | str | None = None,
+        end: datetime | str | None = None,
+        country: str | list[str] | None = None,
+        importance: str | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get economic calendar events.
+
+        Args:
+            period: How much data to fetch. Valid periods: 1d, 1w, 2w, 1mo.
+                    Ignored if start is provided.
+            start: Start date (string or datetime).
+            end: End date (string or datetime). Defaults to start + period.
+            country: Country code(s) to filter by (TR, US, EU, etc.).
+                     Can be a single code or list of codes.
+                     Defaults to ['TR', 'US'].
+            importance: Filter by importance level ('low', 'mid', 'high').
+
+        Returns:
+            DataFrame with columns: Date, Time, Country, Importance, Event,
+                                    Actual, Forecast, Previous, Period.
+
+        Examples:
+            >>> cal = EconomicCalendar()
+            >>> cal.events(period="1w")  # Next 7 days
+            >>> cal.events(country="TR", importance="high")  # High importance TR events
+            >>> cal.events(country=["TR", "US", "EU"])  # Multiple countries
+            >>> cal.events(start="2024-01-01", end="2024-01-31")  # Date range
+        """
+        # Parse dates
+        start_dt = self._parse_date(start) if start else None
+        end_dt = self._parse_date(end) if end else None
+
+        # If no start, use today
+        if start_dt is None:
+            start_dt = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+
+        # If no end, calculate from period
+        if end_dt is None:
+            days = {"1d": 1, "1w": 7, "2w": 14, "1mo": 30}.get(period, 7)
+            end_dt = start_dt + timedelta(days=days)
+
+        # Parse country parameter
+        countries = self._parse_countries(country)
+
+        # Fetch events
+        events = self._provider.get_economic_calendar(
+            start=start_dt,
+            end=end_dt,
+            countries=countries,
+            importance=importance,
+        )
+
+        # Convert to DataFrame
+        if not events:
+            return pd.DataFrame(
+                columns=[
+                    "Date",
+                    "Time",
+                    "Country",
+                    "Importance",
+                    "Event",
+                    "Actual",
+                    "Forecast",
+                    "Previous",
+                    "Period",
+                ]
+            )
+
+        df = pd.DataFrame(events)
+
+        # Rename columns
+        df = df.rename(
+            columns={
+                "date": "Date",
+                "time": "Time",
+                "country": "Country",
+                "importance": "Importance",
+                "event": "Event",
+                "actual": "Actual",
+                "forecast": "Forecast",
+                "previous": "Previous",
+                "period": "Period",
+            }
+        )
+
+        # Drop internal columns
+        if "country_code" in df.columns:
+            df = df.drop(columns=["country_code"])
+
+        # Reorder columns
+        column_order = [
+            "Date",
+            "Time",
+            "Country",
+            "Importance",
+            "Event",
+            "Actual",
+            "Forecast",
+            "Previous",
+            "Period",
+        ]
+        df = df[[c for c in column_order if c in df.columns]]
+
+        return df
+
+    def today(
+        self,
+        country: str | list[str] | None = None,
+        importance: str | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get today's economic events.
+
+        Args:
+            country: Country code(s) to filter by.
+            importance: Filter by importance level.
+
+        Returns:
+            DataFrame with today's economic events.
+        """
+        return self.events(period="1d", country=country, importance=importance)
+
+    def this_week(
+        self,
+        country: str | list[str] | None = None,
+        importance: str | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get this week's economic events.
+
+        Args:
+            country: Country code(s) to filter by.
+            importance: Filter by importance level.
+
+        Returns:
+            DataFrame with this week's economic events.
+        """
+        return self.events(period="1w", country=country, importance=importance)
+
+    def this_month(
+        self,
+        country: str | list[str] | None = None,
+        importance: str | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get this month's economic events.
+
+        Args:
+            country: Country code(s) to filter by.
+            importance: Filter by importance level.
+
+        Returns:
+            DataFrame with this month's economic events.
+        """
+        return self.events(period="1mo", country=country, importance=importance)
+
+    def high_importance(
+        self,
+        period: str = "1w",
+        country: str | list[str] | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get high importance events only.
+
+        Args:
+            period: Time period (1d, 1w, 2w, 1mo).
+            country: Country code(s) to filter by.
+
+        Returns:
+            DataFrame with high importance events.
+        """
+        return self.events(period=period, country=country, importance="high")
+
+    @staticmethod
+    def countries() -> list[str]:
+        """
+        Get list of supported country codes.
+
+        Returns:
+            List of country codes.
+
+        Examples:
+            >>> EconomicCalendar.countries()
+            ['TR', 'US', 'EU', 'DE', 'GB', 'JP', 'CN', ...]
+        """
+        return EconomicCalendar.COUNTRIES.copy()
+
+    def _parse_date(self, 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}")
+
+    def _parse_countries(self, country: str | list[str] | None) -> list[str]:
+        """Parse country parameter to list of codes."""
+        if country is None:
+            return ["TR", "US"]
+        if isinstance(country, str):
+            return [country.upper()]
+        return [c.upper() for c in country]
+
+    def __repr__(self) -> str:
+        return "EconomicCalendar()"
+
+
+def economic_calendar(
+    period: str = "1w",
+    country: str | list[str] | None = None,
+    importance: str | None = None,
+) -> pd.DataFrame:
+    """
+    Get economic calendar events (convenience function).
+
+    Args:
+        period: Time period (1d, 1w, 2w, 1mo). Defaults to 1w.
+        country: Country code(s) to filter by. Defaults to ['TR', 'US'].
+        importance: Filter by importance level ('low', 'mid', 'high').
+
+    Returns:
+        DataFrame with economic events.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> bp.economic_calendar()  # This week, TR + US
+        >>> bp.economic_calendar(country="TR", importance="high")
+    """
+    cal = EconomicCalendar()
+    return cal.events(period=period, country=country, importance=importance)

borsapy/crypto.py

@@ -0,0 +1,153 @@
+"""Crypto class for cryptocurrency data - yfinance-like API."""
+
+from datetime import datetime
+from typing import Any
+
+import pandas as pd
+
+from borsapy._providers.btcturk import get_btcturk_provider
+
+
+class Crypto:
+    """
+    A yfinance-like interface for cryptocurrency data from BtcTurk.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> btc = bp.Crypto("BTCTRY")
+        >>> btc.current
+        {'symbol': 'BTCTRY', 'last': 3500000.0, ...}
+        >>> btc.history(period="1mo")
+                             Open       High        Low      Close      Volume
+        Date
+        2024-12-01   3400000.0  3550000.0  3380000.0  3500000.0   1234.5678
+        ...
+
+        >>> eth = bp.Crypto("ETHTRY")
+        >>> eth.current['last']
+        125000.0
+    """
+
+    def __init__(self, pair: str):
+        """
+        Initialize a Crypto object.
+
+        Args:
+            pair: Trading pair (e.g., "BTCTRY", "ETHTRY", "BTCUSDT").
+                  Common pairs: BTCTRY, ETHTRY, XRPTRY, DOGETRY, SOLTRY
+        """
+        self._pair = pair.upper()
+        self._provider = get_btcturk_provider()
+        self._current_cache: dict[str, Any] | None = None
+
+    @property
+    def pair(self) -> str:
+        """Return the trading pair."""
+        return self._pair
+
+    @property
+    def symbol(self) -> str:
+        """Return the trading pair (alias)."""
+        return self._pair
+
+    @property
+    def current(self) -> dict[str, Any]:
+        """
+        Get current ticker information.
+
+        Returns:
+            Dictionary with current market data:
+            - symbol: Trading pair
+            - last: Last traded price
+            - open: Opening price
+            - high: 24h high
+            - low: 24h low
+            - bid: Best bid price
+            - ask: Best ask price
+            - volume: 24h volume
+            - change: Price change
+            - change_percent: Percent change
+        """
+        if self._current_cache is None:
+            self._current_cache = self._provider.get_ticker(self._pair)
+        return self._current_cache
+
+    @property
+    def info(self) -> dict[str, Any]:
+        """Alias for current property (yfinance compatibility)."""
+        return self.current
+
+    def history(
+        self,
+        period: str = "1mo",
+        interval: str = "1d",
+        start: datetime | str | None = None,
+        end: datetime | str | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get historical OHLCV data.
+
+        Args:
+            period: How much data to fetch. Valid periods:
+                    1d, 5d, 1mo, 3mo, 6mo, 1y.
+                    Ignored if start is provided.
+            interval: Data granularity. Valid intervals:
+                      1m, 5m, 15m, 30m, 1h, 4h, 1d, 1wk.
+            start: Start date (string or datetime).
+            end: End date (string or datetime). Defaults to now.
+
+        Returns:
+            DataFrame with columns: Open, High, Low, Close, Volume.
+            Index is the Date.
+
+        Examples:
+            >>> crypto = Crypto("BTCTRY")
+            >>> crypto.history(period="1mo")  # Last month
+            >>> crypto.history(period="1y", interval="1wk")  # Weekly for 1 year
+            >>> crypto.history(start="2024-01-01", end="2024-06-30")  # Date range
+        """
+        start_dt = self._parse_date(start) if start else None
+        end_dt = self._parse_date(end) if end else None
+
+        return self._provider.get_history(
+            pair=self._pair,
+            period=period,
+            interval=interval,
+            start=start_dt,
+            end=end_dt,
+        )
+
+    def _parse_date(self, 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}")
+
+    def __repr__(self) -> str:
+        return f"Crypto('{self._pair}')"
+
+
+def crypto_pairs(quote: str = "TRY") -> list[str]:
+    """
+    Get list of available cryptocurrency trading pairs.
+
+    Args:
+        quote: Quote currency filter (TRY, USDT, BTC)
+
+    Returns:
+        List of available trading pair symbols.
+
+    Examples:
+        >>> import borsapy as bp
+        >>> bp.crypto_pairs()
+        ['BTCTRY', 'ETHTRY', 'XRPTRY', ...]
+        >>> bp.crypto_pairs("USDT")
+        ['BTCUSDT', 'ETHUSDT', ...]
+    """
+    provider = get_btcturk_provider()
+    return provider.get_pairs(quote)

borsapy/exceptions.py

@@ -0,0 +1,64 @@
+"""Custom exceptions for borsapy."""
+
+
+class BorsapyError(Exception):
+    """Base exception for all borsapy errors."""
+
+    pass
+
+
+class TickerNotFoundError(BorsapyError):
+    """Raised when a ticker symbol is not found."""
+
+    def __init__(self, symbol: str):
+        self.symbol = symbol
+        super().__init__(f"Ticker not found: {symbol}")
+
+
+class DataNotAvailableError(BorsapyError):
+    """Raised when requested data is not available."""
+
+    def __init__(self, message: str = "Data not available"):
+        super().__init__(message)
+
+
+class APIError(BorsapyError):
+    """Raised when an API request fails."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(
+            f"API Error: {message}" + (f" (status: {status_code})" if status_code else "")
+        )
+
+
+class AuthenticationError(BorsapyError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class RateLimitError(BorsapyError):
+    """Raised when rate limit is exceeded."""
+
+    pass
+
+
+class InvalidPeriodError(BorsapyError):
+    """Raised when an invalid period is specified."""
+
+    def __init__(self, period: str):
+        self.period = period
+        valid_periods = ["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"]
+        super().__init__(f"Invalid period: {period}. Valid periods: {', '.join(valid_periods)}")
+
+
+class InvalidIntervalError(BorsapyError):
+    """Raised when an invalid interval is specified."""
+
+    def __init__(self, interval: str):
+        self.interval = interval
+        valid_intervals = ["1m", "5m", "15m", "30m", "1h", "1d", "1wk", "1mo"]
+        super().__init__(
+            f"Invalid interval: {interval}. Valid intervals: {', '.join(valid_intervals)}"
+        )