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

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

@@ -5,6 +5,24 @@ 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.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, integration tests, and functional plotting tests
+- **Plotting Test Coverage**: Added functional tests for all 11 plotting methods
+
 ## [0.2.1] - 2026-03-12
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.1
+Version: 0.2.3
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -99,6 +99,12 @@ fb.corporate_lobbying.ticker("AAPL",
                              date_to="2025-06-30",
                              as_dataframe=True)
 
+# ---------- reddit mentions ----------
+fb.reddit_mentions.ticker("TSLA",
+                          date_from="2026-03-01",
+                          date_to="2026-03-17",
+                          as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -130,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)
@@ -244,6 +251,21 @@ fb.plot.corporate_lobbying("AAPL",
                            price_data=price_df,
                            date_from="2024-01-01",
                            date_to="2025-06-30")
+
+# Plot Reddit mentions (stacked bars per subreddit) on your price chart
+fb.plot.reddit_mentions("TSLA",
+                        price_data=price_df,
+                        date_from="2026-03-01",
+                        date_to="2026-03-17")
+```
+
+```python
+# ---------- Reddit Mentions Screener Chart (no price data needed) ----------
+# Stacked horizontal bar chart of top 15 most mentioned tickers
+fb.plot.reddit_mentions_top(market="S&P 500")
+
+# Customize the number of tickers shown
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -289,12 +311,14 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | House trades         | `client.house_trades.ticker()`           | `/congress/house/{SYMBOL}`                  |
 | 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}`                 |
 | 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.1 → finbrain_python-0.2.3}/README.md

@@ -73,6 +73,12 @@ fb.corporate_lobbying.ticker("AAPL",
                              date_to="2025-06-30",
                              as_dataframe=True)
 
+# ---------- reddit mentions ----------
+fb.reddit_mentions.ticker("TSLA",
+                          date_from="2026-03-01",
+                          date_to="2026-03-17",
+                          as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -104,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)
@@ -218,6 +225,21 @@ fb.plot.corporate_lobbying("AAPL",
                            price_data=price_df,
                            date_from="2024-01-01",
                            date_to="2025-06-30")
+
+# Plot Reddit mentions (stacked bars per subreddit) on your price chart
+fb.plot.reddit_mentions("TSLA",
+                        price_data=price_df,
+                        date_from="2026-03-01",
+                        date_to="2026-03-17")
+```
+
+```python
+# ---------- Reddit Mentions Screener Chart (no price data needed) ----------
+# Stacked horizontal bar chart of top 15 most mentioned tickers
+fb.plot.reddit_mentions_top(market="S&P 500")
+
+# Customize the number of tickers shown
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -263,12 +285,14 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | House trades         | `client.house_trades.ticker()`           | `/congress/house/{SYMBOL}`                  |
 | 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}`                 |
 | 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.1 → finbrain_python-0.2.3}/src/finbrain/aio/client.py

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

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.1 → 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.1 → finbrain_python-0.2.3}/src/finbrain/client.py

@@ -24,6 +24,7 @@ from .endpoints.news import NewsAPI
 from .endpoints.screener import ScreenerAPI
 from .endpoints.recent import RecentAPI
 from .endpoints.corporate_lobbying import CorporateLobbyingAPI
+from .endpoints.reddit_mentions import RedditMentionsAPI
 
 
 # Which status codes merit a retry
@@ -77,6 +78,7 @@ class FinBrainClient:
         self.screener = ScreenerAPI(self)
         self.recent = RecentAPI(self)
         self.corporate_lobbying = CorporateLobbyingAPI(self)
+        self.reddit_mentions = RedditMentionsAPI(self)
 
     # ---------- private helpers ----------
     def _request(

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.1 → 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.1 → finbrain_python-0.2.3}/src/finbrain/plotting.py

@@ -907,6 +907,253 @@ class _PlotNamespace:
             return None
         return fig.to_json() if as_json else fig
 
+    # --------------------------------------------------------------------- #
+    # Reddit Mentions  → bars on price chart                                 #
+    # --------------------------------------------------------------------- #
+    def reddit_mentions(
+        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 Reddit mention counts 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. ``"AAPL"``).
+        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 mentions 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.reddit_mentions.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 Reddit mentions
+        mentions_df = self._fb.reddit_mentions.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"Reddit Mentions · {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 %H:%M}</b><br>Price: $%{y:.2f}<extra></extra>",
+        )
+
+        if not mentions_df.empty:
+            mentions_normalized = mentions_df.copy()
+            if mentions_normalized.index.tz is not None:
+                mentions_normalized.index = mentions_normalized.index.tz_localize(None)
+
+            # Exclude _all (aggregate) — use individual subreddits for stacked bars
+            per_sub = mentions_normalized[
+                mentions_normalized["subreddit"] != "_all"
+            ]
+
+            if not per_sub.empty:
+                for subreddit in sorted(per_sub["subreddit"].unique()):
+                    sub_data = per_sub[per_sub["subreddit"] == subreddit]
+                    fig.add_bar(
+                        name=f"r/{subreddit}",
+                        x=sub_data.index,
+                        y=sub_data["mentions"],
+                        yaxis="y2",
+                        hovertemplate=(
+                            "<b>%{x|%Y-%m-%d %H:%M}</b><br>"
+                            f"r/{subreddit}: " + "%{y:,}<extra></extra>"
+                        ),
+                    )
+
+        fig.update_layout(
+            barmode="stack",
+            yaxis=dict(title="Price", showgrid=True),
+            yaxis2=dict(
+                title="Mentions",
+                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
+
+    # --------------------------------------------------------------------- #
+    # Reddit Mentions Screener  → stacked horizontal bars (top N tickers)    #
+    # --------------------------------------------------------------------- #
+    def reddit_mentions_top(
+        self,
+        *,
+        top_n: int = 15,
+        market: str | None = None,
+        region: str | None = None,
+        limit: int | None = None,
+        as_json: bool = False,
+        show: bool = True,
+        template: str = "plotly_dark",
+        **kwargs,
+    ):
+        """
+        Plot a stacked horizontal bar chart of the most mentioned tickers
+        from the latest Reddit mentions screener snapshot.
+
+        Parameters
+        ----------
+        top_n : int, default 15
+            Number of top-mentioned tickers to display.
+        market : str or None, optional
+            Filter by market name (e.g. ``"S&P 500"``).
+        region : str or None, optional
+            Filter by region (e.g. ``"US"``).
+        limit : int or None, optional
+            Maximum records to fetch from the screener API.
+        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.screener.reddit_mentions`.
+
+        Returns
+        -------
+        plotly.graph_objects.Figure or str or None
+        """
+        data = self._fb.screener.reddit_mentions(
+            market=market,
+            region=region,
+            limit=limit,
+            **kwargs,
+        )
+
+        rows = data if isinstance(data, list) else data.get("data", [])
+        if not rows:
+            raise ValueError("No screener data returned")
+
+        # Keep only the latest snapshot per ticker
+        latest: dict[str, dict] = {}
+        for row in rows:
+            sym = row["symbol"]
+            if sym not in latest or row["date"] > latest[sym]["date"]:
+                latest[sym] = row
+
+        # Sort by totalMentions descending, take top N
+        ranked = sorted(latest.values(), key=lambda r: r.get("totalMentions", 0), reverse=True)
+        top = ranked[:top_n]
+
+        # Reverse so the highest-mentioned ticker is at the top of the chart
+        top = list(reversed(top))
+
+        symbols = [r["symbol"] for r in top]
+
+        # Collect all subreddit names across top tickers
+        all_subs: set[str] = set()
+        for r in top:
+            all_subs.update(r.get("subreddits", {}).keys())
+
+        fig = go.Figure(
+            layout=dict(
+                template=template,
+                title=f"Reddit Mentions · Top {len(top)} Tickers",
+                xaxis_title="Mentions",
+                hovermode="y unified",
+                barmode="stack",
+            )
+        )
+
+        for subreddit in sorted(all_subs):
+            values = [r.get("subreddits", {}).get(subreddit, 0) for r in top]
+            fig.add_bar(
+                name=f"r/{subreddit}",
+                y=symbols,
+                x=values,
+                orientation="h",
+                hovertemplate=f"r/{subreddit}: " + "%{x:,}<extra></extra>",
+            )
+
+        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.1 → 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.1
+Version: 0.2.3
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -99,6 +99,12 @@ fb.corporate_lobbying.ticker("AAPL",
                              date_to="2025-06-30",
                              as_dataframe=True)
 
+# ---------- reddit mentions ----------
+fb.reddit_mentions.ticker("TSLA",
+                          date_from="2026-03-01",
+                          date_to="2026-03-17",
+                          as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -130,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)
@@ -244,6 +251,21 @@ fb.plot.corporate_lobbying("AAPL",
                            price_data=price_df,
                            date_from="2024-01-01",
                            date_to="2025-06-30")
+
+# Plot Reddit mentions (stacked bars per subreddit) on your price chart
+fb.plot.reddit_mentions("TSLA",
+                        price_data=price_df,
+                        date_from="2026-03-01",
+                        date_to="2026-03-17")
+```
+
+```python
+# ---------- Reddit Mentions Screener Chart (no price data needed) ----------
+# Stacked horizontal bar chart of top 15 most mentioned tickers
+fb.plot.reddit_mentions_top(market="S&P 500")
+
+# Customize the number of tickers shown
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -289,12 +311,14 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | House trades         | `client.house_trades.ticker()`           | `/congress/house/{SYMBOL}`                  |
 | 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}`                 |
 | 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`                   |