Skip to main content

A simple framework for interacting with Dune Analytics official API service.

Project description

Python 3.11 Code style: black License Build

Dune Client

A python framework for interacting with Dune Analytics' officially supported API service.

Installation

Import as a project dependency

pip install dune-client

Example Usage

Quickstart: run_query

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)

Further Examples

Get Latest Results

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)

Paid Subscription Features

CRUD Operations

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)

Developer Usage & Deployment

Makefile

This project's makefile comes equipped with sufficient commands for local development.

Installation

make install

Format, Lint & Types

make check

can also be run individually with fmt, lint and types respectively.

Testing

make test-unit  # Unit tests 
make test-e2e   # Requires valid `DUNE_API_KEY`

can also run both with make test-all

Deployment

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dune_client-1.6.0.tar.gz (41.7 kB view hashes)

Uploaded Source

Built Distribution

dune_client-1.6.0-py3-none-any.whl (36.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page