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

{finbrain_python-0.2.4 → finbrain_python-0.2.6}/.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.6}/.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.6}/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.6] - 2026-07-24
+
+### Added
+
+- **Congressional disclosure date**: House and Senate trade rows now carry `disclosureDate` alongside the transaction `date` — the date the trade was publicly disclosed in the member's periodic transaction report. The gap between the two is the reporting lag. Available on `fb.house_trades.ticker()`, `fb.senate_trades.ticker()`, their async equivalents, and the `fb.screener.congress_house()` / `fb.screener.congress_senate()` rows
+- **Congressional trade date documentation**: README section explaining the two dates, and expanded docstrings on the sync/async ticker and screener methods
+- **Tests**: Unit tests assert `disclosureDate` passes through in both the raw-dict and DataFrame branches, including the null case for historical rows; integration tests assert the key is present on live responses
+
+### Changed
+
+- **DataFrame shape**: `fb.house_trades.ticker(..., as_dataframe=True)`, `fb.senate_trades.ticker(..., as_dataframe=True)` and the congress screener frames gain a `disclosureDate` column. Code that asserts an exact column set (`set(df.columns) == {...}`) or compares frames for equality needs updating
+
+### Notes
+
+- `disclosureDate` is `null` for rows collected before the upstream pipeline captured the field. In a DataFrame the missing value reads as `None` or `NaN` depending on the pandas version, so test it with `pandas.isna()` rather than `is None`
+- **`.dropna()` caveat**: because historical rows have no disclosure date, calling `.dropna()` on a congressional trades DataFrame now drops those rows entirely. Use `.dropna(subset=[...])` if that is not what you want
+- `date_from` / `date_to` bound the transaction date, not the disclosure date
+- The raw-dict branch is purely additive — no call-site changes are required there to receive the new field
+
+## [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 → finbrain_python-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.4
+Version: 0.2.6
 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 -->
@@ -82,6 +84,7 @@ fb.analyst_ratings.ticker("AMZN",
                           as_dataframe=True)
 
 # ---------- house trades ----------
+# Rows include `disclosureDate` alongside the transaction `date`.
 fb.house_trades.ticker("AMZN",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
@@ -112,6 +115,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,12 +155,46 @@ 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)
+fb.screener.congress_house(limit=50)     # rows carry `disclosureDate`
+fb.screener.congress_senate(limit=50)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
 fb.recent.analyst_ratings(limit=50)
 ```
 
+### Congressional trade dates
+
+House and Senate trade rows carry **two** dates, and the gap between them is
+the reporting lag — often weeks:
+
+| Field            | Meaning                                                          |
+| ---------------- | ---------------------------------------------------------------- |
+| `date`           | Transaction date — when the member actually bought or sold        |
+| `disclosureDate` | Public disclosure date — when the periodic transaction report ran |
+
+`disclosureDate` is `null` on historical rows collected before the field was
+captured upstream. With `as_dataframe=True`, `date` is the **index** and
+`disclosureDate` is a column whose missing values read as `None` or `NaN`
+depending on your pandas version — test them with `pandas.isna()` rather than
+`is None`. Note that `.dropna()` on such a frame will now discard every
+historical row. The same field is present on `fb.screener.congress_house()`
+and `fb.screener.congress_senate()` rows.
+
+`date_from` / `date_to` bound the **transaction** date, not the disclosure
+date — a trade executed inside the window is returned even if it was disclosed
+after `date_to`.
+
+```python
+trades = fb.house_trades.ticker("AMZN")["trades"]
+lag_days = [
+    (pd.Timestamp(t["disclosureDate"]) - pd.Timestamp(t["date"])).days
+    for t in trades
+    if t["disclosureDate"]
+]
+```
+
 ## ⚡ Async Usage
 
 For async/await support, install with the `async` extra:
@@ -265,6 +309,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 +377,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 +386,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 +414,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.6}/README.md

@@ -56,6 +56,7 @@ fb.analyst_ratings.ticker("AMZN",
                           as_dataframe=True)
 
 # ---------- house trades ----------
+# Rows include `disclosureDate` alongside the transaction `date`.
 fb.house_trades.ticker("AMZN",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
@@ -86,6 +87,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)
 
@@ -119,12 +127,46 @@ 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)
+fb.screener.congress_house(limit=50)     # rows carry `disclosureDate`
+fb.screener.congress_senate(limit=50)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
 fb.recent.analyst_ratings(limit=50)
 ```
 
+### Congressional trade dates
+
+House and Senate trade rows carry **two** dates, and the gap between them is
+the reporting lag — often weeks:
+
+| Field            | Meaning                                                          |
+| ---------------- | ---------------------------------------------------------------- |
+| `date`           | Transaction date — when the member actually bought or sold        |
+| `disclosureDate` | Public disclosure date — when the periodic transaction report ran |
+
+`disclosureDate` is `null` on historical rows collected before the field was
+captured upstream. With `as_dataframe=True`, `date` is the **index** and
+`disclosureDate` is a column whose missing values read as `None` or `NaN`
+depending on your pandas version — test them with `pandas.isna()` rather than
+`is None`. Note that `.dropna()` on such a frame will now discard every
+historical row. The same field is present on `fb.screener.congress_house()`
+and `fb.screener.congress_senate()` rows.
+
+`date_from` / `date_to` bound the **transaction** date, not the disclosure
+date — a trade executed inside the window is returned even if it was disclosed
+after `date_to`.
+
+```python
+trades = fb.house_trades.ticker("AMZN")["trades"]
+lag_days = [
+    (pd.Timestamp(t["disclosureDate"]) - pd.Timestamp(t["date"])).days
+    for t in trades
+    if t["disclosureDate"]
+]
+```
+
 ## ⚡ Async Usage
 
 For async/await support, install with the `async` extra:
@@ -239,6 +281,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
@@ -295,6 +349,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}`                  |
@@ -303,6 +358,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`                   |
@@ -330,6 +386,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.6}/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.6}/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.6}/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.6/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.4 → finbrain_python-0.2.6}/src/finbrain/aio/endpoints/house_trades.py

@@ -24,7 +24,19 @@ class AsyncHouseTradesAPI:
         limit: int | None = None,
         as_dataframe: bool = False,
     ) -> Dict[str, Any] | pd.DataFrame:
-        """Fetch House-member trades for a symbol (async)."""
+        """
+        Fetch House-member trades for a symbol (async).
+
+        Each row in ``trades`` carries ``date`` (the transaction date),
+        ``politician``, ``transactionType``, ``amount`` and
+        ``disclosureDate`` — the date the trade was publicly disclosed in the
+        member's periodic transaction report. ``disclosureDate`` is ``None``
+        for historical rows collected before the field was captured (``NaN``
+        in the DataFrame branch on newer pandas — use ``pandas.isna``).
+
+        ``date_from``/``date_to`` bound the transaction date, not the
+        disclosure date.
+        """
         params: Dict[str, str] = {}
         if date_from:
             params["startDate"] = to_datestr(date_from)

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

@@ -107,7 +107,13 @@ class AsyncScreenerAPI:
         limit: int | None = None,
         as_dataframe: bool = False,
     ) -> List[Dict[str, Any]] | pd.DataFrame:
-        """Screen House trades across all tickers."""
+        """
+        Screen House trades across all tickers.
+
+        Rows carry ``symbol``, ``name``, ``date``, ``politician``,
+        ``transactionType``, ``amount`` and ``disclosureDate`` (the public
+        disclosure date, ``None`` on historical rows).
+        """
         params = self._build_params(limit=limit)
         return await self._get("screener/congress/house", params, as_dataframe)
 
@@ -119,7 +125,13 @@ class AsyncScreenerAPI:
         limit: int | None = None,
         as_dataframe: bool = False,
     ) -> List[Dict[str, Any]] | pd.DataFrame:
-        """Screen Senate trades across all tickers."""
+        """
+        Screen Senate trades across all tickers.
+
+        Rows carry ``symbol``, ``name``, ``date``, ``politician``,
+        ``transactionType``, ``amount`` and ``disclosureDate`` (the public
+        disclosure date, ``None`` on historical rows).
+        """
         params = self._build_params(limit=limit)
         return await self._get("screener/congress/senate", params, as_dataframe)
 
@@ -234,3 +246,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.6}/src/finbrain/aio/endpoints/senate_trades.py

@@ -24,7 +24,19 @@ class AsyncSenateTradesAPI:
         limit: int | None = None,
         as_dataframe: bool = False,
     ) -> Dict[str, Any] | pd.DataFrame:
-        """Fetch Senate-member trades for a symbol (async)."""
+        """
+        Fetch Senate-member trades for a symbol (async).
+
+        Each row in ``trades`` carries ``date`` (the transaction date),
+        ``politician``, ``transactionType``, ``amount`` and
+        ``disclosureDate`` — the date the trade was publicly disclosed in the
+        member's periodic transaction report. ``disclosureDate`` is ``None``
+        for historical rows collected before the field was captured (``NaN``
+        in the DataFrame branch on newer pandas — use ``pandas.isna``).
+
+        ``date_from``/``date_to`` bound the transaction date, not the
+        disclosure date.
+        """
         params: Dict[str, str] = {}
         if date_from:
             params["startDate"] = to_datestr(date_from)

{finbrain_python-0.2.4 → finbrain_python-0.2.6}/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.6}/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