graphsense-python 2.15.0__tar.gz → 2.15.1__tar.gz

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsense-python
-Version: 2.15.0
+Version: 2.15.1
 Summary: GraphSense API
 Author-email: Iknaio Cryptoasset Analytics GmbH <contact@iknaio.com>
 License-Expression: MIT
@@ -63,8 +63,8 @@ connector or tool source; the assistant then handles the rest.
 
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
-- API version: 2.15.0
-- Package version: 2.15.0
+- API version: 2.15.1
+- Package version: 2.15.1
 - 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/)

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/README.md

@@ -41,8 +41,8 @@ connector or tool source; the assistant then handles the rest.
 
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
-- API version: 2.15.0
-- Package version: 2.15.0
+- API version: 2.15.1
+- Package version: 2.15.1
 - 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/)

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/__init__.py

@@ -12,7 +12,7 @@
 """
 
 
-__version__ = "2.15.0"
+__version__ = "2.15.1"
 
 # Define package exports
 __all__ = [

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/api/addresses_api.py

@@ -1795,7 +1795,7 @@ class AddressesApi:
     ) -> NeighborAddresses:
         """List neighboring addresses
 
-        Returns neighboring addresses connected to the given address in the transaction graph.
+        Returns neighboring addresses connected to the given address in the transaction graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried address and that neighbor), while the embedded `address` object carries the neighbor's own **lifetime** attributes (its balance, degrees, first_tx/last_tx, …), not relative to the queried address.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -1892,7 +1892,7 @@ class AddressesApi:
     ) -> ApiResponse[NeighborAddresses]:
         """List neighboring addresses
 
-        Returns neighboring addresses connected to the given address in the transaction graph.
+        Returns neighboring addresses connected to the given address in the transaction graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried address and that neighbor), while the embedded `address` object carries the neighbor's own **lifetime** attributes (its balance, degrees, first_tx/last_tx, …), not relative to the queried address.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -1989,7 +1989,7 @@ class AddressesApi:
     ) -> RESTResponseType:
         """List neighboring addresses
 
-        Returns neighboring addresses connected to the given address in the transaction graph.
+        Returns neighboring addresses connected to the given address in the transaction graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried address and that neighbor), while the embedded `address` object carries the neighbor's own **lifetime** attributes (its balance, degrees, first_tx/last_tx, …), not relative to the queried address.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/api/bulk_api.py

@@ -147,7 +147,7 @@ class BulkApi:
     ) -> object:
         """Stream bulk operation results as CSV
 
-        Executes a supported operation for multiple key values and streams flattened result rows as CSV.
+        Executes a supported operation for multiple key values and streams flattened result rows as CSV. Each key list in the request body is capped (10,000 items by default), as is the body itself (8 MiB by default); split longer requests into several calls.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -193,6 +193,7 @@ class BulkApi:
         _response_types_map: Dict[str, Optional[str]] = {
             '200': "object",
             '400': None,
+            '413': None,
             '422': None,
         }
         response_data = self.api_client.call_api(
@@ -228,7 +229,7 @@ class BulkApi:
     ) -> ApiResponse[object]:
         """Stream bulk operation results as CSV
 
-        Executes a supported operation for multiple key values and streams flattened result rows as CSV.
+        Executes a supported operation for multiple key values and streams flattened result rows as CSV. Each key list in the request body is capped (10,000 items by default), as is the body itself (8 MiB by default); split longer requests into several calls.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -274,6 +275,7 @@ class BulkApi:
         _response_types_map: Dict[str, Optional[str]] = {
             '200': "object",
             '400': None,
+            '413': None,
             '422': None,
         }
         response_data = self.api_client.call_api(
@@ -309,7 +311,7 @@ class BulkApi:
     ) -> RESTResponseType:
         """Stream bulk operation results as CSV
 
-        Executes a supported operation for multiple key values and streams flattened result rows as CSV.
+        Executes a supported operation for multiple key values and streams flattened result rows as CSV. Each key list in the request body is capped (10,000 items by default), as is the body itself (8 MiB by default); split longer requests into several calls.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -355,6 +357,7 @@ class BulkApi:
         _response_types_map: Dict[str, Optional[str]] = {
             '200': "object",
             '400': None,
+            '413': None,
             '422': None,
         }
         response_data = self.api_client.call_api(
@@ -474,7 +477,7 @@ class BulkApi:
     ) -> object:
         """Stream bulk operation results as JSON
 
-        Executes a supported operation for multiple key values and streams flattened result rows as JSON.
+        Executes a supported operation for multiple key values and streams flattened result rows as JSON. Each key list in the request body is capped (10,000 items by default), as is the body itself (8 MiB by default); split longer requests into several calls.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -520,6 +523,7 @@ class BulkApi:
         _response_types_map: Dict[str, Optional[str]] = {
             '200': "object",
             '400': None,
+            '413': None,
             '422': None,
         }
         response_data = self.api_client.call_api(
@@ -555,7 +559,7 @@ class BulkApi:
     ) -> ApiResponse[object]:
         """Stream bulk operation results as JSON
 
-        Executes a supported operation for multiple key values and streams flattened result rows as JSON.
+        Executes a supported operation for multiple key values and streams flattened result rows as JSON. Each key list in the request body is capped (10,000 items by default), as is the body itself (8 MiB by default); split longer requests into several calls.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -601,6 +605,7 @@ class BulkApi:
         _response_types_map: Dict[str, Optional[str]] = {
             '200': "object",
             '400': None,
+            '413': None,
             '422': None,
         }
         response_data = self.api_client.call_api(
@@ -636,7 +641,7 @@ class BulkApi:
     ) -> RESTResponseType:
         """Stream bulk operation results as JSON
 
-        Executes a supported operation for multiple key values and streams flattened result rows as JSON.
+        Executes a supported operation for multiple key values and streams flattened result rows as JSON. Each key list in the request body is capped (10,000 items by default), as is the body itself (8 MiB by default); split longer requests into several calls.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -682,6 +687,7 @@ class BulkApi:
         _response_types_map: Dict[str, Optional[str]] = {
             '200': "object",
             '400': None,
+            '413': None,
             '422': None,
         }
         response_data = self.api_client.call_api(

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/api/clusters_api.py

@@ -1549,7 +1549,7 @@ class ClustersApi:
     ) -> NeighborClusters:
         """(Deprecated) List neighboring clusters
 
-        Returns neighboring clusters connected to the given cluster in the cluster graph.
+        Returns neighboring clusters connected to the given cluster in the cluster graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried cluster and that neighbor), while the embedded cluster object carries the neighbor's own **lifetime** attributes, not relative to the queried cluster.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -1655,7 +1655,7 @@ class ClustersApi:
     ) -> ApiResponse[NeighborClusters]:
         """(Deprecated) List neighboring clusters
 
-        Returns neighboring clusters connected to the given cluster in the cluster graph.
+        Returns neighboring clusters connected to the given cluster in the cluster graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried cluster and that neighbor), while the embedded cluster object carries the neighbor's own **lifetime** attributes, not relative to the queried cluster.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -1761,7 +1761,7 @@ class ClustersApi:
     ) -> RESTResponseType:
         """(Deprecated) List neighboring clusters
 
-        Returns neighboring clusters connected to the given cluster in the cluster graph.
+        Returns neighboring clusters connected to the given cluster in the cluster graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried cluster and that neighbor), while the embedded cluster object carries the neighbor's own **lifetime** attributes, not relative to the queried cluster.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/api/entities_api.py

@@ -1555,7 +1555,7 @@ class EntitiesApi:
     ) -> NeighborEntities:
         """(Deprecated) List neighboring entities
 
-        Returns neighboring entities connected to the given entity in the entity graph.
+        Returns neighboring entities connected to the given entity in the entity graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried entity and that neighbor), while the embedded entity/cluster object carries the neighbor's own **lifetime** attributes, not relative to the queried entity.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -1661,7 +1661,7 @@ class EntitiesApi:
     ) -> ApiResponse[NeighborEntities]:
         """(Deprecated) List neighboring entities
 
-        Returns neighboring entities connected to the given entity in the entity graph.
+        Returns neighboring entities connected to the given entity in the entity graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried entity and that neighbor), while the embedded entity/cluster object carries the neighbor's own **lifetime** attributes, not relative to the queried entity.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -1767,7 +1767,7 @@ class EntitiesApi:
     ) -> RESTResponseType:
         """(Deprecated) List neighboring entities
 
-        Returns neighboring entities connected to the given entity in the entity graph.
+        Returns neighboring entities connected to the given entity in the entity graph. Per neighbor, `value` and `no_txs` are **edge-scoped** (the value transferred and number of transactions between the queried entity and that neighbor), while the embedded entity/cluster object carries the neighbor's own **lifetime** attributes, not relative to the queried entity.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/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 = 'graphsense-python/2.15.0'
+        self.user_agent = 'graphsense-python/2.15.1'
         self.client_side_validation = configuration.client_side_validation
 
     def __enter__(self):

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/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.15.0\n"\
-               "SDK Package Version: 2.15.0".\
+               "Version of the API: 2.15.1\n"\
+               "SDK Package Version: 2.15.1".\
                format(env=sys.platform, pyversion=sys.version)
 
     def get_host_settings(self) -> List[HostSetting]:

graphsense_python-2.15.1/graphsense/ext/bulk.py

@@ -0,0 +1,116 @@
+"""Decide between per-item calls and the /bulk endpoint."""
+
+from __future__ import annotations
+
+import csv
+import io
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Iterable, Iterator, Optional
+
+DEFAULT_BULK_THRESHOLD = 10
+
+# The server bounds how many items one bulk request may carry (10,000 by
+# default) and answers a longer list with a 400.
+# Splitting below that bound keeps arbitrarily long key lists working from the
+# client's side. Deployments that lower the server cap need a matching
+# `chunk_size` on the call.
+DEFAULT_BULK_CHUNK_SIZE = 5000
+
+
+def should_bulk(
+    n: int,
+    *,
+    threshold: int = DEFAULT_BULK_THRESHOLD,
+    override: Optional[bool] = None,
+) -> bool:
+    """True if we should go through the bulk endpoint.
+
+    `override=None`: use threshold.
+    `override=True`: always bulk (even for small N).
+    `override=False`: never bulk.
+    """
+    if override is not None:
+        return override
+    return n >= threshold
+
+
+def run_parallel(
+    call: Callable[[str], Any],
+    keys: Iterable[str],
+    *,
+    max_workers: int = 8,
+) -> list[Any]:
+    """Call `call(k)` for each k in keys across a thread pool, preserving order."""
+    items = list(keys)
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        return list(pool.map(call, items))
+
+
+def announce_switch(stream=None) -> None:
+    """Emit a one-line stderr notice the first time we switch to bulk.
+
+    Caller must implement the "first time" logic — this just prints.
+    """
+    out = stream if stream is not None else sys.stderr
+    print(
+        "notice: switching to bulk endpoint "
+        "(rows are flat; per-item typed models are available with --no-bulk)",
+        file=out,
+    )
+
+
+def chunked(items: Iterable[Any], size: int) -> Iterator[list]:
+    """Yield consecutive lists of at most `size` items."""
+    if size <= 0:
+        raise ValueError("chunk size must be positive")
+    batch: list = []
+    for item in items:
+        batch.append(item)
+        if len(batch) == size:
+            yield batch
+            batch = []
+    if batch:
+        yield batch
+
+
+def merge_json_chunks(chunks: Iterable[Any]) -> list:
+    """Concatenate the row lists returned by several bulk.json calls."""
+    rows: list = []
+    for chunk in chunks:
+        if chunk is None:
+            continue
+        rows.extend(chunk if isinstance(chunk, list) else [chunk])
+    return rows
+
+
+def merge_csv_chunks(chunks: Iterable[str]) -> str:
+    """Concatenate several bulk.csv responses into one CSV document.
+
+    Each response carries its own header, and the server infers those columns
+    from the first rows of that request — so two chunks of the same query can
+    legitimately disagree on the column set. Rows are therefore re-keyed onto
+    the union of all headers (in first-seen order) rather than pasted together.
+    """
+    rows: list[dict] = []
+    columns: list[str] = []
+    seen = set()
+    for chunk in chunks:
+        if not chunk or not chunk.strip():
+            continue
+        reader = csv.DictReader(io.StringIO(chunk))
+        for name in reader.fieldnames or []:
+            if name not in seen:
+                seen.add(name)
+                columns.append(name)
+        rows.extend(reader)
+
+    if not columns:
+        return ""
+
+    out = io.StringIO()
+    writer = csv.DictWriter(out, columns, restval="", extrasaction="ignore")
+    writer.writeheader()
+    for row in rows:
+        writer.writerow(row)
+    return out.getvalue()

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/ext/client.py

@@ -26,6 +26,7 @@ from dateutil import parser as _dateutil_parser
 import graphsense
 from graphsense.api_client import ApiClient
 from graphsense.configuration import Configuration
+from graphsense.ext import bulk as bulk_mod
 from graphsense.ext.deprecation import install as install_deprecation_hook
 
 # APIs that expose only deprecated endpoints; hidden from the convenience
@@ -506,15 +507,31 @@ class GraphSense:
         format: str = "json",
         num_pages: int = 1,
         key_field: str = "address",
+        chunk_size: int = bulk_mod.DEFAULT_BULK_CHUNK_SIZE,
     ) -> Any:
         """Call the /bulk.<format>/<operation> endpoint with `keys`.
 
         `key_field` is the dict key that the bulk operation expects in the
         request body (e.g. "address", "tx_hash", "cluster"). Default is
         "address" which is by far the most common.
+
+        The server bounds how many items a single bulk request may carry, so a
+        longer key list is split into `chunk_size` batches and the responses are
+        merged. Pass `chunk_size=0` to send the list in one request regardless.
         """
         ccy = self._currency(currency)
-        body = {key_field: list(keys)}
+        keys = list(keys)
+
+        def call(batch: list) -> Any:
+            body = {key_field: batch}
+            if format == "csv":
+                return self.raw.bulk.bulk_csv(ccy, operation, num_pages, body)
+            return self.raw.bulk.bulk_json(ccy, operation, num_pages, body)
+
+        if chunk_size <= 0 or len(keys) <= chunk_size:
+            return call(keys)
+
+        results = [call(batch) for batch in bulk_mod.chunked(keys, chunk_size)]
         if format == "csv":
-            return self.raw.bulk.bulk_csv(ccy, operation, num_pages, body)
-        return self.raw.bulk.bulk_json(ccy, operation, num_pages, body)
+            return bulk_mod.merge_csv_chunks(results)
+        return bulk_mod.merge_json_chunks(results)

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/models/address.py

@@ -35,8 +35,8 @@ class Address(BaseModel):
     balance: Values
     total_received: Values
     total_spent: Values
-    first_tx: Optional[TxSummary] = None
-    last_tx: Optional[TxSummary] = None
+    first_tx: Optional[TxSummary] = Field(default=None, description="First transaction in which this address appears, over its entire history — independent of any neighbor, direction, or date filter. Null if the address has no transactions of its own.")
+    last_tx: Optional[TxSummary] = Field(default=None, description="Last transaction in which this address appears, over its entire history — independent of any neighbor, direction, or date filter. Null if the address has no transactions of its own.")
     in_degree: StrictInt
     out_degree: StrictInt
     no_incoming_txs: StrictInt

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/models/entity.py

@@ -25,7 +25,7 @@ ENTITY_ANY_OF_SCHEMAS = ["Entity", "int"]
 
 class Entity(BaseModel):
     """
-    Deprecated alias of `cluster`. Use `cluster` instead; this field is retained for backwards compatibility and will be removed in a future release.
+    Deprecated alias of `cluster`. Use `cluster` instead; this field is retained for backwards compatibility and will be removed in a future release. When expanded to an object, these are the neighbor cluster's own lifetime attributes, NOT relative to the queried cluster or the edge between them.
     """
 
     # data type: Entity

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/models/neighbor_address.py

@@ -15,7 +15,7 @@ import pprint
 import re  # noqa: F401
 import json
 
-from pydantic import BaseModel, ConfigDict, StrictInt, StrictStr
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
 from typing import Any, ClassVar, Dict, List, Optional
 from graphsense.models.address import Address
 from graphsense.models.values import Values
@@ -27,10 +27,10 @@ class NeighborAddress(BaseModel):
     Neighbor address model.
     """ # noqa: E501
     value: Values
-    no_txs: StrictInt
+    no_txs: StrictInt = Field(description="Number of transactions on the edge between the queried address and this neighbor (edge-scoped, not the neighbor's lifetime transaction count).")
     address: Address
     labels: Optional[List[StrictStr]] = None
-    token_values: Optional[Dict[str, Values]] = None
+    token_values: Optional[Dict[str, Values]] = Field(default=None, description="Per-token value transferred on this edge (edge-scoped).")
     __properties: ClassVar[List[str]] = ["value", "no_txs", "address", "labels", "token_values"]
 
     model_config = ConfigDict(

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/models/neighbor_cluster.py

@@ -15,7 +15,7 @@ import pprint
 import re  # noqa: F401
 import json
 
-from pydantic import BaseModel, ConfigDict, StrictInt, StrictStr
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
 from typing import Any, ClassVar, Dict, List, Optional
 from graphsense.models.cluster import Cluster
 from graphsense.models.entity import Entity
@@ -28,10 +28,10 @@ class NeighborCluster(BaseModel):
     Neighbor cluster (canonical name, supersedes `NeighborEntity`).
     """ # noqa: E501
     value: Values
-    no_txs: StrictInt
+    no_txs: StrictInt = Field(description="Number of transactions on the edge between the queried cluster and this neighbor (edge-scoped, not the neighbor's lifetime transaction count).")
     entity: Optional[Entity] = None
     labels: Optional[List[StrictStr]] = None
-    token_values: Optional[Dict[str, Values]] = None
+    token_values: Optional[Dict[str, Values]] = Field(default=None, description="Per-token value transferred on this edge (edge-scoped).")
     cluster: Optional[Cluster]
     __properties: ClassVar[List[str]] = ["value", "no_txs", "entity", "labels", "token_values", "cluster"]
 

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense/models/neighbor_entity.py

@@ -15,7 +15,7 @@ import pprint
 import re  # noqa: F401
 import json
 
-from pydantic import BaseModel, ConfigDict, StrictInt, StrictStr
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
 from typing import Any, ClassVar, Dict, List, Optional
 from graphsense.models.cluster import Cluster
 from graphsense.models.entity import Entity
@@ -28,10 +28,10 @@ class NeighborEntity(BaseModel):
     Neighbor cluster model (legacy name: NeighborEntity).  Dual-emits the neighbor reference under both `entity` (deprecated) and `cluster` (preferred) keys, mirroring the alias pattern on the top-level `Entity`/`Cluster` models. The value is either an integer ID or a full `Entity`/`Cluster` object; whichever shape `entity` carries, `cluster` carries the same value.
     """ # noqa: E501
     value: Values
-    no_txs: StrictInt
+    no_txs: StrictInt = Field(description="Number of transactions on the edge between the queried cluster and this neighbor (edge-scoped, not the neighbor's lifetime transaction count).")
     entity: Optional[Entity] = None
     labels: Optional[List[StrictStr]] = None
-    token_values: Optional[Dict[str, Values]] = None
+    token_values: Optional[Dict[str, Values]] = Field(default=None, description="Per-token value transferred on this edge (edge-scoped).")
     cluster: Optional[Cluster]
     __properties: ClassVar[List[str]] = ["value", "no_txs", "entity", "labels", "token_values", "cluster"]
 

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/graphsense_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsense-python
-Version: 2.15.0
+Version: 2.15.1
 Summary: GraphSense API
 Author-email: Iknaio Cryptoasset Analytics GmbH <contact@iknaio.com>
 License-Expression: MIT
@@ -63,8 +63,8 @@ connector or tool source; the assistant then handles the rest.
 
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
-- API version: 2.15.0
-- Package version: 2.15.0
+- API version: 2.15.1
+- Package version: 2.15.1
 - 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/)

{graphsense_python-2.15.0 → graphsense_python-2.15.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphsense-python"
-version = "2.15.0"
+version = "2.15.1"
 description = "GraphSense API"
 license = "MIT"
 authors = [

graphsense_python-2.15.1/tests/test_ext_bulk.py

@@ -0,0 +1,105 @@
+"""Bulk-vs-per-item dispatch heuristic and GraphSense.bulk()."""
+
+from __future__ import annotations
+
+from graphsense.ext import bulk as bulk_mod
+from graphsense.ext import GraphSense
+
+
+def test_should_bulk_default_threshold():
+    assert not bulk_mod.should_bulk(5)
+    assert bulk_mod.should_bulk(10)
+    assert bulk_mod.should_bulk(100)
+
+
+def test_should_bulk_override_true():
+    assert bulk_mod.should_bulk(1, override=True)
+
+
+def test_should_bulk_override_false():
+    assert not bulk_mod.should_bulk(1000, override=False)
+
+
+def test_run_parallel_preserves_order():
+    def f(x):
+        return x * 2
+
+    assert bulk_mod.run_parallel(f, [1, 2, 3, 4]) == [2, 4, 6, 8]
+
+
+def test_gs_bulk_posts_to_json_endpoint(gs: GraphSense, http_mock):
+    http_mock.add(
+        "POST",
+        "/btc/bulk.json/get_address",
+        json_body=[{"address": "1A", "balance": 1}],
+    )
+    gs.bulk("get_address", ["1A", "1B"])
+    assert any("/btc/bulk.json/get_address" in c.url for c in http_mock.calls)
+    # body should contain the key list
+    call = [c for c in http_mock.calls if "/bulk.json" in c.url][0]
+    body = call.body
+    assert "1A" in str(body)
+    assert "1B" in str(body)
+
+
+def test_gs_bulk_csv_hits_csv_endpoint(gs: GraphSense, http_mock):
+    http_mock.add(
+        "POST",
+        "/btc/bulk.csv/get_address",
+        body="address,balance\n1A,1\n",
+        headers={"content-type": "text/csv"},
+    )
+    gs.bulk("get_address", ["1A"], format="csv")
+    assert any("/btc/bulk.csv/get_address" in c.url for c in http_mock.calls)
+
+
+def test_chunked_splits_evenly_and_keeps_remainder():
+    assert list(bulk_mod.chunked([1, 2, 3, 4, 5], 2)) == [[1, 2], [3, 4], [5]]
+    assert list(bulk_mod.chunked([], 2)) == []
+
+
+def test_merge_json_chunks_concatenates_rows():
+    merged = bulk_mod.merge_json_chunks([[{"a": 1}], [{"a": 2}, {"a": 3}], None])
+    assert merged == [{"a": 1}, {"a": 2}, {"a": 3}]
+
+
+def test_merge_csv_chunks_unions_headers():
+    """Each chunk gets its own server-side header inference, so a later chunk
+    may carry a column the first one never saw. Nothing may be dropped."""
+    first = "address,balance\n1A,1\n"
+    second = "address,balance,token\n1B,2,usdt\n"
+    merged = bulk_mod.merge_csv_chunks([first, second])
+    lines = merged.strip().splitlines()
+    assert lines[0] == "address,balance,token"
+    assert lines[1] == "1A,1,"
+    assert lines[2] == "1B,2,usdt"
+
+
+def test_gs_bulk_splits_long_key_lists(gs: GraphSense, http_mock):
+    """A key list longer than the server's per-request cap is sent as several
+    requests instead of one oversized (and rejected) request."""
+    http_mock.add(
+        "POST",
+        "/btc/bulk.json/get_address",
+        json_body=[{"address": "1A", "balance": 1}],
+    )
+    keys = [f"addr{i}" for i in range(7)]
+    result = gs.bulk("get_address", keys, chunk_size=3)
+
+    calls = [c for c in http_mock.calls if "/bulk.json" in c.url]
+    assert len(calls) == 3
+    sent = [str(c.body) for c in calls]
+    assert "addr0" in sent[0] and "addr2" in sent[0] and "addr3" not in sent[0]
+    assert "addr6" in sent[2]
+    # every chunk's rows come back concatenated
+    assert len(result) == 3
+
+
+def test_gs_bulk_sends_one_request_below_the_chunk_size(gs: GraphSense, http_mock):
+    http_mock.add(
+        "POST",
+        "/btc/bulk.json/get_address",
+        json_body=[{"address": "1A", "balance": 1}],
+    )
+    gs.bulk("get_address", ["1A", "1B"], chunk_size=100)
+    assert len([c for c in http_mock.calls if "/bulk.json" in c.url]) == 1