Add modern Uploads and Datasets APIs, deprecate legacy Table API

dune_client/api/datasets.py

@@ -0,0 +1,71 @@
+"""
+Datasets API endpoints for dataset discovery via /v1/datasets/*
+"""
+
+from __future__ import annotations
+
+from dune_client.api.base import BaseRouter
+from dune_client.models import DatasetListResponse, DatasetResponse, DuneError
+
+
+class DatasetsAPI(BaseRouter):
+    """
+    Implementation of Datasets endpoints
+    https://docs.dune.com/api-reference/datasets/
+    """
+
+    def list_datasets(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+        owner_handle: str | None = None,
+        type: str | None = None,
+    ) -> DatasetListResponse:
+        """
+        https://docs.dune.com/api-reference/datasets/endpoint/list
+        Retrieve a paginated list of datasets with optional filtering.
+
+        Args:
+            limit: Maximum number of datasets to return (max 250)
+            offset: Pagination offset
+            owner_handle: Optional filter by owner handle
+            type: Optional filter by dataset type (transformation_view, transformation_table,
+                  uploaded_table, decoded_table, spell, dune_table)
+
+        Returns:
+            DatasetListResponse with list of datasets and total count
+        """
+        params: dict[str, int | str] = {
+            "limit": limit,
+            "offset": offset,
+        }
+        if owner_handle is not None:
+            params["owner_handle"] = owner_handle
+        if type is not None:
+            params["type"] = type
+
+        response_json = self._get(
+            route="/v1/datasets",
+            params=params,
+        )
+        try:
+            return DatasetListResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "DatasetListResponse", err) from err
+
+    def get_dataset(self, slug: str) -> DatasetResponse:
+        """
+        https://docs.dune.com/api-reference/datasets/endpoint/get
+        Retrieve detailed information about a specific dataset.
+
+        Args:
+            slug: The dataset slug (e.g., 'dex.trades')
+
+        Returns:
+            DatasetResponse with full dataset details including columns and metadata
+        """
+        response_json = self._get(route=f"/v1/datasets/{slug}")
+        try:
+            return DatasetResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "DatasetResponse", err) from err

dune_client/api/extensions.py

@@ -16,10 +16,12 @@
     MAX_NUM_ROWS_PER_BATCH,
 )
 from dune_client.api.custom import CustomEndpointAPI
+from dune_client.api.datasets import DatasetsAPI
 from dune_client.api.execution import ExecutionAPI
 from dune_client.api.pipeline import PipelineAPI
 from dune_client.api.query import QueryAPI
 from dune_client.api.table import TableAPI
+from dune_client.api.uploads import UploadsAPI
 from dune_client.api.usage import UsageAPI
 from dune_client.models import (
     DuneError,
@@ -40,10 +42,26 @@
 POLL_FREQUENCY_SECONDS = 1
 
 
-class ExtendedAPI(ExecutionAPI, QueryAPI, TableAPI, UsageAPI, CustomEndpointAPI, PipelineAPI):
+class ExtendedAPI(  # type: ignore[misc]
+    ExecutionAPI,
+    QueryAPI,
+    UploadsAPI,
+    DatasetsAPI,
+    TableAPI,
+    UsageAPI,
+    CustomEndpointAPI,
+    PipelineAPI,
+):
     """
     Provides higher level helper methods for faster
     and easier development on top of the base ExecutionAPI.
+
+    Includes both legacy TableAPI (deprecated) and modern UploadsAPI/DatasetsAPI.
+    UploadsAPI is listed before TableAPI in the MRO to ensure modern methods
+    take precedence over deprecated ones with the same name.
+
+    Note: TableAPI has incompatible method signatures with UploadsAPI but is
+    kept for backward compatibility. The UploadsAPI methods take precedence.
     """
 
     def run_query(

dune_client/api/table.py

@@ -1,12 +1,17 @@
 """
 Table API endpoints enables users to
 create and insert data into Dune.
+
+DEPRECATED: This API uses legacy /table/* routes.
+Please use UploadsAPI for the modern /v1/uploads/* endpoints instead.
 """
 
 from __future__ import annotations
 
 from typing import IO
 
+from deprecated import deprecated
+
 from dune_client.api.base import BaseRouter
 from dune_client.models import (
     ClearTableResult,
@@ -21,8 +26,15 @@ class TableAPI(BaseRouter):
     """
     Implementation of Table endpoints - Plus subscription only
     https://docs.dune.com/api-reference/tables/
+
+    DEPRECATED: This API uses legacy /table/* routes.
+    Please use UploadsAPI for the modern /v1/uploads/* endpoints instead.
     """
 
+    @deprecated(
+        version="1.9.0",
+        reason="Use UploadsAPI.upload_csv() instead. This method uses legacy /table/* routes.",
+    )
     def upload_csv(
         self,
         table_name: str,
@@ -54,6 +66,10 @@ def upload_csv(
         except KeyError as err:
             raise DuneError(response_json, "UploadCsvResponse", err) from err
 
+    @deprecated(
+        version="1.9.0",
+        reason="Use UploadsAPI.create_table() instead. This method uses legacy /table/* routes.",
+    )
     def create_table(
         self,
         namespace: str,
@@ -87,6 +103,10 @@ def create_table(
         except KeyError as err:
             raise DuneError(result_json, "CreateTableResult", err) from err
 
+    @deprecated(
+        version="1.9.0",
+        reason="Use UploadsAPI.insert_data() instead. This method uses legacy /table/* routes.",
+    )
     def insert_table(
         self,
         namespace: str,
@@ -113,6 +133,10 @@ def insert_table(
         except KeyError as err:
             raise DuneError(result_json, "InsertTableResult", err) from err
 
+    @deprecated(
+        version="1.9.0",
+        reason="Use UploadsAPI.clear_table() instead. This method uses legacy /table/* routes.",
+    )
     def clear_data(self, namespace: str, table_name: str) -> ClearTableResult:
         """
         https://docs.dune.com/api-reference/tables/endpoint/clear
@@ -126,6 +150,10 @@ def clear_data(self, namespace: str, table_name: str) -> ClearTableResult:
         except KeyError as err:
             raise DuneError(result_json, "ClearTableResult", err) from err
 
+    @deprecated(
+        version="1.9.0",
+        reason="Use UploadsAPI.delete_table() instead. This method uses legacy /table/* routes.",
+    )
     def delete_table(self, namespace: str, table_name: str) -> DeleteTableResult:
         """
         https://docs.dune.com/api-reference/tables/endpoint/delete