finbrain-python 0.2.4__py3-none-any.whl → 0.2.6__py3-none-any.whl

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/aio/endpoints/_utils.py

@@ -1,37 +1,12 @@
 """
 Shared utility functions for async endpoint modules.
 
-This module contains common helper functions used across multiple async endpoint
-implementations to avoid code duplication.
+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
-import datetime as _dt
 
+from ...endpoints._utils import to_datestr
 
-def to_datestr(value: _dt.date | str) -> str:
-    """
-    Convert datetime.date to ISO format string (YYYY-MM-DD).
-
-    If the input is already a string, it is returned unchanged.
-    This allows flexible date parameter handling in API calls.
-
-    Parameters
-    ----------
-    value : datetime.date or str
-        Date value to convert.
-
-    Returns
-    -------
-    str
-        ISO format date string (YYYY-MM-DD).
-
-    Examples
-    --------
-    >>> from datetime import date
-    >>> to_datestr(date(2025, 1, 15))
-    '2025-01-15'
-    >>> to_datestr("2025-01-15")
-    '2025-01-15'
-    """
-    return value.isoformat() if isinstance(value, _dt.date) else value
+__all__ = ["to_datestr"]

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/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/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/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/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/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/endpoints/house_trades.py

@@ -49,6 +49,30 @@ class HouseTradesAPI:
         Returns
         -------
         dict | pandas.DataFrame
+            The raw dict has a ``trades`` list whose rows carry ``date``
+            (the transaction date), ``politician``, ``transactionType``,
+            ``amount`` and ``disclosureDate`` — the date the trade was
+            publicly disclosed in the member's periodic transaction report.
+            The gap between the two dates is the reporting lag.
+
+            ``disclosureDate`` is ``None`` for historical rows collected
+            before the field was captured upstream. In the DataFrame branch
+            ``date`` becomes the index and ``disclosureDate`` is a column
+            whose missing values read as ``None`` or ``NaN`` depending on the
+            pandas version — test them with :func:`pandas.isna`.
+
+        Notes
+        -----
+        ``date_from`` and ``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``.
+
+        Example row::
+
+            {"date": "2026-06-15", "politician": "Jane Doe",
+             "transactionType": "Purchase", "amount": "$1,001 - $15,000",
+             "disclosureDate": "2026-07-01"}
+
         """
         params: Dict[str, str] = {}
         if date_from:

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/endpoints/screener.py

@@ -112,7 +112,13 @@ class ScreenerAPI:
         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 self._get("screener/congress/house", params, as_dataframe)
 
@@ -124,7 +130,13 @@ class ScreenerAPI:
         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 self._get("screener/congress/senate", params, as_dataframe)
 
@@ -239,3 +251,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/endpoints/senate_trades.py

@@ -49,6 +49,30 @@ class SenateTradesAPI:
         Returns
         -------
         dict | pandas.DataFrame
+            The raw dict has a ``trades`` list whose rows carry ``date``
+            (the transaction date), ``politician``, ``transactionType``,
+            ``amount`` and ``disclosureDate`` — the date the trade was
+            publicly disclosed in the member's periodic transaction report.
+            The gap between the two dates is the reporting lag.
+
+            ``disclosureDate`` is ``None`` for historical rows collected
+            before the field was captured upstream. In the DataFrame branch
+            ``date`` becomes the index and ``disclosureDate`` is a column
+            whose missing values read as ``None`` or ``NaN`` depending on the
+            pandas version — test them with :func:`pandas.isna`.
+
+        Notes
+        -----
+        ``date_from`` and ``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``.
+
+        Example row::
+
+            {"date": "2026-06-10", "politician": "Jane Doe",
+             "transactionType": "Purchase", "amount": "$1,001 - $15,000",
+             "disclosureDate": "2026-06-25"}
+
         """
         params: Dict[str, str] = {}
         if date_from:

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)