kapps_triplestore_interface.utils.processing#

kapps_triplestore_interface.utils.processing.process_bindings_select(bindings: list[dict[str, dict[str, Any]]], variables: list[str] | None = None, grouping_variables: list[str] | None = None) → tuple[tuple[Any, ...], ...] | tuple[Any, ...] | dict[source]#

Process SPARQL SELECT bindings into tuples or a nested dictionary.

Converts raw SPARQL JSON bindings (results.bindings) into a convenient Python structure for downstream processing and display.

Parameters:

  • bindings (list[dict[str, dict[str, Any]]]) – Raw bindings from SPARQL query results (i.e., response[‘results’][‘bindings’]).

  • variables (Optional[list[str]]) – Variable names (without leading ?) that define the tuple entries and their order in the result.

  • grouping_variables (Optional[list[str]]) – Grouping variable names (without leading ?) that define hierarchical dictionary keys in order. When provided, the result is a nested dict keyed by these values, with leaves as described below.

Returns:

When grouping_variables is not provided:

  • variables is empty or None -> () (empty tuple)

  • variables has length 1 -> (a1, a2, …) (tuple of scalar values)

  • variables has length > 1 -> ((a1, b1, …), (a2, b2, …), …) (tuple of tuples)

When grouping_variables is provided:

  • Nested dict keyed by the values of grouping_variables (in order)

  • Each leaf is processed using the entries in variables (shapes as above)

Return type:

tuple[tuple[Any, …], …] | tuple[Any, …] | dict

Raises:

  • AssertionError – If any values referenced by grouping_variables in the first binding are not hashable. Grouping keys must be hashable to serve as dict keys.

  • TypeError – If the bindings are empty and neither variables nor grouping_variables are provided.

Notes

  • variables and grouping_variables are expected without the leading ?.

  • If neither is provided, variables are inferred from the first binding when available.