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

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

@@ -5,15 +5,23 @@ 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.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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.2
+Version: 0.2.3
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -105,9 +105,6 @@ 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)
-
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -139,6 +136,7 @@ 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)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -264,10 +262,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 +312,13 @@ 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`                 |
 | 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`                 |
 |                      | ... 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.3}/README.md

@@ -79,9 +79,6 @@ 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)
-
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -113,6 +110,7 @@ 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)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -238,10 +236,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 +286,13 @@ 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`                 |
 | 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`                 |
 |                      | ... and 8 more screener methods          |                                             |
 | Recent               | `client.recent.news()`                   | `/recent/news`                              |
 |                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |

finbrain_python-0.2.3/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.3}/src/finbrain/aio/endpoints/screener.py

@@ -208,3 +208,17 @@ 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)

finbrain_python-0.2.3/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.3}/src/finbrain/endpoints/screener.py

@@ -213,3 +213,17 @@ 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)

{finbrain_python-0.2.2 → finbrain_python-0.2.3}/src/finbrain/plotting.py

@@ -1057,7 +1057,7 @@ class _PlotNamespace:
     # --------------------------------------------------------------------- #
     # Reddit Mentions Screener  → stacked horizontal bars (top N tickers)    #
     # --------------------------------------------------------------------- #
-    def reddit_mentions_screener(
+    def reddit_mentions_top(
         self,
         *,
         top_n: int = 15,
@@ -1091,20 +1091,20 @@ class _PlotNamespace:
             Plotly template name.
         **kwargs
             Additional arguments passed to
-            :meth:`FinBrainClient.reddit_mentions.screener`.
+            :meth:`FinBrainClient.screener.reddit_mentions`.
 
         Returns
         -------
         plotly.graph_objects.Figure or str or None
         """
-        data = self._fb.reddit_mentions.screener(
+        data = self._fb.screener.reddit_mentions(
             market=market,
             region=region,
             limit=limit,
             **kwargs,
         )
 
-        rows = data.get("data", [])
+        rows = data if isinstance(data, list) else data.get("data", [])
         if not rows:
             raise ValueError("No screener data returned")
 

{finbrain_python-0.2.2 → finbrain_python-0.2.3}/src/finbrain_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.2
+Version: 0.2.3
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -105,9 +105,6 @@ 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)
-
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -139,6 +136,7 @@ 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)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -264,10 +262,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 +312,13 @@ 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`                 |
 | 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`                 |
 |                      | ... 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.3}/tests/test_integration.py

@@ -319,19 +319,16 @@ class TestRedditMentions:
         assert "_all" in df["subreddit"].values
 
     def test_screener_raw(self, fb):
-        data = fb.reddit_mentions.screener()
-        assert isinstance(data, dict)
-        assert "data" in data
-        rows = data["data"]
-        assert isinstance(rows, list)
-        assert len(rows) > 0
-        row = rows[0]
+        data = fb.screener.reddit_mentions()
+        assert isinstance(data, list)
+        assert len(data) > 0
+        row = data[0]
         assert "symbol" in row
         assert "totalMentions" in row
         assert "subreddits" in row
 
     def test_screener_dataframe(self, fb):
-        df = fb.reddit_mentions.screener(as_dataframe=True)
+        df = fb.screener.reddit_mentions(as_dataframe=True)
         assert isinstance(df, pd.DataFrame)
         assert len(df) > 0
 

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

@@ -152,19 +152,17 @@ class MockRedditMentionsClient:
             }).set_index("date")
             return df
 
+    class screener:
         @staticmethod
-        def screener(*args, **kwargs):
-            return {
-                "data": [
-                    {"symbol": "TSLA", "name": "Tesla", "date": "2024-01-01T08:00:00Z",
-                     "totalMentions": 120, "subreddits": {"wallstreetbets": 85, "stocks": 12}},
-                    {"symbol": "AAPL", "name": "Apple", "date": "2024-01-01T08:00:00Z",
-                     "totalMentions": 45, "subreddits": {"wallstreetbets": 30, "stocks": 8}},
-                    {"symbol": "NVDA", "name": "NVIDIA", "date": "2024-01-01T08:00:00Z",
-                     "totalMentions": 80, "subreddits": {"wallstreetbets": 60, "stocks": 5}},
-                ],
-                "summary": {},
-            }
+        def reddit_mentions(*args, **kwargs):
+            return [
+                {"symbol": "TSLA", "name": "Tesla", "date": "2024-01-01T08:00:00Z",
+                 "totalMentions": 120, "subreddits": {"wallstreetbets": 85, "stocks": 12}},
+                {"symbol": "AAPL", "name": "Apple", "date": "2024-01-01T08:00:00Z",
+                 "totalMentions": 45, "subreddits": {"wallstreetbets": 30, "stocks": 8}},
+                {"symbol": "NVDA", "name": "NVIDIA", "date": "2024-01-01T08:00:00Z",
+                 "totalMentions": 80, "subreddits": {"wallstreetbets": 60, "stocks": 5}},
+            ]
 
 
 # ═══════════════════════════════════════════════════════════════════════════
@@ -480,11 +478,11 @@ def test_reddit_mentions_as_json():
     assert isinstance(result, str)
 
 
-# ── reddit_mentions_screener ──────────────────────────────────────────────
+# ── reddit_mentions_top ──────────────────────────────────────────────
 
-def test_reddit_mentions_screener_plot():
+def test_reddit_mentions_top_plot():
     plot = _PlotNamespace(MockRedditMentionsClient())
-    fig = plot.reddit_mentions_screener(show=False)
+    fig = plot.reddit_mentions_top(show=False)
 
     assert isinstance(fig, go.Figure)
     # 2 subreddits → 2 bar traces (stocks, wallstreetbets)
@@ -499,9 +497,9 @@ def test_reddit_mentions_screener_plot():
     assert symbols[0] == "AAPL"  # lowest mentions
 
 
-def test_reddit_mentions_screener_top_n():
+def test_reddit_mentions_top_top_n():
     plot = _PlotNamespace(MockRedditMentionsClient())
-    fig = plot.reddit_mentions_screener(top_n=2, show=False)
+    fig = plot.reddit_mentions_top(top_n=2, show=False)
 
     assert isinstance(fig, go.Figure)
     # Only top 2 tickers
@@ -512,43 +510,40 @@ def test_reddit_mentions_screener_top_n():
     assert "AAPL" not in symbols
 
 
-def test_reddit_mentions_screener_empty_data():
+def test_reddit_mentions_top_empty_data():
     class EmptyScreenerClient:
-        class reddit_mentions:
+        class screener:
             @staticmethod
-            def screener(*args, **kwargs):
-                return {"data": [], "summary": {}}
+            def reddit_mentions(*args, **kwargs):
+                return []
 
     plot = _PlotNamespace(EmptyScreenerClient())
     with pytest.raises(ValueError, match="No screener data returned"):
-        plot.reddit_mentions_screener(show=False)
+        plot.reddit_mentions_top(show=False)
 
 
-def test_reddit_mentions_screener_as_json():
+def test_reddit_mentions_top_as_json():
     plot = _PlotNamespace(MockRedditMentionsClient())
-    result = plot.reddit_mentions_screener(show=False, as_json=True)
+    result = plot.reddit_mentions_top(show=False, as_json=True)
     assert isinstance(result, str)
 
 
-def test_reddit_mentions_screener_latest_snapshot():
+def test_reddit_mentions_top_latest_snapshot():
     """Verify that only the latest snapshot per ticker is used."""
 
     class MultiSnapshotClient:
-        class reddit_mentions:
+        class screener:
             @staticmethod
-            def screener(*args, **kwargs):
-                return {
-                    "data": [
-                        {"symbol": "TSLA", "date": "2024-01-01T04:00:00Z",
-                         "totalMentions": 50, "subreddits": {"wsb": 30}},
-                        {"symbol": "TSLA", "date": "2024-01-01T08:00:00Z",
-                         "totalMentions": 120, "subreddits": {"wsb": 85}},
-                    ],
-                    "summary": {},
-                }
+            def reddit_mentions(*args, **kwargs):
+                return [
+                    {"symbol": "TSLA", "date": "2024-01-01T04:00:00Z",
+                     "totalMentions": 50, "subreddits": {"wsb": 30}},
+                    {"symbol": "TSLA", "date": "2024-01-01T08:00:00Z",
+                     "totalMentions": 120, "subreddits": {"wsb": 85}},
+                ]
 
     plot = _PlotNamespace(MultiSnapshotClient())
-    fig = plot.reddit_mentions_screener(show=False)
+    fig = plot.reddit_mentions_top(show=False)
 
     # Should use the 08:00 snapshot (120 mentions), not 04:00 (50)
     assert fig.data[0].x == (85,)  # wsb=85 from the latest snapshot

{finbrain_python-0.2.2 → finbrain_python-0.2.3}/tests/test_reddit_mentions.py

@@ -117,11 +117,10 @@ def test_reddit_mentions_screener_raw_ok(client, _activate_responses):
 
     stub_json(_activate_responses, "GET", path, payload)
 
-    data = client.reddit_mentions.screener()
-    assert isinstance(data["data"], list)
-    assert data["data"][0]["symbol"] == "TSLA"
-    assert data["data"][0]["totalMentions"] == 120
-    assert data["summary"]["totalTickers"] == 1
+    data = client.screener.reddit_mentions()
+    assert isinstance(data, list)
+    assert data[0]["symbol"] == "TSLA"
+    assert data[0]["totalMentions"] == 120
 
 
 # ─────────── screener DataFrame ─────────────────────────────────────────
@@ -155,14 +154,9 @@ def test_reddit_mentions_screener_dataframe_ok(client, _activate_responses):
 
     stub_json(_activate_responses, "GET", path, payload)
 
-    df = client.reddit_mentions.screener(as_dataframe=True)
+    df = client.screener.reddit_mentions(as_dataframe=True)
 
     assert isinstance(df, pd.DataFrame)
     assert len(df) == 2
-    assert df.index.name == "date"
-    assert pd.api.types.is_datetime64_any_dtype(df.index)
-    # Verify timestamps preserve time component (UTC-aware from ISO Z suffix)
-    assert pd.Timestamp("2026-03-17 08:00:00", tz="UTC") in df.index
-    assert pd.Timestamp("2026-03-17 12:00:00", tz="UTC") in df.index
+    assert df.index.name == "symbol"
     assert "totalMentions" in df.columns
-    assert "symbol" in df.columns

finbrain_python-0.2.2/src/finbrain/aio/endpoints/reddit_mentions.py

@@ -1,79 +0,0 @@
-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
-
-    async def screener(
-        self,
-        *,
-        limit: int | None = None,
-        market: str | None = None,
-        region: str | None = None,
-        as_dataframe: bool = False,
-    ) -> Dict[str, Any] | pd.DataFrame:
-        """Get recent Reddit mention counts across all tickers (async)."""
-        params: Dict[str, str] = {}
-        if limit is not None:
-            params["limit"] = str(limit)
-        if market:
-            params["market"] = market
-        if region:
-            params["region"] = region
-
-        data: Dict[str, Any] = await self._c._request(
-            "GET", "screener/reddit-mentions", 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/src/finbrain/endpoints/reddit_mentions.py

@@ -1,123 +0,0 @@
-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
-
-    # ------------------------------------------------------------------ #
-    def screener(
-        self,
-        *,
-        limit: int | None = None,
-        market: str | None = None,
-        region: str | None = None,
-        as_dataframe: bool = False,
-    ) -> Dict[str, Any] | pd.DataFrame:
-        """
-        Get recent Reddit mention counts across all tickers.
-
-        Parameters
-        ----------
-        limit :
-            Maximum number of records to return (1-20000).
-        market :
-            Filter by market name (e.g. ``"S&P 500"``, ``"NASDAQ"``).
-        region :
-            Filter by region (e.g. ``"US"``, ``"Europe"``).
-        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 limit is not None:
-            params["limit"] = str(limit)
-        if market:
-            params["market"] = market
-        if region:
-            params["region"] = region
-
-        data: Dict[str, Any] = self._c._request(
-            "GET", "screener/reddit-mentions", 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