graphsense-python 2.12.0__tar.gz → 2.13.0__tar.gz

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsense-python
-Version: 2.12.0
+Version: 2.13.0
 Summary: GraphSense API
 Author-email: Iknaio Cryptoasset Analytics GmbH <contact@iknaio.com>
 License-Expression: MIT
@@ -43,22 +43,10 @@ See the [full versioning and deprecation policy](https://github.com/graphsense/g
 for details.
 
 
-## Using the high-level wrapper or CLI
-
-Two hand-written convenience layers ride on top of the generated client
-(both protected from regeneration via `.openapi-generator-ignore`):
-
-- **Python** — [`README_EXT.md`](README_EXT.md) documents
-  `graphsense.ext.GraphSense`, a single facade that removes boilerplate and
-  bundles commonly-paired calls (ships with the base install).
-- **Shell** — [`README_CLI.md`](README_CLI.md) documents the `graphsense` CLI
-  (installed via `uv add 'graphsense-python[cli]'`): pipe-friendly,
-  JSON/CSV I/O, auto-bulk.
-
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
-- API version: 2.12.0
-- Package version: 2.12.0
+- API version: 2.13.0
+- Package version: 2.13.0
 - Generator version: 7.19.0
 - Build package: org.openapitools.codegen.languages.PythonClientCodegen
 For more information, please visit [https://www.iknaio.com/](https://www.iknaio.com/)
@@ -295,3 +283,12 @@ Authentication schemes defined for the API:
 
 contact@iknaio.com
 
+
+## Using the high-level wrapper or CLI
+
+- **Python** — [`README_EXT.md`](README_EXT.md) documents
+  `graphsense.ext.GraphSense`, a single facade that removes boilerplate and
+  bundles commonly-paired calls (ships with the base install).
+- **Shell** — [`README_CLI.md`](README_CLI.md) documents the `graphsense` CLI
+  (installed via `uv add 'graphsense-python[cli]'`): pipe-friendly,
+  JSON/CSV I/O, auto-bulk.

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/README.md

@@ -21,22 +21,10 @@ See the [full versioning and deprecation policy](https://github.com/graphsense/g
 for details.
 
 
-## Using the high-level wrapper or CLI
-
-Two hand-written convenience layers ride on top of the generated client
-(both protected from regeneration via `.openapi-generator-ignore`):
-
-- **Python** — [`README_EXT.md`](README_EXT.md) documents
-  `graphsense.ext.GraphSense`, a single facade that removes boilerplate and
-  bundles commonly-paired calls (ships with the base install).
-- **Shell** — [`README_CLI.md`](README_CLI.md) documents the `graphsense` CLI
-  (installed via `uv add 'graphsense-python[cli]'`): pipe-friendly,
-  JSON/CSV I/O, auto-bulk.
-
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
-- API version: 2.12.0
-- Package version: 2.12.0
+- API version: 2.13.0
+- Package version: 2.13.0
 - Generator version: 7.19.0
 - Build package: org.openapitools.codegen.languages.PythonClientCodegen
 For more information, please visit [https://www.iknaio.com/](https://www.iknaio.com/)
@@ -273,3 +261,12 @@ Authentication schemes defined for the API:
 
 contact@iknaio.com
 
+
+## Using the high-level wrapper or CLI
+
+- **Python** — [`README_EXT.md`](README_EXT.md) documents
+  `graphsense.ext.GraphSense`, a single facade that removes boilerplate and
+  bundles commonly-paired calls (ships with the base install).
+- **Shell** — [`README_CLI.md`](README_CLI.md) documents the `graphsense` CLI
+  (installed via `uv add 'graphsense-python[cli]'`): pipe-friendly,
+  JSON/CSV I/O, auto-bulk.

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/graphsense/__init__.py

@@ -12,7 +12,7 @@
 """
 
 
-__version__ = "2.12.0"
+__version__ = "2.13.0"
 
 # Define package exports
 __all__ = [

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/graphsense/api_client.py

@@ -95,7 +95,7 @@ class ApiClient:
             self.default_headers[header_name] = header_value
         self.cookie = cookie
         # Set default User-Agent.
-        self.user_agent = 'OpenAPI-Generator/2.12.0/python'
+        self.user_agent = 'OpenAPI-Generator/2.13.0/python'
         self.client_side_validation = configuration.client_side_validation
 
     def __enter__(self):

graphsense_python-2.13.0/graphsense/cli/gs.py

@@ -0,0 +1,139 @@
+"""`graphsense gs ...` — read GraphSense `.gs` save files (graph + pathfinder).
+
+The extraction commands `txs` and `addresses` emit a uniform
+`[{"network", "id"}, ...]` shape that feeds directly into `lookup-tx`
+and `lookup-address` via the standard
+`--address-jq '[].id' --network-jq '[].network'` selectors.
+
+Example:
+    graphsense gs txs graph.gs | \\
+        graphsense --address-jq '[].id' --network-jq '[].network' \\
+        lookup-tx btc
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import rich_click as click
+
+from graphsense.cli.context import CliContext
+from graphsense.ext import output as out_mod
+from graphsense.gs_files import (
+    GraphData,
+    PathfinderData,
+    decode_gs,
+    structure,
+    summarize,
+    to_jsonable,
+)
+
+pass_ctx = click.make_pass_decorator(CliContext)
+
+
+def _write(ctx: CliContext, payload: Any) -> None:
+    out_mod.write(
+        payload,
+        output=ctx.output,
+        directory=ctx.directory,
+        format=ctx.format,
+        color=ctx.color,
+    )
+
+
+def _load(file: Path) -> PathfinderData | GraphData:
+    return structure(decode_gs(file))
+
+
+def _dedupe(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Drop duplicate (network, id) pairs, preserving first-seen order."""
+    seen: set[tuple[str, str]] = set()
+    out: list[dict[str, Any]] = []
+    for r in records:
+        key = (str(r["network"]), str(r["id"]))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(r)
+    return out
+
+
+def _txs(data: PathfinderData | GraphData) -> list[dict[str, Any]]:
+    if isinstance(data, PathfinderData):
+        return [{"network": t.id.currency, "id": t.id.id} for t in data.txs]
+    return []
+
+
+def _addresses(data: PathfinderData | GraphData) -> list[dict[str, Any]]:
+    if isinstance(data, PathfinderData):
+        return [{"network": t.id.currency, "id": t.id.id} for t in data.addresses]
+    return [{"network": a.currency, "id": a.address} for a in data.addresses]
+
+
+@click.group(name="gs")
+def gs_group() -> None:
+    """Read GraphSense `.gs` save files (Pathfinder + Graph dashboards)."""
+
+
+@gs_group.command("txs")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--dedupe/--no-dedupe",
+    default=True,
+    help="Drop duplicate (network, id) pairs. Default: on.",
+)
+@pass_ctx
+def txs_cmd(ctx: CliContext, file: Path, dedupe: bool) -> None:
+    """Emit `{network, id}` records for every transaction in FILE.
+
+    Only Pathfinder files contain transactions; for Graph files this emits
+    an empty list.
+    """
+    data = _load(file)
+    records = _txs(data)
+    if dedupe:
+        records = _dedupe(records)
+    _write(ctx, records)
+
+
+@gs_group.command("addresses")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--dedupe/--no-dedupe",
+    default=True,
+    help="Drop duplicate (network, id) pairs. Default: on.",
+)
+@pass_ctx
+def addresses_cmd(ctx: CliContext, file: Path, dedupe: bool) -> None:
+    """Emit `{network, id}` records for every address in FILE."""
+    data = _load(file)
+    records = _addresses(data)
+    if dedupe:
+        records = _dedupe(records)
+    _write(ctx, records)
+
+
+@gs_group.command("decode")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--raw",
+    is_flag=True,
+    default=False,
+    help="Emit the raw decoded JSON instead of the structured view.",
+)
+@pass_ctx
+def decode_cmd(ctx: CliContext, file: Path, raw: bool) -> None:
+    """Decode FILE to JSON (structured by default)."""
+    if raw:
+        _write(ctx, decode_gs(file))
+        return
+    _write(ctx, to_jsonable(structure(decode_gs(file))))
+
+
+@gs_group.command("summary")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@pass_ctx
+def summary_cmd(ctx: CliContext, file: Path) -> None:
+    """Emit a short summary (kind, version, counts) for FILE."""
+    _write(ctx, summarize(_load(file)))

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/graphsense/cli/main.py

@@ -16,6 +16,7 @@ from graphsense.cli.bulk_cmd import bulk_command
 from graphsense.cli.context import CliContext
 from graphsense.cli.convenience import register_convenience_commands
 from graphsense.cli.errors import FriendlyErrorGroup
+from graphsense.cli.gs import gs_group
 from graphsense.cli.raw import build_raw_group
 from graphsense.ext.client import API_KEY_ENV_VARS, HOST_ENV_VARS
 
@@ -206,6 +207,7 @@ def cli(
 register_convenience_commands(cli)
 cli.add_command(bulk_command, name="bulk")
 cli.add_command(build_raw_group(), name="raw")
+cli.add_command(gs_group, name="gs")
 
 
 def main() -> None:  # pragma: no cover - trivial

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/graphsense/configuration.py

@@ -533,8 +533,8 @@ conf = graphsense.Configuration(
         return "Python SDK Debug Report:\n"\
                "OS: {env}\n"\
                "Python Version: {pyversion}\n"\
-               "Version of the API: 2.12.0\n"\
-               "SDK Package Version: 2.12.0".\
+               "Version of the API: 2.13.0\n"\
+               "SDK Package Version: 2.13.0".\
                format(env=sys.platform, pyversion=sys.version)
 
     def get_host_settings(self) -> List[HostSetting]:

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/graphsense/ext/client.py

@@ -280,7 +280,10 @@ class GraphSense:
                 cluster_id = getattr(base, "cluster", None)
                 if cluster_id is not None:
                     jobs["cluster"] = pool.submit(
-                        clusters.get_cluster, ccy, int(cluster_id)
+                        clusters.get_cluster,
+                        ccy,
+                        int(cluster_id),
+                        exclude_best_address_tag=True,
                     )
             results = {k: f.result() for k, f in jobs.items()}
 
@@ -302,7 +305,7 @@ class GraphSense:
         ccy = self._currency(currency)
         clusters = self.raw.clusters
         cid = int(cluster_id)
-        base = clusters.get_cluster(ccy, cid)
+        base = clusters.get_cluster(ccy, cid, exclude_best_address_tag=True)
 
         jobs: dict[str, Any] = {}
         with ThreadPoolExecutor(max_workers=self.max_workers) as pool:

{graphsense_python-2.12.0 → graphsense_python-2.13.0}/graphsense/ext/io.py

@@ -131,27 +131,32 @@ def _extract_from_csv(
     rows = list(reader)
     if not rows:
         return []
-    header, body = rows[0], rows[1:]
-    has_header = _looks_like_header(header)
-    if has_header:
-        if col is None:
-            if len(header) != 1:
+    header = rows[0]
+
+    # Named --col: row 1 is the header, look the name up directly. This
+    # avoids relying on `_looks_like_header` heuristics for the path that
+    # users hit most often.
+    if col is not None:
+        try:
+            idx = int(col)
+        except ValueError:
+            try:
+                idx = header.index(col)
+            except ValueError as exc:
                 raise ValueError(
-                    "CSV has multiple columns; specify --col <name_or_index>"
-                )
-            idx = 0
-        else:
-            idx = _resolve_col_index(col, header)
-        return [_cell(row, idx) for row in body if _row_keep(row, idx, skip_empty)]
-    # No header: treat all rows as data
-    all_rows = [header] + body
-    if col is None:
-        if len(header) != 1:
-            raise ValueError("CSV has multiple columns; specify --col <index>")
-        idx = 0
-    else:
-        idx = _resolve_col_index(col, None)
-    return [_cell(row, idx) for row in all_rows if _row_keep(row, idx, skip_empty)]
+                    f"column {col!r} not found in header {header!r}"
+                ) from exc
+            return [_cell(r, idx) for r in rows[1:] if _row_keep(r, idx, skip_empty)]
+
+        data_rows = rows[1:] if _looks_like_header(header) else rows
+        return [_cell(r, idx) for r in data_rows if _row_keep(r, idx, skip_empty)]
+
+    # No --col: only single-column input is unambiguous.
+    has_header = _looks_like_header(header)
+    if len(header) != 1:
+        raise ValueError("CSV has multiple columns; specify --col <name_or_index>")
+    data_rows = rows[1:] if has_header else rows
+    return [_cell(r, 0) for r in data_rows if _row_keep(r, 0, skip_empty)]
 
 
 def _cell(row: list[str], idx: int) -> str:
@@ -164,35 +169,21 @@ def _row_keep(row: list[str], idx: int, skip_empty: bool) -> bool:
     return True
 
 
-def _resolve_col_index(col: str, header: Optional[list[str]]) -> int:
-    try:
-        return int(col)
-    except ValueError:
-        pass
-    if header is None:
-        raise ValueError(f"column name {col!r} given but CSV has no header")
-    try:
-        return header.index(col)
-    except ValueError as exc:
-        raise ValueError(f"column {col!r} not found in header {header!r}") from exc
-
-
 def _looks_like_header(row: list[str]) -> bool:
     """Treat the first row as a header unless every cell looks like an id."""
     if not row:
         return False
-    # If any cell contains characters that are common in plain-text headers
-    # but unusual in blockchain ids, treat it as a header. Simple heuristic:
-    # header cells tend to be short and contain only letters/_.
     for cell in row:
         c = cell.strip()
         if not c:
             return False
-        if not c.replace("_", "").isalnum():
+        # Header cells: letters + underscores only, capped length. Digits
+        # disqualify (would suggest an id like `1A1z…`, `0xabc…`, or a
+        # numeric cluster id).
+        stripped = c.replace("_", "")
+        if not stripped.isalpha() or len(c) > 32:
             return False
-    # As a pragmatic default: if each cell is purely alphabetic and <= 20
-    # chars, call it a header. Otherwise treat it as data.
-    return all(c.strip().isalpha() and len(c.strip()) <= 20 for c in row)
+    return True
 
 
 def _extract_from_lines(text: str, *, skip_empty: bool = True) -> list[str]:

graphsense_python-2.13.0/graphsense/gs_files/__init__.py

@@ -0,0 +1,69 @@
+# AUTO-GENERATED — DO NOT EDIT.
+# Synced from src/graphsenselib/convert/gs_files/__init__.py via
+# clients/python/scripts/sync_gs_files.py. Edit the source and re-run
+# `make -C clients/python sync-gs-files`.
+"""Encode and decode GraphSense `.gs` save files.
+
+Decode:
+    decode_gs_bytes / decode_gs  — bytes/path to raw JSON
+    structure                    — raw JSON to typed dataclasses
+    summarize                    — typed dataclasses to short summary dict
+    to_jsonable / write_json     — JSON serialization helpers
+
+Encode:
+    GsBuilder                    — high-level fluent API for building graphs
+    encode_gs_payload            — raw payload list to .gs bytes
+    builder_from_spec            — build a GsBuilder from a JSON spec dict
+"""
+
+from .encoder import (
+    GsBuilder,
+    builder_from_spec,
+    encode_gs_payload,
+)
+from .parser import (
+    Color,
+    GraphAddress,
+    GraphData,
+    GraphEntity,
+    Highlight,
+    PathfinderAggEdge,
+    PathfinderAnnotation,
+    PathfinderData,
+    PathfinderId,
+    PathfinderThing,
+    UserTag,
+    decode_gs,
+    decode_gs_bytes,
+    lzw_pack,
+    lzw_unpack,
+    structure,
+)
+from .summary import summarize
+from .writer import to_jsonable, write_decoded, write_json
+
+__all__ = [
+    "Color",
+    "GraphAddress",
+    "GraphData",
+    "GraphEntity",
+    "GsBuilder",
+    "Highlight",
+    "PathfinderAggEdge",
+    "PathfinderAnnotation",
+    "PathfinderData",
+    "PathfinderId",
+    "PathfinderThing",
+    "UserTag",
+    "builder_from_spec",
+    "decode_gs",
+    "decode_gs_bytes",
+    "encode_gs_payload",
+    "lzw_pack",
+    "lzw_unpack",
+    "structure",
+    "summarize",
+    "to_jsonable",
+    "write_decoded",
+    "write_json",
+]