Base Filters

class webgrid.filters.Operator(key, display, field_type, hint=None)

Filter operator representing name and potential inputs.

See webgrid.filters.ops for a collection of predefined operators.

Args:

key (str): Internal identifier to be used in code and in request args.

display (str): Label for rendering the operator.

field_type (str): Input field spec. Can be: - None: no input fields - input: single freeform text input - 2inputs: two freeform text inputs - select: single select box - select+input: select box as first input, freeform text as second

hint (str, optional): Input field hint to show in UI. Defaults to None.

class webgrid.filters.FilterBase(sa_col=None, default_op=None, default_value1=None, default_value2=None, dialect=None)

Base filter class interface for webgrid filters.

Contains filter operators, inputs, render information, and the inner workings to apply the filter to the database query as needed.

Args:

sa_col (Expression): SQLAlchemy expression to which we apply operator/values.

default_op (str, optional): UI shortcut to enable filter with the specified op if none is given by the user. Defaults to None.

default_value1 (str, optional): Use with default_op to set input. Defaults to None.

default_value2 (str, optional): Use with default_op to set input. Defaults to None.

dialect (str, optional): DB dialect in use, for filters supporting multiple DBMS platforms. Defaults to None.

Class attributes:

operators (tuple(Operator)): Available filter operators in the order they should appear.

primary_op (str, optional): Key of operator to be selected automatically when the filter is added in UI. Defaults to first available filter op.

init_attrs_for_instance (tuple(str)): Attributes to set when copying filter instance. Should not normally need to be set.

input_types (tuple(str)): Possible input types for renderer to make available. Can be “input”, “input2”, and/or “select”. Defaults to (“input”, ).

receives_list (bool): Filter takes a list of values in its set method. Defaults to False.

is_aggregate (bool): Filter applies to HAVING clause instead of WHERE

Instance attributes:

op (str): Operator key set by the user or programmatically.

value1 (Any): First input value following validation processing.

value2 (Any): Second input value following validation processing.

value1_set_with (str): First input value raw from set call.

value2_set_with (str): Second input value raw from set call.

error (bool): True if input processing encountered a validation error.

apply(query)

Query modifier to apply the needed clauses for filter inputs.

format_invalid(exc, col)

Wrapper for generating a validation error string.

get_search_expr()

Filters can be used for the general “single search” function on the grid. For this to work in SQL, the grid needs to pull search expressions from all filters and OR them together.

Return value is expected to be a callable taking one argument (the search value). E.g. lambda value: self.sa_col.like(‘%{}%’.format(value))

Return value of None is filtered out, essentially disabling search for the filter.

property is_active

Filter is active if op is set and input requirements are met.

property is_display_active

Filter display is active (i.e. show as a selected filter in UI) if op is set.

new_instance(**kwargs)

Note: Ensure any overrides of this method accept and pass through kwargs to preserve compatibility in future

property op_keys

List of Operator keys used by this filter.

process(value, is_value2)

Process the values as given to .set(), validating and manipulating as needed.

raise_unrecognized_op()

Specified operator was not in the filter’s list.

set(op, value1, value2=None)

Set filter operator and input values.

Stores the raw inputs, then processes the inputs for validation. Applies the default operator if needed.

Args:

op (str): Operator key. value1 (Any): First filter input value. Pass None if the operator takes no input. value2 (Any, optional): Second filter input value. Defaults to None.

Raises:

validators.ValueInvalid: One or more inputs did not validate.

class webgrid.filters.OptionsFilterBase(sa_col, value_modifier='auto', default_op=None, default_value1=None, default_value2=None)

Base class for filters having a list of options.

UI for these is a single select box. By default, these are all shown with a search box within the filter, and checkboxes to pick multiple items.

Notable args:

value_modifier (Union(str, callable, Validator), optional): modifier to apply to the input value(s) in the request. Generally, the options list in the filter will have the “true” type in the identifier, but the request will come in with strings. If value_modifier is “auto”, we’ll check one of the options IDs with some known types to pick a webgrid validator. Or, a webgrid validator can be passed in. Or, pass a callable, and it will be wrapped as a validator. Defaults to “auto”.

Class attributes:

options_from (tuple): Iterable of options available to the filter. Defined here as a class attribute, but can be overridden as an instance attribute, property, or method. Options are expected to be tuples of the form (key, value). key is the part that will be validated on input and used in the filter query clause. value is displayed in UI.

apply(query)

Query modifier to apply the needed clauses for filter inputs.

get_search_expr()

Match up a search value to option display, grab the corresponding keys, and search.

match_keys_for_value(value)

Used for single-search to match search value to part of an option’s display string.

new_instance(**kwargs)

Note: Ensure any overrides of this method accept and pass through kwargs to preserve compatibility in future

property option_keys

Extract a keys list from the options tuples.

property options_seq

Resolver for options_from that caches the options values.

Tries to treat options_from as a callable first, and if that fails, refers to it as an attribute/property value instead.

process(value)

Apply the value_modifier to a value.

set(op, values, value2=None)

Set the filter op/values to be used by query modifiers.

Since this type of filter has only one input box, value2 is ignored (present here for consistent API). Each of the items passed in the first filter value is processed with the selected/given validator. Any items that do not pass validation are ignored and left out of the query.

Args:

op (str): Operator key. values (iterable): List/tuple/iterable of values to be validated. value2 (Any, optional): Ignored. Defaults to None.

setup_validator()

Select a validator by type if value_modifier is “auto”, or wrap a callable.

class webgrid.filters.OptionsIntFilterBase(sa_col, value_modifier=<class 'webgrid.validators.IntValidator'>, default_op=None, default_value1=None, default_value2=None)

Base class for filters having a list of options with integer keys.

Shortcut for using OptionsFilterBase and supplying webgrid.validators.IntValidator as the value_modifier.