Add SQL execution and table listing features to Dune client (#184)

* Add SQL execution and table listing features to Dune client

- Implemented `execute_sql` method in `ExecutionAPI` to allow direct SQL execution via the API.
- Updated `ExtendedAPI` to utilize the new SQL execution method for running queries.
- Added `list_tables` method in `TableAPI` to retrieve a paginated list of tables.
- Introduced `UsageResponse`, `TableInfo`, and `ListTablesResponse` models for handling API responses.
- Enhanced unit tests to cover new features and response parsing for usage and table information.

* formating

* fix how post params are done

* test and fix

* fixes to get_usage and proper tests

Author: 0xRobin

dune_client/api/execution.py

@@ -6,6 +6,8 @@
     get results: https://docs.dune.com/api-reference/executions/endpoint/get-execution-result
 """
 
+from __future__ import annotations
+
 from io import BytesIO
 from typing import Any
 
@@ -47,6 +49,40 @@ def execute_query(self, query: QueryBase, performance: str | None = None) -> Exe
         except KeyError as err:
             raise DuneError(response_json, "ExecutionResponse", err) from err
 
+    def execute_sql(
+        self,
+        query_sql: str,
+        performance: str | None = None,
+    ) -> ExecutionResponse:
+        """
+        Execute arbitrary SQL directly via the API without creating a saved query.
+        https://docs.dune.com/api-reference/executions/endpoint/execute-sql
+
+        Note: This endpoint does not support parameterized queries. If you need
+        parameters, use the regular execute_query() with a saved query.
+
+        Args:
+            query_sql: The SQL query string to execute
+            performance: Optional performance tier ("medium" or "large")
+
+        Returns:
+            ExecutionResponse with execution_id and state
+        """
+        payload: dict[str, str] = {
+            "sql": query_sql,
+            "performance": performance or self.performance,
+        }
+
+        self.logger.info(f"executing SQL on {performance or self.performance} cluster")
+        response_json = self._post(
+            route="/sql/execute",
+            params=payload,
+        )
+        try:
+            return ExecutionResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "ExecutionResponse", err) from err
+
     def cancel_execution(self, job_id: str) -> bool:
         """POST Execution Cancellation to Dune API for `job_id` (aka `execution_id`)"""
         response_json = self._post(

dune_client/api/extensions.py

@@ -19,6 +19,7 @@
 from dune_client.api.execution import ExecutionAPI
 from dune_client.api.query import QueryAPI
 from dune_client.api.table import TableAPI
+from dune_client.api.usage import UsageAPI
 from dune_client.models import (
     DuneError,
     ExecutionResultCSV,
@@ -38,7 +39,7 @@
 POLL_FREQUENCY_SECONDS = 1
 
 
-class ExtendedAPI(ExecutionAPI, QueryAPI, TableAPI, CustomEndpointAPI):
+class ExtendedAPI(ExecutionAPI, QueryAPI, TableAPI, UsageAPI, CustomEndpointAPI):
     """
     Provides higher level helper methods for faster
     and easier development on top of the base ExecutionAPI.
@@ -321,20 +322,47 @@ def run_sql(
         name: str = "API Query",
     ) -> ResultsResponse:
         """
-        Allows user to provide execute raw_sql via the CRUD interface
-        - create, run, get results with optional archive/delete.
-        - Query is by default made private and archived after execution.
+        Execute arbitrary SQL directly via the API and return results.
+        Uses the /sql/execute endpoint introduced in the Dune API.
+        https://docs.dune.com/api-reference/executions/endpoint/execute-query
+
+        Note: The `name`, `is_private`, `archive_after`, and `params` parameters are
+        kept for backward compatibility but are ignored when using the direct SQL execution
+        endpoint. The /sql/execute endpoint does not support parameterized queries.
+
+        Args:
+            query_sql: The SQL query string to execute
+            params: (Ignored) Kept for backward compatibility
+            is_private: (Ignored) Kept for backward compatibility
+            archive_after: (Ignored) Kept for backward compatibility
+            performance: Optional performance tier ("medium" or "large")
+            ping_frequency: Seconds between status checks while polling
+            name: (Ignored) Kept for backward compatibility
+
+        Returns:
+            ResultsResponse with the query execution results
+
         Requires Plus subscription!
         """
-        query = self.create_query(name, query_sql, params, is_private)
-        try:
-            results = self.run_query(
-                query=query.base, performance=performance, ping_frequency=ping_frequency
-            )
-        finally:
-            if archive_after:
-                self.archive_query(query.base.query_id)
-        return results
+        # Execute SQL directly using the new endpoint
+        job_id = self.execute_sql(
+            query_sql=query_sql,
+            performance=performance,
+        ).execution_id
+
+        # Poll for completion
+        status = self.get_execution_status(job_id)
+        while status.state not in ExecutionState.terminal_states():
+            self.logger.info(f"waiting for query execution {job_id} to complete: {status}")
+            time.sleep(ping_frequency)
+            status = self.get_execution_status(job_id)
+
+        if status.state == ExecutionState.FAILED:
+            self.logger.error(status)
+            raise QueryFailedError(f"Error data: {status.error}")
+
+        # Fetch and return results
+        return self._fetch_entire_result(self.get_execution_results(job_id))
 
     ######################
     # Deprecated Functions

dune_client/api/table.py

@@ -14,6 +14,7 @@
     DeleteTableResult,
     DuneError,
     InsertTableResult,
+    ListTablesResponse,
 )
 
 
@@ -137,3 +138,34 @@ def delete_table(self, namespace: str, table_name: str) -> DeleteTableResult:
             return DeleteTableResult.from_dict(response_json)
         except KeyError as err:
             raise DuneError(response_json, "DeleteTableResult", err) from err
+
+    def list_tables(
+        self,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> ListTablesResponse:
+        """
+        https://docs.dune.com/api-reference/tables/endpoint/list
+        Get a paginated list of tables uploaded to Dune.
+
+        Args:
+            limit: Maximum number of tables to return (optional)
+            offset: Offset for pagination (optional)
+
+        Returns:
+            ListTablesResponse containing list of tables and pagination info
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        response_json = self._get(
+            route="/tables",
+            params=params if params else None,
+        )
+        try:
+            return ListTablesResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "ListTablesResponse", err) from err

dune_client/api/usage.py

@@ -0,0 +1,49 @@
+"""
+Usage API endpoints enable users to retrieve usage and billing information.
+https://docs.dune.com/api-reference/usage/endpoint/get-usage
+"""
+
+from __future__ import annotations
+
+from dune_client.api.base import BaseRouter
+from dune_client.models import DuneError, UsageResponse
+
+
+class UsageAPI(BaseRouter):
+    """
+    Implementation of Usage endpoints - Plus subscription only
+    https://docs.dune.com/api-reference/usage/
+    """
+
+    def get_usage(
+        self,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> UsageResponse:
+        """
+        Get credits usage data, billing periods, storage, etc.
+        https://docs.dune.com/api-reference/usage/endpoint/get-usage
+
+        Args:
+            start_date: Optional start date for the usage period (format: YYYY-MM-DD)
+            end_date: Optional end date for the usage period (format: YYYY-MM-DD)
+
+        Returns:
+            UsageResponse containing usage statistics and billing periods
+
+        Requires Plus subscription!
+        """
+        payload = {}
+        if start_date:
+            payload["start_date"] = start_date
+        if end_date:
+            payload["end_date"] = end_date
+
+        response_json = self._post(
+            route="/usage",
+            params=payload,
+        )
+        try:
+            return UsageResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "UsageResponse", err) from err