finbrain-python 0.2.3__tar.gz → 0.2.4__tar.gz

{finbrain_python-0.2.3 → finbrain_python-0.2.4}/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.4] - 2026-03-30
+
+### Added
+
+- **Government Contracts Endpoint**: `fb.government_contracts.ticker("LMT")` — fetch U.S. government contract awards with award amounts, agencies, NAICS codes, and descriptions (`/government-contracts/{SYMBOL}`)
+- **Government Contracts Screener**: `fb.screener.government_contracts()` — cross-ticker government contracts with summary stats (`/screener/government-contracts`)
+- **Government Contracts Plotting**: `fb.plot.government_contracts()` — visualize contract award amounts as bars on a secondary y-axis overlaid on a price chart, with hover details showing agency, NAICS description, and contract description
+- **Async Government Contracts**: Full async support via `AsyncGovernmentContractsAPI`
+- **Government Contracts Tests**: Unit tests (`tests/test_government_contracts.py`), screener tests, integration tests, and plotting tests
+
 ## [0.2.3] - 2026-03-17
 
 ### Changed

{finbrain_python-0.2.3 → finbrain_python-0.2.4}/PKG-INFO

@@ -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 → finbrain_python-0.2.4}/README.md

@@ -79,6 +79,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)
 
@@ -111,6 +118,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)
@@ -286,6 +294,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}`                  |
@@ -293,6 +302,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 → finbrain_python-0.2.4}/src/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_python-0.2.4/src/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_python-0.2.3 → finbrain_python-0.2.4}/src/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_python-0.2.3 → finbrain_python-0.2.4}/src/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_python-0.2.4/src/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_python-0.2.3 → finbrain_python-0.2.4}/src/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_python-0.2.3 → finbrain_python-0.2.4}/src/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 → finbrain_python-0.2.4}/src/finbrain_python.egg-info/PKG-INFO

@@ -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 → finbrain_python-0.2.4}/src/finbrain_python.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ src/finbrain/aio/endpoints/analyst_ratings.py
 src/finbrain/aio/endpoints/app_ratings.py
 src/finbrain/aio/endpoints/available.py
 src/finbrain/aio/endpoints/corporate_lobbying.py
+src/finbrain/aio/endpoints/government_contracts.py
 src/finbrain/aio/endpoints/house_trades.py
 src/finbrain/aio/endpoints/insider_transactions.py
 src/finbrain/aio/endpoints/linkedin_data.py
@@ -39,6 +40,7 @@ src/finbrain/endpoints/analyst_ratings.py
 src/finbrain/endpoints/app_ratings.py
 src/finbrain/endpoints/available.py
 src/finbrain/endpoints/corporate_lobbying.py
+src/finbrain/endpoints/government_contracts.py
 src/finbrain/endpoints/house_trades.py
 src/finbrain/endpoints/insider_transactions.py
 src/finbrain/endpoints/linkedin_data.py
@@ -63,6 +65,7 @@ tests/test_async_client.py
 tests/test_available.py
 tests/test_corporate_lobbying.py
 tests/test_envelope.py
+tests/test_government_contracts.py
 tests/test_house_trades.py
 tests/test_insider_transactions.py
 tests/test_integration.py

{finbrain_python-0.2.3 → finbrain_python-0.2.4}/tests/test_async_client.py

@@ -72,3 +72,5 @@ async def test_async_endpoints_exist():
         assert hasattr(client, "linkedin_data")
         assert hasattr(client, "options")
         assert hasattr(client, "corporate_lobbying")
+        assert hasattr(client, "reddit_mentions")
+        assert hasattr(client, "government_contracts")

finbrain_python-0.2.4/tests/test_government_contracts.py

@@ -0,0 +1,214 @@
+# tests/test_government_contracts.py
+import pandas as pd
+import pytest
+
+from .conftest import stub_json, wrap_v2
+from finbrain.exceptions import BadRequest
+
+TICKER = "LMT"
+
+
+# ─────────── raw JSON branch ────────────────────────────────────────────
+def test_government_contracts_raw_ok(client, _activate_responses):
+    path = f"government-contracts/{TICKER}"
+    payload = wrap_v2({
+        "symbol": "LMT",
+        "name": "Lockheed Martin Corporation",
+        "contracts": [
+            {
+                "awardId": "CONT_AWD_0001",
+                "awardAmount": 50000000,
+                "awardType": "",
+                "awardingAgency": "Department of Defense",
+                "awardingSubAgency": "Department of the Army",
+                "recipientName": "Lockheed Martin Corporation",
+                "startDate": "2025-06-01",
+                "endDate": "2026-06-01",
+                "description": "Aircraft maintenance services",
+                "naicsCode": "336411",
+                "naicsDescription": "Aircraft Manufacturing",
+                "contractAwardType": "",
+            },
+            {
+                "awardId": "CONT_AWD_0002",
+                "awardAmount": 12000000,
+                "awardType": "",
+                "awardingAgency": "NASA",
+                "awardingSubAgency": "NASA Headquarters",
+                "recipientName": "Lockheed Martin Corporation",
+                "startDate": "2025-03-15",
+                "endDate": "2027-03-15",
+                "description": "Space systems development",
+                "naicsCode": "336414",
+                "naicsDescription": "Guided Missile and Space Vehicle Manufacturing",
+                "contractAwardType": "",
+            },
+        ],
+    })
+
+    stub_json(_activate_responses, "GET", path, payload)
+
+    data = client.government_contracts.ticker(symbol=TICKER)
+    assert data["symbol"] == TICKER
+    assert isinstance(data["contracts"], list)
+    assert len(data["contracts"]) == 2
+    assert data["contracts"][0]["awardingAgency"] == "Department of Defense"
+    assert data["contracts"][0]["awardAmount"] == 50000000
+
+
+# ─────────── DataFrame branch ───────────────────────────────────────────
+def test_government_contracts_dataframe_ok(client, _activate_responses):
+    path = f"government-contracts/{TICKER}"
+    payload = wrap_v2({
+        "symbol": "LMT",
+        "name": "Lockheed Martin Corporation",
+        "contracts": [
+            {
+                "awardId": "CONT_AWD_0001",
+                "awardAmount": 50000000,
+                "awardingAgency": "Department of Defense",
+                "recipientName": "Lockheed Martin Corporation",
+                "startDate": "2025-06-01",
+                "endDate": "2026-06-01",
+                "description": "Aircraft maintenance services",
+                "naicsCode": "336411",
+                "naicsDescription": "Aircraft Manufacturing",
+            },
+            {
+                "awardId": "CONT_AWD_0002",
+                "awardAmount": 12000000,
+                "awardingAgency": "NASA",
+                "recipientName": "Lockheed Martin Corporation",
+                "startDate": "2025-03-15",
+                "endDate": "2027-03-15",
+                "description": "Space systems development",
+                "naicsCode": "336414",
+                "naicsDescription": "Guided Missile and Space Vehicle Manufacturing",
+            },
+        ],
+    })
+
+    stub_json(_activate_responses, "GET", path, payload)
+
+    df = client.government_contracts.ticker(symbol=TICKER, as_dataframe=True)
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert "awardAmount" in df.columns
+    assert "awardingAgency" in df.columns
+    assert df.index.name == "startDate"
+    assert pd.api.types.is_datetime64_any_dtype(df.index)
+
+
+# ─────────── with query params ──────────────────────────────────────────
+def test_government_contracts_with_params(client, _activate_responses):
+    path = f"government-contracts/{TICKER}"
+    payload = wrap_v2({
+        "symbol": "LMT",
+        "name": "Lockheed Martin Corporation",
+        "contracts": [],
+    })
+    stub_json(
+        _activate_responses,
+        "GET",
+        path,
+        payload,
+        params={"startDate": "2025-01-01", "endDate": "2025-12-31", "limit": "10"},
+    )
+
+    data = client.government_contracts.ticker(
+        symbol=TICKER,
+        date_from="2025-01-01",
+        date_to="2025-12-31",
+        limit=10,
+    )
+    assert data["symbol"] == TICKER
+
+
+# ─────────── error mapping ──────────────────────────────────────────────
+def test_government_contracts_bad_request(client, _activate_responses):
+    path = f"government-contracts/{TICKER}"
+    stub_json(
+        _activate_responses,
+        "GET",
+        path,
+        {"success": False, "error": {"code": "VALIDATION_ERROR", "message": "bad"}},
+        status=400,
+    )
+
+    with pytest.raises(BadRequest):
+        client.government_contracts.ticker(symbol=TICKER)
+
+
+# ─────────── screener raw JSON ──────────────────────────────────────────
+def test_government_contracts_screener_raw_ok(client, _activate_responses):
+    path = "screener/government-contracts"
+    payload = wrap_v2({
+        "data": [
+            {
+                "symbol": "LMT",
+                "name": "Lockheed Martin Corporation",
+                "awardId": "CONT_AWD_0001",
+                "awardAmount": 50000000,
+                "recipientName": "Lockheed Martin Corporation",
+                "startDate": "2025-06-01",
+                "awardingAgency": "Department of Defense",
+                "naicsDescription": "Aircraft Manufacturing",
+            },
+        ],
+        "summary": {
+            "totalContracts": 1,
+            "totalTickers": 1,
+            "totalValue": 50000000,
+        },
+    })
+
+    stub_json(_activate_responses, "GET", path, payload)
+
+    data = client.screener.government_contracts()
+    assert isinstance(data, list)
+    assert data[0]["symbol"] == "LMT"
+    assert data[0]["awardAmount"] == 50000000
+
+
+# ─────────── screener DataFrame ─────────────────────────────────────────
+def test_government_contracts_screener_dataframe_ok(client, _activate_responses):
+    path = "screener/government-contracts"
+    payload = wrap_v2({
+        "data": [
+            {
+                "symbol": "LMT",
+                "name": "Lockheed Martin Corporation",
+                "awardId": "CONT_AWD_0001",
+                "awardAmount": 50000000,
+                "recipientName": "Lockheed Martin Corporation",
+                "startDate": "2025-06-01",
+                "awardingAgency": "Department of Defense",
+                "naicsDescription": "Aircraft Manufacturing",
+            },
+            {
+                "symbol": "BA",
+                "name": "The Boeing Company",
+                "awardId": "CONT_AWD_0003",
+                "awardAmount": 80000000,
+                "recipientName": "The Boeing Company",
+                "startDate": "2025-05-20",
+                "awardingAgency": "Department of Defense",
+                "naicsDescription": "Aircraft Manufacturing",
+            },
+        ],
+        "summary": {
+            "totalContracts": 2,
+            "totalTickers": 2,
+            "totalValue": 130000000,
+        },
+    })
+
+    stub_json(_activate_responses, "GET", path, payload)
+
+    df = client.screener.government_contracts(as_dataframe=True)
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert df.index.name == "symbol"
+    assert "awardAmount" in df.columns

{finbrain_python-0.2.3 → finbrain_python-0.2.4}/tests/test_integration.py

@@ -333,6 +333,47 @@ class TestRedditMentions:
         assert len(df) > 0
 
 
+# =====================================================================
+# Government Contracts
+# =====================================================================
+class TestGovernmentContracts:
+    def test_raw(self, fb):
+        data = fb.government_contracts.ticker("LMT")
+        assert isinstance(data, dict)
+        assert "contracts" in data
+        contracts = data["contracts"]
+        assert isinstance(contracts, list)
+        if len(contracts) > 0:
+            assert "startDate" in contracts[0]
+            assert "awardAmount" in contracts[0]
+            assert "awardingAgency" in contracts[0]
+            assert "recipientName" in contracts[0]
+
+    def test_dataframe(self, fb):
+        df = fb.government_contracts.ticker("LMT", as_dataframe=True)
+        assert isinstance(df, pd.DataFrame)
+        if len(df) > 0:
+            assert df.index.name == "startDate"
+            assert pd.api.types.is_datetime64_any_dtype(df.index)
+            assert "awardAmount" in df.columns
+            assert "awardingAgency" in df.columns
+
+    def test_screener_raw(self, fb):
+        data = fb.screener.government_contracts()
+        assert isinstance(data, list)
+        if len(data) > 0:
+            row = data[0]
+            assert "symbol" in row
+            assert "awardAmount" in row
+            assert "awardingAgency" in row
+
+    def test_screener_dataframe(self, fb):
+        df = fb.screener.government_contracts(as_dataframe=True)
+        assert isinstance(df, pd.DataFrame)
+        if len(df) > 0:
+            assert df.index.name == "symbol"
+
+
 # =====================================================================
 # LinkedIn Data
 # =====================================================================

{finbrain_python-0.2.3 → finbrain_python-0.2.4}/tests/test_plotting.py

@@ -547,3 +547,48 @@ def test_reddit_mentions_top_latest_snapshot():
 
     # Should use the 08:00 snapshot (120 mentions), not 04:00 (50)
     assert fig.data[0].x == (85,)  # wsb=85 from the latest snapshot
+
+
+# ── government_contracts ──────────────────────────────────────────────
+
+class MockGovernmentContractsClient:
+    class government_contracts:
+        @staticmethod
+        def ticker(*args, **kwargs):
+            df = pd.DataFrame({
+                "awardAmount": [50000000, 12000000],
+                "awardingAgency": ["Department of Defense", "NASA"],
+                "description": ["Aircraft maintenance", "Space systems"],
+                "naicsDescription": ["Aircraft Manufacturing", "Guided Missile Mfg"],
+                "startDate": pd.to_datetime(["2024-01-15", "2024-03-20"]),
+            }).set_index("startDate")
+            return df
+
+
+def test_government_contracts_plot():
+    plot = _PlotNamespace(MockGovernmentContractsClient())
+    fig = plot.government_contracts("LMT", price_data=PRICE_DF, show=False)
+
+    assert isinstance(fig, go.Figure)
+    # price line + contract award bars
+    assert len(fig.data) >= 2
+    assert "Government Contracts" in fig.layout.title.text
+
+
+def test_government_contracts_empty_price_data():
+    plot = _PlotNamespace(MockClient())
+    with pytest.raises(ValueError, match="price_data cannot be empty"):
+        plot.government_contracts("LMT", price_data=pd.DataFrame())
+
+
+def test_government_contracts_missing_price_column():
+    plot = _PlotNamespace(MockClient())
+    bad_df = pd.DataFrame({"volume": [100, 200]})
+    with pytest.raises(ValueError, match="price_data must contain a price column"):
+        plot.government_contracts("LMT", price_data=bad_df)
+
+
+def test_government_contracts_as_json():
+    plot = _PlotNamespace(MockGovernmentContractsClient())
+    result = plot.government_contracts("LMT", price_data=PRICE_DF, show=False, as_json=True)
+    assert isinstance(result, str)

{finbrain_python-0.2.3 → finbrain_python-0.2.4}/tests/test_screener.py

@@ -312,3 +312,39 @@ def test_screener_predictions_monthly_dataframe(client, _activate_responses):
     assert set(df.columns) == {"name", "expectedLongTerm"}
     assert df.loc["AAPL", "expectedLongTerm"] == 1.5
     assert df.loc["TSLA", "expectedLongTerm"] == 2.1
+
+
+# ── government contracts ─────────────────────────────────────────────
+def test_screener_government_contracts(client, _activate_responses):
+    payload = wrap_v2({
+        "data": [
+            {"symbol": "LMT", "name": "Lockheed Martin", "awardAmount": 50000000,
+             "awardingAgency": "Department of Defense", "startDate": "2025-06-01"},
+        ],
+        "summary": {"totalContracts": 1, "totalTickers": 1, "totalValue": 50000000},
+    })
+    stub_json(_activate_responses, "GET", "screener/government-contracts", payload, params={"limit": "5"})
+    data = client.screener.government_contracts(limit=5)
+    assert isinstance(data, list)
+    assert len(data) == 1
+    assert data[0]["symbol"] == "LMT"
+    assert data[0]["awardAmount"] == 50000000
+
+
+def test_screener_government_contracts_dataframe(client, _activate_responses):
+    payload = wrap_v2({
+        "data": [
+            {"symbol": "LMT", "name": "Lockheed Martin", "awardAmount": 50000000,
+             "awardingAgency": "Department of Defense", "startDate": "2025-06-01"},
+            {"symbol": "BA", "name": "Boeing", "awardAmount": 80000000,
+             "awardingAgency": "Department of Defense", "startDate": "2025-05-20"},
+        ],
+        "summary": {"totalContracts": 2, "totalTickers": 2, "totalValue": 130000000},
+    })
+    stub_json(_activate_responses, "GET", "screener/government-contracts", payload, params={"limit": "5"})
+    df = client.screener.government_contracts(limit=5, as_dataframe=True)
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert df.index.name == "symbol"
+    assert "awardAmount" in df.columns
+    assert df.loc["LMT", "awardAmount"] == 50000000