Base#

SubgroundsBase

This module implements the base API that developers can use to build custom clients to

allow for intricate customization of the subgrounds feature set.

{{ lab_bdg }} The building of Custom Clients is an experimental feature.

class subgrounds.client.base.SubgroundsBase(timeout=30, headers=<factory>, global_transforms=<factory>, subgraphs=<factory>, schema_cache=PosixPath('schemas'))#

A base instance for all Subgrounds (should not be used directly)

classmethod from_pg_key(key, **kwargs)#

Create a Subgrounds* instance using a playgrounds key directly.

This sets the headers field internally to be used with all queries made out.

Parameters:

  • key (str) -- The aforementioned Playgrounds API Key

  • **kwargs (Any) -- Anything else to construct the Subgrounds* instance

Returns:

An instance Subgrounds* with Playgrounds API support baked in

Return type:

Self

make_request(fpaths)#

Creates a DataRequest object by combining one or more FieldPath objects.

Parameters:

fpaths (subgrounds.subgraph.fieldpath.FieldPath | list[subgrounds.subgraph.fieldpath.FieldPath]) -- One or more FieldPath objects that should be included in the request

Returns:

Brand new request

Return type:

DataRequest

mk_request(fpaths)#

Creates a DataRequest object by combining one or more FieldPath objects.

Parameters:

fpaths (subgrounds.subgraph.fieldpath.FieldPath | list[subgrounds.subgraph.fieldpath.FieldPath]) -- One or more FieldPath objects that should be included in the request

Returns:

Brand new request

Return type:

DataRequest

fetch_schema(url)#

Reads schema from filesystem based on subgraph_slug of the url

cache_schema(url, data)#

Writes schema into filesystem based on subgraph_slug of the url

_load(url, save_schema=False, is_subgraph=True)#

Loads a subgraph / graphql API by fetching the schema.

If save_schema is set True, grabs schema from disk and skips query made to

url.

`{note} This method utilizes the sans-io generator pattern. More on that [here](/subgrounds/advanced_topics/custom_clients/#methodology). `

_execute(req, pagination_strategy=LegacyStrategy)#

Executes a DataRequest and returns a DataResponse.

Parameters:

  • req (DataRequest) -- The DataRequest object to be executed.

  • pagination_strategy (Optional[Type[PaginationStrategy]]) -- A Class implementing the PaginationStrategy Protocol. If None, then automatic pagination is disabled. Defaults to LegacyStrategy.

Returns:

A DataResponse object representing the response

Return type:

Generator[Document, DocumentResponse, DataResponse]

_execute_iter(req, pagination_strategy=LegacyStrategy)#

Same as execute, except that an iterator is returned which will iterate the data pages.

Parameters:

  • req (DataRequest) -- The DataRequest object to be executed

  • pagination_strategy (Optional[Type[PaginationStrategy]]) -- A Class implementing the PaginationStrategy Protocol. If None, then automatic pagination is disabled. Defaults to LegacyStrategy.

Returns:

An iterator over the DocumentResponse pages.

Return type:

Generator[subgrounds.query.Document | subgrounds.query.DocumentResponse, DocumentResponse, None]

⚠️ DOES NOT apply global transforms across multiple documents or their pages.

Since we yield each page as we get it, it's not possible to accurately perform the transforms since we don't collect the pages. This means transforms expecting multiple documents or pages of documents will be inaccurate.