trac.util.presentation – Utilities for dynamic content generation

The following utilities are all available within Genshi templates.

trac.util.presentation.captioned_button(req, symbol, text)

Return symbol and text or only symbol, according to user preferences.

trac.util.presentation.classes(*args, **kwargs)

Helper function for dynamically assembling a list of CSS class names in templates.

Any positional arguments are added to the list of class names. All positional arguments must be strings:

>>> classes('foo', 'bar')
u'foo bar'

In addition, the names of any supplied keyword arguments are added if they have a truth value:

>>> classes('foo', bar=True)
u'foo bar'
>>> classes('foo', bar=False)
u'foo'

If none of the arguments are added to the list, this function returns None:

>>> classes(bar=False)

trac.util.presentation.first_last(idx, seq)

Generate first or last or both, according to the position idx in sequence seq.

trac.util.presentation.group(iterable, num, predicate=None)

Combines the elements produced by the given iterable so that every n items are returned as a tuple.

>>> items = [1, 2, 3, 4]
>>> for item in group(items, 2):
...     print item
(1, 2)
(3, 4)

The last tuple is padded with None values if its’ length is smaller than num.

>>> items = [1, 2, 3, 4, 5]
>>> for item in group(items, 2):
...     print item
(1, 2)
(3, 4)
(5, None)

The optional predicate parameter can be used to flag elements that should not be packed together with other items. Only those elements where the predicate function returns True are grouped with other elements, otherwise they are returned as a tuple of length 1:

>>> items = [1, 2, 3, 4]
>>> for item in group(items, 2, lambda x: x != 3):
...     print item
(1, 2)
(3,)
(4, None)

trac.util.presentation.istext(text)

True for text (unicode and str), but False for Markup.

trac.util.presentation.paginate(items, page=0, max_per_page=10)

Simple generic pagination.

Given an iterable, this function returns:

• the slice of objects on the requested page,
• the total number of items, and
• the total number of pages.

The items parameter can be a list, tuple, or iterator:

>>> items = range(12)
>>> items
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
>>> paginate(items)
([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 12, 2)
>>> paginate(items, page=1)
([10, 11], 12, 2)
>>> paginate(iter(items))
([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 12, 2)
>>> paginate(iter(items), page=1)
([10, 11], 12, 2)

This function also works with generators:

>>> def generate():
...     for idx in range(12):
...         yield idx
>>> paginate(generate())
([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 12, 2)
>>> paginate(generate(), page=1)
([10, 11], 12, 2)

The max_per_page parameter can be used to set the number of items that should be displayed per page:

>>> items = range(12)
>>> paginate(items, page=0, max_per_page=6)
([0, 1, 2, 3, 4, 5], 12, 2)
>>> paginate(items, page=1, max_per_page=6)
([6, 7, 8, 9, 10, 11], 12, 2)

trac.util.presentation.separated(items, sep=', ')

Yield (item, sep) tuples, one for each element in items.

sep will be None for the last item.

>>> list(separated([1, 2]))
[(1, ','), (2, None)]

>>> list(separated([1]))
[(1, None)]

>>> list(separated("abc", ':'))
[('a', ':'), ('b', ':'), ('c', None)]

trac.util.presentation.to_json(value)

Encode value to JSON.

Modules generating paginated output will be happy to use a rich pagination controller. See Query, Report and Search modules for example usage.

class trac.util.presentation.Paginator(items, page=0, max_per_page=10, num_items=None)

Pagination controller