buildgrid.server.persistence.sql.utils module

Holds constants and utility functions for the SQL scheduler.

buildgrid.server.persistence.sql.utils.strtobool(val: str) bool

Convert a string representation of truth to true (1) or false (0). True values are ‘y’, ‘yes’, ‘t’, ‘true’, ‘on’, and ‘1’; false values are ‘n’, ‘no’, ‘f’, ‘false’, ‘off’, and ‘0’. Raises ValueError if ‘val’ is anything else.

buildgrid.server.persistence.sql.utils.parse_list_operations_sort_value(value: str, column: Column) Any

Convert the string representation of a value to the proper Python type.

buildgrid.server.persistence.sql.utils.dump_list_operations_token_value(token_value: Any) str

Convert a value to a string for use in the page_token.

buildgrid.server.persistence.sql.utils.build_pagination_clause_for_sort_key(sort_value: Any, previous_sort_values: List[Any], sort_keys: List[SortKey]) ClauseElement

Build part of a filter clause to figure out the starting point of the page given by the page_token. See the docstring of build_page_filter for more details.

buildgrid.server.persistence.sql.utils.build_page_filter(page_token: str, sort_keys: List[SortKey]) ClauseElement

Build a filter to determine the starting point of the rows to fetch, based on the page_token.

The page_token is directly related to the sort order, and in this way it acts as a “cursor.” It is given in the format Xval|Yval|Zval|…, where each element is a value corresponding to an orderable column in the database. If the corresponding rows are X, Y, and Z, then X is the primary sort key, with Y breaking ties between X, and Z breaking ties between X and Y. The corresponding filter clause is then:

(X > Xval) OR (X == XVal AND Y > Yval) OR (X == Xval AND Y == Yval AND Z > Zval) …

buildgrid.server.persistence.sql.utils.build_page_token(operation: Column, sort_keys: List[SortKey]) str

Use the sort keys to build a page token from the given operation.

buildgrid.server.persistence.sql.utils.extract_sort_keys(operation_filters: List[OperationFilter]) Tuple[List[SortKey], List[OperationFilter]]

Splits the operation filters into sort keys and non-sort filters, returning both as separate lists.

Sort keys are specified with the “sort_order” parameter in the filter string. Multiple “sort_order”s can appear in the filter string, and all are extracted and returned.

buildgrid.server.persistence.sql.utils.build_sort_column_list(sort_keys: List[SortKey]) List[ColumnOperators[Any]]

Convert the list of sort keys into a list of columns that can be passed to an order_by.

This function checks the sort keys to ensure that they are in the parameter-model map and raises an InvalidArgumentError if they are not.

buildgrid.server.persistence.sql.utils.convert_filter_to_sql_filter(operation_filter: OperationFilter) ClauseElement

Convert the internal representation of a filter to a representation that SQLAlchemy can understand. The return type is a “ColumnElement,” per the end of this section in the SQLAlchemy docs: https://docs.sqlalchemy.org/en/13/core/tutorial.html#selecting-specific-columns

This function assumes that the parser has appropriately converted the filter value to a Python type that can be compared to the parameter.

buildgrid.server.persistence.sql.utils.build_custom_filters(operation_filters: List[OperationFilter]) List[ClauseElement]