filingstudio 0.4.0__tar.gz

filingstudio-0.4.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+packages/proxy-python/dist/
+*.egg-info/

filingstudio-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filing Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

filingstudio-0.4.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: filingstudio
+Version: 0.4.0
+Summary: Client for the Filing Studio API: search SEC filings, resolve traces, verify claims. One call per door, typed results, your key never in a URL.
+Project-URL: Homepage, https://filingstudio.com
+Project-URL: Documentation, https://filingstudio.com/docs#sdk
+Author-email: Filing Studio <support@filingstudio.com>
+License: MIT
+License-File: LICENSE
+Keywords: 10-K,10-Q,api-client,citations,edgar,filings,finance,provenance,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: anyio>=3; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# filingstudio
+
+Python client for the [Filing Studio](https://filingstudio.com) API. Search
+SEC filings exactly as printed, resolve any number back to the line that
+printed it, and verify claims deterministically. One call per door, typed
+results, and your key never in a URL.
+
+```bash
+pip install filingstudio
+```
+
+```python
+import os
+from filingstudio import FilingStudio
+
+fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])
+
+hits = fs.search("NVDA", "purchase commitments", type="prose")
+for p in hits.passages:
+    print(p.text, p.trace_id)
+
+v = fs.verify("NVDA", metric="Revenue", value=130497, period="FY2025")
+print(v.verdict)                       # supported | unsupported | ambiguous | unavailable
+print(v.receipts[0].printed_text)      # "130,497"
+print(v.receipts[0].links.highlight)   # opens the filing with that cell marked
+
+t = fs.trace(v.receipts[0].trace_id)   # the printed line plus its neighbours
+for row in t.context:
+    print(row.label, row.printed_text, "<- source" if row.is_source else "")
+```
+
+Async is the same API:
+
+```python
+from filingstudio import AsyncFilingStudio
+
+async with AsyncFilingStudio(api_key=key) as fs:
+    cov = await fs.coverage("NVDA")
+```
+
+## The six doors
+
+| method | what it answers |
+|---|---|
+| `search(ticker, q, type=, period=, forms=, limit=, offset=)` | printed rows, tables, and prose matching plain words |
+| `verify(ticker, metric=, value=, period=, claim=)` | is this claim what the filing prints? |
+| `trace(trace_id, include_context=True)` | the exact printed line behind a traceId, with neighbours |
+| `filings(ticker, form=, year=, limit=)` | a company's indexed filings |
+| `coverage(ticker)` | is anything indexed, and how fresh |
+| `table(ticker, accession, table_id, format="records")` | one printed table, as filed |
+
+Pass `value` to `verify` as the raw figure you hold (130497 or 130497000000
+alike). The API tries every printed scale a filer could use. Do not pre-scale.
+
+## Honest answers
+
+Every result carries `index_state`. `coverage` is one of:
+
+- `indexed`: a populated index answered, with results
+- `empty`: a populated index answered and had nothing. The only real negative.
+- `incomplete`: the index could not fully answer. Says nothing about the filing.
+- `unavailable`: the service or your quota could not answer. Same.
+
+`RateLimitError` (HTTP 429) carries `index_state.note`, a sentence safe to
+show a user. Other non-2xx answers raise `FilingStudioError` with `status`,
+`code`, and the API's `message`. 5xx and network failures are retried with
+backoff; 4xx are not. No error ever contains your key.
+
+## Research with receipts (experimental)
+
+```python
+from filingstudio.research import answer
+
+def llm(system: str, user: str, json_mode: bool) -> str:
+    ...  # any chat model; return the assistant text
+
+res = answer("How is Data Center revenue trending?", "NVDA", llm=llm, client=fs,
+             on_step=lambda label, detail: print(label, detail))
+res.answer, res.sources, res.hard_stop
+```
+
+Plan, search, assess, write, with hard stops. Every `[n]` in the answer is a
+search hit you can trace; citations to nothing are stripped; with no evidence
+the answer says so. `llm=None` runs one search and returns the evidence only.
+
+## Options
+
+`FilingStudio(api_key, base_url=None, timeout=30.0, max_retries=2, transport=None)`
+
+`transport` accepts an `httpx` transport, for tests (`httpx.MockTransport`).
+
+## Develop
+
+```bash
+pip install -e .[test]
+pytest
+```
+
+MIT

filingstudio-0.4.0/README.md

@@ -0,0 +1,99 @@
+# filingstudio
+
+Python client for the [Filing Studio](https://filingstudio.com) API. Search
+SEC filings exactly as printed, resolve any number back to the line that
+printed it, and verify claims deterministically. One call per door, typed
+results, and your key never in a URL.
+
+```bash
+pip install filingstudio
+```
+
+```python
+import os
+from filingstudio import FilingStudio
+
+fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])
+
+hits = fs.search("NVDA", "purchase commitments", type="prose")
+for p in hits.passages:
+    print(p.text, p.trace_id)
+
+v = fs.verify("NVDA", metric="Revenue", value=130497, period="FY2025")
+print(v.verdict)                       # supported | unsupported | ambiguous | unavailable
+print(v.receipts[0].printed_text)      # "130,497"
+print(v.receipts[0].links.highlight)   # opens the filing with that cell marked
+
+t = fs.trace(v.receipts[0].trace_id)   # the printed line plus its neighbours
+for row in t.context:
+    print(row.label, row.printed_text, "<- source" if row.is_source else "")
+```
+
+Async is the same API:
+
+```python
+from filingstudio import AsyncFilingStudio
+
+async with AsyncFilingStudio(api_key=key) as fs:
+    cov = await fs.coverage("NVDA")
+```
+
+## The six doors
+
+| method | what it answers |
+|---|---|
+| `search(ticker, q, type=, period=, forms=, limit=, offset=)` | printed rows, tables, and prose matching plain words |
+| `verify(ticker, metric=, value=, period=, claim=)` | is this claim what the filing prints? |
+| `trace(trace_id, include_context=True)` | the exact printed line behind a traceId, with neighbours |
+| `filings(ticker, form=, year=, limit=)` | a company's indexed filings |
+| `coverage(ticker)` | is anything indexed, and how fresh |
+| `table(ticker, accession, table_id, format="records")` | one printed table, as filed |
+
+Pass `value` to `verify` as the raw figure you hold (130497 or 130497000000
+alike). The API tries every printed scale a filer could use. Do not pre-scale.
+
+## Honest answers
+
+Every result carries `index_state`. `coverage` is one of:
+
+- `indexed`: a populated index answered, with results
+- `empty`: a populated index answered and had nothing. The only real negative.
+- `incomplete`: the index could not fully answer. Says nothing about the filing.
+- `unavailable`: the service or your quota could not answer. Same.
+
+`RateLimitError` (HTTP 429) carries `index_state.note`, a sentence safe to
+show a user. Other non-2xx answers raise `FilingStudioError` with `status`,
+`code`, and the API's `message`. 5xx and network failures are retried with
+backoff; 4xx are not. No error ever contains your key.
+
+## Research with receipts (experimental)
+
+```python
+from filingstudio.research import answer
+
+def llm(system: str, user: str, json_mode: bool) -> str:
+    ...  # any chat model; return the assistant text
+
+res = answer("How is Data Center revenue trending?", "NVDA", llm=llm, client=fs,
+             on_step=lambda label, detail: print(label, detail))
+res.answer, res.sources, res.hard_stop
+```
+
+Plan, search, assess, write, with hard stops. Every `[n]` in the answer is a
+search hit you can trace; citations to nothing are stripped; with no evidence
+the answer says so. `llm=None` runs one search and returns the evidence only.
+
+## Options
+
+`FilingStudio(api_key, base_url=None, timeout=30.0, max_retries=2, transport=None)`
+
+`transport` accepts an `httpx` transport, for tests (`httpx.MockTransport`).
+
+## Develop
+
+```bash
+pip install -e .[test]
+pytest
+```
+
+MIT

filingstudio-0.4.0/filingstudio/__init__.py

@@ -0,0 +1,48 @@
+"""Filing Studio client: search SEC filings, resolve traces, verify claims."""
+
+from . import research
+from .client import AsyncFilingStudio, FilingStudio
+from .errors import FilingStudioError, NotConfigured, RateLimitError
+from .models import (
+    ContextRow,
+    CoverageResult,
+    EvidenceLinks,
+    EvidenceSource,
+    FilingRef,
+    FilingsResult,
+    IndexState,
+    Pagination,
+    SearchCell,
+    SearchPassage,
+    SearchResult,
+    TableResult,
+    TraceDetail,
+    VerifyReceipt,
+    VerifyResult,
+)
+
+__version__ = "0.4.0"
+__all__ = [
+    "AsyncFilingStudio",
+    "ContextRow",
+    "CoverageResult",
+    "EvidenceLinks",
+    "EvidenceSource",
+    "FilingRef",
+    "FilingStudio",
+    "FilingStudioError",
+    "FilingsResult",
+    "IndexState",
+    "NotConfigured",
+    "Pagination",
+    "RateLimitError",
+    "SearchCell",
+    "SearchPassage",
+    "SearchResult",
+    "TableResult",
+    "TraceDetail",
+    "VerifyReceipt",
+    "VerifyResult",
+    "__version__",
+    "research",
+]

filingstudio-0.4.0/filingstudio/client.py

@@ -0,0 +1,333 @@
+"""
+The Filing Studio client, sync and async. One method per /v1 door, the same
+names as the Node `@filingstudio/client` and the browser `ProvenanceClient`.
+
+    from filingstudio import FilingStudio
+    fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])
+    hits = fs.search("NVDA", "purchase commitments", type="prose")
+    v = fs.verify("NVDA", metric="Revenue", value=130497, period="FY2025")
+
+The key travels only in the X-API-Key header, never in a URL, never in an
+error message. 5xx and transport failures are retried with backoff; 4xx are
+not. Pass `value` to verify as the raw figure you hold: the API tries every
+printed scale a filer could use.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import anyio
+import httpx
+
+from .errors import FilingStudioError, NotConfigured, RateLimitError
+from .models import (
+    CoverageResult,
+    FilingsResult,
+    IndexState,
+    SearchResult,
+    TableResult,
+    TraceDetail,
+    VerifyResult,
+    parse_hit,
+)
+
+DEFAULT_BASE = "https://api.filingstudio.com"
+
+
+def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+def _describe(status: int, body: Any) -> "tuple[str, Optional[str]]":
+    err = body.get("error") if isinstance(body, dict) else None
+    if isinstance(err, str):
+        return err, None
+    if isinstance(err, dict):
+        msg = err.get("message") if isinstance(err.get("message"), str) else f"HTTP {status}"
+        code = err.get("code") if isinstance(err.get("code"), str) else None
+        return msg, code
+    return f"HTTP {status}", None
+
+
+def _raise_for(status: int, body: Any) -> None:
+    """Map a non-2xx answer to an exception. Never touches the key."""
+    if status == 429:
+        st = body.get("indexState") if isinstance(body, dict) else None
+        index_state = IndexState.model_validate(st) if isinstance(st, dict) else IndexState(
+            coverage="unavailable", note=_describe(429, body)[0]
+        )
+        raise RateLimitError(index_state, body)
+    msg, code = _describe(status, body)
+    raise FilingStudioError(status, msg, code, body)
+
+
+class _Base:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        key = (api_key or "").strip()
+        if not key:
+            raise NotConfigured()
+        self._key = key
+        self._base = (base_url or DEFAULT_BASE).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max(0, int(max_retries))
+
+    def _headers(self, json_body: bool) -> Dict[str, str]:
+        h = {"X-API-Key": self._key, "Accept": "application/json"}
+        if json_body:
+            h["Content-Type"] = "application/json"
+        return h
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}{path}"
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return 0.2 * (2 ** (attempt - 1)) + random.random() * 0.1
+
+    @staticmethod
+    def _parse(res: httpx.Response) -> Any:
+        try:
+            return res.json()
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _unreachable(exc: Optional[BaseException]) -> FilingStudioError:
+        reason = type(exc).__name__ if exc else "network error"
+        return FilingStudioError(0, f"Filing Studio could not be reached ({reason}).", "unreachable")
+
+    # ---- result shaping, shared by sync and async ---------------------------
+
+    @staticmethod
+    def _search(body: Any, default_type: str) -> SearchResult:
+        env = body if isinstance(body, dict) else {}
+        data = env.get("data") or {}
+        return SearchResult(
+            type=data.get("type") or default_type,
+            results=[parse_hit(h) for h in (data.get("results") or [])],
+            indexState=env.get("indexState") or {},
+            pagination=env.get("pagination"),
+            note=env.get("note"),
+        )
+
+    @staticmethod
+    def _verify(body: Any) -> VerifyResult:
+        env = body if isinstance(body, dict) else {}
+        data = dict(env.get("data") or {})
+        data["indexState"] = env.get("indexState") or {}
+        return VerifyResult.model_validate(data)
+
+    @staticmethod
+    def _trace(body: Any) -> Optional[TraceDetail]:
+        env = body if isinstance(body, dict) else {}
+        traces = (env.get("data") or {}).get("traces") or []
+        return TraceDetail.model_validate(traces[0]) if traces else None
+
+    @staticmethod
+    def _filings(body: Any, ticker: str) -> FilingsResult:
+        env = body if isinstance(body, dict) else {}
+        data = env.get("data") or {}
+        return FilingsResult(
+            ticker=data.get("ticker") or ticker,
+            filings=data.get("filings") or [],
+            indexState=env.get("indexState") or {},
+            pagination=env.get("pagination"),
+            note=env.get("note"),
+        )
+
+    @staticmethod
+    def _coverage(body: Any, ticker: str) -> CoverageResult:
+        env = body if isinstance(body, dict) else {}
+        data = dict(env.get("data") or {})
+        data.setdefault("ticker", ticker)
+        data["note"] = env.get("note")
+        return CoverageResult.model_validate(data)
+
+    @staticmethod
+    def _table(body: Any) -> TableResult:
+        env = body if isinstance(body, dict) else {}
+        return TableResult(
+            data=env.get("data") or {},
+            provenance=env.get("provenance") or {},
+            links=env.get("links") or {},
+        )
+
+    # ---- paths ----------------------------------------------------------------
+
+    @staticmethod
+    def _search_params(ticker, q, type, period, forms, limit, offset) -> Dict[str, Any]:
+        return _clean({"ticker": ticker.upper(), "q": q, "type": type, "period": period,
+                       "forms": forms, "limit": limit, "offset": offset})
+
+    @staticmethod
+    def _trace_path(trace_id: str, include_context: bool) -> str:
+        return f"/v1/trace/{quote(trace_id, safe='')}" + ("?include=context" if include_context else "")
+
+    @staticmethod
+    def _table_path(ticker: str, accession: str, table_id: str) -> str:
+        return (f"/v1/tables/{quote(ticker.upper(), safe='')}/{quote(accession, safe='')}/"
+                f"{quote(table_id, safe='')}")
+
+
+class FilingStudio(_Base):
+    """Synchronous client. Use as a context manager to reuse one connection."""
+
+    def __init__(self, api_key: Optional[str], *, base_url: Optional[str] = None,
+                 timeout: float = 30.0, max_retries: int = 2,
+                 transport: Optional[httpx.BaseTransport] = None) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self._http = httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FilingStudio":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                 json: Any = None) -> Any:
+        last: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            if attempt:
+                time.sleep(self._backoff(attempt))
+            try:
+                res = self._http.request(method, self._url(path), params=params, json=json,
+                                         headers=self._headers(json is not None))
+            except httpx.TransportError as exc:
+                last = exc
+                continue
+            body = self._parse(res)
+            if res.is_success:
+                return body if body is not None else {}
+            if res.status_code >= 500:
+                last = FilingStudioError(res.status_code, _describe(res.status_code, body)[0], None, body)
+                continue
+            _raise_for(res.status_code, body)
+        if isinstance(last, FilingStudioError):
+            raise last
+        raise self._unreachable(last)
+
+    def search(self, ticker: str, q: str, *, type: Optional[str] = None, period: Optional[str] = None,
+               forms: Optional[str] = None, limit: Optional[int] = None,
+               offset: Optional[int] = None) -> SearchResult:
+        """Search a company's printed rows, tables, and prose by plain words."""
+        body = self._request("GET", "/v1/search",
+                             params=self._search_params(ticker, q, type, period, forms, limit, offset))
+        return self._search(body, type or "all")
+
+    def verify(self, ticker: str, *, metric: Optional[str] = None, value: Optional[float] = None,
+               period: Optional[str] = None, claim: Optional[str] = None) -> VerifyResult:
+        """Check a claim against what the filings print. Deterministic."""
+        payload = _clean({"ticker": ticker.upper(), "metric": metric, "value": value,
+                          "period": period, "claim": claim})
+        return self._verify(self._request("POST", "/v1/verify", json=payload))
+
+    def trace(self, trace_id: str, *, include_context: bool = True) -> Optional[TraceDetail]:
+        """Resolve a traceId to the exact printed line, with neighbouring rows."""
+        return self._trace(self._request("GET", self._trace_path(trace_id, include_context)))
+
+    def filings(self, ticker: str, *, form: Optional[str] = None, year: Optional[str] = None,
+                limit: Optional[int] = None) -> FilingsResult:
+        """A company's indexed filings."""
+        t = ticker.upper()
+        body = self._request("GET", f"/v1/filings/{quote(t, safe='')}",
+                             params=_clean({"form": form, "year": year, "limit": limit}))
+        return self._filings(body, t)
+
+    def coverage(self, ticker: str) -> CoverageResult:
+        """Is there anything indexed for this ticker, and how fresh?"""
+        t = ticker.upper()
+        return self._coverage(self._request("GET", "/v1/coverage", params={"ticker": t}), t)
+
+    def table(self, ticker: str, accession: str, table_id: str, *, format: str = "records") -> TableResult:
+        """One printed table, as filed: heading, row order, period headers, traces."""
+        return self._table(self._request("GET", self._table_path(ticker, accession, table_id),
+                                         params={"format": format}))
+
+
+class AsyncFilingStudio(_Base):
+    """Asynchronous client with the same methods."""
+
+    def __init__(self, api_key: Optional[str], *, base_url: Optional[str] = None,
+                 timeout: float = 30.0, max_retries: int = 2,
+                 transport: Optional[httpx.AsyncBaseTransport] = None) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncFilingStudio":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                       json: Any = None) -> Any:
+        last: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            if attempt:
+                await anyio.sleep(self._backoff(attempt))
+            try:
+                res = await self._http.request(method, self._url(path), params=params, json=json,
+                                               headers=self._headers(json is not None))
+            except httpx.TransportError as exc:
+                last = exc
+                continue
+            body = self._parse(res)
+            if res.is_success:
+                return body if body is not None else {}
+            if res.status_code >= 500:
+                last = FilingStudioError(res.status_code, _describe(res.status_code, body)[0], None, body)
+                continue
+            _raise_for(res.status_code, body)
+        if isinstance(last, FilingStudioError):
+            raise last
+        raise self._unreachable(last)
+
+    async def search(self, ticker: str, q: str, *, type: Optional[str] = None,
+                     period: Optional[str] = None, forms: Optional[str] = None,
+                     limit: Optional[int] = None, offset: Optional[int] = None) -> SearchResult:
+        body = await self._request("GET", "/v1/search",
+                                   params=self._search_params(ticker, q, type, period, forms, limit, offset))
+        return self._search(body, type or "all")
+
+    async def verify(self, ticker: str, *, metric: Optional[str] = None, value: Optional[float] = None,
+                     period: Optional[str] = None, claim: Optional[str] = None) -> VerifyResult:
+        payload = _clean({"ticker": ticker.upper(), "metric": metric, "value": value,
+                          "period": period, "claim": claim})
+        return self._verify(await self._request("POST", "/v1/verify", json=payload))
+
+    async def trace(self, trace_id: str, *, include_context: bool = True) -> Optional[TraceDetail]:
+        return self._trace(await self._request("GET", self._trace_path(trace_id, include_context)))
+
+    async def filings(self, ticker: str, *, form: Optional[str] = None, year: Optional[str] = None,
+                      limit: Optional[int] = None) -> FilingsResult:
+        t = ticker.upper()
+        body = await self._request("GET", f"/v1/filings/{quote(t, safe='')}",
+                                   params=_clean({"form": form, "year": year, "limit": limit}))
+        return self._filings(body, t)
+
+    async def coverage(self, ticker: str) -> CoverageResult:
+        t = ticker.upper()
+        return self._coverage(await self._request("GET", "/v1/coverage", params={"ticker": t}), t)
+
+    async def table(self, ticker: str, accession: str, table_id: str, *,
+                    format: str = "records") -> TableResult:
+        return self._table(await self._request("GET", self._table_path(ticker, accession, table_id),
+                                               params={"format": format}))

filingstudio-0.4.0/filingstudio/errors.py

@@ -0,0 +1,38 @@
+"""Errors. None of them ever carries the API key: it travels in a header, and
+messages are built from the status and the API's own error body only."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .models import IndexState
+
+
+class FilingStudioError(Exception):
+    """Any non-2xx answer (or an unreachable API, status 0)."""
+
+    def __init__(self, status: int, message: str, code: Optional[str] = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return f"{self.message} (HTTP {self.status})" if self.status else self.message
+
+
+class RateLimitError(FilingStudioError):
+    """429: the daily limit is spent. `index_state.note` is the honest sentence
+    to show a user: it says nothing about what the filings contain."""
+
+    def __init__(self, index_state: IndexState, body: Any = None) -> None:
+        super().__init__(429, index_state.note or "Daily request limit reached.", "rate_limited", body)
+        self.index_state = index_state
+
+
+class NotConfigured(FilingStudioError):
+    """No API key was given."""
+
+    def __init__(self) -> None:
+        super().__init__(0, "FilingStudio requires an api_key.", "not_configured")