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

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

@@ -5,15 +5,33 @@ 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
+
+- **Reddit Mentions Screener**: Moved from `fb.reddit_mentions.screener()` to `fb.screener.reddit_mentions()` for consistency with other screener endpoints
+- **Plotting rename**: `fb.plot.reddit_mentions_screener()` renamed to `fb.plot.reddit_mentions_top()` to better reflect the chart's purpose (top N most mentioned tickers)
+
 ## [0.2.2] - 2026-03-17
 
 ### Added
 
 - **Reddit Mentions Endpoint**: `fb.reddit_mentions.ticker("TSLA")` — fetch per-subreddit mention counts with full timestamps (sampled every 4 hours) (`/reddit-mentions/{SYMBOL}`)
-- **Reddit Mentions Screener**: `fb.reddit_mentions.screener()` — cross-ticker Reddit mentions with aggregated totals and per-subreddit breakdowns (`/screener/reddit-mentions`)
-- **Reddit Mentions Plotting**: `fb.plot.reddit_mentions()` — stacked bars per subreddit overlaid on a price chart; `fb.plot.reddit_mentions_screener()` — horizontal stacked bar chart of top N most mentioned tickers from the latest screener snapshot
+- **Reddit Mentions Screener**: `fb.screener.reddit_mentions()` — cross-ticker Reddit mentions with aggregated totals and per-subreddit breakdowns (`/screener/reddit-mentions`)
+- **Reddit Mentions Plotting**: `fb.plot.reddit_mentions()` — stacked bars per subreddit overlaid on a price chart; `fb.plot.reddit_mentions_top()` — horizontal stacked bar chart of top N most mentioned tickers
 - **Async Reddit Mentions**: Full async support via `AsyncRedditMentionsAPI`
-- **Reddit Mentions Tests**: Unit tests (`tests/test_reddit_mentions.py`) covering ticker, screener, DataFrame, and error handling
+- **Reddit Mentions Tests**: Unit tests, integration tests, and functional plotting tests
+- **Plotting Test Coverage**: Added functional tests for all 11 plotting methods
 
 ## [0.2.1] - 2026-03-12
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.2
+Version: 0.2.4
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -105,8 +105,12 @@ fb.reddit_mentions.ticker("TSLA",
                           date_to="2026-03-17",
                           as_dataframe=True)
 
-# screener — cross-ticker Reddit mentions
-fb.reddit_mentions.screener(market="S&P 500", limit=100, 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)
@@ -139,6 +143,8 @@ fb.news.ticker("AMZN", limit=20, as_dataframe=True)
 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)
@@ -264,10 +270,10 @@ fb.plot.reddit_mentions("TSLA",
 ```python
 # ---------- Reddit Mentions Screener Chart (no price data needed) ----------
 # Stacked horizontal bar chart of top 15 most mentioned tickers
-fb.plot.reddit_mentions_screener(market="S&P 500")
+fb.plot.reddit_mentions_top(market="S&P 500")
 
 # Customize the number of tickers shown
-fb.plot.reddit_mentions_screener(top_n=10, region="US")
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -314,13 +320,15 @@ 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}`                 |
-|                      | `client.reddit_mentions.screener()`      | `/screener/reddit-mentions`                 |
+| 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}`                  |
 | Screener             | `client.screener.sentiment()`            | `/screener/sentiment`                       |
 |                      | `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.2 → finbrain_python-0.2.4}/README.md

@@ -79,8 +79,12 @@ fb.reddit_mentions.ticker("TSLA",
                           date_to="2026-03-17",
                           as_dataframe=True)
 
-# screener — cross-ticker Reddit mentions
-fb.reddit_mentions.screener(market="S&P 500", limit=100, 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)
@@ -113,6 +117,8 @@ fb.news.ticker("AMZN", limit=20, as_dataframe=True)
 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)
@@ -238,10 +244,10 @@ fb.plot.reddit_mentions("TSLA",
 ```python
 # ---------- Reddit Mentions Screener Chart (no price data needed) ----------
 # Stacked horizontal bar chart of top 15 most mentioned tickers
-fb.plot.reddit_mentions_screener(market="S&P 500")
+fb.plot.reddit_mentions_top(market="S&P 500")
 
 # Customize the number of tickers shown
-fb.plot.reddit_mentions_screener(top_n=10, region="US")
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -288,13 +294,15 @@ 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}`                 |
-|                      | `client.reddit_mentions.screener()`      | `/screener/reddit-mentions`                 |
+| 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}`                  |
 | Screener             | `client.screener.sentiment()`            | `/screener/sentiment`                       |
 |                      | `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.2 → 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.4/src/finbrain/aio/endpoints/reddit_mentions.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 AsyncRedditMentionsAPI:
+    """Async wrapper for /reddit-mentions and /screener/reddit-mentions 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 Reddit mention counts for a symbol across subreddits (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"reddit-mentions/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("data", [])
+            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_python-0.2.2 → finbrain_python-0.2.4}/src/finbrain/aio/endpoints/screener.py

@@ -208,3 +208,29 @@ class AsyncScreenerAPI:
         """Screen monthly (12-month) predictions across tickers."""
         params = self._build_params(limit=limit, market=market, region=region)
         return await self._get("screener/predictions/monthly", params, as_dataframe)
+
+    # ── reddit mentions ────────────────────────────────────────
+
+    async def reddit_mentions(
+        self,
+        *,
+        limit: int | None = None,
+        market: str | None = None,
+        region: str | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """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.2 → 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.4/src/finbrain/endpoints/reddit_mentions.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 RedditMentionsAPI:
+    """
+    Endpoints
+    ---------
+    ``/reddit-mentions/<TICKER>`` - Reddit mention counts per subreddit.
+    ``/screener/reddit-mentions``  - cross-ticker Reddit mentions 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 Reddit mention counts for *symbol* across subreddits.
+
+        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 ``date``;
+            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"reddit-mentions/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("data", [])
+            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_python-0.2.2 → finbrain_python-0.2.4}/src/finbrain/endpoints/screener.py

@@ -213,3 +213,29 @@ class ScreenerAPI:
         """Screen monthly (12-month) predictions across tickers."""
         params = self._build_params(limit=limit, market=market, region=region)
         return self._get("screener/predictions/monthly", params, as_dataframe)
+
+    # ── reddit mentions ────────────────────────────────────────
+
+    def reddit_mentions(
+        self,
+        *,
+        limit: int | None = None,
+        market: str | None = None,
+        region: str | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """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)