form4api 0.4.3__tar.gz → 0.6.0__tar.gz

{form4api-0.4.3 → form4api-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.4.3
+Version: 0.6.0
 Summary: Python client for the Form4API — real-time SEC Form 4 insider trading data
 License-Expression: MIT
 Project-URL: Homepage, https://www.form4api.com
@@ -82,22 +82,27 @@ asyncio.run(main())
 | Resource | Methods |
 |---|---|
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
-| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.transactions(cik, **params)` |
-| `client.companies` | `.get(ticker)`, `.insiders(ticker)` |
-| `client.signals` | `.list(**params)`, `.paginate(**params)` — Business plan |
+| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
+| `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
+| `client.signals` | `.list(**params)`, `.paginate(**params)`, `.explain(ticker)`, `.sentiment(ticker, **params)` — Business; `.convergence(**params)` — Pro |
+| `client.congress` | `.trades(**params)`, `.politicians(**params)` *(Pro)*, `.politician(id_or_slug)` *(Pro)*, `.ticker(ticker)` *(Pro)* |
+| `client.form144` | `.list(**params)` — Business plan |
+| `client.holdings` | `.list(**params)`, `.managers(**params)` — Business plan |
+| `client.filings` | `.list(**params)`, `.recent(**params)`, `.get(accession_number)` |
+| `client.stats` | `.get()` — public, no key required |
+| `client.data_quality` | `.get()` — public, no key required |
+| `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
-### Not yet in this SDK
+Every plan-gated endpoint the API exposes has a typed method here. Calling one
+your key isn't entitled to raises `PlanError` (HTTP 402) carrying
+`required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
 
-The API surface is broader than the typed client. These backend features are **available via the REST API and the `form4api-mcp` server today, but don't have a typed SDK resource yet**:
+An `AsyncForm4ApiClient` mirrors the whole surface with the same resources and
+method names — `await client.insiders.leaderboard()`.
 
-- **Form 144** notice-of-proposed-sale — `GET /v1/form144` *(Business)*
-- **Institutional holdings (13F-HR)** — `GET /v1/holdings`, **managers** — `GET /v1/managers` *(Business)*
-- **Sentiment** (MSPR-style, 10b5-1-clean) — `GET /v1/signals/sentiment/{ticker}` *(Business)*
-- **Insider career summary** — `GET /v1/insiders/{cik}/summary` *(Pro)*
-- **Post-trade returns** (1d/1w/1m/3m/6m) + `min_return_*` screening filters on `/v1/transactions` *(visible free; screening Pro)*
-
-Until they land in the SDK, call them directly (`client._get("/v1/holdings", {...})`) or see the [full REST reference](https://form4api.com/docs). For LLM workflows, `form4api-mcp` exposes all of the above as tools.
+For the full parameter reference see the [REST docs](https://form4api.com/docs).
+For LLM workflows, `form4api-mcp` exposes the same endpoints as tools.
 
 ### Transaction filters
 
@@ -181,7 +186,7 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 ```python
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=500):
+for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
     all_txns.extend(batch)
 
 # signals.paginate()

{form4api-0.4.3 → form4api-0.6.0}/README.md

@@ -63,22 +63,27 @@ asyncio.run(main())
 | Resource | Methods |
 |---|---|
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
-| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.transactions(cik, **params)` |
-| `client.companies` | `.get(ticker)`, `.insiders(ticker)` |
-| `client.signals` | `.list(**params)`, `.paginate(**params)` — Business plan |
+| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
+| `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
+| `client.signals` | `.list(**params)`, `.paginate(**params)`, `.explain(ticker)`, `.sentiment(ticker, **params)` — Business; `.convergence(**params)` — Pro |
+| `client.congress` | `.trades(**params)`, `.politicians(**params)` *(Pro)*, `.politician(id_or_slug)` *(Pro)*, `.ticker(ticker)` *(Pro)* |
+| `client.form144` | `.list(**params)` — Business plan |
+| `client.holdings` | `.list(**params)`, `.managers(**params)` — Business plan |
+| `client.filings` | `.list(**params)`, `.recent(**params)`, `.get(accession_number)` |
+| `client.stats` | `.get()` — public, no key required |
+| `client.data_quality` | `.get()` — public, no key required |
+| `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
-### Not yet in this SDK
+Every plan-gated endpoint the API exposes has a typed method here. Calling one
+your key isn't entitled to raises `PlanError` (HTTP 402) carrying
+`required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
 
-The API surface is broader than the typed client. These backend features are **available via the REST API and the `form4api-mcp` server today, but don't have a typed SDK resource yet**:
+An `AsyncForm4ApiClient` mirrors the whole surface with the same resources and
+method names — `await client.insiders.leaderboard()`.
 
-- **Form 144** notice-of-proposed-sale — `GET /v1/form144` *(Business)*
-- **Institutional holdings (13F-HR)** — `GET /v1/holdings`, **managers** — `GET /v1/managers` *(Business)*
-- **Sentiment** (MSPR-style, 10b5-1-clean) — `GET /v1/signals/sentiment/{ticker}` *(Business)*
-- **Insider career summary** — `GET /v1/insiders/{cik}/summary` *(Pro)*
-- **Post-trade returns** (1d/1w/1m/3m/6m) + `min_return_*` screening filters on `/v1/transactions` *(visible free; screening Pro)*
-
-Until they land in the SDK, call them directly (`client._get("/v1/holdings", {...})`) or see the [full REST reference](https://form4api.com/docs). For LLM workflows, `form4api-mcp` exposes all of the above as tools.
+For the full parameter reference see the [REST docs](https://form4api.com/docs).
+For LLM workflows, `form4api-mcp` exposes the same endpoints as tools.
 
 ### Transaction filters
 
@@ -162,7 +167,7 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 ```python
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=500):
+for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
     all_txns.extend(batch)
 
 # signals.paginate()

{form4api-0.4.3 → form4api-0.6.0}/form4api/_client.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
+from __future__ import annotations
 
 import asyncio
 import re
@@ -18,11 +18,33 @@ try:
 except PackageNotFoundError:  # not installed (e.g. running from a source tree)
     _SDK_VERSION = "0.0.0"
 _USER_AGENT = f"form4api-py/{_SDK_VERSION}"
-from form4api.resources._companies import CompaniesResource
-from form4api.resources._insiders import InsidersResource
-from form4api.resources._signals import SignalsResource
-from form4api.resources._transactions import TransactionsResource
-from form4api.resources._webhooks import WebhooksResource
+from form4api.resources._companies import AsyncCompaniesResource, CompaniesResource
+from form4api.resources._insiders import AsyncInsidersResource, InsidersResource
+from form4api.resources._signals import AsyncSignalsResource, SignalsResource
+from form4api.resources._transactions import AsyncTransactionsResource, TransactionsResource
+from form4api.resources._webhooks import AsyncWebhooksResource, WebhooksResource
+
+# Spec-derived families with no hand-written wrapper. Before these, all 6
+# Pro-gated and 9 of the 10 Business-gated endpoints were unreachable from this
+# SDK — a Business customer could not call Form 144 or 13F holdings at all.
+# Sync and async variants are generated separately; see the note on
+# AsyncForm4ApiClient below for why that matters here but not in the JS SDK.
+from form4api._generated import (
+    GeneratedAsyncCongressResource,
+    GeneratedAsyncDataQualityResource,
+    GeneratedAsyncFilingsResource,
+    GeneratedAsyncForm144Resource,
+    GeneratedAsyncHoldingsResource,
+    GeneratedAsyncStatsResource,
+    GeneratedAsyncStatusResource,
+    GeneratedCongressResource,
+    GeneratedDataQualityResource,
+    GeneratedFilingsResource,
+    GeneratedForm144Resource,
+    GeneratedHoldingsResource,
+    GeneratedStatsResource,
+    GeneratedStatusResource,
+)
 
 DEFAULT_BASE_URL = "https://api.form4api.com"
 _RETRY_DELAYS = [0.5, 1.0, 2.0]
@@ -66,6 +88,13 @@ class Form4ApiClient:
         self.companies = CompaniesResource(self)
         self.signals = SignalsResource(self)
         self.webhooks = WebhooksResource(self)
+        self.congress = GeneratedCongressResource(self)
+        self.filings = GeneratedFilingsResource(self)
+        self.form144 = GeneratedForm144Resource(self)
+        self.holdings = GeneratedHoldingsResource(self)
+        self.stats = GeneratedStatsResource(self)
+        self.status = GeneratedStatusResource(self)
+        self.data_quality = GeneratedDataQualityResource(self)
 
     def __enter__(self) -> Form4ApiClient:
         return self
@@ -127,7 +156,17 @@ class Form4ApiClient:
         if res.status_code == 401:
             raise AuthError(message, code)
         if res.status_code == 402:
-            raise PlanError(message, body.get("requiredPlan") if isinstance(body, dict) else None)
+            # Read from the nested `error` object, not the top level. This was
+            # reading body["requiredPlan"], which the API has never emitted at
+            # any level, so PlanError.required_plan was permanently None. The
+            # backend now returns requiredPlan/currentPlan/upgradeUrl inside the
+            # standard error envelope.
+            raise PlanError(
+                message,
+                error.get("requiredPlan") if isinstance(error, dict) else None,
+                error.get("currentPlan") if isinstance(error, dict) else None,
+                error.get("upgradeUrl") if isinstance(error, dict) else None,
+            )
         if res.status_code == 404:
             raise NotFoundError(message, code)
         if res.status_code == 429:
@@ -154,11 +193,27 @@ class AsyncForm4ApiClient:
             timeout=timeout,
             headers={"X-Api-Key": api_key, "User-Agent": _USER_AGENT},
         )
-        self.transactions = TransactionsResource(self)  # type: ignore[arg-type]
-        self.insiders = InsidersResource(self)  # type: ignore[arg-type]
-        self.companies = CompaniesResource(self)  # type: ignore[arg-type]
-        self.signals = SignalsResource(self)  # type: ignore[arg-type]
-        self.webhooks = WebhooksResource(self)  # type: ignore[arg-type]
+        # Async twins, not the sync classes. Until 2026-08-06 this client reused
+        # the sync resources behind `# type: ignore[arg-type]`; because _get here
+        # is a coroutine, `Dataclass(**data)` was handed a coroutine and raised
+        # "argument after ** must be a mapping, not coroutine" on EVERY call, so
+        # every hand-written resource method was broken on the async client and
+        # always had been. There were no async tests, and the type: ignore
+        # suppressed the exact error that would have caught it. Both are fixed:
+        # real async classes, plus async coverage for each of them.
+        self.transactions = AsyncTransactionsResource(self)
+        self.insiders = AsyncInsidersResource(self)
+        self.companies = AsyncCompaniesResource(self)
+        self.signals = AsyncSignalsResource(self)
+        self.webhooks = AsyncWebhooksResource(self)
+        # Spec-derived families, async variants.
+        self.congress = GeneratedAsyncCongressResource(self)
+        self.filings = GeneratedAsyncFilingsResource(self)
+        self.form144 = GeneratedAsyncForm144Resource(self)
+        self.holdings = GeneratedAsyncHoldingsResource(self)
+        self.stats = GeneratedAsyncStatsResource(self)
+        self.status = GeneratedAsyncStatusResource(self)
+        self.data_quality = GeneratedAsyncDataQualityResource(self)
 
     async def __aenter__(self) -> AsyncForm4ApiClient:
         return self
@@ -220,7 +275,17 @@ class AsyncForm4ApiClient:
         if res.status_code == 401:
             raise AuthError(message, code)
         if res.status_code == 402:
-            raise PlanError(message, body.get("requiredPlan") if isinstance(body, dict) else None)
+            # Read from the nested `error` object, not the top level. This was
+            # reading body["requiredPlan"], which the API has never emitted at
+            # any level, so PlanError.required_plan was permanently None. The
+            # backend now returns requiredPlan/currentPlan/upgradeUrl inside the
+            # standard error envelope.
+            raise PlanError(
+                message,
+                error.get("requiredPlan") if isinstance(error, dict) else None,
+                error.get("currentPlan") if isinstance(error, dict) else None,
+                error.get("upgradeUrl") if isinstance(error, dict) else None,
+            )
         if res.status_code == 404:
             raise NotFoundError(message, code)
         if res.status_code == 429:

{form4api-0.4.3 → form4api-0.6.0}/form4api/_errors.py

@@ -1,30 +1,47 @@
-from __future__ import annotations
-
-
-class Form4ApiError(Exception):
-    def __init__(self, message: str, status_code: int, error_code: str | None = None) -> None:
-        super().__init__(message)
-        self.status_code = status_code
-        self.error_code = error_code
-
-
-class AuthError(Form4ApiError):
-    def __init__(self, message: str, error_code: str | None = None) -> None:
-        super().__init__(message, 401, error_code)
-
-
-class PlanError(Form4ApiError):
-    def __init__(self, message: str, required_plan: str | None = None) -> None:
-        super().__init__(message, 402, "PLAN_REQUIRED")
-        self.required_plan = required_plan
-
-
-class NotFoundError(Form4ApiError):
-    def __init__(self, message: str, error_code: str | None = None) -> None:
-        super().__init__(message, 404, error_code)
-
-
-class RateLimitError(Form4ApiError):
-    def __init__(self, message: str, retry_after: int | None = None) -> None:
-        super().__init__(message, 429, "RATE_LIMIT_EXCEEDED")
-        self.retry_after = retry_after
+from __future__ import annotations
+
+
+class Form4ApiError(Exception):
+    def __init__(self, message: str, status_code: int, error_code: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+
+
+class AuthError(Form4ApiError):
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        super().__init__(message, 401, error_code)
+
+
+class PlanError(Form4ApiError):
+    """Raised on 402 PLAN_REQUIRED.
+
+    ``required_plan`` is the minimum plan that unlocks the endpoint (e.g.
+    ``"Business"``), ``current_plan`` is the plan the calling key is on, and
+    ``upgrade_url`` is where to upgrade. All three may be ``None`` against
+    backends older than 2026-08-05, which carried the plan names only as prose
+    inside ``message``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        required_plan: str | None = None,
+        current_plan: str | None = None,
+        upgrade_url: str | None = None,
+    ) -> None:
+        super().__init__(message, 402, "PLAN_REQUIRED")
+        self.required_plan = required_plan
+        self.current_plan = current_plan
+        self.upgrade_url = upgrade_url
+
+
+class NotFoundError(Form4ApiError):
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        super().__init__(message, 404, error_code)
+
+
+class RateLimitError(Form4ApiError):
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        super().__init__(message, 429, "RATE_LIMIT_EXCEEDED")
+        self.retry_after = retry_after