graphsense-python 2.11.0__py3-none-any.whl → 2.13.0__py3-none-any.whl

graphsense/__init__.py

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

graphsense/api/addresses_api.py

@@ -20,6 +20,7 @@ from typing_extensions import Annotated
 from graphsense.models.address import Address
 from graphsense.models.address_tags import AddressTags
 from graphsense.models.address_txs import AddressTxs
+from graphsense.models.cluster import Cluster
 from graphsense.models.entity import Entity
 from graphsense.models.links import Links
 from graphsense.models.neighbor_addresses import NeighborAddresses
@@ -433,6 +434,305 @@ class AddressesApi:
 
 
 
+    @validate_call_compat
+    def get_address_cluster(
+        self,
+        currency: Annotated[StrictStr, Field(description="The cryptocurrency code (e.g., btc)")],
+        address: Annotated[StrictStr, Field(description="The cryptocurrency address")],
+        include_actors: Annotated[Optional[StrictBool], Field(description="Whether to include actor information")] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> Cluster:
+        """Get the cluster for an address
+
+        Returns the address cluster that contains the given address.
+
+        :param currency: The cryptocurrency code (e.g., btc) (required)
+        :type currency: str
+        :param address: The cryptocurrency address (required)
+        :type address: str
+        :param include_actors: Whether to include actor information
+        :type include_actors: bool
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_address_cluster_serialize(
+            currency=currency,
+            address=address,
+            include_actors=include_actors,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "Cluster",
+            '404': None,
+            '422': "HTTPValidationError",
+        }
+        response_data = self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        ).data
+
+
+    @validate_call_compat
+    def get_address_cluster_with_http_info(
+        self,
+        currency: Annotated[StrictStr, Field(description="The cryptocurrency code (e.g., btc)")],
+        address: Annotated[StrictStr, Field(description="The cryptocurrency address")],
+        include_actors: Annotated[Optional[StrictBool], Field(description="Whether to include actor information")] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ApiResponse[Cluster]:
+        """Get the cluster for an address
+
+        Returns the address cluster that contains the given address.
+
+        :param currency: The cryptocurrency code (e.g., btc) (required)
+        :type currency: str
+        :param address: The cryptocurrency address (required)
+        :type address: str
+        :param include_actors: Whether to include actor information
+        :type include_actors: bool
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_address_cluster_serialize(
+            currency=currency,
+            address=address,
+            include_actors=include_actors,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "Cluster",
+            '404': None,
+            '422': "HTTPValidationError",
+        }
+        response_data = self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        )
+
+
+    @validate_call_compat
+    def get_address_cluster_without_preload_content(
+        self,
+        currency: Annotated[StrictStr, Field(description="The cryptocurrency code (e.g., btc)")],
+        address: Annotated[StrictStr, Field(description="The cryptocurrency address")],
+        include_actors: Annotated[Optional[StrictBool], Field(description="Whether to include actor information")] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> RESTResponseType:
+        """Get the cluster for an address
+
+        Returns the address cluster that contains the given address.
+
+        :param currency: The cryptocurrency code (e.g., btc) (required)
+        :type currency: str
+        :param address: The cryptocurrency address (required)
+        :type address: str
+        :param include_actors: Whether to include actor information
+        :type include_actors: bool
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_address_cluster_serialize(
+            currency=currency,
+            address=address,
+            include_actors=include_actors,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "Cluster",
+            '404': None,
+            '422': "HTTPValidationError",
+        }
+        response_data = self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        return response_data.response
+
+
+    def _get_address_cluster_serialize(
+        self,
+        currency,
+        address,
+        include_actors,
+        _request_auth,
+        _content_type,
+        _headers,
+        _host_index,
+    ) -> RequestSerialized:
+
+        _host = None
+
+        _collection_formats: Dict[str, str] = {
+        }
+
+        _path_params: Dict[str, str] = {}
+        _query_params: List[Tuple[str, str]] = []
+        _header_params: Dict[str, Optional[str]] = _headers or {}
+        _form_params: List[Tuple[str, str]] = []
+        _files: Dict[
+            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
+        ] = {}
+        _body_params: Optional[bytes] = None
+
+        # process the path parameters
+        if currency is not None:
+            _path_params['currency'] = currency
+        if address is not None:
+            _path_params['address'] = address
+        # process the query parameters
+        if include_actors is not None:
+            
+            _query_params.append(('include_actors', include_actors))
+            
+        # process the header parameters
+        # process the form parameters
+        # process the body parameter
+
+
+        # set the HTTP header `Accept`
+        if 'Accept' not in _header_params:
+            _header_params['Accept'] = self.api_client.select_header_accept(
+                [
+                    'application/json'
+                ]
+            )
+
+
+        # authentication setting
+        _auth_settings: List[str] = [
+            'api_key'
+        ]
+
+        return self.api_client.param_serialize(
+            method='GET',
+            resource_path='/{currency}/addresses/{address}/cluster',
+            path_params=_path_params,
+            query_params=_query_params,
+            header_params=_header_params,
+            body=_body_params,
+            post_params=_form_params,
+            files=_files,
+            auth_settings=_auth_settings,
+            collection_formats=_collection_formats,
+            _host=_host,
+            _request_auth=_request_auth
+        )
+
+
+
+
     @validate_call_compat
     def get_address_entity(
         self,
@@ -452,9 +752,9 @@ class AddressesApi:
         _headers: Optional[Dict[StrictStr, Any]] = None,
         _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
     ) -> Entity:
-        """Get the entity for an address
+        """(Deprecated) Get the entity for an address
 
-        Returns the clustered entity that contains the given address.
+        Deprecated alias for `GET /{currency}/addresses/{address}/cluster`. Returns the address cluster that contains the given address.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -483,6 +783,7 @@ class AddressesApi:
         :type _host_index: int, optional
         :return: Returns the result object.
         """ # noqa: E501
+        warnings.warn("GET /{currency}/addresses/{address}/entity is deprecated.", DeprecationWarning)
 
         _param = self._get_address_entity_serialize(
             currency=currency,
@@ -529,9 +830,9 @@ class AddressesApi:
         _headers: Optional[Dict[StrictStr, Any]] = None,
         _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
     ) -> ApiResponse[Entity]:
-        """Get the entity for an address
+        """(Deprecated) Get the entity for an address
 
-        Returns the clustered entity that contains the given address.
+        Deprecated alias for `GET /{currency}/addresses/{address}/cluster`. Returns the address cluster that contains the given address.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -560,6 +861,7 @@ class AddressesApi:
         :type _host_index: int, optional
         :return: Returns the result object.
         """ # noqa: E501
+        warnings.warn("GET /{currency}/addresses/{address}/entity is deprecated.", DeprecationWarning)
 
         _param = self._get_address_entity_serialize(
             currency=currency,
@@ -606,9 +908,9 @@ class AddressesApi:
         _headers: Optional[Dict[StrictStr, Any]] = None,
         _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
     ) -> RESTResponseType:
-        """Get the entity for an address
+        """(Deprecated) Get the entity for an address
 
-        Returns the clustered entity that contains the given address.
+        Deprecated alias for `GET /{currency}/addresses/{address}/cluster`. Returns the address cluster that contains the given address.
 
         :param currency: The cryptocurrency code (e.g., btc) (required)
         :type currency: str
@@ -637,6 +939,7 @@ class AddressesApi:
         :type _host_index: int, optional
         :return: Returns the result object.
         """ # noqa: E501
+        warnings.warn("GET /{currency}/addresses/{address}/entity is deprecated.", DeprecationWarning)
 
         _param = self._get_address_entity_serialize(
             currency=currency,

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.11.0/python'
+        self.user_agent = 'OpenAPI-Generator/2.13.0/python'
         self.client_side_validation = configuration.client_side_validation
 
     def __enter__(self):

graphsense/cli/__init__.py

@@ -0,0 +1 @@
+"""graphsense CLI — requires the [cli] extra (`pip install graphsense-python[cli]`)."""

graphsense/cli/__main__.py

@@ -0,0 +1,4 @@
+from graphsense.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

graphsense/cli/bulk_cmd.py

@@ -0,0 +1,95 @@
+"""`graphsense bulk <operation>` — direct access to /bulk.json / /bulk.csv."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import rich_click as click
+
+from graphsense.cli.context import CliContext
+from graphsense.ext import io as io_mod
+from graphsense.ext import output as out_mod
+
+pass_ctx = click.make_pass_decorator(CliContext)
+
+
+@click.command(name="bulk")
+@click.argument("operation")
+@click.argument("currency")
+@click.argument("keys", nargs=-1)
+@click.option(
+    "--key-field",
+    default="address",
+    help="Field name the bulk operation expects (address, tx_hash, cluster, ...).",
+)
+@click.option("--num-pages", type=int, default=1)
+@pass_ctx
+def bulk_command(
+    ctx: CliContext,
+    operation: str,
+    currency: str,
+    keys: tuple[str, ...],
+    key_field: str,
+    num_pages: int,
+) -> None:
+    """Call /bulk.json/<operation> or /bulk.csv/<operation> for a list of keys.
+
+    Keys come from positionals, --input, or stdin (JSON/CSV/lines, with
+    --address-jq / --address-col).
+    Output format follows --format (default json).
+    """
+    ids = _collect_keys(ctx, keys)
+    if not ids:
+        raise click.UsageError("no keys provided for bulk")
+
+    fmt = (ctx.format or "json").lower()
+    gs = ctx.gs()
+    result = gs.bulk(
+        operation,
+        ids,
+        currency=currency,
+        format="csv" if fmt == "csv" else "json",
+        num_pages=num_pages,
+        key_field=key_field,
+    )
+
+    if fmt == "csv":
+        _write_raw(ctx, result)
+    else:
+        out_mod.write(
+            result,
+            output=ctx.output,
+            directory=ctx.directory,
+            format=ctx.format,
+            color=ctx.color,
+        )
+
+
+def _collect_keys(ctx: CliContext, positional: tuple[str, ...]) -> list[str]:
+    if positional:
+        return list(positional)
+    text = ctx.read_input_text()
+    if text is None:
+        return []
+    return io_mod.parse_input(
+        text,
+        input_format=ctx.input_format,
+        jq=ctx.address_jq,
+        col=ctx.address_col,
+    )
+
+
+def _write_raw(ctx: CliContext, payload) -> None:
+    """For CSV bulk output, the server already returns flat rows; pass through."""
+    text: Optional[str]
+    if isinstance(payload, (bytes, bytearray)):
+        text = payload.decode("utf-8")
+    elif isinstance(payload, str):
+        text = payload
+    else:
+        # Some generated clients deserialize the CSV as {"value": "...raw..."}
+        text = str(payload)
+    with out_mod.open_out(ctx.output) as fh:
+        fh.write(text)
+        if not text.endswith("\n"):
+            fh.write("\n")

graphsense/cli/context.py

@@ -0,0 +1,64 @@
+"""Shared Click context for all `gs` commands."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+import rich_click as click
+
+from graphsense.ext.client import GraphSense
+
+
+@dataclass
+class CliContext:
+    api_key: Optional[str] = None
+    host: Optional[str] = None
+    format: Optional[str] = None
+    output: Optional[str] = None
+    directory: Optional[str] = None
+    input: Optional[str] = None
+    input_format: str = "auto"
+    # Primary id selectors. "address" in the flag name is conventional —
+    # for lookup-tx / lookup-cluster these extract tx hashes / cluster ids.
+    address_jq: Optional[str] = None
+    address_col: Optional[str] = None
+    # Per-row network selectors — see docs/cli/inputs.md.
+    # "network" is the preferred term in new code; the generated API still
+    # uses "currency" for backward compatibility (see CLAUDE.md).
+    network_jq: Optional[str] = None
+    network_col: Optional[str] = None
+    bulk: Optional[bool] = None
+    bulk_threshold: int = 10
+    color: str = "auto"
+    quiet: bool = False
+    verbose: int = 0
+    _gs: Optional[GraphSense] = field(default=None, repr=False)
+
+    def gs(self) -> GraphSense:
+        if self._gs is None:
+            self._gs = GraphSense(
+                api_key=self.api_key,
+                host=self.host,
+                quiet_deprecation=self.quiet,
+                show_deprecated=os.environ.get(
+                    "GRAPHSENSE_CLIENT_SHOW_DEPRECATED_ENDPOINTS"
+                )
+                == "1",
+                # Resolve click's current stderr stream on each write so
+                # `CliRunner(mix_stderr=False)` on click 8.1 captures it.
+                deprecation_stream=lambda: click.get_text_stream("stderr"),
+            )
+        return self._gs
+
+    def read_input_text(self) -> Optional[str]:
+        """Read the input blob from --input or, if stdin is piped, from stdin."""
+        if self.input:
+            with open(self.input, "r", encoding="utf-8") as fh:
+                return fh.read()
+        if not sys.stdin.isatty():
+            data = sys.stdin.read()
+            return data if data else None
+        return None