Utility module for Subgrounds

subgrounds.utils.merge(data1: list[T], data2: list[T]) list[T]#
subgrounds.utils.merge(data1: dict[str, T], data2: dict[str, T]) dict[str, T]

Merges data1 and data2 and returns the combined result.

data1 and data2 must be of the same type. Either both are dict or list.

>>> a = {'a': 1, 'b': {'c': 2, 'd': 3}}
>>> b = {'b': {'e': 4}, 'f': 5}
>>> merge(a, b)
{'a': 1, 'b': {'c': 2, 'd': 3, 'e': 4}, 'f': 5}

Combined data blob

Return type:

list[T] | dict[str, T]

class subgrounds.utils.Sentinel#

This class purely used for 'Sentinel' type values such as default arguments to functions (where None is a significant value) or as a default return (such as str.find, where -1 is returned if a substring isn't found).

subgrounds.utils.flatten_dict(data, keys=[])#

Takes a dictionary containing key-value pairs where all values are of type other than list and flattens it such that all key-value pairs in nested dictionaries are now at depth 1.

  • values (data Dictionary containing non-list) --

  • keys (list[str]) -- Keys of data if data is a nested dict (len(keys) == depth of data). Defaults to [].


Flat dictionary containing all key-value pairs in data and its nested


Return type:



Returns True if data contains a value of type list in its nested data and False otherwise


data (dict | list | str | int | float | bool) -- Data


True if data contains a list, False otherwise

Return type:



This defines a coroutine styled generator.

All this does is start the generator via a next call allowing you to use .send

immediately instead of needing to use gen.send(None) or next first.

Inspired from: http://www.dabeaz.com/coroutines/Coroutines.pdf (p. 27)

Essentially, the logic is as follows: >>> def start(*args, **kwargs): ... gen = func(*args, **kwargs) ... next(gen) ... return gen


Contains the default header information for requests made by subgrounds

Inserts the Playgrounds API Key iff:

a) targetting the Playgrounds API AND b) if the PLAYGROUNDS_API_KEY environment variable is set


A basic user agent describing the following details:

  • "Subgrounds" (and version)

  • Platform/OS (and architecture)

  • Python Type (and version)

Examples: - Subgrounds/1.1.2 (Darwin; arm64) CPython/3.11.2 - Subgrounds/1.1.2 (Emscripten; wasm32) CPython/3.10.2

⚠️ To override this, construct your Subgrounds with a headers

parameter with a dictionary containing an empty "User-Agent" key-value pairing.

Pandas DataFrame utility module containing functions related to the formatting of GraphQL JSON data into DataFrames.

class subgrounds.dataframe_utils.DataFrameColumns(key, fpaths)#

Helper class that holds data related to the shape of a DataFrame


Returns new DataFrameColumns containing the union of self and other's columns


other (Self) -- Columns to be combined to self


New Self containing the union of self and other

Return type:


mk_df(data, path_map)#

Formats the JSON data data into a DataFrame containing the columns defined in self.


The JSON data formatted into a DataFrame

Return type:



Generates a list of DataFrame columns specifications based on a list of Selection trees.


selections (list[subgrounds.query.Selection]) -- The selection trees


The list of DataFrame columns specifications

Return type:


subgrounds.dataframe_utils.df_of_json(json_data, fpaths, columns=None, concat=False)#

Formats the JSON data json_data into Pandas DataFrames, flattening the data in the process.

Depending on the request's fieldpaths, either one or multiple dataframes will be returned based on how flattenable the response data is.

fpaths is a list of FieldPath objects corresponding to the set of fieldpaths that were used to get the response data json_data.

columns is an optional argument used to rename the dataframes(s) columns. The length of columns must be the same as the number of columns of all returned dataframes.

concat indicates whether or not the resulting dataframes should be concatenated together. The dataframes must have the same number of columns, as well as the same column names (which can be set using the columns argument).


The resulting dataframe(s)

Return type:

pandas.core.frame.DataFrame | list[pandas.core.frame.DataFrame]