form4api 0.5.0__tar.gz → 0.7.0__tar.gz

{form4api-0.5.0 → form4api-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.5.0
+Version: 0.7.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,13 +82,13 @@ asyncio.run(main())
 | Resource | Methods |
 |---|---|
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
-| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
+| `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` | `.recent(**params)`, `.get(accession_number)` |
+| `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)` |
@@ -183,27 +183,52 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 
 ### Pagination
 
+`paginate()` pages through the data until it runs out (a short or empty page)
+or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20
+pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402.
+That 402 is not swallowed — it raises `PaginationLimitError` mid-iteration,
+after every page already yielded has been delivered to your loop. Pages you
+already received are real and complete; the error only means iteration
+stopped early. Pass `max_pages` to stop deliberately before that ever
+happens, or catch `PaginationLimitError` to know when a Free/Starter key ran
+out of depth on a bulk pull:
+
 ```python
+from form4api import PaginationLimitError
+
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
-    all_txns.extend(batch)
+try:
+    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
+        all_txns.extend(batch)
+except PaginationLimitError as e:
+    print(f"Stopped after {e.pages_yielded} pages — {e}")
+    # all_txns still holds every page yielded before the limit hit
 
 # signals.paginate()
 all_signals = []
-for batch in client.signals.paginate(cluster_buy=True, per_page=100):
+for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
     all_signals.extend(batch)
 ```
 
 ## Error handling
 
 ```python
-from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    PlanError,
+    PaginationLimitError,
+    RateLimitError,
+    NotFoundError,
+)
 
 client = Form4ApiClient("YOUR_API_KEY")
 
 try:
     signals = client.signals.list()
+except PaginationLimitError as e:
+    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
 except PlanError as e:
     print(f"Upgrade required")
 except RateLimitError as e:

{form4api-0.5.0 → form4api-0.7.0}/README.md

@@ -63,13 +63,13 @@ asyncio.run(main())
 | Resource | Methods |
 |---|---|
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
-| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
+| `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` | `.recent(**params)`, `.get(accession_number)` |
+| `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)` |
@@ -164,27 +164,52 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 
 ### Pagination
 
+`paginate()` pages through the data until it runs out (a short or empty page)
+or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20
+pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402.
+That 402 is not swallowed — it raises `PaginationLimitError` mid-iteration,
+after every page already yielded has been delivered to your loop. Pages you
+already received are real and complete; the error only means iteration
+stopped early. Pass `max_pages` to stop deliberately before that ever
+happens, or catch `PaginationLimitError` to know when a Free/Starter key ran
+out of depth on a bulk pull:
+
 ```python
+from form4api import PaginationLimitError
+
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
-    all_txns.extend(batch)
+try:
+    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
+        all_txns.extend(batch)
+except PaginationLimitError as e:
+    print(f"Stopped after {e.pages_yielded} pages — {e}")
+    # all_txns still holds every page yielded before the limit hit
 
 # signals.paginate()
 all_signals = []
-for batch in client.signals.paginate(cluster_buy=True, per_page=100):
+for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
     all_signals.extend(batch)
 ```
 
 ## Error handling
 
 ```python
-from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    PlanError,
+    PaginationLimitError,
+    RateLimitError,
+    NotFoundError,
+)
 
 client = Form4ApiClient("YOUR_API_KEY")
 
 try:
     signals = client.signals.list()
+except PaginationLimitError as e:
+    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
 except PlanError as e:
     print(f"Upgrade required")
 except RateLimitError as e:

{form4api-0.5.0 → form4api-0.7.0}/form4api/__init__.py

@@ -1,30 +1,38 @@
-from form4api._client import AsyncForm4ApiClient, Form4ApiClient
-from form4api._errors import AuthError, Form4ApiError, NotFoundError, PlanError, RateLimitError
-from form4api._types import (
-    Company,
-    Insider,
-    InsiderSignal,
-    Transaction,
-    WebhookCreated,
-    WebhookEvent,
-    WebhookSubscription,
-)
-from form4api._webhook_utils import verify_webhook
-
-__all__ = [
-    "Form4ApiClient",
-    "AsyncForm4ApiClient",
-    "Form4ApiError",
-    "AuthError",
-    "PlanError",
-    "NotFoundError",
-    "RateLimitError",
-    "Transaction",
-    "Insider",
-    "Company",
-    "InsiderSignal",
-    "WebhookCreated",
-    "WebhookEvent",
-    "WebhookSubscription",
-    "verify_webhook",
-]
+from form4api._client import AsyncForm4ApiClient, Form4ApiClient
+from form4api._errors import (
+    AuthError,
+    Form4ApiError,
+    NotFoundError,
+    PaginationLimitError,
+    PlanError,
+    RateLimitError,
+)
+from form4api._types import (
+    Company,
+    Insider,
+    InsiderSignal,
+    Transaction,
+    WebhookCreated,
+    WebhookEvent,
+    WebhookSubscription,
+)
+from form4api._webhook_utils import verify_webhook
+
+__all__ = [
+    "Form4ApiClient",
+    "AsyncForm4ApiClient",
+    "Form4ApiError",
+    "AuthError",
+    "PlanError",
+    "PaginationLimitError",
+    "NotFoundError",
+    "RateLimitError",
+    "Transaction",
+    "Insider",
+    "Company",
+    "InsiderSignal",
+    "WebhookCreated",
+    "WebhookEvent",
+    "WebhookSubscription",
+    "verify_webhook",
+]

form4api-0.7.0/form4api/_errors.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import re
+
+
+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
+
+
+# Backend message shape for the plan-gated *pagination depth* 402 (see
+# PaginationHelpers.MaxPageFor / TransactionsEndpoints.cs / CongressEndpoints.cs
+# on the API). This is deliberately narrow: `error_code` is "PLAN_REQUIRED" for
+# EVERY 402 the API returns — a whole-endpoint plan gate (e.g. GET /v1/signals
+# on a sub-Business key) and a plan-gated query parameter both use the same
+# code — so the message text is the only reliable signal that a given 402 is
+# specifically the depth limit rather than some other plan gate. If the
+# backend ever changes this message shape, the regex stops matching and
+# `paginate()` re-raises the original `PlanError` untouched instead of
+# mislabeling an unrelated 402.
+_PAGINATION_DEPTH_MESSAGE_RE = re.compile(r"pagination depth on /v1/", re.IGNORECASE)
+
+
+def is_pagination_depth_error(err: Exception) -> bool:
+    """True when `err` is specifically the plan-gated pagination-depth 402 that
+    `paginate()` knows how to turn into a `PaginationLimitError`."""
+    return isinstance(err, PlanError) and bool(_PAGINATION_DEPTH_MESSAGE_RE.search(str(err)))
+
+
+class PaginationLimitError(PlanError):
+    """Raised by `paginate()` (on `transactions` and `signals`) when the backend
+    rejects the next page because the calling key's plan has reached its
+    pagination depth limit (Free: 20 pages, Starter: 100, Pro+: unlimited).
+
+    Pages already yielded before this point were real, complete pages — this
+    error only means iteration stopped early, not that any data already
+    delivered to the caller was wrong. `pages_yielded` tells you exactly how
+    many. The original `PlanError` is chained as `__cause__` (via `raise ... from err`).
+
+    **Subclasses PlanError deliberately.** Before this type existed, `paginate()`
+    raised a plain `PlanError` at the depth limit, so `except PlanError:` was the
+    documented way to handle it. Subclassing keeps every one of those handlers
+    working while letting new code catch the narrower type — and it is the
+    truthful relationship anyway, since this IS a 402 PLAN_REQUIRED. Making it a
+    sibling would break existing callers for no gain.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        pages_yielded: int,
+        cause: PlanError | None = None,
+    ) -> None:
+        # Carry the upgrade metadata through from the original 402 where the
+        # backend supplied it, so a caller can link straight to the upgrade page
+        # without unwrapping __cause__ themselves. The depth-limit branch
+        # populates upgrade_url but leaves required_plan/current_plan None.
+        super().__init__(
+            message,
+            cause.required_plan if cause else None,
+            cause.current_plan if cause else None,
+            cause.upgrade_url if cause else None,
+        )
+        self.pages_yielded = pages_yielded

{form4api-0.5.0 → form4api-0.7.0}/form4api/_generated.py

@@ -427,6 +427,47 @@ class DataQualityResponse:
         return cls(**kwargs)
 
 
+@dataclass
+class DirectoryEntryResponse:
+    cik: str | None = None
+    filer_group_size: int | None = None
+    is_director: bool | None = None
+    is_officer: bool | None = None
+    is_ten_percent_owner: bool | None = None
+    last_filed_at: str | None = None
+    name: str | None = None
+    officer_title: str | None = None
+    primary_company_name: str | None = None
+    primary_ticker: str | None = None
+    transaction_count: int | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "DirectoryEntryResponse":
+        """Build from an API payload, ignoring unknown keys.
+
+        Constructing with **data directly (as the hand-written resources do)
+        means the SDK raises TypeError the moment the backend adds a field.
+        Filtering keeps older SDK versions working against a newer API."""
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class DirectoryLetter:
+    count: int | None = None
+    letter: str | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "DirectoryLetter":
+        """Build from an API payload, ignoring unknown keys.
+
+        Constructing with **data directly (as the hand-written resources do)
+        means the SDK raises TypeError the moment the backend adds a field.
+        Filtering keeps older SDK versions working against a newer API."""
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
 @dataclass
 class ExcludedTradeEntry:
     code: str | None = None
@@ -678,6 +719,33 @@ class InsiderCompanyEntry:
         return cls(**{k: v for k, v in data.items() if k in known})
 
 
+@dataclass
+class InsiderDirectoryResponse:
+    entries: list[DirectoryEntryResponse] | None = None
+    letter: str | None = None
+    letter_total: int | None = None
+    letters: list[DirectoryLetter] | None = None
+    page: int | None = None
+    per_page: int | None = None
+    refreshed_at: str | None = None
+    total: int | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "InsiderDirectoryResponse":
+        """Build from an API payload, ignoring unknown keys.
+
+        Constructing with **data directly (as the hand-written resources do)
+        means the SDK raises TypeError the moment the backend adds a field.
+        Filtering keeps older SDK versions working against a newer API."""
+        known = {f.name for f in fields(cls)}
+        kwargs = {k: v for k, v in data.items() if k in known}
+        if isinstance(kwargs.get("entries"), list):
+            kwargs["entries"] = [DirectoryEntryResponse._from_dict(i) if isinstance(i, dict) else i for i in kwargs["entries"]]
+        if isinstance(kwargs.get("letters"), list):
+            kwargs["letters"] = [DirectoryLetter._from_dict(i) if isinstance(i, dict) else i for i in kwargs["letters"]]
+        return cls(**kwargs)
+
+
 @dataclass
 class InsiderLeaderboardResponse:
     insiders: list[LeaderboardEntry] | None = None
@@ -1302,7 +1370,7 @@ class GeneratedCongressResource:
     def trades(self, *, ticker: str | None = None, politician: str | None = None, party: str | None = None, chamber: str | None = None, state: str | None = None, transaction_type: str | None = None, min_amount: float | None = None, transaction_date_from: str | None = None, transaction_date_to: str | None = None, disclosure_date_from: str | None = None, disclosure_date_to: str | None = None, page: int | None = None, per_page: int | None = None) -> list[CongressTradeDto]:
         """Query congressional STOCK Act trades (Free+, plan-clamped disclosure window)
 
-        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). Query runs live against the database — no caching."""
+        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). COVERAGE — HOUSE ONLY TODAY: every trade in this dataset comes from the U.S. House Clerk's PTR index. Senate eFD (efdsearch.senate.gov) returns 403 to datacenter traffic, so no Senate filings are ingested yet. chamber=Senate remains a valid filter but matches nothing and returns the response header X-Coverage-Note: chamber-not-covered, so an empty result is never ambiguous. Scanning by chamber should treat that header as "not covered", not as "no trades". PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate — see the coverage note above), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). Query runs live against the database — no caching."""
         params = {
             "ticker": ticker,
             "politician": politician,
@@ -1365,7 +1433,7 @@ class GeneratedAsyncCongressResource:
     async def trades(self, *, ticker: str | None = None, politician: str | None = None, party: str | None = None, chamber: str | None = None, state: str | None = None, transaction_type: str | None = None, min_amount: float | None = None, transaction_date_from: str | None = None, transaction_date_to: str | None = None, disclosure_date_from: str | None = None, disclosure_date_to: str | None = None, page: int | None = None, per_page: int | None = None) -> list[CongressTradeDto]:
         """Query congressional STOCK Act trades (Free+, plan-clamped disclosure window)
 
-        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). Query runs live against the database — no caching."""
+        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). COVERAGE — HOUSE ONLY TODAY: every trade in this dataset comes from the U.S. House Clerk's PTR index. Senate eFD (efdsearch.senate.gov) returns 403 to datacenter traffic, so no Senate filings are ingested yet. chamber=Senate remains a valid filter but matches nothing and returns the response header X-Coverage-Note: chamber-not-covered, so an empty result is never ambiguous. Scanning by chamber should treat that header as "not covered", not as "no trades". PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate — see the coverage note above), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). Query runs live against the database — no caching."""
         params = {
             "ticker": ticker,
             "politician": politician,
@@ -1421,6 +1489,23 @@ class GeneratedFilingsResource:
         data = self._client._get(f"/v1/filings/{accession}")
         return FilingResponse._from_dict(data)
 
+    def list(self, *, ticker: str | None = None, cik: str | None = None, from_: str | None = None, to: str | None = None, page: int | None = None, per_page: int | None = None, limit: int | None = None) -> list[FilingResponse]:
+        """List Form 4 filings with optional ticker, CIK and date filters
+
+        Returns a paginated list of Form 4 filings, newest filed first. Filter by ticker, cik, and a from/to filed-date window. Each entry carries the accession number, company ticker/name, period of report, filed date, amendment type (Original/Amendment), and the count of non-superseded transactions in that filing. Use this for a company's filing HISTORY; use GET /v1/filings/recent for a live newest-first feed (it has no page parameter), and GET /v1/transactions when you want the individual trades rather than the filings that contain them. `limit` is accepted as an alias for `per_page`. Not plan-gated."""
+        params = {
+            "ticker": ticker,
+            "cik": cik,
+            "from": from_,
+            "to": to,
+            "page": page,
+            "per_page": per_page,
+            "limit": limit,
+        }
+        params = {k: str(v) for k, v in params.items() if v is not None}
+        data = self._client._get(f"/v1/filings", params=params)
+        return [FilingResponse._from_dict(item) for item in data]
+
     def recent(self, *, ticker: str | None = None, per_page: int | None = None) -> list[FilingResponse]:
         """Get the most recently filed Form 4s, optionally filtered by ticker
 
@@ -1445,6 +1530,23 @@ class GeneratedAsyncFilingsResource:
         data = await self._client._get(f"/v1/filings/{accession}")
         return FilingResponse._from_dict(data)
 
+    async def list(self, *, ticker: str | None = None, cik: str | None = None, from_: str | None = None, to: str | None = None, page: int | None = None, per_page: int | None = None, limit: int | None = None) -> list[FilingResponse]:
+        """List Form 4 filings with optional ticker, CIK and date filters
+
+        Returns a paginated list of Form 4 filings, newest filed first. Filter by ticker, cik, and a from/to filed-date window. Each entry carries the accession number, company ticker/name, period of report, filed date, amendment type (Original/Amendment), and the count of non-superseded transactions in that filing. Use this for a company's filing HISTORY; use GET /v1/filings/recent for a live newest-first feed (it has no page parameter), and GET /v1/transactions when you want the individual trades rather than the filings that contain them. `limit` is accepted as an alias for `per_page`. Not plan-gated."""
+        params = {
+            "ticker": ticker,
+            "cik": cik,
+            "from": from_,
+            "to": to,
+            "page": page,
+            "per_page": per_page,
+            "limit": limit,
+        }
+        params = {k: str(v) for k, v in params.items() if v is not None}
+        data = await self._client._get(f"/v1/filings", params=params)
+        return [FilingResponse._from_dict(item) for item in data]
+
     async def recent(self, *, ticker: str | None = None, per_page: int | None = None) -> list[FilingResponse]:
         """Get the most recently filed Form 4s, optionally filtered by ticker
 
@@ -1578,6 +1680,36 @@ class GeneratedInsidersResource:
     def __init__(self, client) -> None:
         self._client = client
 
+    def directory(self, *, letter: str | None = None, page: int | None = None, per_page: int | None = None) -> InsiderDirectoryResponse:
+        """Browse insiders alphabetically by surname
+
+        Returns the A-Z rail with a count per letter, plus one page of insiders under the
+requested letter. Omit `letter` to get the rail and totals with no rows.
+
+Names come from EDGAR surname-first ("HENNEMAN JOHN B III"), so alphabetical order
+is order by surname. Casing in the source is inconsistent and is not normalised here.
+
+This lists only insiders with at least 3 non-superseded transactions, capped at the
+5,000 most active — the same set as the insiders sitemap shard, so the two cannot
+drift. To find someone outside that set, use GET /v1/insiders?name= which searches
+every filer. Rebuilt daily; `refreshedAt` reports when. Not plan-gated.
+
+One row per FILER GROUP. A fund group files a single Form 4 listing several
+reporting owners — the fund, its GP, its management company — and each is a real
+EDGAR filer with its own CIK. Listing all of them spent about 11% of this capped
+surface describing the same actors more than once, so browse shows one per group
+and `filerGroupSize` says how many others share those exact transactions. The
+others are not hidden: each keeps its own profile and is still returned by
+GET /v1/insiders?name=."""
+        params = {
+            "letter": letter,
+            "page": page,
+            "per_page": per_page,
+        }
+        params = {k: str(v) for k, v in params.items() if v is not None}
+        data = self._client._get(f"/v1/insiders/directory", params=params)
+        return InsiderDirectoryResponse._from_dict(data)
+
     def leaderboard(self, *, horizon: str | None = None, order: str | None = None, min_trades: int | None = None, limit: int | None = None) -> InsiderLeaderboardResponse:
         """Ranked leaderboard of insiders by buy track-record (Business plan+)
 
@@ -1651,6 +1783,36 @@ class GeneratedAsyncInsidersResource:
     def __init__(self, client) -> None:
         self._client = client
 
+    async def directory(self, *, letter: str | None = None, page: int | None = None, per_page: int | None = None) -> InsiderDirectoryResponse:
+        """Browse insiders alphabetically by surname
+
+        Returns the A-Z rail with a count per letter, plus one page of insiders under the
+requested letter. Omit `letter` to get the rail and totals with no rows.
+
+Names come from EDGAR surname-first ("HENNEMAN JOHN B III"), so alphabetical order
+is order by surname. Casing in the source is inconsistent and is not normalised here.
+
+This lists only insiders with at least 3 non-superseded transactions, capped at the
+5,000 most active — the same set as the insiders sitemap shard, so the two cannot
+drift. To find someone outside that set, use GET /v1/insiders?name= which searches
+every filer. Rebuilt daily; `refreshedAt` reports when. Not plan-gated.
+
+One row per FILER GROUP. A fund group files a single Form 4 listing several
+reporting owners — the fund, its GP, its management company — and each is a real
+EDGAR filer with its own CIK. Listing all of them spent about 11% of this capped
+surface describing the same actors more than once, so browse shows one per group
+and `filerGroupSize` says how many others share those exact transactions. The
+others are not hidden: each keeps its own profile and is still returned by
+GET /v1/insiders?name=."""
+        params = {
+            "letter": letter,
+            "page": page,
+            "per_page": per_page,
+        }
+        params = {k: str(v) for k, v in params.items() if v is not None}
+        data = await self._client._get(f"/v1/insiders/directory", params=params)
+        return InsiderDirectoryResponse._from_dict(data)
+
     async def leaderboard(self, *, horizon: str | None = None, order: str | None = None, min_trades: int | None = None, limit: int | None = None) -> InsiderLeaderboardResponse:
         """Ranked leaderboard of insiders by buy track-record (Business plan+)
 

{form4api-0.5.0 → form4api-0.7.0}/form4api/resources/_signals.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
 
 from collections.abc import AsyncGenerator
 
+from form4api._errors import PaginationLimitError, PlanError, is_pagination_depth_error
 from form4api._generated import GeneratedAsyncSignalsResource, GeneratedSignalsResource
 from form4api._types import InsiderSignal
 
@@ -58,16 +59,39 @@ class SignalsResource(GeneratedSignalsResource):
         cluster_buy: bool | None = None,
         cluster_sell: bool | None = None,
         per_page: int = 100,
+        max_pages: int | None = None,
     ) -> Generator[list[InsiderSignal], None, None]:
+        """Pages through /v1/signals until the data runs out (a short or empty
+        page) or the calling key's plan-gated pagination depth is exceeded —
+        see `TransactionsResource.paginate` for the full rationale. That 402
+        is NOT swallowed; it becomes a `PaginationLimitError` after every page
+        already yielded has been delivered to the caller. Pass `max_pages` to
+        stop deliberately before that happens.
+        """
         page = 1
+        pages_yielded = 0
         while True:
-            batch = self.list(
-                ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = self.list(
+                    ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"signals.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1
@@ -102,16 +126,34 @@ class AsyncSignalsResource(GeneratedAsyncSignalsResource):
         cluster_buy: bool | None = None,
         cluster_sell: bool | None = None,
         per_page: int = 100,
+        max_pages: int | None = None,
     ) -> AsyncGenerator[list[InsiderSignal], None]:
+        """Async twin of `SignalsResource.paginate` — same depth-limit
+        semantics, see there for the full rationale."""
         page = 1
+        pages_yielded = 0
         while True:
-            batch = await self.list(
-                ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = await self.list(
+                    ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"signals.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1

{form4api-0.5.0 → form4api-0.7.0}/form4api/resources/_transactions.py

@@ -3,6 +3,7 @@
 from collections.abc import AsyncGenerator, Generator
 from typing import TYPE_CHECKING
 
+from form4api._errors import PaginationLimitError, PlanError, is_pagination_depth_error
 from form4api._types import Transaction
 
 if TYPE_CHECKING:
@@ -121,23 +122,49 @@ class TransactionsResource:
         min_shares: float | None = None,
         max_shares: float | None = None,
         per_page: int = 50,
+        max_pages: int | None = None,
     ) -> Generator[list[Transaction], None, None]:
+        """Pages through /v1/transactions until the data runs out (a short or
+        empty page) or, since the backend's 2026-08-01 plan-gated pagination
+        depth (Free: 20 pages, Starter: 100, Pro+: unlimited), the next page is
+        rejected with a 402. That 402 is NOT swallowed — a scripted caller who
+        silently stopped there would see what looks like "no more data" and
+        never learn their dataset was truncated. Instead this raises
+        `PaginationLimitError` mid-iteration, after every page already yielded
+        has been delivered to the caller. Pass `max_pages` to stop deliberately
+        before that ever happens.
+        """
         page = 1
+        pages_yielded = 0
         while True:
-            batch = self.list(
-                ticker=ticker, cik=cik, insider_cik=insider_cik,
-                code=code, from_date=from_date, to_date=to_date,
-                exclude_10b5=exclude_10b5,
-                codes=codes, exclude_codes=exclude_codes,
-                category=category, exclude_category=exclude_category,
-                exclude_derivative=exclude_derivative, significant=significant,
-                min_value=min_value, max_value=max_value,
-                min_shares=min_shares, max_shares=max_shares,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = self.list(
+                    ticker=ticker, cik=cik, insider_cik=insider_cik,
+                    code=code, from_date=from_date, to_date=to_date,
+                    exclude_10b5=exclude_10b5,
+                    codes=codes, exclude_codes=exclude_codes,
+                    category=category, exclude_category=exclude_category,
+                    exclude_derivative=exclude_derivative, significant=significant,
+                    min_value=min_value, max_value=max_value,
+                    min_shares=min_shares, max_shares=max_shares,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"transactions.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1
@@ -205,21 +232,39 @@ class AsyncTransactionsResource:
         min_shares: float | None = None,
         max_shares: float | None = None,
         per_page: int = 50,
+        max_pages: int | None = None,
     ) -> AsyncGenerator[list[Transaction], None]:
+        """Async twin of `TransactionsResource.paginate` — same depth-limit
+        semantics, see there for the full rationale."""
         page = 1
+        pages_yielded = 0
         while True:
-            batch = await self.list(
-            ticker=ticker, cik=cik, insider_cik=insider_cik, code=code,
-            from_date=from_date, to_date=to_date, exclude_10b5=exclude_10b5,
-            codes=codes, exclude_codes=exclude_codes, category=category,
-            exclude_category=exclude_category, exclude_derivative=exclude_derivative,
-            significant=significant, min_value=min_value, max_value=max_value,
-            min_shares=min_shares, max_shares=max_shares,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = await self.list(
+                    ticker=ticker, cik=cik, insider_cik=insider_cik, code=code,
+                    from_date=from_date, to_date=to_date, exclude_10b5=exclude_10b5,
+                    codes=codes, exclude_codes=exclude_codes, category=category,
+                    exclude_category=exclude_category, exclude_derivative=exclude_derivative,
+                    significant=significant, min_value=min_value, max_value=max_value,
+                    min_shares=min_shares, max_shares=max_shares,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"transactions.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1

{form4api-0.5.0 → form4api-0.7.0}/form4api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.5.0
+Version: 0.7.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,13 +82,13 @@ asyncio.run(main())
 | Resource | Methods |
 |---|---|
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
-| `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
+| `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` | `.recent(**params)`, `.get(accession_number)` |
+| `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)` |
@@ -183,27 +183,52 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 
 ### Pagination
 
+`paginate()` pages through the data until it runs out (a short or empty page)
+or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20
+pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402.
+That 402 is not swallowed — it raises `PaginationLimitError` mid-iteration,
+after every page already yielded has been delivered to your loop. Pages you
+already received are real and complete; the error only means iteration
+stopped early. Pass `max_pages` to stop deliberately before that ever
+happens, or catch `PaginationLimitError` to know when a Free/Starter key ran
+out of depth on a bulk pull:
+
 ```python
+from form4api import PaginationLimitError
+
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
-    all_txns.extend(batch)
+try:
+    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
+        all_txns.extend(batch)
+except PaginationLimitError as e:
+    print(f"Stopped after {e.pages_yielded} pages — {e}")
+    # all_txns still holds every page yielded before the limit hit
 
 # signals.paginate()
 all_signals = []
-for batch in client.signals.paginate(cluster_buy=True, per_page=100):
+for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
     all_signals.extend(batch)
 ```
 
 ## Error handling
 
 ```python
-from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    PlanError,
+    PaginationLimitError,
+    RateLimitError,
+    NotFoundError,
+)
 
 client = Form4ApiClient("YOUR_API_KEY")
 
 try:
     signals = client.signals.list()
+except PaginationLimitError as e:
+    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
 except PlanError as e:
     print(f"Upgrade required")
 except RateLimitError as e:

{form4api-0.5.0 → form4api-0.7.0}/form4api.egg-info/SOURCES.txt

@@ -19,4 +19,5 @@ form4api/resources/_signals.py
 form4api/resources/_transactions.py
 form4api/resources/_webhooks.py
 tests/test_client.py
-tests/test_generated.py
+tests/test_generated.py
+tests/test_method_name.py

{form4api-0.5.0 → form4api-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "form4api"
-version = "0.5.0"
+version = "0.7.0"
 description = "Python client for the Form4API — real-time SEC Form 4 insider trading data"
 keywords = ["insider-trading", "sec", "sec-edgar", "edgar", "form-4", "form4", "form-144", "13f", "13f-hr", "financial-data", "stock-market", "stocks", "fintech", "api", "sdk", "webhooks", "form4api"]
 requires-python = ">=3.11"

{form4api-0.5.0 → form4api-0.7.0}/tests/test_client.py

@@ -6,6 +6,7 @@ from form4api import (
     Form4ApiClient,
     AuthError,
     NotFoundError,
+    PaginationLimitError,
     PlanError,
     RateLimitError,
     Form4ApiError,
@@ -161,6 +162,128 @@ def test_transactions_paginate_stops_on_short_page(client):
     assert pages[0][0].ticker == "AAPL"
 
 
+@respx.mock
+def test_transactions_paginate_raises_pagination_limit_error_after_delivering_prior_pages(client):
+    """The plan-gated pagination-depth 402 is not swallowed: it becomes a
+    PaginationLimitError raised mid-iteration, after every page already
+    yielded has been delivered to the caller."""
+    call = {"n": 0}
+
+    def handler(_request):
+        call["n"] += 1
+        if call["n"] <= 2:
+            return httpx.Response(200, json=[TX, TX])
+        return httpx.Response(
+            402,
+            json={
+                "error": {
+                    "code": "PLAN_REQUIRED",
+                    "message": (
+                        "Page 3 is beyond the Free plan's pagination depth on /v1/transactions "
+                        "(2 pages). The Starter plan reaches 100 pages and Pro removes the limit "
+                        "— upgrade at https://form4api.com/dashboard/billing?from=page_depth_402. "
+                        "For a bulk historical pull, GET /v1/transactions/export (Business plan) "
+                        "streams the full filtered set as CSV instead of paging."
+                    ),
+                    "requestId": "req_test",
+                }
+            },
+        )
+
+    respx.get(f"{BASE}/v1/transactions").mock(side_effect=handler)
+
+    pages = []
+    caught = None
+    try:
+        for page in client.transactions.paginate(per_page=2):
+            pages.append(page)
+    except PaginationLimitError as err:
+        caught = err
+
+    assert len(pages) == 2
+    assert caught is not None
+    assert caught.pages_yielded == 2
+    assert "yielding 2 page(s)" in str(caught)
+    assert "/v1/transactions/export" in str(caught)
+    assert isinstance(caught.__cause__, PlanError)
+
+    # Backward compatibility, and the reason PaginationLimitError subclasses
+    # PlanError rather than sitting beside it. Before this type existed,
+    # paginate() raised a plain PlanError here, so `except PlanError:` was the
+    # documented way to handle the depth limit. If this assertion ever fails,
+    # every caller written against the old behaviour is silently no longer
+    # catching this — an uncaught exception rather than a handled upgrade path.
+    assert isinstance(caught, PlanError)
+    # The upgrade metadata is carried through from the original 402 so callers
+    # do not have to unwrap __cause__ to find it.
+    assert caught.upgrade_url == caught.__cause__.upgrade_url
+
+
+@respx.mock
+def test_transactions_paginate_max_pages_stops_before_depth_limit(client):
+    respx.get(f"{BASE}/v1/transactions").mock(return_value=httpx.Response(200, json=[TX, TX]))
+    pages = list(client.transactions.paginate(per_page=2, max_pages=3))
+    assert len(pages) == 3
+
+
+@respx.mock
+def test_transactions_paginate_does_not_swallow_or_mislabel_non_402_error(client):
+    call = {"n": 0}
+
+    def handler(_request):
+        call["n"] += 1
+        if call["n"] == 1:
+            return httpx.Response(200, json=[TX, TX])
+        return httpx.Response(500, json={})
+
+    respx.get(f"{BASE}/v1/transactions").mock(side_effect=handler)
+
+    pages = []
+    caught = None
+    try:
+        for page in client.transactions.paginate(per_page=2):
+            pages.append(page)
+    except Form4ApiError as err:
+        caught = err
+
+    assert len(pages) == 1
+    assert caught is not None
+    assert not isinstance(caught, PaginationLimitError)
+    assert caught.status_code == 500
+
+
+@respx.mock
+def test_signals_paginate_reraises_non_depth_402_as_plan_error(client):
+    """GET /v1/signals is gated at the whole-endpoint level (Business plan) —
+    this 402 has nothing to do with pagination depth, and must not be
+    rewritten as though it were the depth limit."""
+    respx.get(f"{BASE}/v1/signals").mock(
+        return_value=httpx.Response(
+            402,
+            json={
+                "error": {
+                    "code": "PLAN_REQUIRED",
+                    "message": "This endpoint requires the Business plan or higher. Your current plan is Free.",
+                    "requestId": "req_test",
+                    "requiredPlan": "Business",
+                    "currentPlan": "Free",
+                }
+            },
+        )
+    )
+
+    caught = None
+    try:
+        for _page in client.signals.paginate():
+            pass
+    except PlanError as err:
+        caught = err
+
+    assert caught is not None
+    assert not isinstance(caught, PaginationLimitError)
+    assert caught.required_plan == "Business"
+
+
 # ── insiders ──────────────────────────────────────────────────────────────────
 
 @respx.mock

{form4api-0.5.0 → form4api-0.7.0}/tests/test_generated.py

@@ -387,3 +387,47 @@ def test_nested_objects_hydrate_all_the_way_down(client: Form4ApiClient) -> None
     assert result.career.returns.avg_return3m == 0.109
     # And through a list, not just a single object.
     assert result.career.companies[0].ticker == "AAPL"
+
+
+# The two methods that arrived by derivation rather than by a hand-written
+# METHOD_NAMES entry. Codegen could not run at all between 2026-08-04 and
+# 2026-08-25, so these are the first endpoints to reach this SDK without anyone
+# naming them — worth pinning that they are wired to the right paths and not
+# just present on the class.
+@respx.mock
+def test_filings_list_hits_path_and_forwards_filters(client: Form4ApiClient) -> None:
+    route = respx.get(f"{BASE}/v1/filings").mock(return_value=httpx.Response(200, json=[]))
+    client.filings.list(ticker="AAPL", per_page=5)
+
+    request = route.calls.last.request
+    assert request.url.path == "/v1/filings"
+    assert request.url.params["ticker"] == "AAPL"
+    assert request.url.params["per_page"] == "5"
+
+
+@respx.mock
+def test_filings_list_is_distinct_from_filings_recent(client: Form4ApiClient) -> None:
+    # Derivation stripped the resource from both operationIds; if it had
+    # collapsed them, one would silently shadow the other.
+    route = respx.get(f"{BASE}/v1/filings/recent").mock(return_value=httpx.Response(200, json=[]))
+    client.filings.recent()
+    assert route.calls.last.request.url.path == "/v1/filings/recent"
+
+
+@respx.mock
+def test_insiders_directory_hits_path_and_forwards_letter(client: Form4ApiClient) -> None:
+    route = respx.get(f"{BASE}/v1/insiders/directory").mock(
+        return_value=httpx.Response(200, json={"letters": [], "insiders": []})
+    )
+    client.insiders.directory(letter="S", per_page=200)
+
+    request = route.calls.last.request
+    assert request.url.path == "/v1/insiders/directory"
+    assert request.url.params["letter"] == "S"
+
+
+@respx.mock
+def test_insiders_directory_does_not_shadow_insiders_list(client: Form4ApiClient) -> None:
+    route = respx.get(f"{BASE}/v1/insiders").mock(return_value=httpx.Response(200, json=[]))
+    client.insiders.list()
+    assert route.calls.last.request.url.path == "/v1/insiders"

form4api-0.7.0/tests/test_method_name.py

@@ -0,0 +1,88 @@
+"""The generator derives a method name when no override is pinned.
+
+It used to raise instead, which is why this SDK could not regenerate at all
+between 2026-08-04 (/v1/filings) and 2026-08-25 (/v1/insiders/directory): a new
+backend endpoint took codegen down until someone hand-added a line, and with CI
+billing-blocked nobody saw it go red.
+
+So the rule is load-bearing and pinned here. Deriving a name wrong is worse
+than not deriving one — the method ships, someone imports it, and correcting it
+afterwards is a breaking rename.
+
+Mirrors tests/methodNames.test.ts in the JS SDK. The two derivations must agree
+on which words are dropped; they differ only in casing.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "codegen"))
+
+from method_name import derive_method_name  # noqa: E402
+
+
+def test_drops_the_resource_the_method_already_lives_on() -> None:
+    # filings.get_recent_filings() says "filings" twice.
+    assert derive_method_name("GetRecentFilings", "filings") == "recent"
+    assert derive_method_name("GetInsiderScorecard", "insiders") == "scorecard"
+    assert derive_method_name("GetConvergenceSignals", "signals") == "convergence"
+    assert derive_method_name("GetStatusHistory", "status") == "history"
+
+
+def test_falls_back_to_the_verb_when_the_resource_was_the_whole_name() -> None:
+    # What makes companies.list() and filings.get() read correctly.
+    assert derive_method_name("ListCompanies", "companies") == "list"
+    assert derive_method_name("ListInsiders", "insiders") == "list"
+    assert derive_method_name("GetFiling", "filings") == "get"
+    assert derive_method_name("GetDataQuality", "data_quality") == "get"
+
+
+def test_derives_the_two_endpoints_that_had_been_breaking_codegen() -> None:
+    assert derive_method_name("ListFilings", "filings") == "list"
+    assert derive_method_name("GetInsiderDirectory", "insiders") == "directory"
+
+
+def test_matches_exact_or_simple_plural_never_a_prefix() -> None:
+    # A looser test would strip "Sentiment" for a resource called "signals"
+    # and collapse two different endpoints onto signals.get().
+    assert derive_method_name("GetSentiment", "signals") == "sentiment"
+    assert derive_method_name("ListManagers", "holdings") == "managers"
+
+
+def test_handles_a_resource_carrying_digits() -> None:
+    # "Form144" must stay one word. Split into "Form" + "144", neither half
+    # matches the resource and this derives to form144() instead of list().
+    assert derive_method_name("ListForm144", "form144") == "list"
+
+
+def test_snake_cases_a_multi_word_remainder() -> None:
+    # The one place the two SDKs differ: JS camelCases this to tickerRollup.
+    assert derive_method_name("GetCongressTickerRollup", "congress") == "ticker_rollup"
+
+
+def test_already_published_names_stay_pinned() -> None:
+    """Every shipped name is kept as an explicit override even where the
+    derived value agrees, so no upstream operationId rename can quietly change
+    a method someone has already imported."""
+    source = (Path(__file__).resolve().parents[1] / "codegen" / "generate.py").read_text(
+        encoding="utf-8"
+    )
+    block = source[source.index("METHOD_NAME_OVERRIDES = {") :]
+    block = block[: block.index("\n}")]
+
+    # These two would derive to something else entirely — the case the
+    # override list exists for.
+    assert '"GetCongressTickerRollup": "ticker"' in block
+    assert '"GetPublicStats": "get"' in block
+
+    for operation_id in (
+        "ListCompanies",
+        "ListCongressTrades",
+        "GetInsiderLeaderboard",
+        "ListHoldings",
+        "ExplainSignal",
+        "GetSentiment",
+    ):
+        assert f'"{operation_id}":' in block, f"{operation_id} must stay pinned"

form4api-0.5.0/form4api/_errors.py

@@ -1,47 +0,0 @@
-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