General Utility

Search

This is an expanded version of get(). However, it returns an iterable by filtering relevant predicate.

starlight.search(iterable, /, *, check_any=False, sort=False, **attrs)

A helper that returns all elements in the iterable that meet all or any of the traits passed in attrs depending on check_any. To have a nested attribute search (i.e. search by x.y) then pass in x__y as the keyword argument. If nothing is found that matches the attributes passed, then an empty list is returned.

Examples

Using SearchFilter:

cmds_by_name_and_desc = await starlight.search(bot.commands,
    name=FuzzyFilter('user'),
    description=ContainsFilter('user')
)

Sorting output based on fuzzy ratio:

sorted_cmds_by_fuzzy_name = await starlight.search(bot.commands,
    sort=True,
    name=FuzzyFilter('user')
)

Use logical OR for attribute matching:

cmds_by_name_or_desc = await starlight.search(bot.commands,
    check_any=True,
    name=FuzzyFilter('user'),
    description=ContainsFilter('user')
)

Parameters:

• iterable (Union[collections.abc.Iterable, collections.abc.AsyncIterable]) – The iterable to search through. Using a collections.abc.AsyncIterable, makes this function return a coroutine.

• check_any (class:bool) – When multiple attributes are specified, determines whether they are checked using logical AND or logical OR. when this value is False, logical AND is used meaning they have to meet every attribute passed in and not one of them. Default is False.

• sort (class:bool) – Whether to sort the output based on the scoring values. Default is False. The order of attributes determines their weighting for sorting with the first having the most weight and last the least weight.

• **attrs – Keyword arguments that denote attributes to search with.

Returns:

List of values that match the filters passed in through attrs.

Return type:

List[Any]

Filters

This are supported utility classes that can be used along side search().

SearchFilter

class starlight.SearchFilter(query)

Base class for filtering with search().

User should subclass this class for compatibility with search().

Parameters:

query (Any) – The query value to filter by.

filter(value, /)

Filters the value from the iterable. The return value will be included if it is truthy or excluded if it is falsy. The return value is used to sort the item.

Subclasses should override this method.

Parameters:

value (Any) – The value of the attribute from the item in iterable.

Returns:

The value to sort this item by.

Return type:

Any

ContainsFilter

class starlight.ContainsFilter(query)

Bases: SearchFilter[Any]

Basic filter that checks if query is in the attribute value.

starlight.search(items, my_attr=ContainsFilter('my_value'))

Equivalent of

[item for item in items if 'my_value' in item.my_attr]

Parameters:

query (Any) – The query value to filter by.

filter(value, /)

Filters the value from the iterable. The return value will be included if it is truthy or excluded if it is falsy. The return value is used to sort the item.

Parameters:

value (Any) – The value of the attribute from the item in iterable.

Returns:

The value to sort this item by.

Return type:

bool

FuzzyFilter

class starlight.FuzzyFilter(query, /, *, cutoff_ratio=0.6, quick=True)

Bases: SearchFilter[str]

Basic fuzzy filter using difflib that filters based on the distance between two strings.

starlight.search(items, my_attr=FuzzyFilter('value', cutoff_ratio=0.5))

Equivalent to

[item for item in items
 if 'value' in str(item.my_attr)
 or quick_ratio('value', str(item.my_attr)) >= 0.5]

Parameters:

• query – The query value to filter by.

• cutoff_ratio (float) – The minimum ratio the input must be to be included. Default is 0.6.

• quick (bool) – Whether to use quick_ratio or slower ratio for getting the fuzzy ratio. Defaults to True to use quick_ratio.

filter(value, /)

Filters the value from the iterable. The return value will be included if it is truthy or excluded if it is falsy. The return value is used to sort the item.

Parameters:

value (Any) – The value of the attribute from the item in iterable. It is cast to str before.

Returns:

The value to sort this item by.

Return type:

float

get_ratio(query, value)

Uses difflib to get the ratio between query and value.

Parameters:

• query (str) – The value to use as a for difflib ratio/quick_ratio.

• value (str) – The value to use as b for difflib ratio/quick_ratio.

Returns:

The ratio between the two input strings.

Return type:

float

RegexFilter

class starlight.RegexFilter(query, /, flags)

Bases: SearchFilter[str]

Basic filter that uses the provided regex pattern to search.

starlight.search(items, my_attr=RegexFilter(r'[0-9]{15,20}'))

Equivalent to

[item for item in items if re.search(item.myattr, r'[0-9]{15,20}')]

Parameters:

• query (str) – The regex pattern to filter by.

• flags (Union[int, re.RegexFlag]) – The flags to use for regex.

filter(value, /)

Filters the value from the iterable. The return value will be included if it is truthy or excluded if it is falsy.

Parameters:

value (Any) – The value of the attribute from the item in iterable. It is cast to str before.

Returns:

The value to sort this item by.

Return type:

bool

get_app_signature

starlight.get_app_signature(command)

To retrieve app command signature similar to signature.

Parameters:

command (Command) – App command to get signature from.

Returns:

Parameter string that was extracted.

Return type:

str

Iterables

recursive_unpack

starlight.recursive_unpack(iterable, /, *, allowed_recursion=(<class 'list'>, <class 'tuple'>, <class 'set'>, <class 'dict'>))

Used to unpack an iterable from any level of data structure. This is similar to itertools.chain.from_iterable() but recursive with any level of depth.

Parameters:

• iterable (List[Union[List[T], T]]) – The multi level list that will be unpacked.

• allowed_recursion (Tuple[Type]) – Data structure that is allowed to be recursived. Defaults to Tuple[list, tuple, set, dict].

Yields:

T – The element that was uncover from the data structure.

flatten

starlight.flatten(iterable, /, *, allowed_recursion=(<class 'list'>, <class 'tuple'>, <class 'set'>, <class 'dict'>))

Used to unpack an iterable from any level of list of list into a single list. This is similar to itertools.chain.from_iterable() but recursive with any level of depth.

Parameters:

• iterable (List[Union[List[T], T]]) – The multi level list that will be unpacked.

• allowed_recursion (Tuple[Type]) – Data structure that is allowed to be recursived. Defaults to Tuple[list, tuple, set, dict].

Returns:

The list that was uncover from the data stucture.

Return type:

List[T]