async api should match sync api (#179)

mewwts · web-flow · commit fbefedf40561 · 2025-10-02T09:43:27.000+02:00
match sync api
diff --git a/dune_client/client_async.py b/dune_client/client_async.py
@@ -24,6 +24,7 @@
     ContentTypeError,
     TCPConnector,
 )
+from deprecated import deprecated
 
 from dune_client.api.base import (
     DUNE_CSV_NEXT_OFFSET_HEADER,
@@ -196,7 +197,10 @@ async def _request(
                 return response
             return await self._handle_response(response)
 
-    async def execute(self, query: QueryBase, performance: str | None = None) -> ExecutionResponse:
+    async def execute_query(
+        self, query: QueryBase, performance: str | None = None
+    ) -> ExecutionResponse:
+        """Post's to Dune API for execute `query`"""
         params = query.request_format()
         params["performance"] = performance or self.performance
 
@@ -210,14 +214,15 @@ async def execute(self, query: QueryBase, performance: str | None = None) -> Exe
         except KeyError as err:
             raise DuneError(response_json, "ExecutionResponse", err) from err
 
-    async def get_status(self, job_id: str) -> ExecutionStatusResponse:
+    async def get_execution_status(self, job_id: str) -> ExecutionStatusResponse:
+        """GET status from Dune API for `job_id` (aka `execution_id`)"""
         response_json = await self._get(route=f"/execution/{job_id}/status")
         try:
             return ExecutionStatusResponse.from_dict(response_json)
         except KeyError as err:
             raise DuneError(response_json, "ExecutionStatusResponse", err) from err
 
-    async def get_result(
+    async def get_execution_results(
         self,
         job_id: str,
         batch_size: int | None = None,
@@ -226,6 +231,7 @@ async def get_result(
         filters: str | None = None,
         sort_by: list[str] | None = None,
     ) -> ResultsResponse:
+        """GET results from Dune API for `job_id` (aka `execution_id`)"""
         self._validate_sampling(sample_count, batch_size, filters)
 
         if sample_count is None and batch_size is None:
@@ -243,7 +249,7 @@ async def get_result(
             self._get_result_by_url,
         )
 
-    async def get_result_csv(
+    async def get_execution_results_csv(
         self,
         job_id: str,
         batch_size: int | None = None,
@@ -257,7 +263,7 @@ async def get_result_csv(
 
         this API only returns the raw data in CSV format, it is faster & lighterweight
         use this method for large results where you want lower CPU and memory overhead
-        if you need metadata information use get_results() or get_status()
+        if you need metadata information use get_execution_results() or get_execution_status()
         """
         self._validate_sampling(sample_count, batch_size, filters)
 
@@ -320,11 +326,70 @@ async def cancel_execution(self, job_id: str) -> bool:
         else:
             return success
 
+    #######################
+    # Deprecated Functions:
+    #######################
+    @deprecated(version="1.9.3", reason="Please use execute_query")
+    async def execute(self, query: QueryBase, performance: str | None = None) -> ExecutionResponse:
+        """Post's to Dune API for execute `query`"""
+        return await self.execute_query(query, performance)
+
+    @deprecated(version="1.9.3", reason="Please use get_execution_status")
+    async def get_status(self, job_id: str) -> ExecutionStatusResponse:
+        """GET status from Dune API for `job_id` (aka `execution_id`)"""
+        return await self.get_execution_status(job_id)
+
+    @deprecated(version="1.9.3", reason="Please use get_execution_results")
+    async def get_result(
+        self,
+        job_id: str,
+        batch_size: int | None = None,
+        columns: list[str] | None = None,
+        sample_count: int | None = None,
+        filters: str | None = None,
+        sort_by: list[str] | None = None,
+    ) -> ResultsResponse:
+        """GET results from Dune API for `job_id` (aka `execution_id`)"""
+        return await self.get_execution_results(
+            job_id,
+            batch_size=batch_size,
+            columns=columns,
+            sample_count=sample_count,
+            filters=filters,
+            sort_by=sort_by,
+        )
+
+    @deprecated(version="1.9.3", reason="Please use get_execution_results_csv")
+    async def get_result_csv(
+        self,
+        job_id: str,
+        batch_size: int | None = None,
+        columns: list[str] | None = None,
+        sample_count: int | None = None,
+        filters: str | None = None,
+        sort_by: list[str] | None = None,
+    ) -> ExecutionResultCSV:
+        """
+        GET results in CSV format from Dune API for `job_id` (aka `execution_id`)
+
+        this API only returns the raw data in CSV format, it is faster & lighterweight
+        use this method for large results where you want lower CPU and memory overhead
+        if you need metadata information use get_execution_results() or get_execution_status()
+        """
+        return await self.get_execution_results_csv(
+            job_id,
+            batch_size=batch_size,
+            columns=columns,
+            sample_count=sample_count,
+            filters=filters,
+            sort_by=sort_by,
+        )
+
     ########################
     # Higher level functions
     ########################
 
-    async def refresh(
+    async def run_query(
         self,
         query: QueryBase,
         ping_frequency: int = 5,
@@ -343,7 +408,7 @@ async def refresh(
         self._validate_sampling(sample_count, batch_size, filters)
 
         job_id = await self._refresh(query, ping_frequency=ping_frequency, performance=performance)
-        return await self.get_result(
+        return await self.get_execution_results(
             job_id,
             columns=columns,
             sample_count=sample_count,
@@ -352,7 +417,7 @@ async def refresh(
             batch_size=batch_size,
         )
 
-    async def refresh_csv(
+    async def run_query_csv(
         self,
         query: QueryBase,
         ping_frequency: int = 5,
@@ -371,7 +436,7 @@ async def refresh_csv(
         self._validate_sampling(sample_count, batch_size, filters)
 
         job_id = await self._refresh(query, ping_frequency=ping_frequency, performance=performance)
-        return await self.get_result_csv(
+        return await self.get_execution_results_csv(
             job_id,
             columns=columns,
             sample_count=sample_count,
@@ -380,7 +445,7 @@ async def refresh_csv(
             batch_size=batch_size,
         )
 
-    async def refresh_into_dataframe(
+    async def run_query_dataframe(
         self,
         query: QueryBase,
         performance: str | None = None,
@@ -394,13 +459,13 @@ async def refresh_into_dataframe(
         Execute a Dune Query, waits till execution completes,
         fetched and returns the result as a Pandas DataFrame
 
-        This is a convenience method that uses refresh_csv underneath
+        This is a convenience method that uses run_query_csv() + pandas.read_csv() underneath
         """
         try:
             import pandas as pd  # noqa: PLC0415
         except ImportError as exc:
             raise ImportError("dependency failure, pandas is required but missing") from exc
-        results = await self.refresh_csv(
+        results = await self.run_query_csv(
             query,
             performance=performance,
             columns=columns,
@@ -411,6 +476,92 @@ async def refresh_into_dataframe(
         )
         return pd.read_csv(results.data)
 
+    ######################
+    # Deprecated Functions
+    ######################
+    @deprecated(version="1.9.3", reason="Please use run_query")
+    async def refresh(
+        self,
+        query: QueryBase,
+        ping_frequency: int = 5,
+        performance: str | None = None,
+        batch_size: int | None = None,
+        columns: list[str] | None = None,
+        sample_count: int | None = None,
+        filters: str | None = None,
+        sort_by: list[str] | None = None,
+    ) -> ResultsResponse:
+        """
+        Executes a Dune `query`, waits until execution completes,
+        fetches and returns the results.
+        Sleeps `ping_frequency` seconds between each status request.
+        """
+        return await self.run_query(
+            query,
+            ping_frequency=ping_frequency,
+            performance=performance,
+            batch_size=batch_size,
+            columns=columns,
+            sample_count=sample_count,
+            filters=filters,
+            sort_by=sort_by,
+        )
+
+    @deprecated(version="1.9.3", reason="Please use run_query_csv")
+    async def refresh_csv(
+        self,
+        query: QueryBase,
+        ping_frequency: int = 5,
+        performance: str | None = None,
+        batch_size: int | None = None,
+        columns: list[str] | None = None,
+        sample_count: int | None = None,
+        filters: str | None = None,
+        sort_by: list[str] | None = None,
+    ) -> ExecutionResultCSV:
+        """
+        Executes a Dune query, waits till execution completes,
+        fetches and the results in CSV format
+        (use it load the data directly in pandas.from_csv() or similar frameworks)
+        """
+        return await self.run_query_csv(
+            query,
+            ping_frequency=ping_frequency,
+            performance=performance,
+            batch_size=batch_size,
+            columns=columns,
+            sample_count=sample_count,
+            filters=filters,
+            sort_by=sort_by,
+        )
+
+    @deprecated(version="1.9.3", reason="Please use run_query_dataframe")
+    async def refresh_into_dataframe(
+        self,
+        query: QueryBase,
+        performance: str | None = None,
+        batch_size: int | None = None,
+        columns: list[str] | None = None,
+        sample_count: int | None = None,
+        filters: str | None = None,
+        sort_by: list[str] | None = None,
+    ) -> Any:
+        """
+        Execute a Dune Query, waits till execution completes,
+        fetched and returns the result as a Pandas DataFrame
+
+        This is a convenience method that uses run_query_csv underneath
+        """
+        return await self.run_query_dataframe(
+            query,
+            performance=performance,
+            batch_size=batch_size,
+            columns=columns,
+            sample_count=sample_count,
+            filters=filters,
+            sort_by=sort_by,
+        )
+
     #################
     # Private Methods
     #################
@@ -522,11 +673,11 @@ async def _refresh(
         ping_frequency: int = 5,
         performance: str | None = None,
     ) -> str:
-        job_id = (await self.execute(query=query, performance=performance)).execution_id
+        job_id = (await self.execute_query(query=query, performance=performance)).execution_id
         terminal_states = ExecutionState.terminal_states()
 
         while True:
-            status = await self.get_status(job_id)
+            status = await self.get_execution_status(job_id)
             if status.state in terminal_states:
                 if status.state == ExecutionState.FAILED:
                     self.logger.error(status)
diff --git a/tests/e2e/test_async_client.py b/tests/e2e/test_async_client.py
@@ -18,27 +18,27 @@ def setUp(self) -> None:
     async def test_disconnect(self):
         dune = AsyncDuneClient()
         await dune.connect()
-        results = (await dune.refresh(self.query)).get_rows()
+        results = (await dune.run_query(self.query)).get_rows()
         assert len(results) > 0
         await dune.disconnect()
         assert dune._session is None
 
-    async def test_refresh_context_manager_singleton(self):
+    async def test_run_query_context_manager_singleton(self):
         dune = AsyncDuneClient()
         async with dune as cl:
-            results = (await cl.refresh(self.query)).get_rows()
+            results = (await cl.run_query(self.query)).get_rows()
         assert len(results) > 0
 
-    async def test_refresh_context_manager(self):
+    async def test_run_query_context_manager(self):
         async with AsyncDuneClient() as cl:
-            results = (await cl.refresh(self.query)).get_rows()
+            results = (await cl.run_query(self.query)).get_rows()
         assert len(results) > 0
 
-    async def test_refresh_with_pagination(self):
+    async def test_run_query_with_pagination(self):
         # Arrange
         async with AsyncDuneClient() as cl:
             # Act
-            results = (await cl.refresh(self.multi_rows_query, batch_size=1)).get_rows()
+            results = (await cl.run_query(self.multi_rows_query, batch_size=1)).get_rows()
 
         # Assert
         assert results == [
@@ -49,20 +49,20 @@ async def test_refresh_with_pagination(self):
             {"number": 5},
         ]
 
-    async def test_refresh_with_filters(self):
+    async def test_run_query_with_filters(self):
         # Arrange
         async with AsyncDuneClient() as cl:
             # Act
-            results = (await cl.refresh(self.multi_rows_query, filters="number < 3")).get_rows()
+            results = (await cl.run_query(self.multi_rows_query, filters="number < 3")).get_rows()
 
         # Assert
         assert results == [{"number": 1}, {"number": 2}]
 
-    async def test_refresh_csv_with_pagination(self):
+    async def test_run_query_csv_with_pagination(self):
         # Arrange
         async with AsyncDuneClient() as cl:
             # Act
-            result_csv = await cl.refresh_csv(self.multi_rows_query, batch_size=1)
+            result_csv = await cl.run_query_csv(self.multi_rows_query, batch_size=1)
 
         # Assert
         assert pd.read_csv(result_csv.data).to_dict(orient="records") == [
@@ -73,11 +73,11 @@ async def test_refresh_csv_with_pagination(self):
             {"number": 5},
         ]
 
-    async def test_refresh_csv_with_filters(self):
+    async def test_run_query_csv_with_filters(self):
         # Arrange
         async with AsyncDuneClient() as cl:
             # Act
-            result_csv = await cl.refresh_csv(self.multi_rows_query, filters="number < 3")
+            result_csv = await cl.run_query_csv(self.multi_rows_query, filters="number < 3")
 
         # Assert
         assert pd.read_csv(result_csv.data).to_dict(orient="records") == [
@@ -86,9 +86,9 @@ async def test_refresh_csv_with_filters(self):
         ]
 
     @unittest.skip("Large performance tier doesn't currently work.")
-    async def test_refresh_context_manager_performance_large(self):
+    async def test_run_query_context_manager_performance_large(self):
         async with AsyncDuneClient() as cl:
-            results = (await cl.refresh(self.query, performance="large")).get_rows()
+            results = (await cl.run_query(self.query, performance="large")).get_rows()
         assert len(results) > 0
 
     async def test_get_latest_result_with_query_object(self):
diff --git a/tests/unit/test_async_client_logic.py b/tests/unit/test_async_client_logic.py
