finbrain-python 0.1.1__py3-none-any.whl

finbrain/__init__.py

@@ -0,0 +1,12 @@
+"""FinBrain Python SDK."""
+
+from importlib import metadata as _meta
+
+try:  # installed from a wheel / sdist
+    __version__: str = _meta.version(__name__)
+except _meta.PackageNotFoundError:  # running from a Git checkout
+    __version__ = "0.0.0.dev0"
+
+from .client import FinBrainClient
+
+__all__ = ["FinBrainClient", "__version__"]

finbrain/client.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, Optional
+import requests
+from urllib.parse import urljoin
+
+from .exceptions import http_error_to_exception, InvalidResponse
+from . import __version__
+
+from .endpoints.available import AvailableAPI
+from .endpoints.predictions import PredictionsAPI
+from .endpoints.sentiments import SentimentsAPI
+from .endpoints.app_ratings import AppRatingsAPI
+from .endpoints.analyst_ratings import AnalystRatingsAPI
+from .endpoints.house_trades import HouseTradesAPI
+from .endpoints.insider_transactions import InsiderTransactionsAPI
+from .endpoints.linkedin_data import LinkedInDataAPI
+from .endpoints.options import OptionsAPI
+
+
+# Which status codes merit a retry
+_RETRYABLE_STATUS = {500}
+# How long to wait between retries   (2, 4, 8 … seconds)
+_BACKOFF_BASE = 2
+
+
+class FinBrainClient:
+    """
+    Thin wrapper around the FinBrain REST API.
+    """
+
+    DEFAULT_BASE_URL = "https://api.finbrain.tech/v1/"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str | None = None,
+        timeout: float = 10,
+        retries: int = 3,
+    ):
+        self.api_key = api_key or os.getenv("FINBRAIN_API_KEY")
+        if not self.api_key:
+            raise ValueError("FinBrain API key missing")
+        self.base_url = base_url or self.DEFAULT_BASE_URL
+
+        self.session = requests.Session()
+        self.session.headers["User-Agent"] = f"finbrain-python/{__version__}"
+        # optional: mount urllib3 Retry adapter here
+
+        self.timeout = timeout
+        self.retries = retries
+
+        # wire endpoint helpers
+        self.available = AvailableAPI(self)
+        self.predictions = PredictionsAPI(self)
+        self.sentiments = SentimentsAPI(self)
+        self.app_ratings = AppRatingsAPI(self)
+        self.analyst_ratings = AnalystRatingsAPI(self)
+        self.house_trades = HouseTradesAPI(self)
+        self.insider_transactions = InsiderTransactionsAPI(self)
+        self.linkedin_data = LinkedInDataAPI(self)
+        self.options = OptionsAPI(self)
+
+    # ---------- private helpers ----------
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Perform a single HTTP request with auth token and retries.
+
+        Raises
+        ------
+        FinBrainError
+            Mapped from HTTP status via ``http_error_to_exception``.
+        InvalidResponse
+            If the body is not valid JSON.
+        """
+        params = params.copy() if params else {}
+        params["token"] = self.api_key  # FinBrain authentication
+        url = urljoin(self.base_url, path)
+
+        for attempt in range(self.retries + 1):
+            try:
+                resp = self.session.request(
+                    method, url, params=params, timeout=self.timeout
+                )
+            except requests.RequestException as exc:
+                # Network problem → retry if budget allows, else wrap into FinBrainError
+                if attempt == self.retries:
+                    raise InvalidResponse(f"Network error: {exc}") from exc
+                time.sleep(_BACKOFF_BASE**attempt)
+                continue
+
+            # ── Happy path ────────────────────────────────────
+            if resp.ok:  # 2xx / 3xx
+                try:
+                    return resp.json()
+                except ValueError as exc:
+                    raise InvalidResponse("Response body is not valid JSON") from exc
+
+            # ── Error path ───────────────────────────────────
+            if resp.status_code in _RETRYABLE_STATUS and attempt < self.retries:
+                # 500 – exponential back-off then retry
+                time.sleep(_BACKOFF_BASE**attempt)
+                continue
+
+            # No more retries → raise the mapped FinBrainError
+            raise http_error_to_exception(resp)

finbrain/endpoints/analyst_ratings.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Dict, Any, List
+
+if TYPE_CHECKING:  # imported only by type-checkers
+    from ..client import FinBrainClient
+
+
+class AnalystRatingsAPI:
+    """
+    Endpoint: ``/analystratings/<MARKET>/<TICKER>``
+
+    Retrieve broker/analyst rating actions for a single ticker.
+    Market names may contain spaces (``"S&P 500"``, ``"HK Hang Seng"``...);
+    they are URL-encoded automatically.
+    """
+
+    # ------------------------------------------------------------------ #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        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:
+        """
+        Analyst ratings 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 (case-insensitive; converted to upper-case).
+        date_from, date_to :
+            Optional ISO dates ``YYYY-MM-DD`` limiting the range.
+        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"analystratings/{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("analystRatings", [])
+            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 ``datetime.date`` → ``YYYY-MM-DD``; pass strings through untouched."""
+    return value.isoformat() if isinstance(value, _dt.date) else value

finbrain/endpoints/app_ratings.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import datetime as _dt
+import pandas as pd
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Dict, Any, List
+
+if TYPE_CHECKING:  # imported only by static-type tools
+    from ..client import FinBrainClient
+
+
+class AppRatingsAPI:
+    """
+    Mobile-app rating analytics for a single ticker.
+
+    Example
+    -------
+    >>> fb.app_ratings.ticker(
+    ...     market="S&P 500",
+    ...     symbol="AMZN",
+    ...     date_from="2024-01-01",
+    ...     date_to="2024-02-02",
+    ... )["appRatings"][:2]
+    [
+        {
+            "playStoreScore": 3.75,
+            "playStoreRatingsCount": 567996,
+            "appStoreScore": 4.07,
+            "appStoreRatingsCount": 88533,
+            "playStoreInstallCount": null,
+            "date": "2024-02-02"
+        },
+        ...
+    ]
+    """
+
+    # ------------------------------------------------------------------ #
+    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,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Fetch mobile-app ratings 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, upper-cased before the request.
+        date_from, date_to :
+            Optional ISO dates (``YYYY-MM-DD``) to bound the range.
+        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"appratings/{market_slug}/{symbol.upper()}"
+        data = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("appRatings", [])
+            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 :pyclass:`~datetime.date` → ``YYYY-MM-DD`` but pass strings."""
+    if isinstance(value, _dt.date):
+        return value.isoformat()
+    return value

finbrain/endpoints/available.py

@@ -0,0 +1,83 @@
+# src/finbrain/endpoints/available.py
+from __future__ import annotations
+import pandas as pd
+from typing import TYPE_CHECKING, Literal, List, Dict, Any
+
+if TYPE_CHECKING:  # imported only by type-checkers (mypy, pyright…)
+    from ..client import FinBrainClient
+
+_PType = Literal["daily", "monthly"]
+_ALLOWED: set[str] = {"daily", "monthly"}
+
+
+class AvailableAPI:
+    """
+    Wrapper for FinBrain's **/available** endpoints
+    -----------------------------------------------
+
+    • ``/available/markets``                → list supported indices
+    • ``/available/tickers/<TYPE>``         → list tickers for that *TYPE*
+
+      The docs call the path segment “TYPE”; it might be a market name
+      (``sp500`` / ``nasdaq``) or something else. We don't guess—caller passes it.
+    """
+
+    # ------------------------------------------------------------
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ------------------------------------------------------------
+    def markets(self) -> List[str]:
+        """
+        Return every market index string FinBrain supports.
+
+        Example
+        -------
+        >>> fb.available.markets()
+        ['S&P 500', 'NASDAQ', ...]
+        """
+        data = self._c._request("GET", "available/markets")
+
+        if isinstance(data, List):
+            return data
+
+        return data.get("availableMarkets", [])
+
+    # ------------------------------------------------------------
+    def tickers(
+        self,
+        prediction_type: _PType,
+        *,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """
+        List all tickers for which **FinBrain has predictions** of the given type.
+
+        Parameters
+        ----------
+        prediction_type :
+            Either ``"daily"`` (10-day horizon predictions) or
+            ``"monthly"`` (12-month horizon predictions).  Case-insensitive.
+        as_dataframe :
+            If *True*, return a ``pd.DataFrame``;
+            otherwise return the raw list of dicts.
+
+        Returns
+        -------
+        list[dict] | pandas.DataFrame
+            Each row / dict contains at least::
+
+                {
+                    "ticker": "AAPL",
+                    "name":   "Apple Inc.",
+                    "market": "S&P 500"
+                }
+        """
+        prediction_type = prediction_type.lower()
+        if prediction_type not in _ALLOWED:
+            raise ValueError("prediction_type must be 'daily' or 'monthly'")
+
+        path = f"available/tickers/{prediction_type}"
+        data: List[Dict[str, Any]] = self._c._request("GET", path)
+
+        return pd.DataFrame(data) if as_dataframe else data

finbrain/endpoints/house_trades.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any
+
+if TYPE_CHECKING:  # imported only by type-checkers
+    from ..client import FinBrainClient
+
+
+class HouseTradesAPI:
+    """
+    Endpoint
+    --------
+    ``/housetrades/<MARKET>/<TICKER>`` - trading activity of U.S. House
+    Representatives for the selected ticker.
+    """
+
+    # ------------------------------------------------------------------ #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        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:
+        """
+        Fetch House-member trades 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; auto-upper-cased.
+        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"housetrades/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows = data.get("houseTrades", [])
+            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 ``datetime.date`` → ``YYYY-MM-DD``; leave strings untouched."""
+    return value.isoformat() if isinstance(value, _dt.date) else value

finbrain/endpoints/insider_transactions.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Dict, Any
+
+if TYPE_CHECKING:  # imported only by static-type tools
+    from ..client import FinBrainClient
+
+
+class InsiderTransactionsAPI:
+    """
+    Endpoint
+    --------
+    ``/insidertransactions/<MARKET>/<TICKER>`` - recent Form-4 insider trades
+    for the requested ticker.
+    """
+
+    # ------------------------------------------------------------------ #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        self,
+        market: str,
+        symbol: str,
+        *,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Insider transactions 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.
+        as_dataframe :
+            If *True*, return a **pandas.DataFrame** indexed by ``date``;
+            otherwise return the raw JSON dict.
+
+        Returns
+        -------
+        dict | pandas.DataFrame
+        """
+        market_slug = quote(market, safe="")
+        path = f"insidertransactions/{market_slug}/{symbol.upper()}"
+        data: Dict[str, Any] = self._c._request("GET", path)
+
+        # --- DataFrame conversion ---
+        if as_dataframe:
+            rows = data.get("insiderTransactions", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "date" in df.columns:
+                # examples show dates like "Mar 08 '24" – let pandas parse flexibly
+                _fmt = "%b %d '%y"  # e.g. Mar 08 '24
+                dt = pd.to_datetime(df["date"], format=_fmt, errors="coerce")
+                if dt.isna().any():  # fallback if format ever changes
+                    dt = pd.to_datetime(df["date"], errors="coerce", dayfirst=False)
+                df["date"] = dt
+                df.set_index("date", inplace=True)
+            return df
+
+        return data

finbrain/endpoints/linkedin_data.py

@@ -0,0 +1,85 @@
+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 static type-checkers
+    from ..client import FinBrainClient
+
+
+class LinkedInDataAPI:
+    """
+    Endpoint
+    --------
+    ``/linkedindata/<MARKET>/<TICKER>`` - LinkedIn follower / employee-count
+    metrics for a single ticker.
+    """
+
+    # ------------------------------------------------------------------ #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        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:
+        """
+        LinkedIn follower- and employee-count metrics for a single ticker.
+
+        Market names may contain spaces (“S&P 500”, “Germany DAX”, “HK Hang Seng”);
+        they are URL-encoded automatically.
+
+        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 symbol; auto-upper-cased.
+        date_from, date_to :
+            Optional ``YYYY-MM-DD`` bounds.
+        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"linkedindata/{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("linkedinData", [])
+            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