finbrain-python 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

finbrain/aio/client.py

@@ -24,6 +24,7 @@ from .endpoints.screener import AsyncScreenerAPI
 from .endpoints.recent import AsyncRecentAPI
 from .endpoints.corporate_lobbying import AsyncCorporateLobbyingAPI
 from .endpoints.reddit_mentions import AsyncRedditMentionsAPI
+from .endpoints.government_contracts import AsyncGovernmentContractsAPI
 
 
 # Which status codes merit a retry
@@ -84,6 +85,7 @@ class AsyncFinBrainClient:
         self.recent = AsyncRecentAPI(self)
         self.corporate_lobbying = AsyncCorporateLobbyingAPI(self)
         self.reddit_mentions = AsyncRedditMentionsAPI(self)
+        self.government_contracts = AsyncGovernmentContractsAPI(self)
 
     async def __aenter__(self) -> "AsyncFinBrainClient":
         """Context manager entry."""

finbrain/aio/endpoints/government_contracts.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any, List
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:
+    from ..client import AsyncFinBrainClient
+
+
+class AsyncGovernmentContractsAPI:
+    """Async wrapper for /government-contracts and /screener/government-contracts endpoints."""
+
+    def __init__(self, client: "AsyncFinBrainClient") -> None:
+        self._c = client
+
+    async def ticker(
+        self,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """Fetch government contract awards for a symbol (async)."""
+        params: Dict[str, str] = {}
+        if date_from:
+            params["startDate"] = to_datestr(date_from)
+        if date_to:
+            params["endDate"] = to_datestr(date_to)
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        path = f"government-contracts/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("contracts", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "startDate" in df.columns:
+                df["startDate"] = pd.to_datetime(df["startDate"])
+                df.set_index("startDate", inplace=True)
+            return df
+
+        return data

finbrain/aio/endpoints/screener.py

@@ -222,3 +222,15 @@ class AsyncScreenerAPI:
         """Screen Reddit mention counts across tickers (async)."""
         params = self._build_params(limit=limit, market=market, region=region)
         return await self._get("screener/reddit-mentions", params, as_dataframe)
+
+    # ── government contracts ──────────────────────────────────
+
+    async def government_contracts(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen government contracts across all tickers (async)."""
+        params = self._build_params(limit=limit)
+        return await self._get("screener/government-contracts", params, as_dataframe)

finbrain/client.py

@@ -25,6 +25,7 @@ from .endpoints.screener import ScreenerAPI
 from .endpoints.recent import RecentAPI
 from .endpoints.corporate_lobbying import CorporateLobbyingAPI
 from .endpoints.reddit_mentions import RedditMentionsAPI
+from .endpoints.government_contracts import GovernmentContractsAPI
 
 
 # Which status codes merit a retry
@@ -79,6 +80,7 @@ class FinBrainClient:
         self.recent = RecentAPI(self)
         self.corporate_lobbying = CorporateLobbyingAPI(self)
         self.reddit_mentions = RedditMentionsAPI(self)
+        self.government_contracts = GovernmentContractsAPI(self)
 
     # ---------- private helpers ----------
     def _request(

finbrain/endpoints/government_contracts.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any, List
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:  # imported only by type-checkers
+    from ..client import FinBrainClient
+
+
+class GovernmentContractsAPI:
+    """
+    Endpoints
+    ---------
+    ``/government-contracts/<TICKER>`` - U.S. government contract awards.
+    ``/screener/government-contracts``  - cross-ticker government contracts screener.
+    """
+
+    # ------------------------------------------------------------------ #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        self,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Fetch government contract awards for *symbol*.
+
+        Parameters
+        ----------
+        symbol :
+            Ticker symbol; auto-upper-cased.
+        date_from, date_to :
+            Optional ISO dates (``YYYY-MM-DD``) bounding the returned rows.
+        limit :
+            Maximum number of records to return (1-500).
+        as_dataframe :
+            If *True*, return a **pandas.DataFrame** indexed by ``startDate``;
+            otherwise return the raw JSON dict.
+
+        Returns
+        -------
+        dict | pandas.DataFrame
+        """
+        params: Dict[str, str] = {}
+        if date_from:
+            params["startDate"] = to_datestr(date_from)
+        if date_to:
+            params["endDate"] = to_datestr(date_to)
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        path = f"government-contracts/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("contracts", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "startDate" in df.columns:
+                df["startDate"] = pd.to_datetime(df["startDate"])
+                df.set_index("startDate", inplace=True)
+            return df
+
+        return data

finbrain/endpoints/screener.py

@@ -227,3 +227,15 @@ class ScreenerAPI:
         """Screen Reddit mention counts across tickers."""
         params = self._build_params(limit=limit, market=market, region=region)
         return self._get("screener/reddit-mentions", params, as_dataframe)
+
+    # ── government contracts ──────────────────────────────────
+
+    def government_contracts(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen government contracts across all tickers."""
+        params = self._build_params(limit=limit)
+        return self._get("screener/government-contracts", params, as_dataframe)

finbrain/plotting.py

@@ -1154,6 +1154,160 @@ class _PlotNamespace:
             return None
         return fig.to_json() if as_json else fig
 
+    # --------------------------------------------------------------------- #
+    # Government Contracts  → bars on price chart                            #
+    # --------------------------------------------------------------------- #
+    def government_contracts(
+        self,
+        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 government contract awards overlaid on a price chart.
+
+        This method requires user-provided historical price data, as FinBrain
+        does not currently offer a price history endpoint.
+
+        Parameters
+        ----------
+        ticker : str
+            Ticker symbol (e.g. ``"LMT"``).
+        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 contracts 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.government_contracts.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.
+        """
+        # 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):
+            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 government contracts
+        contracts_df = self._fb.government_contracts.ticker(
+            ticker,
+            date_from=date_from,
+            date_to=date_to,
+            as_dataframe=True,
+            **kwargs,
+        )
+
+        # Normalize timezones
+        price_data_normalized = price_data.copy()
+        if price_data_normalized.index.tz is not None:
+            price_data_normalized.index = price_data_normalized.index.tz_localize(None)
+
+        fig = go.Figure(
+            layout=dict(
+                template=template,
+                title=f"Government Contracts · {ticker}",
+                xaxis_title="Date",
+                hovermode="x unified",
+            )
+        )
+
+        # Plot price line on primary y-axis
+        fig.add_scatter(
+            name="Price",
+            x=price_data_normalized.index,
+            y=price_data_normalized[price_col],
+            mode="lines",
+            line=dict(width=2, color="#02d2ff"),
+            hovertemplate="<b>%{x|%Y-%m-%d}</b><br>Price: $%{y:.2f}<extra></extra>",
+        )
+
+        if not contracts_df.empty:
+            contracts_normalized = contracts_df.copy()
+            if contracts_normalized.index.tz is not None:
+                contracts_normalized.index = contracts_normalized.index.tz_localize(None)
+
+            amounts = contracts_normalized.get("awardAmount", pd.Series(dtype=float))
+
+            hover_text = []
+            for _, row in contracts_normalized.iterrows():
+                agency = row.get("awardingAgency", "N/A")
+                desc = row.get("description", "")
+                if len(str(desc)) > 80:
+                    desc = str(desc)[:80] + "…"
+                naics = row.get("naicsDescription", "")
+                amount = row.get("awardAmount", 0)
+                hover_text.append(
+                    f"Agency: {agency}<br>"
+                    f"Amount: ${amount:,.0f}<br>"
+                    f"NAICS: {naics}<br>"
+                    f"Desc: {desc}"
+                )
+
+            fig.add_bar(
+                name="Contract Award",
+                x=contracts_normalized.index,
+                y=amounts,
+                marker_color="rgba(249,200,14,0.6)",
+                yaxis="y2",
+                hovertext=hover_text,
+                hovertemplate="<b>%{x|%Y-%m-%d}</b><br>%{hovertext}<extra></extra>",
+            )
+
+        fig.update_layout(
+            yaxis=dict(title="Price", showgrid=True),
+            yaxis2=dict(
+                title="Award Amount ($)",
+                overlaying="y",
+                side="right",
+                showgrid=False,
+                zeroline=False,
+                rangemode="tozero",
+            ),
+        )
+
+        if show and not as_json:
+            fig.show()
+            return None
+        return fig.to_json() if as_json else fig
+
     # --------------------------------------------------------------------- #
     # Helper methods                                                         #
     # --------------------------------------------------------------------- #

{finbrain_python-0.2.3.dist-info → finbrain_python-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.3
+Version: 0.2.4
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -105,6 +105,13 @@ fb.reddit_mentions.ticker("TSLA",
                           date_to="2026-03-17",
                           as_dataframe=True)
 
+# ---------- government contracts ----------
+fb.government_contracts.ticker("LMT",
+                               date_from="2025-01-01",
+                               date_to="2025-12-31",
+                               limit=50,
+                               as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -137,6 +144,7 @@ fb.screener.sentiment(market="S&P 500", as_dataframe=True)
 fb.screener.predictions_daily(limit=100, as_dataframe=True)
 fb.screener.insider_trading(limit=50)
 fb.screener.reddit_mentions(limit=100, as_dataframe=True)
+fb.screener.government_contracts(limit=100, as_dataframe=True)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -312,6 +320,7 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | Senate trades        | `client.senate_trades.ticker()`          | `/congress/senate/{SYMBOL}`                 |
 | Corporate lobbying   | `client.corporate_lobbying.ticker()`     | `/lobbying/{SYMBOL}`                        |
 | Reddit mentions      | `client.reddit_mentions.ticker()`        | `/reddit-mentions/{SYMBOL}`                 |
+| Gov. contracts       | `client.government_contracts.ticker()`   | `/government-contracts/{SYMBOL}`            |
 | Insider transactions | `client.insider_transactions.ticker()`   | `/insider-trading/{SYMBOL}`                 |
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedin/{SYMBOL}`                        |
 | Options – Put/Call   | `client.options.put_call()`              | `/put-call-ratio/{SYMBOL}`                  |
@@ -319,6 +328,7 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 |                      | `client.screener.predictions_daily()`    | `/screener/predictions/daily`               |
 |                      | `client.screener.insider_trading()`      | `/screener/insider-trading`                 |
 |                      | `client.screener.reddit_mentions()`      | `/screener/reddit-mentions`                 |
+|                      | `client.screener.government_contracts()` | `/screener/government-contracts`            |
 |                      | ... and 8 more screener methods          |                                             |
 | Recent               | `client.recent.news()`                   | `/recent/news`                              |
 |                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |

{finbrain_python-0.2.3.dist-info → finbrain_python-0.2.4.dist-info}/RECORD

@@ -1,16 +1,17 @@
 finbrain/__init__.py,sha256=ULIgwHkWbj5sT0udC3SlTROhZCgm2y9BtPox-4joNn4,416
-finbrain/client.py,sha256=tk-CzppuN8U1AJ4lR1XfvHs_ymSpn86EP8776nwYmYs,5120
+finbrain/client.py,sha256=7ytNARm22V9ePOIPv6hq-UGvphSC9fsIuxQqTfL313I,5252
 finbrain/exceptions.py,sha256=ZkuhWfaMAqoEfhrN_6V2XPq0eY7vPCINM9S__tfgqYI,6249
-finbrain/plotting.py,sha256=cNLaOVBKhS6wBjB-MwEc_H6F28C4vNXBIiU-aIbUMt0,47971
+finbrain/plotting.py,sha256=ZDswlMAGfQzjCYNmKmcfpkljs9FYl4kOKJyy9vl1z2w,53596
 finbrain/py.typed,sha256=INFR1qO3jdMrtVPs0N0SAVKVbjKV80HQPoPshwGEpGo,27
 finbrain/aio/__init__.py,sha256=eJra9SqvLMkq5zoZfG6WFw7kd1jGpf9l-ovuPMeWvdw,125
-finbrain/aio/client.py,sha256=-MIJBKUfe_dGIDMAmJPlx2mQaq-XLToWWUe6owsbVqE,7029
+finbrain/aio/client.py,sha256=aiYDmukVDoCw9MmrPdxMyLOoPlR77il_nZO9CvP3ZHk,7171
 finbrain/aio/endpoints/__init__.py,sha256=zdNSU1jzvnK6JnHxrvb3ye9KFCkA86xDTu9bBzmwrEQ,48
 finbrain/aio/endpoints/_utils.py,sha256=4ElYWGCcJ7t_lx02e49NvFHMt2g6DTcnwx3Mvwf3KyY,908
 finbrain/aio/endpoints/analyst_ratings.py,sha256=IYG-PU8HDOZoyyMcb_2KRxhiMVicYyaU_TOCVZPWroo,1451
 finbrain/aio/endpoints/app_ratings.py,sha256=QrJoLc7roTPRfInAEMwlr9vtxzruFJulGdB6msz7Eg0,2177
 finbrain/aio/endpoints/available.py,sha256=rQuffHowNF7FrVV5Ds-KE5iFjdz0I_vD7Qk2_zY2WLo,2315
 finbrain/aio/endpoints/corporate_lobbying.py,sha256=4rILB9-W91n6v2UwOnlVeH-ulk4D8onamzdEJf--wko,1429
+finbrain/aio/endpoints/government_contracts.py,sha256=-jKXMHWrdG-4PszBSTQpK-i4SHpVZufPDBABMDB56Gk,1540
 finbrain/aio/endpoints/house_trades.py,sha256=HQVFnCI_rn9mdYWUTiU10iRoFxYdIeR7AhmqKrItndU,1427
 finbrain/aio/endpoints/insider_transactions.py,sha256=EBqHdvapYWvI53PM_sQy0caN2rbl7Qul4OmqzItMUR0,1437
 finbrain/aio/endpoints/linkedin_data.py,sha256=ucnkyNc1waiFHLxas1onPhxh9Y7ekcI_gOfUJ5gu1hI,1469
@@ -19,7 +20,7 @@ finbrain/aio/endpoints/options.py,sha256=k1XL3ktoFL2Exw6UE2XfU-EcS1Xw8BPXQzABLYX
 finbrain/aio/endpoints/predictions.py,sha256=BrUSmqy0v7ngXyoE_UHgqdght8qtJ8IRxAhk_s9UeR0,1285
 finbrain/aio/endpoints/recent.py,sha256=TSaAwf5w86O1plSmm4eg_gKSjSap2Z8rd2i7FAvgm90,2302
 finbrain/aio/endpoints/reddit_mentions.py,sha256=P9ToZRaRN521RJ9W2J8cBCySUsNT47ROe-8TTdVtlqA,1508
-finbrain/aio/endpoints/screener.py,sha256=Sbb_FzGP8-vTSLkysIbdJBcQnTbS_FTvkOSHUtG0zFE,9230
+finbrain/aio/endpoints/screener.py,sha256=MYkIIZ6ocyx9khkxYjJnMQeg098-uZpdoSVbkUUj8Z4,9751
 finbrain/aio/endpoints/senate_trades.py,sha256=nhZd8R7Tclxzn-J4-ZWZ5onvBBd8pVOtiLfhKFtFBHw,1431
 finbrain/aio/endpoints/sentiments.py,sha256=BXFT0jr5j0MnB65MXGxZK36BJLXMTuggkFF9A9eenEQ,1532
 finbrain/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -28,6 +29,7 @@ finbrain/endpoints/analyst_ratings.py,sha256=6q_tecgnbzXn2wLSWqHNUa9MbLcybTD7xEB
 finbrain/endpoints/app_ratings.py,sha256=mbeKiJ87nNibnz9AT2kmH4fVFA4goEcld910abm3tFs,3597
 finbrain/endpoints/available.py,sha256=3cXjDK1qE38RHAfQ2C14oD7l7dR8mhDtUcva3LzlK5s,3911
 finbrain/endpoints/corporate_lobbying.py,sha256=K4jFcgx2_PqxFSlSm2E0rxuunl7FjWEwk_S4nfjsMuw,2213
+finbrain/endpoints/government_contracts.py,sha256=jb96byPNK32AsEQWgCHMU7kAue9BFC539TH10JGfY7I,2343
 finbrain/endpoints/house_trades.py,sha256=x_C5Xc-Cj9CKdR2014XcP6G_zeXSWChwR8bKbkLzuGM,2235
 finbrain/endpoints/insider_transactions.py,sha256=TU6EsSHIeams4OLJ9s8BpNuXeBnWPHghlp4enqkEFe8,2244
 finbrain/endpoints/linkedin_data.py,sha256=zcNboQ-Ejt_7Ncu3p9WCd-PsjEBFbojVaJZdkbaGT8Q,2215
@@ -36,11 +38,11 @@ finbrain/endpoints/options.py,sha256=_TYWPcJ-gmPTQRg_kEVQl6Oj6fAirtZJ8QrfqFA2cMU
 finbrain/endpoints/predictions.py,sha256=og1RY68p4O71smogrx-M5FyGk8FVclBGP18BvttzbZk,2026
 finbrain/endpoints/recent.py,sha256=7D36oVRJKF5hkR42y6M6CiEMYksuFleZou1v86SbEfA,3004
 finbrain/endpoints/reddit_mentions.py,sha256=WiePVAyUbA0VpWOd22M2YTlDWOQITp8qUBraI29y6d4,2305
-finbrain/endpoints/screener.py,sha256=oYavOKnVPwzOHsiUSAHz71saDB549QGkBblWSoZfFJo,9164
+finbrain/endpoints/screener.py,sha256=jBPUvmfj0Zfj5aoDLBtfXlYIR0UynIG613duSkck3NY,9665
 finbrain/endpoints/senate_trades.py,sha256=K6r_-Wt1HOs0dDXngHdj6Eo_UUJXAy5yE4EmmQbGaiU,2226
 finbrain/endpoints/sentiments.py,sha256=sGGPaxzGGFvMOaYv3VSCmnG7H9v7OVlX7Vsndct8jhA,2606
-finbrain_python-0.2.3.dist-info/licenses/LICENSE,sha256=x71LjIUPbK7Y8YBulH_AXzEIX7BK90dgFL2zA6LBT-A,1069
-finbrain_python-0.2.3.dist-info/METADATA,sha256=dEKQiYbSZ0HntdcSEK1SFF_cS8OZqDT9omO9qe10sm8,14828
-finbrain_python-0.2.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-finbrain_python-0.2.3.dist-info/top_level.txt,sha256=dCiQtTx3z2TtO_yQI6q3yODcdb-pABB-iEReJegVAv0,9
-finbrain_python-0.2.3.dist-info/RECORD,,
+finbrain_python-0.2.4.dist-info/licenses/LICENSE,sha256=x71LjIUPbK7Y8YBulH_AXzEIX7BK90dgFL2zA6LBT-A,1069
+finbrain_python-0.2.4.dist-info/METADATA,sha256=qLUp9VxSkq5FRsYFAgpI5rLxClH-uUfcy2auc8bNLno,15402
+finbrain_python-0.2.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+finbrain_python-0.2.4.dist-info/top_level.txt,sha256=dCiQtTx3z2TtO_yQI6q3yODcdb-pABB-iEReJegVAv0,9
+finbrain_python-0.2.4.dist-info/RECORD,,