Add modern Uploads and Datasets APIs, deprecate legacy Table API (#187)

* Add modern Uploads and Datasets APIs, deprecate legacy Table API

This commit introduces the modern /v1/uploads and /v1/datasets API
endpoints while maintaining backward compatibility with the legacy
/table endpoints.

Changes:
- Add UploadsAPI with /v1/uploads/* endpoints for table management
- Add DatasetsAPI with /v1/datasets/* endpoints for dataset discovery
- Deprecate all TableAPI methods with migration guidance
- Add comprehensive response models for new APIs
- Update ExtendedAPI to include new APIs with proper MRO
- Add unit and E2E tests for new functionality
- Configure ruff to allow unittest-style assertions in tests

All existing TableAPI methods remain functional but emit deprecation
warnings pointing users to the new UploadsAPI methods.

* Fix API routes and response models for Uploads and Datasets APIs

- Remove double /v1 prefix from all routes (api_version already includes it)
- Update Dataset models to match actual API responses (full_name instead of slug/namespace)
- Update Table models to match actual API responses (full_name format)
- Change owner from id to handle+type fields
- Add nullable field to column models
- Change InsertDataResponse to use 'name' field instead of 'table_name'
- Update datasets integration tests to use full_name and required filters
- Update uploads integration tests to use DUNE_NAMESPACE env var and handle CSV upload naming
- Fix column types in test schemas (int -> integer)

* Update unit test mocks to match new API response structure

- Change Dataset mocks to use full_name instead of slug/namespace
- Update owner structure to use handle+type instead of id+handle
- Add nullable field to all column mocks
- Change metadata from description field to dict
- Update TableElement mocks to use full_name format
- Change InsertDataResponse mock to use 'name' instead of 'table_name'
- Fix all route expectations to remove /v1 prefix (already in api_version)

* Fix formatting in test_datasets_api.py

* Make next_offset optional in UploadListResponse

Author: va3093

.github/workflows/pull-request.yaml

@@ -45,5 +45,5 @@ jobs:
       - name: Run E2E tests (Python 3.13)
         env:
           DUNE_API_KEY: ${{ secrets.DUNE_API_KEY }}
+          DUNE_API_KEY_OWNER_HANDLE: ${{ secrets.DUNE_API_KEY_OWNER_HANDLE }}
         run: uv run --python 3.13 --dev python -m pytest tests/e2e -v
-

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="/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, full_name: str) -> DatasetResponse:
+        """
+        https://docs.dune.com/api-reference/datasets/endpoint/get
+        Retrieve detailed information about a specific dataset.
+
+        Args:
+            full_name: The dataset full name (e.g., 'dune.shozaib_khan.aarna')
+
+        Returns:
+            DatasetResponse with full dataset details including columns and metadata
+        """
+        response_json = self._get(route=f"/datasets/{full_name}")
+        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