finbrain-python 0.1.1__py3-none-any.whl

finbrain/endpoints/options.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any, List
+
+if TYPE_CHECKING:  # imported only by type-checkers
+    from ..client import FinBrainClient
+
+
+class OptionsAPI:
+    """
+    Options data endpoints
+    ----------------------
+
+    Currently implemented
+    ~~~~~~~~~~~~~~~~~~~~~
+    • **put_call** - ``/putcalldata/<MARKET>/<TICKER>``
+
+    Future additions (open interest, IV, strikes, …) can live in this same class.
+    """
+
+    # ────────────────────────────────────────────────────────────────────
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ────────────────────────────────────────────────────────────────────
+    def put_call(
+        self,
+        market: str,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Put/Call ratio data for *symbol* in *market*.
+
+        Parameters
+        ----------
+        market :
+            Market name **exactly as FinBrain lists it**
+            (e.g. ``"S&P 500"``, ``"Germany DAX"``, ``"HK Hang Seng"``).
+            Spaces and special characters are accepted; they are URL-encoded
+            automatically.
+        symbol :
+            Ticker symbol; converted to upper-case.
+        date_from, date_to :
+            Optional ISO dates (``YYYY-MM-DD``) bounding the returned rows.
+        as_dataframe :
+            If *True*, return a **pandas.DataFrame** indexed by ``date``;
+            otherwise return the raw JSON dict.
+
+        Returns
+        -------
+        dict | pandas.DataFrame
+        """
+        params: Dict[str, str] = {}
+        if date_from:
+            params["dateFrom"] = _to_datestr(date_from)
+        if date_to:
+            params["dateTo"] = _to_datestr(date_to)
+
+        market_slug = quote(market, safe="")
+        path = f"putcalldata/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("putCallData", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "date" in df.columns:
+                df["date"] = pd.to_datetime(df["date"])
+                df.set_index("date", inplace=True)
+            return df
+
+        return data
+
+
+# ────────────────────────────────────────────────────────────────────────
+# helper
+# ────────────────────────────────────────────────────────────────────────
+def _to_datestr(value: _dt.date | str) -> str:
+    """Convert :class:`datetime.date` → ``YYYY-MM-DD``; leave strings untouched."""
+    return value.isoformat() if isinstance(value, _dt.date) else value

finbrain/endpoints/predictions.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import re
+import pandas as pd
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Literal, Dict, Any, List
+
+if TYPE_CHECKING:
+    from ..client import FinBrainClient
+
+
+# ------------------------------------------------------------------------- #
+_PType = Literal["daily", "monthly"]
+_ALLOWED: set[str] = {"daily", "monthly"}
+_DATE_RE = re.compile(r"\d{4}-\d{2}-\d{2}")
+
+
+class PredictionsAPI:
+    """
+    Price-prediction endpoints
+
+    • `/market/<MARKET>/predictions/<TYPE>`
+    • `/ticker/<TICKER>/predictions/<TYPE>`
+
+    where **TYPE** ∈ { `daily`, `monthly` }.
+    """
+
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        self,
+        symbol: str,
+        *,
+        prediction_type: _PType = "daily",
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Single-ticker predictions.
+
+        Parameters
+        ----------
+        symbol :
+            Symbol such as ``AAPL`` (case-insensitive).
+        prediction_type :
+            ``"daily"`` (10-day horizon) or ``"monthly"`` (12-month horizon).
+        as_dataframe :
+            Return a **DataFrame** (index =`date`, cols =`main, lower, upper`)
+            instead of raw JSON.
+
+        Returns
+        -------
+        dict | pandas.DataFrame
+        """
+        _validate(prediction_type)
+        path = f"ticker/{symbol.upper()}/predictions/{prediction_type}"
+        data: Dict[str, Any] = self._c._request("GET", path)
+
+        if as_dataframe:
+            pred = data.get("prediction", {})
+            rows: list[dict[str, float]] = []
+            for k, v in pred.items():
+                if _DATE_RE.fullmatch(k):
+                    main, low, high = map(float, v.split(","))
+                    rows.append({"date": k, "main": main, "lower": low, "upper": high})
+            df = pd.DataFrame(rows).set_index(
+                pd.to_datetime(pd.Series([r["date"] for r in rows]))
+            )
+            df.index.name = "date"
+            df.drop(columns="date", inplace=True)
+            return df
+
+        return data
+
+    # ------------------------------------------------------------------ #
+    def market(
+        self,
+        market: str,
+        *,
+        prediction_type: _PType = "daily",
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """
+        Predictions for **all** tickers in a market.
+
+        Parameters
+        ----------
+        market :
+            Market name **exactly as FinBrain lists it**
+            (e.g. ``"S&P 500"``, ``"Germany DAX"``).  Spaces/`&` are OK.
+        prediction_type :
+            ``"daily"`` or ``"monthly"``.
+        as_dataframe :
+            If *True* return a DataFrame (index =`ticker`) with
+            ``expectedShort``, ``expectedMid``, ``expectedLong``, and optional
+            ``sentimentScore``.
+
+        Returns
+        -------
+        list[dict] | pandas.DataFrame
+        """
+        _validate(prediction_type)
+        slug = quote(market, safe="")
+        path = f"market/{slug}/predictions/{prediction_type}"
+        data: List[Dict[str, Any]] = self._c._request("GET", path)
+
+        if as_dataframe:
+            rows: list[dict[str, Any]] = []
+            for rec in data:
+                p = rec.get("prediction", {})
+                rows.append(
+                    {
+                        "ticker": rec["ticker"],
+                        "expectedShort": float(p["expectedShort"]),
+                        "expectedMid": float(p["expectedMid"]),
+                        "expectedLong": float(p["expectedLong"]),
+                        "sentimentScore": float(rec.get("sentimentScore", "nan")),
+                    }
+                )
+            df = pd.DataFrame(rows).set_index("ticker")
+            return df
+
+        return data
+
+
+# ---------------------------------------------------------------------- #
+def _validate(value: str) -> None:
+    if value not in _ALLOWED:
+        raise ValueError("prediction_type must be 'daily' or 'monthly'")

finbrain/endpoints/sentiments.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Dict, Any
+
+if TYPE_CHECKING:  # imported only by static type-checkers
+    from ..client import FinBrainClient
+
+
+class SentimentsAPI:
+    """
+    Wrapper for **/sentiments/<MARKET>/<TICKER>** endpoints.
+
+    Example
+    -------
+    >>> fb.sentiments.ticker(
+    ...     market="S&P 500",
+    ...     symbol="AMZN",
+    ...     date_from="2024-01-01",
+    ...     date_to="2024-02-02",
+    ... )
+    {
+        "ticker": "AMZN",
+        "name": "Amazon.com Inc.",
+        "sentimentAnalysis": {
+            "2024-01-15": "0.123",
+            ...
+        }
+    }
+    """
+
+    # --------------------------------------------------------------------- #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client
+
+    # --------------------------------------------------------------------- #
+    def ticker(
+        self,
+        market: str,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        days: int | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Retrieve sentiment scores for a *single* ticker.
+
+        Parameters
+        ----------
+        market :
+            Market name **exactly as FinBrain lists it**
+            (e.g. ``"S&P 500"``, ``"Germany DAX"``, ``"HK Hang Seng"``).
+            Spaces and special characters are accepted; they are URL-encoded
+            automatically.
+        symbol :
+            Stock/crypto symbol (``AAPL``, ``AMZN`` …) *uppercase recommended*.
+        date_from, date_to :
+            Optional start / end dates (``YYYY-MM-DD``).  If omitted, FinBrain
+            defaults to its internal window or to ``days``.
+        days :
+            Alternative to explicit dates - integer 1…120 for "past *n* days".
+            Ignored if either ``date_from`` or ``date_to`` is supplied.
+        as_dataframe :
+            If *True*, return a **DataFrame** with a ``date`` index and a single
+            ``sentiment`` column.
+
+        Returns
+        -------
+        dict | pandas.DataFrame
+        """
+        # Build query parameters
+        params: Dict[str, str] = {}
+
+        if date_from:
+            params["dateFrom"] = _to_datestr(date_from)
+        if date_to:
+            params["dateTo"] = _to_datestr(date_to)
+        if days is not None and "dateFrom" not in params and "dateTo" not in params:
+            params["days"] = str(days)
+
+        market_slug = quote(market, safe="")
+        path = f"sentiments/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            sa: Dict[str, str] = data.get("sentimentAnalysis", {})
+            df = (
+                pd.Series(sa, name="sentiment")
+                .astype(float)
+                .rename_axis("date")
+                .to_frame()
+            )
+            df.index = pd.to_datetime(df.index)
+            return df
+
+        return data
+
+
+# ------------------------------------------------------------------------- #
+# Helpers                                                                   #
+# ------------------------------------------------------------------------- #
+def _to_datestr(value: _dt.date | str) -> str:
+    """Convert ``datetime.date`` → 'YYYY-MM-DD' but pass strings through."""
+    return value.isoformat() if isinstance(value, _dt.date) else value

finbrain/exceptions.py

@@ -0,0 +1,140 @@
+"""
+finbrain.exceptions
+~~~~~~~~~~~~~~~~~~~
+
+Canonical exception hierarchy for the FinBrain Python SDK.
+Every public error subclasses :class:`FinBrainError`.
+
+Docs-based mapping
+------------------
+400  Bad Request            → BadRequest
+401  Unauthorized           → AuthenticationError
+403  Forbidden              → PermissionDenied
+404  Not Found              → NotFound
+405  Method Not Allowed     → MethodNotAllowed
+500  Internal Server Error  → ServerError
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Union
+
+__all__ = [
+    "FinBrainError",
+    "BadRequest",
+    "AuthenticationError",
+    "PermissionDenied",
+    "NotFound",
+    "MethodNotAllowed",
+    "ServerError",
+    #
+    "InvalidResponse",
+    "http_error_to_exception",
+]
+
+# ─────────────────────────────────────────────────────────────
+# Base class
+# ─────────────────────────────────────────────────────────────
+
+
+class FinBrainError(Exception):
+    """Root of the SDK's exception tree."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: Any | None = None,
+    ):
+        super().__init__(message)
+        self.status_code: int | None = status_code
+        self.payload: Any | None = payload  # raw JSON/text for debugging
+
+
+# ─────────────────────────────────────────────────────────────
+# 4xx family
+# ─────────────────────────────────────────────────────────────
+
+
+class BadRequest(FinBrainError):
+    """400 - The request is malformed or contains invalid parameters."""
+
+
+class AuthenticationError(FinBrainError):
+    """401 - API key missing or invalid."""
+
+
+class PermissionDenied(FinBrainError):
+    """403 - Authenticated, but not authorised to perform this action."""
+
+
+class NotFound(FinBrainError):
+    """404 - Requested data or endpoint not found."""
+
+
+class MethodNotAllowed(FinBrainError):
+    """405 - Endpoint exists, but the HTTP method is not supported."""
+
+
+# ─────────────────────────────────────────────────────────────
+# 5xx family
+# ─────────────────────────────────────────────────────────────
+
+
+class ServerError(FinBrainError):
+    """500 - Internal error on FinBrain's side. Retrying later may help."""
+
+
+# ─────────────────────────────────────────────────────────────
+# Transport / decoding guard
+# ─────────────────────────────────────────────────────────────
+
+
+class InvalidResponse(FinBrainError):
+    """Response couldn't be parsed as JSON or is missing required fields."""
+
+
+# ─────────────────────────────────────────────────────────────
+# Helper: map HTTP response ➜ exception
+# ─────────────────────────────────────────────────────────────
+
+
+def _extract_message(payload: Any, default: str) -> str:
+    if isinstance(payload, dict):
+        # FinBrain usually returns {"message": "..."}
+        return payload.get("message", default)
+    return default
+
+
+def http_error_to_exception(resp) -> FinBrainError:  # expects requests.Response
+    """
+    Convert a non-2xx ``requests.Response`` into a typed FinBrainError.
+
+    Usage
+    -----
+    >>> raise http_error_to_exception(resp)
+    """
+    status = resp.status_code
+    try:
+        payload: Union[Dict[str, Any], str] = resp.json()
+    except ValueError:
+        payload = resp.text
+
+    message = _extract_message(payload, f"{status} {resp.reason}")
+
+    if status == 400:
+        return BadRequest(message, status_code=status, payload=payload)
+    if status == 401:
+        return AuthenticationError(message, status_code=status, payload=payload)
+    if status == 403:
+        return PermissionDenied(message, status_code=status, payload=payload)
+    if status == 404:
+        return NotFound(message, status_code=status, payload=payload)
+    if status == 405:
+        return MethodNotAllowed(message, status_code=status, payload=payload)
+    if status == 500:
+        return ServerError(message, status_code=status, payload=payload)
+
+    # Fallback for undocumented codes (future-proofing)
+    return FinBrainError(message, status_code=status, payload=payload)