finbrain-python 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

finbrain/aio/client.py

@@ -24,10 +24,12 @@ from .endpoints.screener import AsyncScreenerAPI
 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
 
@@ -84,6 +86,8 @@ class AsyncFinBrainClient:
         self.recent = AsyncRecentAPI(self)
         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."""
@@ -162,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/government_contracts.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 AsyncGovernmentContractsAPI:
+    """Async wrapper for /government-contracts and /screener/government-contracts 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 government contract awards 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"government-contracts/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("contracts", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "startDate" in df.columns:
+                df["startDate"] = pd.to_datetime(df["startDate"])
+                df.set_index("startDate", inplace=True)
+            return df
+
+        return data

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

@@ -222,3 +222,27 @@ class AsyncScreenerAPI:
         """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)
+
+    # ── government contracts ──────────────────────────────────
+
+    async def government_contracts(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """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/client.py

@@ -25,10 +25,12 @@ from .endpoints.screener import ScreenerAPI
 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
 
@@ -79,6 +81,21 @@ class FinBrainClient:
         self.recent = RecentAPI(self)
         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(
@@ -129,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/government_contracts.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 GovernmentContractsAPI:
+    """
+    Endpoints
+    ---------
+    ``/government-contracts/<TICKER>`` - U.S. government contract awards.
+    ``/screener/government-contracts``  - cross-ticker government contracts 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 government contract awards for *symbol*.
+
+        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 ``startDate``;
+            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"government-contracts/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("contracts", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "startDate" in df.columns:
+                df["startDate"] = pd.to_datetime(df["startDate"])
+                df.set_index("startDate", inplace=True)
+            return df
+
+        return data

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

@@ -227,3 +227,27 @@ class ScreenerAPI:
         """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)
+
+    # ── government contracts ──────────────────────────────────
+
+    def government_contracts(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """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/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)