filingstudio 0.4.0__tar.gz → 0.6.0__tar.gz

{filingstudio-0.4.0 → filingstudio-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: filingstudio
-Version: 0.4.0
+Version: 0.6.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
@@ -81,6 +81,16 @@ async with AsyncFilingStudio(api_key=key) as fs:
 | `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 |
+| `kpi_tables(ticker, quarterly=False)` | the newest 10-K's (10-Q's) non-statement tables, as a dict |
+| `kpi_series(ticker, table_id, quarterly=False, years=10)` | one table across filings as rows x periods, as a dict |
+| `statement(ticker, kind, quarterly=False, years=10)` | `income`, `balance` or `cashflow` as a time series, as a dict |
+| `filing_html(ticker, accession)` | the whole filing as sanitized HTML (str) |
+| `filing_tables(ticker, accession)` | every printed table in the filing (list) |
+| `exhibits(ticker, accession)` | the exhibits that carry tables (list) |
+| `similar(ticker, accession, table_id, targets)` | the same table in other filings (list) |
+| `table_xlsx(ticker, accession, table_id)` | one printed table as an Excel file (bytes) |
+| `compare_targets(ticker, accession)` | older same-form filings to compare against (list) |
+| `compare_html(ticker, accession, target=None)` | a word-level redline against an older filing (str) |
 
 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.

{filingstudio-0.4.0 → filingstudio-0.6.0}/README.md

@@ -48,6 +48,16 @@ async with AsyncFilingStudio(api_key=key) as fs:
 | `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 |
+| `kpi_tables(ticker, quarterly=False)` | the newest 10-K's (10-Q's) non-statement tables, as a dict |
+| `kpi_series(ticker, table_id, quarterly=False, years=10)` | one table across filings as rows x periods, as a dict |
+| `statement(ticker, kind, quarterly=False, years=10)` | `income`, `balance` or `cashflow` as a time series, as a dict |
+| `filing_html(ticker, accession)` | the whole filing as sanitized HTML (str) |
+| `filing_tables(ticker, accession)` | every printed table in the filing (list) |
+| `exhibits(ticker, accession)` | the exhibits that carry tables (list) |
+| `similar(ticker, accession, table_id, targets)` | the same table in other filings (list) |
+| `table_xlsx(ticker, accession, table_id)` | one printed table as an Excel file (bytes) |
+| `compare_targets(ticker, accession)` | older same-form filings to compare against (list) |
+| `compare_html(ticker, accession, target=None)` | a word-level redline against an older filing (str) |
 
 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.

{filingstudio-0.4.0 → filingstudio-0.6.0}/filingstudio/__init__.py

@@ -21,7 +21,7 @@ from .models import (
     VerifyResult,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"
 __all__ = [
     "AsyncFilingStudio",
     "ContextRow",

{filingstudio-0.4.0 → filingstudio-0.6.0}/filingstudio/client.py

@@ -1,6 +1,9 @@
 """
 The Filing Studio client, sync and async. One method per /v1 door, the same
-names as the Node `@filingstudio/client` and the browser `ProvenanceClient`.
+names as the Node `@filingstudio/client` and the browser `ProvenanceClient`,
+plus research doors (kpi_tables, kpi_series, statement) and reader doors
+(filing_html, filing_tables, exhibits, similar, table_xlsx, compare_targets,
+compare_html) that answer plain dicts, lists, text, or bytes.
 
     from filingstudio import FilingStudio
     fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])
@@ -17,7 +20,7 @@ from __future__ import annotations
 
 import random
 import time
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Sequence
 from urllib.parse import quote
 
 import anyio
@@ -36,6 +39,7 @@ from .models import (
 )
 
 DEFAULT_BASE = "https://api.filingstudio.com"
+STATEMENT_KINDS = ("income", "balance", "cashflow")
 
 
 def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
@@ -50,6 +54,9 @@ def _describe(status: int, body: Any) -> "tuple[str, Optional[str]]":
         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
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(detail, str):
+        return detail, None
     return f"HTTP {status}", None
 
 
@@ -179,6 +186,41 @@ class _Base:
         return (f"/v1/tables/{quote(ticker.upper(), safe='')}/{quote(accession, safe='')}/"
                 f"{quote(table_id, safe='')}")
 
+    # The research doors answer the raw research JSON, not the /v1 envelope.
+
+    @staticmethod
+    def _kpi_tables_path(ticker: str) -> str:
+        return f"/api/research/kpi/tables/{quote(ticker.upper(), safe='')}"
+
+    @staticmethod
+    def _kpi_series_path(ticker: str) -> str:
+        return f"/api/research/kpi/series/{quote(ticker.upper(), safe='')}"
+
+    @staticmethod
+    def _filing_path(ticker: str, accession: str) -> str:
+        return f"/{quote(ticker.upper(), safe='')}/{quote(accession, safe='')}"
+
+    @staticmethod
+    def _data_list(body: Any, key: str) -> List[Dict[str, Any]]:
+        env = body if isinstance(body, dict) else {}
+        data = env["data"] if isinstance(env.get("data"), dict) else env
+        out = data.get(key) or []
+        return [x for x in out if isinstance(x, dict)] if isinstance(out, list) else []
+
+    @staticmethod
+    def _similar(body: Any) -> List[Dict[str, Any]]:
+        env = body if isinstance(body, dict) else {}
+        data = env["data"] if isinstance(env.get("data"), dict) else env
+        hits = data.get("targets") or data.get("results") or []
+        return [{**h, "tableId": h.get("tableId", h.get("table_id"))}
+                for h in hits if isinstance(h, dict) and h.get("accession")]
+
+    @staticmethod
+    def _statement_path(ticker: str, kind: str) -> str:
+        if kind not in STATEMENT_KINDS:
+            raise ValueError(f"kind is one of {', '.join(STATEMENT_KINDS)}")
+        return f"/api/research/statements/{quote(ticker.upper(), safe='')}/{kind}"
+
 
 class FilingStudio(_Base):
     """Synchronous client. Use as a context manager to reuse one connection."""
@@ -198,8 +240,8 @@ class FilingStudio(_Base):
     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:
+    def _send(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+              json: Any = None) -> httpx.Response:
         last: Optional[BaseException] = None
         for attempt in range(self._max_retries + 1):
             if attempt:
@@ -210,9 +252,9 @@ class FilingStudio(_Base):
             except httpx.TransportError as exc:
                 last = exc
                 continue
-            body = self._parse(res)
             if res.is_success:
-                return body if body is not None else {}
+                return res
+            body = self._parse(res)
             if res.status_code >= 500:
                 last = FilingStudioError(res.status_code, _describe(res.status_code, body)[0], None, body)
                 continue
@@ -221,6 +263,11 @@ class FilingStudio(_Base):
             raise last
         raise self._unreachable(last)
 
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                 json: Any = None) -> Any:
+        body = self._parse(self._send(method, path, params=params, json=json))
+        return body if body is not None else {}
+
     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:
@@ -258,6 +305,65 @@ class FilingStudio(_Base):
         return self._table(self._request("GET", self._table_path(ticker, accession, table_id),
                                          params={"format": format}))
 
+    def kpi_tables(self, ticker: str, *, quarterly: bool = False) -> Dict[str, Any]:
+        """The newest 10-K's (10-Q's) non-statement tables, named by the text above them:
+        {ticker, accession, form, filed, tables}."""
+        return self._request("GET", self._kpi_tables_path(ticker), params={"quarterly": quarterly})
+
+    def kpi_series(self, ticker: str, table_id: str, *, quarterly: bool = False,
+                   years: int = 10) -> Dict[str, Any]:
+        """One printed table carried across filings as rows x periods, every value traced:
+        {ticker, tableId, above, units, periods, sources, rows, gaps}."""
+        return self._request("GET", self._kpi_series_path(ticker),
+                             params={"table_id": table_id, "quarterly": quarterly, "years": years})
+
+    def statement(self, ticker: str, kind: str, *, quarterly: bool = False,
+                  years: int = 10) -> Dict[str, Any]:
+        """A primary statement (income, balance, cashflow) as a time series from each
+        filing's printed table. No model."""
+        return self._request("GET", self._statement_path(ticker, kind),
+                             params={"quarterly": quarterly, "years": years})
+
+    # ---- the reader: one filing, its documents and tables ----------------------
+
+    def filing_html(self, ticker: str, accession: str) -> str:
+        """The whole filing as sanitized HTML, ready for an iframe."""
+        return self._send("GET", f"/api/filings{self._filing_path(ticker, accession)}/html").text
+
+    def filing_tables(self, ticker: str, accession: str) -> List[Dict[str, Any]]:
+        """Every printed table in one filing: id, heading, size, periods."""
+        return self._data_list(
+            self._request("GET", f"/v1/filings{self._filing_path(ticker, accession)}/tables"), "tables")
+
+    def exhibits(self, ticker: str, accession: str) -> List[Dict[str, Any]]:
+        """The filing's exhibits that carry tables, with their table ids."""
+        return self._data_list(
+            self._request("GET", f"/v1/filings{self._filing_path(ticker, accession)}/exhibits"), "exhibits")
+
+    def similar(self, ticker: str, accession: str, table_id: str,
+                targets: Sequence[str]) -> List[Dict[str, Any]]:
+        """The same printed table in other filings (target accessions). One entry per
+        target: `tableId` is None where nothing matched, `matchedBy` and `why` say how it did."""
+        if not targets:
+            return []
+        return self._similar(self._request("GET", self._table_path(ticker, accession, table_id) + "/same-in",
+                                           params={"targets": ",".join(targets)}))
+
+    def table_xlsx(self, ticker: str, accession: str, table_id: str) -> bytes:
+        """One printed table as an Excel workbook."""
+        return self._send("GET", self._table_path(ticker, accession, table_id) + "/xlsx").content
+
+    def compare_targets(self, ticker: str, accession: str) -> List[Dict[str, Any]]:
+        """Older filings of the same form this one can be compared against, newest first."""
+        return self._data_list(
+            self._request("GET", f"/api/filings{self._filing_path(ticker, accession)}/compare-targets"), "targets")
+
+    def compare_html(self, ticker: str, accession: str, target: Optional[str] = None) -> str:
+        """A word-level redline of this filing against `target` (default: the prior
+        filing of the same form), as HTML."""
+        return self._send("GET", f"/api/filings{self._filing_path(ticker, accession)}/compare-filing",
+                          params=_clean({"target": target})).text
+
 
 class AsyncFilingStudio(_Base):
     """Asynchronous client with the same methods."""
@@ -277,8 +383,8 @@ class AsyncFilingStudio(_Base):
     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:
+    async def _send(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                    json: Any = None) -> httpx.Response:
         last: Optional[BaseException] = None
         for attempt in range(self._max_retries + 1):
             if attempt:
@@ -289,9 +395,9 @@ class AsyncFilingStudio(_Base):
             except httpx.TransportError as exc:
                 last = exc
                 continue
-            body = self._parse(res)
             if res.is_success:
-                return body if body is not None else {}
+                return res
+            body = self._parse(res)
             if res.status_code >= 500:
                 last = FilingStudioError(res.status_code, _describe(res.status_code, body)[0], None, body)
                 continue
@@ -300,6 +406,11 @@ class AsyncFilingStudio(_Base):
             raise last
         raise self._unreachable(last)
 
+    async def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                       json: Any = None) -> Any:
+        body = self._parse(await self._send(method, path, params=params, json=json))
+        return body if body is not None else {}
+
     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:
@@ -331,3 +442,46 @@ class AsyncFilingStudio(_Base):
                     format: str = "records") -> TableResult:
         return self._table(await self._request("GET", self._table_path(ticker, accession, table_id),
                                                params={"format": format}))
+
+    async def kpi_tables(self, ticker: str, *, quarterly: bool = False) -> Dict[str, Any]:
+        return await self._request("GET", self._kpi_tables_path(ticker), params={"quarterly": quarterly})
+
+    async def kpi_series(self, ticker: str, table_id: str, *, quarterly: bool = False,
+                         years: int = 10) -> Dict[str, Any]:
+        return await self._request("GET", self._kpi_series_path(ticker),
+                                   params={"table_id": table_id, "quarterly": quarterly, "years": years})
+
+    async def statement(self, ticker: str, kind: str, *, quarterly: bool = False,
+                        years: int = 10) -> Dict[str, Any]:
+        return await self._request("GET", self._statement_path(ticker, kind),
+                                   params={"quarterly": quarterly, "years": years})
+
+    async def filing_html(self, ticker: str, accession: str) -> str:
+        return (await self._send("GET", f"/api/filings{self._filing_path(ticker, accession)}/html")).text
+
+    async def filing_tables(self, ticker: str, accession: str) -> List[Dict[str, Any]]:
+        return self._data_list(
+            await self._request("GET", f"/v1/filings{self._filing_path(ticker, accession)}/tables"), "tables")
+
+    async def exhibits(self, ticker: str, accession: str) -> List[Dict[str, Any]]:
+        return self._data_list(
+            await self._request("GET", f"/v1/filings{self._filing_path(ticker, accession)}/exhibits"), "exhibits")
+
+    async def similar(self, ticker: str, accession: str, table_id: str,
+                      targets: Sequence[str]) -> List[Dict[str, Any]]:
+        if not targets:
+            return []
+        return self._similar(await self._request("GET", self._table_path(ticker, accession, table_id) + "/same-in",
+                                                 params={"targets": ",".join(targets)}))
+
+    async def table_xlsx(self, ticker: str, accession: str, table_id: str) -> bytes:
+        return (await self._send("GET", self._table_path(ticker, accession, table_id) + "/xlsx")).content
+
+    async def compare_targets(self, ticker: str, accession: str) -> List[Dict[str, Any]]:
+        return self._data_list(
+            await self._request("GET", f"/api/filings{self._filing_path(ticker, accession)}/compare-targets"),
+            "targets")
+
+    async def compare_html(self, ticker: str, accession: str, target: Optional[str] = None) -> str:
+        return (await self._send("GET", f"/api/filings{self._filing_path(ticker, accession)}/compare-filing",
+                                 params=_clean({"target": target}))).text

{filingstudio-0.4.0 → filingstudio-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "filingstudio"
-version = "0.4.0"
+version = "0.6.0"
 description = "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."
 readme = "README.md"
 license = { text = "MIT" }

{filingstudio-0.4.0 → filingstudio-0.6.0}/tests/test_client.py

@@ -207,3 +207,111 @@ async def test_async_client_mirrors_sync():
         v = await fs.verify("NVDA", metric="Revenue", value=1)
         assert v.verdict == "unsupported" and v.actual[0].printed_text == "130,497"
         assert seen[-1].headers["x-api-key"] == KEY
+
+
+def test_research_doors_paths_params_and_raw_json():
+    fs, seen = make(lambda r, n: ok({"ticker": "LEN", "tables": [{"tableId": "t1"}]}))
+    assert fs.kpi_tables("len", quarterly=True)["tables"][0]["tableId"] == "t1"
+    fs.kpi_series("len", "primary:83", years=5)
+    fs.statement("len", "cashflow", quarterly=True, years=3)
+    assert [r.url.path for r in seen] == [
+        "/api/research/kpi/tables/LEN",
+        "/api/research/kpi/series/LEN",
+        "/api/research/statements/LEN/cashflow",
+    ]
+    assert dict(seen[0].url.params) == {"quarterly": "true"}
+    assert dict(seen[1].url.params) == {"table_id": "primary:83", "quarterly": "false", "years": "5"}
+    assert dict(seen[2].url.params) == {"quarterly": "true", "years": "3"}
+    assert all(r.headers["x-api-key"] == KEY and KEY not in str(r.url) for r in seen)
+
+
+def test_statement_rejects_unknown_kind_before_calling():
+    fs, seen = make(lambda r, n: ok({}))
+    with pytest.raises(ValueError):
+        fs.statement("LEN", "equity")
+    assert seen == []
+
+
+def test_research_door_404_detail_becomes_the_message():
+    fs, _ = make(lambda r, n: httpx.Response(404, json={"detail": "No 10-K for ZZZZ"}))
+    with pytest.raises(FilingStudioError) as e:
+        fs.kpi_tables("ZZZZ")
+    assert e.value.status == 404
+    assert "No 10-K for ZZZZ" in str(e.value)
+
+
+@pytest.mark.anyio
+async def test_async_research_doors():
+    fs, seen = amake(lambda r, n: ok({"rows": []}))
+    assert await fs.statement("nvda", "income") == {"rows": []}
+    await fs.kpi_series("nvda", "t9")
+    await fs.kpi_tables("nvda")
+    assert [r.url.path for r in seen] == [
+        "/api/research/statements/NVDA/income",
+        "/api/research/kpi/series/NVDA",
+        "/api/research/kpi/tables/NVDA",
+    ]
+
+
+ACC = "0000882184-26-000123"
+
+
+def test_reader_doors_paths_and_shapes():
+    def h(r, n):
+        p = r.url.path
+        if p.endswith("/html") or p.endswith("/compare-filing"):
+            return httpx.Response(200, text="<html>filing</html>", headers={"content-type": "text/html"})
+        if p.endswith("/xlsx"):
+            return httpx.Response(200, content=b"PK\x03\x04")
+        if p.endswith("/tables"):
+            return ok({"data": {"tables": [{"id": "primary:1"}]}})
+        if p.endswith("/exhibits"):
+            return ok({"exhibits": [{"exhibit": "EX-99.1", "tableIds": ["exhibit:3"]}]})
+        if p.endswith("/same-in"):
+            return ok({"data": {"targets": [{"accession": "A1", "table_id": "primary:9"}, {"accession": "A2"}]}})
+        if p.endswith("/compare-targets"):
+            return ok({"targets": [{"accession": "A1"}]})
+        return httpx.Response(404, json={"detail": "nope"})
+
+    fs, seen = make(h)
+    assert fs.filing_html("dhi", ACC) == "<html>filing</html>"
+    assert fs.filing_tables("dhi", ACC) == [{"id": "primary:1"}]
+    assert fs.exhibits("dhi", ACC)[0]["exhibit"] == "EX-99.1"
+    hits = fs.similar("dhi", ACC, "primary:1", ["A1", "A2"])
+    assert [(x["accession"], x["tableId"]) for x in hits] == [("A1", "primary:9"), ("A2", None)]
+    assert fs.table_xlsx("dhi", ACC, "primary:1") == b"PK\x03\x04"
+    assert fs.compare_targets("dhi", ACC) == [{"accession": "A1"}]
+    assert fs.compare_html("dhi", ACC, target="A1") == "<html>filing</html>"
+    assert fs.similar("dhi", ACC, "primary:1", []) == []
+    paths = [r.url.path for r in seen]
+    assert paths == [
+        f"/api/filings/DHI/{ACC}/html",
+        f"/v1/filings/DHI/{ACC}/tables",
+        f"/v1/filings/DHI/{ACC}/exhibits",
+        f"/v1/tables/DHI/{ACC}/primary:1/same-in",
+        f"/v1/tables/DHI/{ACC}/primary:1/xlsx",
+        f"/api/filings/DHI/{ACC}/compare-targets",
+        f"/api/filings/DHI/{ACC}/compare-filing",
+    ]
+    assert dict(seen[3].url.params) == {"targets": "A1,A2"}
+    assert dict(seen[6].url.params) == {"target": "A1"}
+    assert all(r.headers["x-api-key"] == KEY and KEY not in str(r.url) for r in seen)
+
+
+def test_filing_html_404_raises():
+    fs, _ = make(lambda r, n: httpx.Response(404, json={"detail": "Filing not available"}))
+    with pytest.raises(FilingStudioError) as e:
+        fs.filing_html("DHI", ACC)
+    assert e.value.message == "Filing not available"
+
+
+@pytest.mark.anyio
+async def test_async_reader_doors():
+    def h(r, n):
+        if r.url.path.endswith("/html"):
+            return httpx.Response(200, text="<p>x</p>")
+        return ok({"data": {"targets": [{"accession": "A1", "tableId": "primary:2"}]}})
+
+    fs, seen = amake(h)
+    assert await fs.filing_html("dhi", ACC) == "<p>x</p>"
+    assert (await fs.similar("dhi", ACC, "primary:1", ["A1"]))[0]["tableId"] == "primary:2"