Subgrounds

A Pythonic data access layer for applications querying data from The Graph Network.

Design goals

• Simple: Small, easy to use toplevel API
• Automated: Schema introspection and class generation, type checking and pagination is all handled automatically
• Schema-driven: Queries are built with FieldPaths while transformations are defined with SyntheticFields, as opposed to raw GraphQL and transforming raw data

Docs

• Subgrounds Docs: User guide and API documentation (WIP)
• MetricsDAO Subgrounds Workshop: Subgrounds workshop series hosted by MetricsDAO
• Examples: A list of examples showcasing Subgrounds integration with Dash and Plotly
• Community projects: An ever growing list of projects created by our community members

Installation

IMPORTANT: Subgrounds requires Python version 3.10 or higher

Subgrounds is available on PyPi. To install it, run the following:
pip install subgrounds.

Subgrounds also comes bundled with some handy dash wrappers. To use those wrappers, you can install the extra dash dependencies.
pip install subgrounds[dash].

Simple example

>>> from subgrounds.subgrounds import Subgrounds

>>> sg = Subgrounds()
>>> aaveV2 = sg.load_subgraph('https://api.thegraph.com/subgraphs/name/aave/protocol-v2')

>>> aaveV2.Borrow.adjusted_amount = aaveV2.Borrow.amount / 10 ** aaveV2.Borrow.reserve.decimals

>>> last10_borrows = aaveV2.Query.borrows(
...   orderBy=aaveV2.Borrow.timestamp,
...   orderDirection='desc',
...   first=10
... )

>>> sg.query_df([
...   last10_borrows.reserve.symbol, 
...   last10_borrows.timestamp,
...   last10_borrows.adjusted_amount
... ])
  borrows_reserve_symbol  borrows_timestamp  borrows_adjusted_amount
0                   USDT         1643300294            500000.000000
1                    DAI         1643299575              6000.000000
2                   USDT         1643298921            900000.000000
3                   USDT         1643297685            500000.000000
4                   USDC         1643296256             50000.000000
5                    PAX         1643295342              4150.000000
6                   USDT         1643294783              9000.000000
7                    DAI         1643293451             45585.919063
8                    UNI         1643289600             50000.000000
9                   USDT         1643289117             14000.000000

About us

Protean Labs was started by web3 data enthusiasts to build open source tooling for The Graph Network as part of its grants program. Although Protean Labs remains an independent entity, the team has since joined Playgrounds with the goal of revolutionizing the web3 data stack.

Community

• Discord: Playgrounds' official discord server
• Twitter (Playgrounds): Playgrounds' official Twitter account
• Twitter (Protean Labs): Protean Labs' official Twitter account

Acknowledgments

This software project would not be possible without the support of The Graph Foundation. You can learn more about The Graph and its mission here.

This project also builds on the excellent work by the good folks over at Plotly. Lean more about Dash and Plotly here.