A python framework for interacting with Dune Analytics' officially supported API service.
Import as a project dependency
pip install dune-client
Export your DUNE_API_KEY
(or place it in a .env
file - as in
here .env.sample and source .env
).
from dune_client.types import QueryParameter
from dune_client.client import DuneClient
from dune_client.query import QueryBase
query = QueryBase(
name="Sample Query",
query_id=1215383,
params=[
QueryParameter.text_type(name="TextField", value="Word"),
QueryParameter.number_type(name="NumberField", value=3.1415926535),
QueryParameter.date_type(name="DateField", value="2022-05-04 00:00:00"),
QueryParameter.enum_type(name="EnumField", value="Option 1"),
],
)
print("Results available at", query.url())
dune = DuneClient.from_env()
results = dune.run_query(query)
# or as CSV
# results_csv = dune.run_query_csv(query)
# or as Pandas Dataframe
# results_df = dune.run_query_dataframe(query)
Use get_latest_results
to get the most recent query results without using execution credits.
You can specify a max_age_hours
to re-run the query if the data is too outdated.
from dune_client.client import DuneClient
dune = DuneClient.from_env()
results = dune.get_latest_result(1215383, max_age_hours=8)
If you're writing scripts that rely on Dune query results and want to ensure that your local,
peer-reviewed, queries are being used at runtime, you can call update_query
before run_query
!
Here is a fictitious example making use of this functionality;
from dune_client.types import QueryParameter
from dune_client.client import DuneClient
sql = """
SELECT block_time, hash,
FROM ethereum.transactions
ORDER BY CAST(gas_used as uint256) * CAST(gas_price AS uint256) DESC
LIMIT {{N}}
"""
dune = DuneClient.from_env()
query = dune.create_query(
name="Top {N} Most Expensive Transactions on Ethereum",
query_sql=sql,
# Optional fields
params=[QueryParameter.number_type(name="N", value=10)],
is_private=False # default
)
query_id = query.base.query_id
print(f"Created query with id {query.base.query_id}")
# Could retrieve using
# dune.get_query(query_id)
dune.update_query(
query_id,
# All parameters below are optional
name="Top {N} Most Expensive Transactions on {Blockchain}",
query_sql=sql.replace("ethereum", "{{Blockchain}}"),
params=query.base.parameters() + [QueryParameter.text_type("Blockchain", "ethereum")],
description="Shows time and hash of the most expensive transactions",
tags=["XP€N$IV $H1T"]
)
dune.archive_query(query_id)
dune.unarchive_query(query_id)
dune.make_private(query_id)
dune.make_public(query_id)
This project's makefile comes equipped with sufficient commands for local development.
make install
make check
can also be run individually with fmt
, lint
and types
respectively.
make test-unit # Unit tests
make test-e2e # Requires valid `DUNE_API_KEY`
can also run both with make test-all
Publishing releases to PyPi is configured automatically via github actions (cf. ./.github/workflows/py-publish.yaml). Any time a branch is tagged for release this workflow is triggered and published with the same version name.