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

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/.github/workflows/ci.yml

@@ -17,4 +17,5 @@ jobs:
             python-version: ${{ matrix.python }}
       - run: pip install -e .[dev]
       - run: ruff check .
+      - run: mypy
       - run: pytest -q

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/.github/workflows/release.yml

@@ -24,14 +24,14 @@ jobs:
 
       # ─────────── push to TestPyPI first ───────────
       - name: Upload to TestPyPI
-        run: twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+        run: twine upload --skip-existing --repository-url https://test.pypi.org/legacy/ dist/*
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
 
       # ─────────── then to production PyPI ───────────
       - name: Upload to PyPI
-        run: twine upload dist/*
+        run: twine upload --skip-existing dist/*
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

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

@@ -5,6 +5,30 @@ 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.5] - 2026-06-18
+
+### Added
+
+- **Patent Filings Endpoint**: `fb.patent_filings.ticker("AAPL")` — fetch USPTO granted patents mapped to a ticker, with grant date, title, type, claim counts, citations, assignee, inventors, and CPC classifications (`/patent-filings/{SYMBOL}`)
+- **Patent Filings Screener**: `fb.screener.patent_filings()` — cross-ticker patent filings with summary stats (total patents, tickers, top CPC sections) (`/screener/patent-filings`)
+- **Patent Filings Plotting**: `fb.plot.patent_filings()` — visualize patent grants as bars sized by claim count on a secondary y-axis overlaid on a price chart, with hover details showing title, type, and CPC section
+- **Async Patent Filings**: Full async support via `AsyncPatentFilingsAPI`
+- **Patent Filings Tests**: Unit tests (`tests/test_patent_filings.py`), screener tests, integration tests, and plotting tests
+- **Sync Context Manager**: `FinBrainClient` now supports `with FinBrainClient(...) as fb:` and exposes `close()` to release the underlying HTTP session (parity with `AsyncFinBrainClient`)
+- **Exception Types**: Dedicated `BadGateway` (502), `ServiceUnavailable` (503), and `GatewayTimeout` (504) exceptions for transient gateway errors
+- **Analyst Ratings Plotting**: `fb.plot.analyst_ratings()` — overlay analyst rating actions and price targets on a price chart, with markers grouped and coloured by action category (upgrade/downgrade/initiate/maintain); fills the last remaining ticker-level dataset without a plot method
+
+### Fixed
+
+- **Date parameter handling**: `datetime.datetime` values passed to `date_from`/`date_to` are now truncated to `YYYY-MM-DD` instead of leaking a full ISO timestamp into the API query
+
+### Changed
+
+- **Retry coverage**: Transient gateway errors (502/503/504) are now retried alongside 500, with exponential back-off
+- **Internal**: Async endpoint date helper re-exports the synchronous `to_datestr` to keep a single source of truth
+- **Internal**: Plotting price-overlay methods now share `_resolve_price_column` and `_to_naive_index` helpers, removing ~250 lines of duplicated validation/timezone boilerplate across the chart methods
+- **Tooling**: Added `mypy` static type checking (validating the published `py.typed` surface) to the dev extra and CI; added a sync-client endpoint-parity test; release uploads now use `--skip-existing` for idempotent re-runs
+
 ## [0.2.4] - 2026-03-30
 
 ### Added

{finbrain_python-0.2.4/src/finbrain_python.egg-info → finbrain_python-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.4
+Version: 0.2.5
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -22,6 +22,8 @@ Requires-Dist: httpx>=0.24; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
 Dynamic: license-file
 
 # FinBrain Python SDK&nbsp;<!-- omit in toc -->
@@ -112,6 +114,13 @@ fb.government_contracts.ticker("LMT",
                                limit=50,
                                as_dataframe=True)
 
+# ---------- patent filings ----------
+fb.patent_filings.ticker("AAPL",
+                         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)
 
@@ -145,6 +154,7 @@ 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)
+fb.screener.patent_filings(limit=100, as_dataframe=True)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -265,6 +275,18 @@ fb.plot.reddit_mentions("TSLA",
                         price_data=price_df,
                         date_from="2026-03-01",
                         date_to="2026-03-17")
+
+# Plot patent grants (bars sized by claim count) on your price chart
+fb.plot.patent_filings("AAPL",
+                       price_data=price_df,
+                       date_from="2024-01-01",
+                       date_to="2025-06-30")
+
+# Plot analyst ratings & price targets (markers coloured by action) on your price chart
+fb.plot.analyst_ratings("AAPL",
+                        price_data=price_df,
+                        date_from="2024-01-01",
+                        date_to="2025-06-30")
 ```
 
 ```python
@@ -321,6 +343,7 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | 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}`            |
+| Patent filings       | `client.patent_filings.ticker()`         | `/patent-filings/{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}`                  |
@@ -329,6 +352,7 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 |                      | `client.screener.insider_trading()`      | `/screener/insider-trading`                 |
 |                      | `client.screener.reddit_mentions()`      | `/screener/reddit-mentions`                 |
 |                      | `client.screener.government_contracts()` | `/screener/government-contracts`            |
+|                      | `client.screener.patent_filings()`       | `/screener/patent-filings`                  |
 |                      | ... and 8 more screener methods          |                                             |
 | Recent               | `client.recent.news()`                   | `/recent/news`                              |
 |                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |
@@ -356,6 +380,9 @@ except BadRequest as exc:
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
 | 429         | `RateLimitError`         | Too many requests                     |
 | 500         | `ServerError`            | FinBrain internal error               |
+| 502         | `BadGateway`             | Invalid response from upstream server |
+| 503         | `ServiceUnavailable`     | Service temporarily unavailable       |
+| 504         | `GatewayTimeout`         | Upstream server timed out             |
 
 ---
 

finbrain_python-0.2.4/PKG-INFO → finbrain_python-0.2.5/README.md

@@ -1,29 +1,3 @@
-Metadata-Version: 2.4
-Name: finbrain-python
-Version: 0.2.4
-Summary: Official Python client for the FinBrain API
-Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31
-Requires-Dist: typer[all]>=0.12
-Requires-Dist: pandas>=2.2
-Requires-Dist: plotly>=6.0
-Requires-Dist: numpy>=1.22.4
-Provides-Extra: async
-Requires-Dist: httpx>=0.24; extra == "async"
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: responses; extra == "dev"
-Requires-Dist: httpx>=0.24; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Dynamic: license-file
-
 # FinBrain Python SDK&nbsp;<!-- omit in toc -->
 
 [![PyPI version](https://img.shields.io/pypi/v/finbrain-python.svg)](https://pypi.org/project/finbrain-python/)
@@ -112,6 +86,13 @@ fb.government_contracts.ticker("LMT",
                                limit=50,
                                as_dataframe=True)
 
+# ---------- patent filings ----------
+fb.patent_filings.ticker("AAPL",
+                         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)
 
@@ -145,6 +126,7 @@ 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)
+fb.screener.patent_filings(limit=100, as_dataframe=True)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -265,6 +247,18 @@ fb.plot.reddit_mentions("TSLA",
                         price_data=price_df,
                         date_from="2026-03-01",
                         date_to="2026-03-17")
+
+# Plot patent grants (bars sized by claim count) on your price chart
+fb.plot.patent_filings("AAPL",
+                       price_data=price_df,
+                       date_from="2024-01-01",
+                       date_to="2025-06-30")
+
+# Plot analyst ratings & price targets (markers coloured by action) on your price chart
+fb.plot.analyst_ratings("AAPL",
+                        price_data=price_df,
+                        date_from="2024-01-01",
+                        date_to="2025-06-30")
 ```
 
 ```python
@@ -321,6 +315,7 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | 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}`            |
+| Patent filings       | `client.patent_filings.ticker()`         | `/patent-filings/{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}`                  |
@@ -329,6 +324,7 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 |                      | `client.screener.insider_trading()`      | `/screener/insider-trading`                 |
 |                      | `client.screener.reddit_mentions()`      | `/screener/reddit-mentions`                 |
 |                      | `client.screener.government_contracts()` | `/screener/government-contracts`            |
+|                      | `client.screener.patent_filings()`       | `/screener/patent-filings`                  |
 |                      | ... and 8 more screener methods          |                                             |
 | Recent               | `client.recent.news()`                   | `/recent/news`                              |
 |                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |
@@ -356,6 +352,9 @@ except BadRequest as exc:
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
 | 429         | `RateLimitError`         | Too many requests                     |
 | 500         | `ServerError`            | FinBrain internal error               |
+| 502         | `BadGateway`             | Invalid response from upstream server |
+| 503         | `ServiceUnavailable`     | Service temporarily unavailable       |
+| 504         | `GatewayTimeout`         | Upstream server timed out             |
 
 ---
 

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/RELEASE.md

@@ -10,7 +10,7 @@ Starting from v0.1.6, we use **`v`-prefixed tags** (e.g., `v0.1.6`, `v0.2.0`, `v
 
 ### 1. Update CHANGELOG.md
 
-Edit `CHANGELOG.md` and move items from `[Unreleased]` to a new version section:
+Edit `CHANGELOG.md` and add a new version section at the top, above the previous release:
 
 ```markdown
 ## [0.1.6] - 2025-01-15

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/pyproject.toml

@@ -45,9 +45,18 @@ dev = [
     "build",
     "twine",
     "ruff",                      # linter/formatter (optional)
+    "mypy",                      # static type checker (validates py.typed surface)
+    "types-requests",            # stubs for requests (mypy import-untyped otherwise)
 ]
 
 [tool.pytest.ini_options]
 markers = [
     "integration: hits the real FinBrain v2 API (requires FINBRAIN_API_KEY)",
 ]
+
+[tool.mypy]
+# Code targets >=3.9 but uses `from __future__ import annotations` throughout,
+# so checking against 3.10 (mypy's minimum target) is equivalent here.
+python_version = "3.10"
+files = ["src/finbrain"]
+ignore_missing_imports = true   # third-party libs (pandas, plotly, …) ship no stubs here

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/src/finbrain/aio/client.py

@@ -25,10 +25,11 @@ from .endpoints.recent import AsyncRecentAPI
 from .endpoints.corporate_lobbying import AsyncCorporateLobbyingAPI
 from .endpoints.reddit_mentions import AsyncRedditMentionsAPI
 from .endpoints.government_contracts import AsyncGovernmentContractsAPI
+from .endpoints.patent_filings import AsyncPatentFilingsAPI
 
 
-# Which status codes merit a retry
-_RETRYABLE_STATUS = {500}
+# Which status codes merit a retry (transient server / gateway errors)
+_RETRYABLE_STATUS = {500, 502, 503, 504}
 # How long to wait between retries   (2, 4, 8 … seconds)
 _BACKOFF_BASE = 2
 
@@ -86,6 +87,7 @@ class AsyncFinBrainClient:
         self.corporate_lobbying = AsyncCorporateLobbyingAPI(self)
         self.reddit_mentions = AsyncRedditMentionsAPI(self)
         self.government_contracts = AsyncGovernmentContractsAPI(self)
+        self.patent_filings = AsyncPatentFilingsAPI(self)
 
     async def __aenter__(self) -> "AsyncFinBrainClient":
         """Context manager entry."""
@@ -164,7 +166,7 @@ class AsyncFinBrainClient:
 
             # ── Error path ───────────────────────────────────
             if resp.status_code in _RETRYABLE_STATUS and attempt < self.retries:
-                # 500 – exponential back-off then retry
+                # Transient server/gateway error – exponential back-off then retry
                 await asyncio.sleep(_BACKOFF_BASE**attempt)
                 continue
 

finbrain_python-0.2.5/src/finbrain/aio/endpoints/_utils.py

@@ -0,0 +1,12 @@
+"""
+Shared utility functions for async endpoint modules.
+
+These helpers are identical to the synchronous ones, so they are re-exported
+from :mod:`finbrain.endpoints._utils` to keep a single source of truth.
+"""
+
+from __future__ import annotations
+
+from ...endpoints._utils import to_datestr
+
+__all__ = ["to_datestr"]

finbrain_python-0.2.5/src/finbrain/aio/endpoints/patent_filings.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 AsyncPatentFilingsAPI:
+    """Async wrapper for /patent-filings and /screener/patent-filings 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 USPTO granted patents 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"patent-filings/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("patents", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "patentDate" in df.columns:
+                df["patentDate"] = pd.to_datetime(df["patentDate"])
+                df.set_index("patentDate", inplace=True)
+            return df
+
+        return data

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/src/finbrain/aio/endpoints/screener.py

@@ -234,3 +234,15 @@ class AsyncScreenerAPI:
         """Screen government contracts across all tickers (async)."""
         params = self._build_params(limit=limit)
         return await self._get("screener/government-contracts", params, as_dataframe)
+
+    # ── patent filings ────────────────────────────────────────
+
+    async def patent_filings(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen USPTO patent filings across all tickers (async)."""
+        params = self._build_params(limit=limit)
+        return await self._get("screener/patent-filings", params, as_dataframe)

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/src/finbrain/client.py

@@ -26,10 +26,11 @@ from .endpoints.recent import RecentAPI
 from .endpoints.corporate_lobbying import CorporateLobbyingAPI
 from .endpoints.reddit_mentions import RedditMentionsAPI
 from .endpoints.government_contracts import GovernmentContractsAPI
+from .endpoints.patent_filings import PatentFilingsAPI
 
 
-# Which status codes merit a retry
-_RETRYABLE_STATUS = {500}
+# Which status codes merit a retry (transient server / gateway errors)
+_RETRYABLE_STATUS = {500, 502, 503, 504}
 # How long to wait between retries   (2, 4, 8 … seconds)
 _BACKOFF_BASE = 2
 
@@ -81,6 +82,20 @@ class FinBrainClient:
         self.corporate_lobbying = CorporateLobbyingAPI(self)
         self.reddit_mentions = RedditMentionsAPI(self)
         self.government_contracts = GovernmentContractsAPI(self)
+        self.patent_filings = PatentFilingsAPI(self)
+
+    # ---------- lifecycle ----------
+    def __enter__(self) -> "FinBrainClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit — close the underlying HTTP session."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying ``requests.Session``."""
+        self.session.close()
 
     # ---------- private helpers ----------
     def _request(
@@ -131,7 +146,7 @@ class FinBrainClient:
 
             # ── Error path ───────────────────────────────────
             if resp.status_code in _RETRYABLE_STATUS and attempt < self.retries:
-                # 500 – exponential back-off then retry
+                # Transient server/gateway error – exponential back-off then retry
                 time.sleep(_BACKOFF_BASE**attempt)
                 continue
 

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/src/finbrain/endpoints/_utils.py

@@ -28,10 +28,16 @@ def to_datestr(value: _dt.date | str) -> str:
 
     Examples
     --------
-    >>> from datetime import date
+    >>> from datetime import date, datetime
     >>> to_datestr(date(2025, 1, 15))
     '2025-01-15'
+    >>> to_datestr(datetime(2025, 1, 15, 9, 30))
+    '2025-01-15'
     >>> to_datestr("2025-01-15")
     '2025-01-15'
     """
+    # ``datetime`` subclasses ``date``; take the date part so the time
+    # component never leaks into the ``YYYY-MM-DD`` API parameter.
+    if isinstance(value, _dt.datetime):
+        return value.date().isoformat()
     return value.isoformat() if isinstance(value, _dt.date) else value

finbrain_python-0.2.5/src/finbrain/endpoints/patent_filings.py

@@ -0,0 +1,74 @@
+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 PatentFilingsAPI:
+    """
+    Endpoints
+    ---------
+    ``/patent-filings/<TICKER>`` - USPTO granted patents mapped to a ticker.
+    ``/screener/patent-filings`` - cross-ticker patent filings 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 USPTO granted patents for *symbol*.
+
+        Parameters
+        ----------
+        symbol :
+            Ticker symbol; auto-upper-cased.
+        date_from, date_to :
+            Optional ISO dates (``YYYY-MM-DD``) bounding the returned rows by
+            grant date (``patentDate``).
+        limit :
+            Maximum number of records to return (1-500).
+        as_dataframe :
+            If *True*, return a **pandas.DataFrame** indexed by ``patentDate``;
+            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"patent-filings/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("patents", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "patentDate" in df.columns:
+                df["patentDate"] = pd.to_datetime(df["patentDate"])
+                df.set_index("patentDate", inplace=True)
+            return df
+
+        return data

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/src/finbrain/endpoints/screener.py

@@ -239,3 +239,15 @@ class ScreenerAPI:
         """Screen government contracts across all tickers."""
         params = self._build_params(limit=limit)
         return self._get("screener/government-contracts", params, as_dataframe)
+
+    # ── patent filings ────────────────────────────────────────
+
+    def patent_filings(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen USPTO patent filings across all tickers."""
+        params = self._build_params(limit=limit)
+        return self._get("screener/patent-filings", params, as_dataframe)

{finbrain_python-0.2.4 → finbrain_python-0.2.5}/src/finbrain/exceptions.py

@@ -14,6 +14,9 @@ Docs-based mapping
 405  Method Not Allowed     → MethodNotAllowed
 429  Rate Limit Exceeded    → RateLimitError
 500  Internal Server Error  → ServerError
+502  Bad Gateway            → BadGateway
+503  Service Unavailable    → ServiceUnavailable
+504  Gateway Timeout        → GatewayTimeout
 """
 
 from __future__ import annotations
@@ -29,6 +32,9 @@ __all__ = [
     "MethodNotAllowed",
     "RateLimitError",
     "ServerError",
+    "BadGateway",
+    "ServiceUnavailable",
+    "GatewayTimeout",
     #
     "InvalidResponse",
     "http_error_to_exception",
@@ -96,6 +102,18 @@ class ServerError(FinBrainError):
     """500 - Internal error on FinBrain's side. Retrying later may help."""
 
 
+class BadGateway(FinBrainError):
+    """502 - Invalid response from an upstream server. Usually transient."""
+
+
+class ServiceUnavailable(FinBrainError):
+    """503 - Service temporarily unavailable (overloaded or in maintenance)."""
+
+
+class GatewayTimeout(FinBrainError):
+    """504 - Upstream server did not respond in time. Usually transient."""
+
+
 # ─────────────────────────────────────────────────────────────
 # Transport / decoding guard
 # ─────────────────────────────────────────────────────────────
@@ -167,6 +185,12 @@ def http_error_to_exception(resp) -> FinBrainError:  # expects requests.Response
         return RateLimitError(message, **kwargs)
     if status == 500:
         return ServerError(message, **kwargs)
+    if status == 502:
+        return BadGateway(message, **kwargs)
+    if status == 503:
+        return ServiceUnavailable(message, **kwargs)
+    if status == 504:
+        return GatewayTimeout(message, **kwargs)
 
     # Fallback for undocumented codes (future-proofing)
     return FinBrainError(message, **kwargs)