Quick

This module beefs up the default full text search field to be a little bit more versatile. It allows specifying patterns such as is:unread or !important which are extracted from the query string and returned as standalone values allowing the implementation of a search syntax known from f.e. Google Mail.

Quick rules always consist of two parts: A regular expression pulling values out of the query string and a mapper which maps the values from the regex to something else which may be directly usable by forms.

Usage example:

QUICK_RULES = [
    (re.compile(r'!!'), quick.static(important=True)),
    (re.compile(r'@(?P<username>\w+)'),
        quick.model_mapper(User.objects.all(), 'assigned_to')),
    (re.compile(r'\^\+(?P<due>\d+)'),
        lambda v: {'due': date.today() + timedelta(days=int(v['due']))}),
    (re.compile(r'=(?P<estimated_hours>[\d\.]+)h'),
        quick.identity()),
    ]

data, rest = quick.parse_quickadd(
    request.POST.get('quick', ''),
    QUICK_RULES)

data['notes'] = ' '.join(rest)  # Everything which could not be parsed
                                # is added to the ``notes`` field.
form = TicketForm(data)

Note

The mappers always get the regex matches dict and return a dict.

towel.quick.bool_mapper(attribute)

Maps yes, 1 and on to True and no, 0 and off to False.

towel.quick.due_mapper(attribute)

Understands Today, Tomorrow, the following five localized week day names or (partial) dates such as 20.12. and 01.03.2012.

towel.quick.identity()

Identity mapper. Returns the values from the regular expression directly.

towel.quick.model_choices_mapper(data, attribute)

Needs a value provided by the regular expression and returns the corresponding key value.

Example:

class Ticket(models.Model):
    VISIBILITY_CHOICES = (
        ('public', _('public')),
        ('private', _('private')),
        )
    visibility = models.CharField(choices=VISIBILITY_CHOICES)

QUICK_RULES = [
    (re.compile(r'~(?P<value>[^\s]+)'), quick.model_choices_mapper(
        Ticket.VISIBILITY_CHOICES, 'visibility')),
    ]

towel.quick.model_mapper(queryset, attribute)

The regular expression needs to return a dict which is directly passed to queryset.get(). As a speciality, this mapper returns both the primary key of the instance under the attribute name, and the instance itself as attribute_.

towel.quick.parse_quickadd(quick, regexes)

The main workhorse. Named parse_quickadd for historic reasons, can be used not only for adding but for searching etc. too. In fact, towel.forms.SearchForm supports quick rules out of the box when they are specified in quick_rules.

towel.quick.static(**kwargs)

Return a predefined dict when the given regex matches.