feat: async support for subgrounds (+ more) (#36)

# Features
- Adds `AsyncSubgrounds` as a new client to use `async/await` with subgrounds
- Adds `SubgroundsBase` as an experimental client base to be used to develop custom clients

# Changes
- The entirety of the transformation application has been refactored to be simplified
- Subgrounds is now sans-io, where `SubgroundsBase` handles all of the buisness logic, and the implementations adds the IO work (such as making the actual request).
- And much, much more ✨

CONTRIBUTING.md

@@ -19,7 +19,7 @@ We also use a `poetry` plugin called `poethepoet` to aid in managing our frequen
 $ poetry self add 'poethepoet[poetry_plugin]'
 ```
 
-<details>
+<details class="admonition hint dropdown toggle-hidden" style="padding: 0.75em">
 <summary>Alternative to using <code>poe</code></summary>
 <br>
 
@@ -52,13 +52,11 @@ We use [black](https://github.com/psf/black) and [ruff](https://github.com/charl
 - Black provides us an opinionated set of style conventions which helps keep the code consistent.
 - Ruff is a bleeding edge `flake8` replacement which helps us lint our code efficiently and effectively.
 
-This library also leverages python typing via the pyright project. We leverage the type-safety via the official [Python Vscode Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python).
+This library also leverages python typing via the pyright project. We leverage the type-safety via the official [Python VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python).
 
 All PRs should be type-checked and adhere to the `black` and `ruff` style conventions.
 
-> Note: We recently moved towards using tools like `black` to help us maintain our codebase. However, our codebase is *still* adapting so there might be several rough edges (hense why we don't enforce linting in our CI yet). If you would like to help us improve these edges, feel free to make a PR!
-
 ```bash
-$ poe format  # doesn't run `ruff check --fix` yet
+$ poe format
 $ poe check
 ```

README.md

@@ -22,10 +22,10 @@ An intuitive python library for interfacing with Subgraphs.
 <!-- end elevator-pitch -->
 
 ## Resources
-- [**Subgrounds Docs**](http://docs.playgrounds.network/): User guide and API documentation
-- [**Examples**](https://github.com/0xPlaygrounds/subgrounds/tree/main/examples): A list of examples showcasing Subgrounds integration with Dash and Plotly
-- [**Tutorials**](https://docs.playgrounds.network/subgrounds/tutorials/): Subgrounds video workshops and tutorials
-- [**Community Projects**](http://docs.playgrounds.network/subgrounds/examples/): An ever growing list of projects created by our community members
+- [**Docs**](http://docs.playgrounds.network/): User guide and API documentation
+- [**Snippets**](https://github.com/0xPlaygrounds/subgrounds/tree/main/examples): A list of examples showcasing Subgrounds integration with Dash and Plotly
+- [**Examples**](http://docs.playgrounds.network/subgrounds/examples/): An ever growing list of projects created by our community members and team
+- [**Videos**](https://docs.playgrounds.network/subgrounds/videos/): Video workshops on Subgrounds
 
 ## Installation
 > Subgrounds **requires** atleast Python 3.10+

pyproject.toml

@@ -13,34 +13,29 @@ keywords = ["graph", "subgrounds", "graphql", "subgraph"]
 
 [tool.poetry.dependencies]
 python = "^3.10"
-requests = "^2.27.1"
 pandas = "^1.4.2"
 pipe = "^2.0"
 pydantic = "^1.10.2"
 dash = { version = "^2.3.1", optional = true }
 plotly = { version = "^5.14.1", optional = true }
-pyodide-http = { version = "^0.2.1", optional = true }
-gql = "^3.4.0"
-aiohttp = "^3.8.4"
+httpx = { extras = ["http2"], version = "^0.24.1" }
+pytest-asyncio = "^0.21.0"
 
 [tool.poetry.extras]
 dash = ["dash"]
 plotly = ["plotly"]
-pyodide = ["pyodide-http"]
-all = ["dash", "plotly", "pyodide-http"]
+all = ["dash", "plotly"]
 
 # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
 [tool.poetry.group.dev.dependencies]
 black = "^22.3.0"
 deepdiff = "^6.2.1"                 # used for debugging data structures
 ipykernel = "^6.13.0"
 mypy = "^0.950"
-nose2 = "^0.11.0"
 pytest = "^7.1.2"
 pytest-mock = "^3.8.2"
 python-semantic-release = "^7.33.1"
 ruff = "^0.0.253"
-pytest-insta = "^0.2.0"
 
 [tool.poe.tasks]
 format = "black subgrounds examples tests"
@@ -67,6 +62,9 @@ build_command = "poetry build"
 "subgrounds/plotly_wrappers" = ["F405", "F403"]
 "subgrounds/dash_wrappers" = ["F405", "F403"]
 
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

subgrounds/__init__.py

@@ -1,17 +1,12 @@
+from subgrounds.client import AsyncSubgrounds, Subgrounds
 from subgrounds.subgraph import FieldPath, Subgraph, SyntheticField
-from subgrounds.subgrounds import Subgrounds
 
 __version__ = "1.6.1"
 
 __all__ = [
+    "AsyncSubgrounds",
     "FieldPath",
     "Subgraph",
     "Subgrounds",
     "SyntheticField",
 ]
-
-### Pyodide Patch ###
-
-from subgrounds.contrib import pyodide as _pyodide
-
-_pyodide.patch()

subgrounds/client/__init__.py

@@ -0,0 +1,16 @@
+""" Top-level Subgrounds subpackage
+
+This subpackage implements the top-level API that most developers will be using when
+ querying subgraphs with Subgrounds. `Subgrounds` and `AsyncSubgrounds` contains fully
+ implemented subgraph querying SDKs for accessing subgraph data (flattened or nested)
+ effectively with transformation and pagination bundled in.
+
+`SubgroundsBase` provides an extended interface to build custom clients on-top allowing
+ for intricate customization on the buisness logic subgrounds implements.
+"""
+
+from .async_ import AsyncSubgrounds
+from .base import SubgroundsBase
+from .sync import Subgrounds
+
+__all__ = ["AsyncSubgrounds", "Subgrounds", "SubgroundsBase"]