keystone.common.driver_hints module

class keystone.common.driver_hints.Hints

Bases: object

Encapsulate driver hints for listing entities.

Hints are modifiers that affect the return of entities from a list_<entities> operation. They are typically passed to a driver to give direction as to what filtering, pagination or list limiting actions are being requested.

It is optional for a driver to action some or all of the list hints, but any filters that it does satisfy must be marked as such by calling removing the filter from the list.

A Hint object contains filters, which is a list of dicts that can be accessed publicly. Also it contains a dict called limit, which will indicate the amount of data we want to limit our listing to.

If the filter is discovered to never match, then cannot_match can be set to indicate that there will not be any matches and the backend work can be short-circuited.

Each filter term consists of:

• name: the name of the attribute being matched

• value: the value against which it is being matched

• comparator: the operation, which can be one of equals,

  contains, startswith or endswith

• case_sensitive: whether any comparison should take account of

  case

add_filter(name, value, comparator: str = 'equals', case_sensitive: bool = False)

Add a filter to the filters list, which is publicly accessible.

get_exact_filter_by_name(name)

Return a filter key and value if exact filter exists for name.

get_limit_or_max() → int

Get page limit or max page size

Return page limit (size) as requested by user (or API flow) or the maximum page size if not present. This method is invoked by the SQL drivers.

Returns int:

Page size

get_limit_with_default(default_limit: int | None = None) → int

Return page limit for the query.

1. limit was set in the query parameters:

   min(limit, MAX_LIMIT)

2. limit is not set and default_limit is set:

   min(default_limit, MAX_LIMIT)

2. limit is null, default_limit is null, CONF.list_limit is set:

   min(CONF.list_limit, MAX_LIMIT)

3. limit is null, default_limit is null, CONF.list_limit is null:

   CONF.max_db_limit

set_limit(limit: int, truncated: bool = False)

Set a limit to indicate the list should be truncated.

set_marker(marker: str)

Set a marker pointing to the last entry of the page.

keystone.common.driver_hints.truncated(f)

Ensure list truncation is detected in Driver list entity methods.

This is designed to wrap Driver list_{entity} methods in order to calculate if the resultant list has been truncated. Provided a limit dict is found in the hints list, we increment the limit by one so as to ask the wrapped function for one more entity than the limit, and then once the list has been generated, we check to see if the original limit has been exceeded, in which case we truncate back to that limit and set the ‘truncated’ boolean to ‘true’ in the hints limit dict.