3.10.12. ResultSpecs

Result specifications are used by the Data API to describe the desired results of a get call. They can be used to filter, sort and paginate the contents of collections, and to limit the fields returned for each item.

Python calls to get can pass a ResultSpec instance directly. Requests to the HTTP REST API are converted into instances automatically.

Implementers of Data API endpoints can ignore result specifications entirely, except where efficiency suffers. Any filters, sort keys, and so on still present after the endpoint returns its result are applied generically. ResultSpec instances are mutable, so endpoints that do apply some of the specification can remove parts of the specification.

Result specifications are applied in the following order:

  • Field Selection (fields)

  • Filters

  • Order

  • Pagination (limit/offset)

  • Properties

Only fields & properties are applied to non-collection results. Endpoints processing a result specification should take care to replicate this behavior.

class buildbot.data.resultspec.ResultSpec

A result specification has the following attributes, which should be treated as read-only:

filters

A list of Filter instances to be applied. The result is a logical AND of all filters.

fields

A list of field names that should be included, or None for no sorting. if the field names all begin with -, then those fields will be omitted and all others included.

order

A list of field names to sort on. if any field name begins with -, then the ordering on that field will be in reverse.

limit

The maximum number of collection items to return.

offset

The 0-based index of the first collection item to return.

properties

A list of Property instances to be applied. The result is a logical AND of all properties.

All of the attributes can be supplied as constructor keyword arguments.

Endpoint implementations may call these methods to indicate that they have processed part of the result spec. A subsequent call to apply will then not waste time re-applying that part.

popProperties()

If a property exists, return its values list and remove it from the result spec.

popFilter(field, op)

If a filter exists for the given field and operator, return its values list and remove it from the result spec.

popBooleanFilter(field)

If a filter exists for the field, remove it and return the expected value (True or False); otherwise return None. This method correctly handles odd cases like field__ne=false.

popStringFilter(field)

If one string filter exists for the field, remove it and return the expected value (as string); otherwise return None.

popIntegerFilter(field)

If one integer filter exists for the field, remove it and return the expected value (as integer); otherwise return None. raises ValueError if the field is not convertible to integer.

removePagination()

Remove the pagination attributes (limit and offset) from the result spec. And endpoint that calls this method should return a ListResult instance with its pagination attributes set appropriately.

removeOrder()

Remove the order attribute.

popField(field)

Remove a single field from the fields attribute, returning True if it was present. Endpoints can use this in conditionals to avoid fetching particularly expensive fields from the DB API.

The following method is used internally to apply any remaining parts of a result spec that are not handled by the endpoint.

apply(data)

Apply the result specification to the data, returning a transformed copy of the data. If the data is a collection, then the result will be a ListResult instance.

class buildbot.data.resultspec.Filter(field, op, values)
Parameters:

  • field (string) – the field to filter on

  • op (string) – the comparison operator (e.g., “eq” or “gt”)

  • values (list) – the values on the right side of the operator

A filter represents a limitation of the items from a collection that should be returned.

Many operators, such as “gt”, only accept one value. Others, such as “eq” or “ne”, can accept multiple values. In either case, the values must be passed as a list.

class buildbot.data.resultspec.Property(values)
Parameters:

values (list) – the values on the right side of the operator (eq)

A property represents an item of a foreign table.

In either case, the values must be passed as a list.