filingstudio 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: filingstudio
-Version: 0.5.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
@@ -84,6 +84,13 @@ async with AsyncFilingStudio(api_key=key) as fs:
 | `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.5.0 → filingstudio-0.6.0}/README.md

@@ -51,6 +51,13 @@ async with AsyncFilingStudio(api_key=key) as fs:
 | `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.5.0 → filingstudio-0.6.0}/filingstudio/__init__.py

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

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

@@ -1,8 +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`,
-plus three research doors (kpi_tables, kpi_series, statement) that answer
-the research JSON as a plain dict.
+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"])
@@ -19,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
@@ -195,6 +196,25 @@ class _Base:
     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:
@@ -220,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:
@@ -232,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
@@ -243,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:
@@ -299,6 +324,46 @@ class FilingStudio(_Base):
         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."""
@@ -318,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:
@@ -330,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
@@ -341,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:
@@ -385,3 +455,33 @@ class AsyncFilingStudio(_Base):
                         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.5.0 → filingstudio-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "filingstudio"
-version = "0.5.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.5.0 → filingstudio-0.6.0}/tests/test_client.py

@@ -251,3 +251,67 @@ async def test_async_research_doors():
         "/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"