finbrain-python 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

finbrain/aio/client.py

@@ -15,6 +15,7 @@ from .endpoints.sentiments import AsyncSentimentsAPI
 from .endpoints.app_ratings import AsyncAppRatingsAPI
 from .endpoints.analyst_ratings import AsyncAnalystRatingsAPI
 from .endpoints.house_trades import AsyncHouseTradesAPI
+from .endpoints.senate_trades import AsyncSenateTradesAPI
 from .endpoints.insider_transactions import AsyncInsiderTransactionsAPI
 from .endpoints.linkedin_data import AsyncLinkedInDataAPI
 from .endpoints.options import AsyncOptionsAPI
@@ -68,6 +69,7 @@ class AsyncFinBrainClient:
         self.app_ratings = AsyncAppRatingsAPI(self)
         self.analyst_ratings = AsyncAnalystRatingsAPI(self)
         self.house_trades = AsyncHouseTradesAPI(self)
+        self.senate_trades = AsyncSenateTradesAPI(self)
         self.insider_transactions = AsyncInsiderTransactionsAPI(self)
         self.linkedin_data = AsyncLinkedInDataAPI(self)
         self.options = AsyncOptionsAPI(self)

finbrain/aio/endpoints/senate_trades.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:
+    from ..client import AsyncFinBrainClient
+
+
+class AsyncSenateTradesAPI:
+    """Async wrapper for /senatetrades endpoints."""
+
+    def __init__(self, client: "AsyncFinBrainClient") -> None:
+        self._c = client
+
+    async 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 Senate-member trades for symbol in market (async)."""
+        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"senatetrades/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows = data.get("senateTrades", [])
+            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

finbrain/client.py

@@ -16,6 +16,7 @@ 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.senate_trades import SenateTradesAPI
 from .endpoints.insider_transactions import InsiderTransactionsAPI
 from .endpoints.linkedin_data import LinkedInDataAPI
 from .endpoints.options import OptionsAPI
@@ -63,6 +64,7 @@ class FinBrainClient:
         self.app_ratings = AppRatingsAPI(self)
         self.analyst_ratings = AnalystRatingsAPI(self)
         self.house_trades = HouseTradesAPI(self)
+        self.senate_trades = SenateTradesAPI(self)
         self.insider_transactions = InsiderTransactionsAPI(self)
         self.linkedin_data = LinkedInDataAPI(self)
         self.options = OptionsAPI(self)

finbrain/endpoints/senate_trades.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:  # imported only by type-checkers
+    from ..client import FinBrainClient
+
+
+class SenateTradesAPI:
+    """
+    Endpoint
+    --------
+    ``/senatetrades/<MARKET>/<TICKER>`` - trading activity of U.S. Senators
+    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 Senate-member trades for *symbol* in *market*.
+
+        Parameters
+        ----------
+        market :
+            Market name **exactly as FinBrain lists it**
+            (e.g. ``"NASDAQ"``, ``"NYSE"``, ``"S&P 500"``).
+            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"senatetrades/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows = data.get("senateTrades", [])
+            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

finbrain/plotting.py

@@ -661,6 +661,117 @@ class _PlotNamespace:
             return None
         return fig.to_json() if as_json else fig
 
+    # --------------------------------------------------------------------- #
+    # Senate Trades  → markers on price chart                               #
+    # --------------------------------------------------------------------- #
+    def senate_trades(
+        self,
+        market: str,
+        ticker: str,
+        price_data: pd.DataFrame,
+        *,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        as_json: bool = False,
+        show: bool = True,
+        template: str = "plotly_dark",
+        **kwargs,
+    ):
+        """
+        Plot U.S. Senate member trades overlaid on a price chart.
+
+        This method requires user-provided historical price data, as FinBrain
+        does not currently offer a price history endpoint.
+
+        Parameters
+        ----------
+        market : str
+            Market identifier (e.g. ``"NASDAQ"``).
+        ticker : str
+            Ticker symbol (e.g. ``"META"``).
+        price_data : pandas.DataFrame
+            **User-provided** price history with a DatetimeIndex and a column
+            containing prices (e.g. ``"close"``, ``"Close"``, or ``"price"``).
+            The index must be timezone-naive or UTC.
+        date_from, date_to : str or None, optional
+            Date range for transactions in ``YYYY-MM-DD`` format.
+        as_json : bool, default False
+            If ``True``, return JSON string instead of Figure object.
+        show : bool, default True
+            If ``True`` and ``as_json=False``, display the figure immediately.
+        template : str, default "plotly_dark"
+            Plotly template name.
+        **kwargs
+            Additional arguments passed to
+            :meth:`FinBrainClient.senate_trades.ticker`.
+
+        Returns
+        -------
+        plotly.graph_objects.Figure or str or None
+            Figure object, JSON string, or None (when shown).
+
+        Raises
+        ------
+        ValueError
+            If ``price_data`` is empty or missing required price column.
+
+        Examples
+        --------
+        >>> import pandas as pd
+        >>> # User provides their own price data from any legal source
+        >>> price_df = pd.DataFrame({
+        ...     "close": [500, 510, 505, 520],
+        ...     "date": pd.date_range("2024-01-01", periods=4)
+        ... }).set_index("date")
+        >>> fb.plot.senate_trades("NASDAQ", "META", price_df,
+        ...                       date_from="2024-01-01", date_to="2024-12-31")
+        """
+        # Validate price_data
+        if price_data.empty:
+            raise ValueError("price_data cannot be empty")
+
+        # Flatten MultiIndex columns if present (e.g., from yf.download())
+        if isinstance(price_data.columns, pd.MultiIndex):
+            # Get the first level (price types like 'Close', 'Open', etc.)
+            price_data = price_data.copy()
+            price_data.columns = price_data.columns.get_level_values(0)
+
+        # Find price column (case-insensitive search)
+        price_col = None
+        for col in ["close", "Close", "price", "Price", "adj_close", "Adj Close"]:
+            if col in price_data.columns:
+                price_col = col
+                break
+        if price_col is None:
+            raise ValueError(
+                f"price_data must contain a price column (e.g. 'close', 'Close', 'price'). "
+                f"Found columns: {price_data.columns.tolist()}"
+            )
+
+        # Fetch senate trades
+        transactions_df = self._fb.senate_trades.ticker(
+            market,
+            ticker,
+            date_from=date_from,
+            date_to=date_to,
+            as_dataframe=True,
+            **kwargs,
+        )
+
+        fig = self._plot_transactions_on_price(
+            price_data=price_data,
+            price_col=price_col,
+            transactions_df=transactions_df,
+            ticker=ticker,
+            template=template,
+            transaction_type="Senate",
+        )
+
+        if show and not as_json:
+            fig.show()
+            return None
+        return fig.to_json() if as_json else fig
+
     # --------------------------------------------------------------------- #
     # Helper methods                                                         #
     # --------------------------------------------------------------------- #

{finbrain_python-0.1.7.dist-info → finbrain_python-0.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.1.7
+Version: 0.1.8
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -86,6 +86,12 @@ fb.house_trades.ticker("S&P 500", "AMZN",
                        date_to="2025-06-30",
                        as_dataframe=True)
 
+# ---------- senate trades ----------
+fb.senate_trades.ticker("NASDAQ", "META",
+                        date_from="2025-01-01",
+                        date_to="2025-06-30",
+                        as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("S&P 500", "AMZN", as_dataframe=True)
 
@@ -185,7 +191,7 @@ fb.plot.sentiments("S&P 500", "AMZN",
                    date_from="2025-01-01",
                    date_to="2025-06-30")
 
-# ---------- Insider Transactions & House Trades (requires user price data) ----------
+# ---------- Insider Transactions, House & Senate Trades (requires user price data) ----------
 # These plots overlay transaction markers on a price chart.
 # Since FinBrain doesn't provide historical prices, you must provide your own:
 
@@ -206,6 +212,12 @@ fb.plot.house_trades("S&P 500", "NVDA",
                      price_data=price_df,
                      date_from="2025-01-01",
                      date_to="2025-06-30")
+
+# Plot Senate member trades on your price chart
+fb.plot.senate_trades("NASDAQ", "META",
+                      price_data=price_df,
+                      date_from="2025-01-01",
+                      date_to="2025-06-30")
 ```
 
 **Price Data Requirements:**
@@ -242,6 +254,7 @@ fb = FinBrainClient(api_key="YOUR_KEY")
 | App ratings          | `client.app_ratings.ticker()`            | `/appratings/{MARKET}/{TICKER}`                      |
 | Analyst ratings      | `client.analyst_ratings.ticker()`        | `/analystratings/{MARKET}/{TICKER}`                  |
 | House trades         | `client.house_trades.ticker()`           | `/housetrades/{MARKET}/{TICKER}`                     |
+| Senate trades        | `client.senate_trades.ticker()`          | `/senatetrades/{MARKET}/{TICKER}`                    |
 | Insider transactions | `client.insider_transactions.ticker()`   | `/insidertransactions/{MARKET}/{TICKER}`             |
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedindata/{MARKET}/{TICKER}`                    |
 | Options – Put/Call   | `client.options.put_call()`              | `/putcalldata/{MARKET}/{TICKER}`                     |

{finbrain_python-0.1.7.dist-info → finbrain_python-0.1.8.dist-info}/RECORD

@@ -1,10 +1,10 @@
 finbrain/__init__.py,sha256=ULIgwHkWbj5sT0udC3SlTROhZCgm2y9BtPox-4joNn4,416
-finbrain/client.py,sha256=6Q9euGD-uxUsQFeS-dGziaLZP4i5czrGQA9Vsxxxac4,4178
+finbrain/client.py,sha256=qo1vqkp10U-xJ5FELtnU2SmN5MkYIuz1w0h4eDVknCY,4282
 finbrain/exceptions.py,sha256=_STlzmP7Z1qDkFic3QU4QqyY07MMhMm46Tmgy7HHuck,5258
-finbrain/plotting.py,sha256=EJrap1W-ZKRntnhOM59PXJziIcQ8d6M_bYgVYNaxC4Q,29928
+finbrain/plotting.py,sha256=qbd1-wwTkJ_obCHFJRUgpBSe835BNNw937RMu1HZfNs,33987
 finbrain/py.typed,sha256=INFR1qO3jdMrtVPs0N0SAVKVbjKV80HQPoPshwGEpGo,27
 finbrain/aio/__init__.py,sha256=eJra9SqvLMkq5zoZfG6WFw7kd1jGpf9l-ovuPMeWvdw,125
-finbrain/aio/client.py,sha256=LwvIR9lZRzKAYckcEi9-wrUtWs6Wci-DV5ouefBq3dM,6039
+finbrain/aio/client.py,sha256=KLC6iHLJd0DNQOEKmLoBNAXDPtXoLuaD9cLrlmlwE4s,6153
 finbrain/aio/endpoints/__init__.py,sha256=zdNSU1jzvnK6JnHxrvb3ye9KFCkA86xDTu9bBzmwrEQ,48
 finbrain/aio/endpoints/_utils.py,sha256=4ElYWGCcJ7t_lx02e49NvFHMt2g6DTcnwx3Mvwf3KyY,908
 finbrain/aio/endpoints/analyst_ratings.py,sha256=JJ0wywQtO2WuEFpJUYsdGyPJj951SrlyFQyCes9UOEs,1468
@@ -15,6 +15,7 @@ finbrain/aio/endpoints/insider_transactions.py,sha256=xMPuTSjIXmyqmlRUloGlkqiYjD
 finbrain/aio/endpoints/linkedin_data.py,sha256=eQ13rNDYTTQRNN6cjBmqKLCW8DtCRsjVC_f-af-KLXM,1489
 finbrain/aio/endpoints/options.py,sha256=DspRz6NBWez0AM0g5tHHhq6rw3rZEo6zbFiv005dvp8,1458
 finbrain/aio/endpoints/predictions.py,sha256=nXoPuXe8KiuLHv8mp6iMz3bcEjkecDOEABipPUdH6bE,2807
+finbrain/aio/endpoints/senate_trades.py,sha256=3TvfxoU_vVpUwoIJtd100XpEbfQevFtUCXLCGKY45-I,1442
 finbrain/aio/endpoints/sentiments.py,sha256=PcVoeqTatiPMnxcBPOX_mV4GaFbr2efIsf40qAjAh1k,1640
 finbrain/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 finbrain/endpoints/_utils.py,sha256=0JIybEiSXVCm5SQI73i80OtoGQ2mJWAjImgA_2ru30U,896
@@ -26,9 +27,10 @@ finbrain/endpoints/insider_transactions.py,sha256=lV3Zaz2SfuEnJvThAyxtfh-WuGjLN0
 finbrain/endpoints/linkedin_data.py,sha256=CG7eSN2o2pVtKyhY_MAipg-hxZXVSSvfQX9LjRs-0wM,2571
 finbrain/endpoints/options.py,sha256=K0fE3mZo0aXqPxHjhMgc1R5gkd12zKeZ54_8DQ11sRE,2823
 finbrain/endpoints/predictions.py,sha256=kDxC1ubKbpapeF12qahiGrD6V68ljBXuWdiu_0jHq64,4166
+finbrain/endpoints/senate_trades.py,sha256=eeQ97fTtxhTGqX-DMUsuZOkbGlBlGrZy8p8JsYezJ4M,2395
 finbrain/endpoints/sentiments.py,sha256=RKDsTxk4o-dz98Sg-BauMXjwev_77Xt2w93ifmP-2p4,3166
-finbrain_python-0.1.7.dist-info/licenses/LICENSE,sha256=x71LjIUPbK7Y8YBulH_AXzEIX7BK90dgFL2zA6LBT-A,1069
-finbrain_python-0.1.7.dist-info/METADATA,sha256=1ssiVR4ooKjsw2Q_r1iJn7AmLl_fi-1dO17PV9FkW44,11304
-finbrain_python-0.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-finbrain_python-0.1.7.dist-info/top_level.txt,sha256=dCiQtTx3z2TtO_yQI6q3yODcdb-pABB-iEReJegVAv0,9
-finbrain_python-0.1.7.dist-info/RECORD,,
+finbrain_python-0.1.8.dist-info/licenses/LICENSE,sha256=x71LjIUPbK7Y8YBulH_AXzEIX7BK90dgFL2zA6LBT-A,1069
+finbrain_python-0.1.8.dist-info/METADATA,sha256=kixciTwD_ySYtJbAxEe1ZTfyf6EPhgwkkZyZdDsxVsc,11875
+finbrain_python-0.1.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+finbrain_python-0.1.8.dist-info/top_level.txt,sha256=dCiQtTx3z2TtO_yQI6q3yODcdb-pABB-iEReJegVAv0,9
+finbrain_python-0.1.8.dist-info/RECORD,,