bloklake 0.1.0__tar.gz

bloklake-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.mypy_cache/

bloklake-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bloklake
+
+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.

bloklake-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: bloklake
+Version: 0.1.0
+Summary: Bloklake API client: typed queries, Apache Arrow transport, JSON-like rows.
+Project-URL: Documentation, https://docs.bloklake.com
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pyarrow>=14
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bloklake
+
+The official Python client for the [Bloklake](https://docs.bloklake.com) API.
+
+- **Typed queries**: filters, field names and rows are `TypedDict`s and `Literal`s, so your
+  editor and mypy catch a misspelled field.
+- **Arrow on the wire, JSON-like rows in your code**: responses travel as Apache Arrow (about
+  2–2.5× smaller than JSON, so cheaper) and are decoded here into plain dicts with the same
+  values `/query/json` returns.
+- **Pagination, retries and integrity built in**: follows `next_block`, reuses prepared
+  queries, retries rate limits and busy servers, and refuses truncated responses.
+
+```bash
+pip install bloklake
+```
+
+Python 3.9+. Depends on `pyarrow` and `requests`.
+
+## Quick start
+
+```python
+from bloklake import Bloklake
+
+bl = Bloklake(chain="eth")  # API key from BLOKLAKE_API_KEY
+
+page = bl.query({
+    "from_block": 19_426_000,
+    "to_block": 19_426_009,
+    "logs": [{
+        "address": ["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],
+        "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"],
+    }],
+    "fields": {"log": ["block_number", "transaction_hash", "topic1", "topic2", "data"]},
+})
+
+for log in page.logs:
+    print(log["block_number"], log["data"])
+print(page.meta.next_block)
+```
+
+Write the query in snake_case, as above, or in the API's camelCase (`"fromBlock"`,
+`"blockNumber"`, as in the HTTP API and curl examples); the client sends camelCase either way.
+Give each key one way only. Rows always come back in snake_case (`log["block_number"]`).
+
+## Reading a whole range
+
+`paginate` follows `next_block` until `to_block` (or the chain head when you leave `to_block`
+out). After the first page it sends only the prepared-query id, and falls back to the full
+query if the id expired.
+
+```python
+for page in bl.paginate({
+    "from_block": 19_000_000,
+    "to_block": 19_100_000,
+    "logs": [{"topic0": [TRANSFER]}],
+    "fields": {"log": ["block_number", "address", "topic1", "topic2", "data"]},
+}):
+    store(page.logs)
+```
+
+`collect(query)` returns all pages merged into one `Page`. Use it for ranges that fit in memory.
+
+## Results
+
+A `Page` has `logs`, `transactions` and `blocks` lists (empty when not requested) and `meta`
+(`from_block`, `to_block`, `next_block`, `objects`, `archive_height`, `finalized_block`,
+`to_block_hash`, `query_id`, `unavailable_fields`).
+
+Rows use the API's column names (`block_number`, `transaction_hash`) and its JSON encoding:
+
+| Field kind | Value |
+|---|---|
+| block numbers, indexes, gas, timestamps | `int` |
+| amounts (`value`, gas prices, fees, uint256) | decimal `str` (`int(x)` to compute) |
+| hashes, addresses, topics, `input`, `data` | `0x` hex `str` |
+| `withdrawals`, `access_list`, `authorization_list` | lists of dicts |
+| not available or not applicable | `None` |
+
+To get a dataframe: `pandas.DataFrame(page.logs)` or `polars.DataFrame(page.logs)`. If you'd
+rather keep the raw Arrow columns, use the API directly as shown in
+[Reading Arrow](https://docs.bloklake.com/responses/reading-arrow).
+
+## Other calls
+
+```python
+s = bl.create_set("address", pools)                    # idempotent: same values, same id
+bl.query({"logs": [{"address_set": s.set_id, "topic0": [SWAP]}], "fields": {"log": ["address", "data"]}})
+bl.get_set(s.set_id)
+bl.delete_set(s.set_id)
+
+bl.prepare({"logs": [...], "fields": {...}})  # Prepared(query_id, expires_in)
+bl.status()   # ChainStatus(chain_id, first_block, archive_height, finalized_block), free
+bl.schema()   # every field and whether this chain has it, free
+bl.account()  # plan, rps, balance or usage, free
+```
+
+## Errors
+
+Failures raise `BloklakeError` with `status` (0 for client-side failures), `code`
+(`invalid_query`, `rate_limited`, `balance_exhausted`, `truncated`, …), `retry_after` and
+`request_id`. The client retries `429`, `503`, `5xx`, network errors and truncated responses
+itself, up to `max_retries` (default 4), honoring `Retry-After`. Other errors need a fix and are
+raised at once. See [Errors](https://docs.bloklake.com/api-reference/errors).
+
+```python
+from bloklake import BloklakeError
+
+try:
+    bl.query(q)
+except BloklakeError as e:
+    if e.code == "balance_exhausted":
+        alert_someone()
+    else:
+        raise
+```
+
+## Options
+
+```python
+Bloklake(
+    api_key="bl_live_…",    # default: BLOKLAKE_API_KEY
+    chain="rh",             # or base_url="https://api.bloklake.com/v1/chains/rh"
+    max_retries=4,
+    timeout=120.0,
+    session=requests.Session(),  # proxies, custom adapters, tests
+)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # unit and fixture tests
+mypy src/bloklake   # strict
+BLOKLAKE_TEST_URL=https://api.bloklake.com/v1/chains/eth BLOKLAKE_API_KEY=… pytest   # plus live tests
+python scripts/generate.py   # regenerate src/bloklake/fields.py after updating scripts/schema.json
+```
+
+The fixture tests decode recorded Arrow responses and compare them with the server's own
+`/query/json` output for the same requests, field by field.
+
+## License
+
+MIT

bloklake-0.1.0/README.md

@@ -0,0 +1,144 @@
+# bloklake
+
+The official Python client for the [Bloklake](https://docs.bloklake.com) API.
+
+- **Typed queries**: filters, field names and rows are `TypedDict`s and `Literal`s, so your
+  editor and mypy catch a misspelled field.
+- **Arrow on the wire, JSON-like rows in your code**: responses travel as Apache Arrow (about
+  2–2.5× smaller than JSON, so cheaper) and are decoded here into plain dicts with the same
+  values `/query/json` returns.
+- **Pagination, retries and integrity built in**: follows `next_block`, reuses prepared
+  queries, retries rate limits and busy servers, and refuses truncated responses.
+
+```bash
+pip install bloklake
+```
+
+Python 3.9+. Depends on `pyarrow` and `requests`.
+
+## Quick start
+
+```python
+from bloklake import Bloklake
+
+bl = Bloklake(chain="eth")  # API key from BLOKLAKE_API_KEY
+
+page = bl.query({
+    "from_block": 19_426_000,
+    "to_block": 19_426_009,
+    "logs": [{
+        "address": ["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],
+        "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"],
+    }],
+    "fields": {"log": ["block_number", "transaction_hash", "topic1", "topic2", "data"]},
+})
+
+for log in page.logs:
+    print(log["block_number"], log["data"])
+print(page.meta.next_block)
+```
+
+Write the query in snake_case, as above, or in the API's camelCase (`"fromBlock"`,
+`"blockNumber"`, as in the HTTP API and curl examples); the client sends camelCase either way.
+Give each key one way only. Rows always come back in snake_case (`log["block_number"]`).
+
+## Reading a whole range
+
+`paginate` follows `next_block` until `to_block` (or the chain head when you leave `to_block`
+out). After the first page it sends only the prepared-query id, and falls back to the full
+query if the id expired.
+
+```python
+for page in bl.paginate({
+    "from_block": 19_000_000,
+    "to_block": 19_100_000,
+    "logs": [{"topic0": [TRANSFER]}],
+    "fields": {"log": ["block_number", "address", "topic1", "topic2", "data"]},
+}):
+    store(page.logs)
+```
+
+`collect(query)` returns all pages merged into one `Page`. Use it for ranges that fit in memory.
+
+## Results
+
+A `Page` has `logs`, `transactions` and `blocks` lists (empty when not requested) and `meta`
+(`from_block`, `to_block`, `next_block`, `objects`, `archive_height`, `finalized_block`,
+`to_block_hash`, `query_id`, `unavailable_fields`).
+
+Rows use the API's column names (`block_number`, `transaction_hash`) and its JSON encoding:
+
+| Field kind | Value |
+|---|---|
+| block numbers, indexes, gas, timestamps | `int` |
+| amounts (`value`, gas prices, fees, uint256) | decimal `str` (`int(x)` to compute) |
+| hashes, addresses, topics, `input`, `data` | `0x` hex `str` |
+| `withdrawals`, `access_list`, `authorization_list` | lists of dicts |
+| not available or not applicable | `None` |
+
+To get a dataframe: `pandas.DataFrame(page.logs)` or `polars.DataFrame(page.logs)`. If you'd
+rather keep the raw Arrow columns, use the API directly as shown in
+[Reading Arrow](https://docs.bloklake.com/responses/reading-arrow).
+
+## Other calls
+
+```python
+s = bl.create_set("address", pools)                    # idempotent: same values, same id
+bl.query({"logs": [{"address_set": s.set_id, "topic0": [SWAP]}], "fields": {"log": ["address", "data"]}})
+bl.get_set(s.set_id)
+bl.delete_set(s.set_id)
+
+bl.prepare({"logs": [...], "fields": {...}})  # Prepared(query_id, expires_in)
+bl.status()   # ChainStatus(chain_id, first_block, archive_height, finalized_block), free
+bl.schema()   # every field and whether this chain has it, free
+bl.account()  # plan, rps, balance or usage, free
+```
+
+## Errors
+
+Failures raise `BloklakeError` with `status` (0 for client-side failures), `code`
+(`invalid_query`, `rate_limited`, `balance_exhausted`, `truncated`, …), `retry_after` and
+`request_id`. The client retries `429`, `503`, `5xx`, network errors and truncated responses
+itself, up to `max_retries` (default 4), honoring `Retry-After`. Other errors need a fix and are
+raised at once. See [Errors](https://docs.bloklake.com/api-reference/errors).
+
+```python
+from bloklake import BloklakeError
+
+try:
+    bl.query(q)
+except BloklakeError as e:
+    if e.code == "balance_exhausted":
+        alert_someone()
+    else:
+        raise
+```
+
+## Options
+
+```python
+Bloklake(
+    api_key="bl_live_…",    # default: BLOKLAKE_API_KEY
+    chain="rh",             # or base_url="https://api.bloklake.com/v1/chains/rh"
+    max_retries=4,
+    timeout=120.0,
+    session=requests.Session(),  # proxies, custom adapters, tests
+)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # unit and fixture tests
+mypy src/bloklake   # strict
+BLOKLAKE_TEST_URL=https://api.bloklake.com/v1/chains/eth BLOKLAKE_API_KEY=… pytest   # plus live tests
+python scripts/generate.py   # regenerate src/bloklake/fields.py after updating scripts/schema.json
+```
+
+The fixture tests decode recorded Arrow responses and compare them with the server's own
+`/query/json` output for the same requests, field by field.
+
+## License
+
+MIT

bloklake-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bloklake"
+version = "0.1.0"
+description = "Bloklake API client: typed queries, Apache Arrow transport, JSON-like rows."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["pyarrow>=14", "requests>=2.31"]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.10"]
+
+[project.urls]
+Documentation = "https://docs.bloklake.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bloklake"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["pyarrow", "pyarrow.*"]
+ignore_missing_imports = true

bloklake-0.1.0/scripts/generate.py

@@ -0,0 +1,110 @@
+"""Generate src/bloklake/fields.py from scripts/schema.json (a copy of GET /v1/schema).
+
+Run `python scripts/generate.py` after refreshing schema.json when the API adds fields.
+"""
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+schema = json.loads((ROOT / "scripts" / "schema.json").read_text())
+
+
+def camel_case(name: str) -> str:
+    """``block_number`` -> ``blockNumber``; must match ``bloklake.client._camel``."""
+    return re.sub(r"_([a-z0-9])", lambda m: m.group(1).upper(), name)
+
+
+# Requests may name a field by its column name (``block_number``); the client turns it into the
+# request name. That only works while every request name is its column name in camelCase.
+for rt, fs in schema["row_types"].items():
+    for f in fs:
+        if camel_case(f["name"]) != f["dsl_name"]:
+            raise SystemExit(f'{rt}.{f["name"]}: request name {f["dsl_name"]} is not the column name in camelCase')
+
+# uint256 amounts: 32 bytes like a hash, but decimal strings in JSON (the server's catalogue)
+UINT256 = ["max_refund", "submission_fee_refund", "deposit_value", "retry_value", "max_submission_fee", "l1_base_fee"]
+STRUCT_NAMES = {"withdrawals": "Withdrawal", "access_list": "AccessListEntry", "authorization_list": "Authorization"}
+structs: dict[str, str] = {}
+
+
+def parse(s: str):
+    pos = 0
+
+    def ws():
+        nonlocal pos
+        while pos < len(s) and s[pos] == " ":
+            pos += 1
+
+    def ident():
+        nonlocal pos
+        m = re.match(r"[A-Za-z0-9_]+", s[pos:])
+        pos += len(m.group(0))
+        return m.group(0)
+
+    def typ():
+        nonlocal pos
+        ws()
+        name = ident()
+        if name == "FixedSizeBinary":
+            pos += 1; n = ident(); pos += 1
+            return ("fsb", int(n))
+        if name == "List":
+            pos += 1; t = typ(); pos += 1
+            return ("list", t)
+        if name == "Struct":
+            pos += 1; fields = []
+            while True:
+                ws(); n = ident(); ws(); pos += 1; t = typ(); fields.append((n, t)); ws()
+                if s[pos] == ",":
+                    pos += 1; continue
+                pos += 1; break
+            return ("struct", fields)
+        return ("prim", name)
+
+    return typ()
+
+
+def py_type(t, column: str) -> str:
+    kind = t[0]
+    if kind == "prim":
+        return "int" if t[1].startswith("UInt") else "str"
+    if kind == "fsb":
+        return "str"
+    if kind == "list":
+        return f"List[{py_type(t[1], column)}]"
+    name = STRUCT_NAMES.get(column, f"{column}_entry")
+    if name not in structs:
+        body = ", ".join(f'"{n}": {py_type(ft, n)}' for n, ft in t[1])
+        structs[name] = f'{name} = TypedDict("{name}", {{{body}}})'
+    return name
+
+
+out = ['"""Generated by scripts/generate.py from scripts/schema.json (GET /v1/schema). Do not edit."""',
+       "from typing import FrozenSet, List, Literal, Mapping, Optional, TypedDict", ""]
+rows = []
+for key, field_alias, row in (("logs", "LogField", "Log"), ("transactions", "TransactionField", "Transaction"), ("blocks", "BlockField", "Block")):
+    fields = schema["row_types"][key]
+    names = [f["dsl_name"] for f in fields] + (["topics"] if key == "logs" else [])
+    # The same fields by column name, for snake_case requests (``block_number``).
+    names += [f["name"] for f in fields if f["name"] != f["dsl_name"]]
+    rows.append(f"{field_alias} = Literal[\n" + "".join(f'    "{n}",\n' for n in names) + "]")
+    rows.append(f'"""Field names for `fields.{ {"logs": "log", "transactions": "transaction", "blocks": "block"}[key] }`: '
+                f'the request name (camelCase) or the column name (snake_case)."""')
+    rows.append("")
+    entries = []
+    for f in fields:
+        t = py_type(parse(f["arrow_type"]), f["name"])
+        if f["nullable"]:
+            t = f"Optional[{t}]"
+        entries.append(f'        "{f["name"]}": {t},  # {f["arrow_type"]}')
+    rows.append(f'{row} = TypedDict(\n    "{row}",\n    {{\n' + "\n".join(entries) + "\n    },\n    total=False,\n)")
+    rows.append(f'"""A {key[:-1]} row: keys are present only for the fields you selected."""')
+    rows.append("")
+out += list(structs.values()) + [""] + rows
+out.append("UINT256_COLUMNS: Mapping[str, FrozenSet[str]] = {")
+out.append(f'    "transactions": frozenset({sorted(UINT256)!r}),')
+out.append("}")
+out.append('"""Response keys that hold uint256 amounts (decimal strings), per row type."""')
+(ROOT / "src" / "bloklake" / "fields.py").write_text("\n".join(out) + "\n")
+print("wrote src/bloklake/fields.py")