wuttaweb.grids.filters

Grid Filters

class wuttaweb.grids.filters.AlchemyFilter(*args, **kwargs)

Filter option for a grid with SQLAlchemy query data.

This is a subclass of GridFilter. It requires a model_property to know how to filter the query.

Parameters:

model_property – Property of a model class, representing the column by which to filter. For instance, model.Person.full_name.

filter_equal(query, value)

Filter data with an equal (=) condition.

filter_greater_equal(query, value)

Filter data with a greater than or equal (>=) condition.

filter_greater_than(query, value)

Filter data with a greater than (>) condition.

filter_is_not_null(query, value)

Filter data with an IS NOT NULL query. The value is ignored.

filter_is_null(query, value)

Filter data with an IS NULL query. The value is ignored.

filter_less_equal(query, value)

Filter data with a less than or equal (<=) condition.

filter_less_than(query, value)

Filter data with a less than (<) condition.

filter_not_equal(query, value)

Filter data with a not equal (!=) condition.

class wuttaweb.grids.filters.BooleanAlchemyFilter(*args, **kwargs)

SQLAlchemy filter option for a boolean data column.

Subclass of AlchemyFilter.

filter_is_false(query, value)

Filter data with an “is false” condition. The value is ignored.

filter_is_false_null(query, value)

Filter data with “is false or null” condition. The value is ignored.

filter_is_true(query, value)

Filter data with an “is true” condition. The value is ignored.

class wuttaweb.grids.filters.DateAlchemyFilter(*args, **kwargs)

SQLAlchemy filter option for a Date column.

Subclass of AlchemyFilter.

This filter class has custom logic to coerce the input value, but does not have custom filter logic beyond that.

coerce_value(value)

Convert the given value to a proper datetime.date object, if applicable.

If the input value is already a date object, it is returned as-is.

Otherwise it is assumed to be a string in %Y-%m-%d format, and will be converted to a date object.

If the conversion fails, or no value is provided, None is returned.

class wuttaweb.grids.filters.DateTimeAlchemyFilter(*args, **kwargs)

SQLAlchemy filter option for a DateTime column.

Subclass of DateAlchemyFilter.

This filter class has custom logic to coerce the input value, inherited from parent class. It also has custom filter logic for most verbs (not/equal, greater/less than etc.).

Please note that this class assumes the underlying data uses “naive UTC” values. It therefore will convert to/from local time zone accordingly, to ensure user gets the data they expect. For more info see DateTime Behavior.

filter_equal(query, value)

Find all records with datetime values which fall on the given date.

filter_greater_equal(query, value)

Find all records with datetime values which fall on or after the given date.

filter_greater_than(query, value)

Find all records with datetime values which fall after the given date.

filter_less_equal(query, value)

Find all records with datetime values which fall on or before the given date.

filter_less_than(query, value)

Find all records with datetime values which fall before the given date.

filter_not_equal(query, value)

Find all records with datetime values which fall outside the given date.

get_end_datetime(value, as_utc=True)

Calculate the “end” timestamp for the given date value.

Due to the nature of queries involving this “end” boundary, the return value will be the “first possible moment” of the day after the given date.

Parameters:

• value – datetime.date instance

• as_utc – Indicates the return value should be naive/UTC; set this to False to get the aware/local value.

Returns:

datetime.datetime instance

get_start_datetime(value, as_utc=True)

Calculate the “start” timestamp for the given date value.

The return value will be the “first possible moment” of the given date.

Parameters:

• value – datetime.date instance

• as_utc – Indicates the return value should be naive/UTC; set this to False to get the aware/local value.

Returns:

datetime.datetime instance

class wuttaweb.grids.filters.GridFilter(request, key, label=None, verbs=None, choices=None, nullable=None, default_active=False, default_verb=None, default_value=None, **kwargs)

Filter option for a grid. Represents both the “features” as well as “state” for the filter.

Parameters:

• request – Current request object.

• nullable – Boolean indicating whether the filter should include is_null and is_not_null verbs. If not specified, the column will be inspected (if possible) and use its nullable flag.

• **kwargs – Any additional kwargs will be set as attributes on the filter instance.

Filter instances have the following attributes:

key

Unique key for the filter. This often corresponds to a “column name” for the grid, but not always.

label

Display label for the filter field.

data_type

Simplistic “data type” which the filter supports. So far this will be one of:

• 'string'

• 'date'

• 'choice'

Note that this mainly applies to the “value input” used by the filter. There is no data type for boolean since it does not need a value input; the verb is enough.

active

Boolean indicating whether the filter is currently active.

See also verb and value.

verb

Verb for current filter, if active is true.

See also value.

choices

OrderedDict of possible values for the filter.

This is safe to read from, but use set_choices() to update it.

value

Value for current filter, if active is true.

See also verb.

default_active

Boolean indicating whether the filter should be active by default, i.e. when first displaying the grid.

See also default_verb and default_value.

default_verb

Filter verb to use by default. This will be auto-selected when the filter is first activated, or when first displaying the grid if default_active is true.

See also default_value.

default_value

Filter value to use by default. This will be auto-populated when the filter is first activated, or when first displaying the grid if default_active is true.

See also default_verb.

apply_filter(data, verb=None, value=<object object>)

Filter the given data set according to a verb/value pair.

If verb and/or value are not specified, will use verb and/or value instead.

This method does not directly filter the data; rather it delegates (based on verb) to some other method. The latter may choose not to filter the data, e.g. if value is empty, in which case this may return the original data set unchanged.

Returns:

The (possibly) filtered data set.

coerce_value(value)

Coerce the given value to the correct type/format for use with the filter. This is where e.g. a boolean or date filter should convert input string to bool or date value.

This is (usually) called from a filter method, when applying the filter. See also apply_filter().

Default logic on the base class returns value as-is; subclass may override as needed.

Parameters:

value – Input string provided by the user via the filter form submission.

Returns:

Value of the appropriate type, depending on the filter subclass.

filter_is_any(data, value)

This is a no-op which always ignores the value and returns the data as-is.

get_default_verb()

Returns the default verb for the filter.

get_valueless_verbs()

Returns a list of verb names which do not need a value.

get_verb_labels()

Returns a dict of all defined verb labels.

get_verbs()

Returns the list of verbs supported by the filter.

normalize_choices(choices)

Normalize a collection of “choices” to standard OrderedDict.

This is called automatically by set_choices().

Parameters:

choices –

A collection of “choices” in one of the following formats:

• enum.Enum class

• simple list, each value of which should be a string, which is assumed to be able to serve as both key and value (ordering of choices will be preserved)

• simple dict, keys and values of which will define the choices (note that the final choices will be sorted by key!)

• OrderedDict, keys and values of which will define the choices (ordering of choices will be preserved)

Return type:

collections.OrderedDict

set_choices(choices)

Set the value choices for the filter.

If choices is non-empty, it is passed to normalize_choices() and the result is assigned to choices. Also, the data_type is set to 'choice' so the UI will present the value input as a dropdown.

But if choices is empty, choices is set to an empty dict, and data_type is set (back) to 'string'.

Parameters:

choices – Collection of “choices” or None.

class wuttaweb.grids.filters.IntegerAlchemyFilter(*args, **kwargs)

SQLAlchemy filter option for an integer data column.

Subclass of NumericAlchemyFilter.

class wuttaweb.grids.filters.NumericAlchemyFilter(*args, **kwargs)

SQLAlchemy filter option for a numeric data column.

Subclass of AlchemyFilter.

class wuttaweb.grids.filters.StringAlchemyFilter(*args, **kwargs)

SQLAlchemy filter option for a text data column.

Subclass of AlchemyFilter.

filter_contains(query, value)

Filter data with an ILIKE condition.

filter_does_not_contain(query, value)

Filter data with a NOT ILIKE condition.