Utils#

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}

Parameters:

data1 (list[T] | dict[str, T]) -- First data blob
data2 (list[T] | dict[str, T]) -- Second data blob

Returns:

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.

Parameters:

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 [].

Returns:

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

Return type:

dict

subgrounds.utils.contains_list(data)#

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

Parameters:: data (dict | list | str | int | float | bool) -- Data
Returns:: True if data contains a list, False otherwise
Return type:: bool

subgrounds.utils.coroutine_generator(func)#

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

subgrounds.utils.default_header(url)#

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

subgrounds.utils.user_agent()#

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

combine(other)#

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

Parameters:: other (Self) -- Columns to be combined to self
Returns:: New Self containing the union of self and other
Return type:: Self

mk_df(data, path_map)#

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

Parameters:

data (list[dict[str, Any]]) -- The JSON data to be formatted into a dataframe
path_map (dict[str, subgrounds.subgraph.fieldpath.FieldPath]) -- A dictionary of (key-FieldPath) pairs

Returns:

The JSON data formatted into a DataFrame

Return type:

DataFrame

subgrounds.dataframe_utils.columns_of_selections(selections)#

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

Parameters:: selections (list[subgrounds.query.Selection]) -- The selection trees
Returns:: The list of DataFrame columns specifications
Return type:: list[subgrounds.dataframe_utils.DataFrameColumns]

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).

Parameters:

json_data (list[dict[str, Any]]) -- Response data
fpaths (list[subgrounds.subgraph.fieldpath.FieldPath]) -- Fieldpaths that yielded the response data
columns (Optional[list[str]]) -- Column names. Defaults to None.
concat (bool) -- Flag indicating whether or not to concatenate the resulting dataframes, if there are more than one. Defaults to False.

Returns:

The resulting dataframe(s)

Return type:

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