Internal APIs

The items documented here are internal and subject to change.

BoundColumns

class django_tables2.columns.BoundColumns(table, base_columns)

Container for spawning BoundColumn objects.

This is bound to a table and provides its Table.columns property. It provides access to those columns in different ways (iterator, item-based, filtered and unfiltered etc), stuff that would not be possible with a simple iterator in the table class.

A BoundColumns object is a container for holding BoundColumn objects. It provides methods that make accessing columns easier than if they were stored in a list or dict. Columns has a similar API to a dict (it actually uses a OrderedDict internally).

At the moment you’ll only come across this class when you access a Table.columns property.

Parameters:

table (Table) – the table containing the columns

__contains__(item)

Check if a column is contained within a BoundColumns object.

item can either be a BoundColumn object, or the name of a column.

__getitem__(index)

Retrieve a specific BoundColumn object.

index can either be 0-indexed or the name of a column

columns['speed']  # returns a bound column with name 'speed'
columns[0]        # returns the first column

__init__(table, base_columns)

__iter__()

Convenience API, alias of itervisible.

__len__()

Return how many BoundColumn objects are contained (and visible).

__weakref__

list of weak references to the object

hide(name)

Hide a column.

Parameters:

name (str) – name of the column

iterall()

Return an iterator that exposes all BoundColumn objects, regardless of visibility or sortability.

iteritems()

Return an iterator of (name, column) pairs (where column is a BoundColumn).

This method is the mechanism for retrieving columns that takes into consideration all of the ordering and filtering modifiers that a table supports (e.g. exclude and sequence).

iterorderable()

Same as BoundColumns.all but only returns orderable columns.

This is useful in templates, where iterating over the full set and checking {% if column.ordarable %} can be problematic in conjunction with e.g. {{ forloop.last }} (the last column might not be the actual last that is rendered).

itervisible()

Same as iterorderable but only returns visible BoundColumn objects.

This is geared towards table rendering.

show(name)

Show a column otherwise hidden.

Parameters:

name (str) – name of the column

BoundColumn

class django_tables2.columns.BoundColumn(table, column, name)

A run-time version of Column.

The difference between BoundColumn and Column, is that BoundColumn objects include the relationship between a Column and a Table. In practice, this means that a BoundColumn knows the “variable name” given to the Column when it was declared on the Table.

Parameters:

• table (Table) – The table in which this column exists

• column (Column) – The type of column

• name (str) –

  The variable name of the column used when defining the Table. In this example the name is age:

  class SimpleTable(tables.Table):
      age = tables.Column()
  

__init__(table, column, name)

__str__()

Return str(self).

__weakref__

list of weak references to the object

_get_cell_class(attrs)

Return a set of the classes from the class key in attrs.

property attrs

Proxy to Column.attrs but injects some values of our own.

A th, td and tf are guaranteed to be defined (irrespective of what is actually defined in the column attrs. This makes writing templates easier. tf is not actually a HTML tag, but this key name will be used for attributes for column’s footer, if the column has one.

property default

Returns the default value for this column.

property footer

The contents of the footer cell for this column.

get_td_class(td_attrs)

Returns the HTML class attribute for a data cell in this column

get_th_class(th_attrs)

Returns the HTML class attribute for a header cell in this column

property header

The contents of the header cell for this column.

property localize

Return True, False or None as described in Column.localize

property order_by

Return an OrderByTuple of appropriately prefixed data source keys used to sort this column.

See order_by_alias for details.

property order_by_alias

Return an OrderBy describing the current state of ordering for this column.

The following attempts to explain the difference between order_by and order_by_alias.

order_by_alias returns and OrderBy instance that’s based on the name of the column, rather than the keys used to order the table data. Understanding the difference is essential.

Having an alias and a keys version is necessary because an N-tuple (of data source keys) can be used by the column to order the data, and it is ambiguous when mapping from N-tuple to column (since multiple columns could use the same N-tuple).

The solution is to use order by aliases (which are really just prefixed column names) that describe the ordering state of the column, rather than the specific keys in the data source should be ordered.

e.g.:

>>> class SimpleTable(tables.Table):
...     name = tables.Column(order_by=("firstname", "last_name"))
...
>>> table = SimpleTable([], order_by=('-name', ))
>>> table.columns["name"].order_by_alias
"-name"
>>> table.columns["name"].order_by
("-first_name", "-last_name")

The OrderBy returned has been patched to include an extra attribute next, which returns a version of the alias that would be transitioned to if the user toggles sorting on this column, for example:

not sorted -> ascending
ascending  -> descending
descending -> ascending

This is useful otherwise in templates you’d need something like:

{% if column.is_ordered %}
    {% querystring table.prefixed_order_by_field=column.order_by_alias.opposite %}
{% else %}
    {% querystring table.prefixed_order_by_field=column.order_by_alias %}
{% endif %}

property orderable

Return whether this column supports ordering.

property verbose_name

Return the verbose name for this column.

In order of preference, this will return:

1. The column’s explicitly defined verbose_name

2. The model’s verbose_name with the first letter capitalized (if applicable)

3. Fall back to the column name, with first letter capitalized.

Any verbose_name that was not passed explicitly in the column definition is returned with the first character capitalized in keeping with the Django convention of verbose_name being defined in lowercase and uppercased as needed by the application.

If the table is using QuerySet data, then use the corresponding model field’s verbose_name. If it is traversing a relationship, then get the last field in the accessor (i.e. stop when the relationship turns from ORM relationships to object attributes [e.g. person.upper should stop at person]).

property visible

Return whether this column is visible.

BoundRows

class django_tables2.rows.BoundRows(data, table, pinned_data=None)

Container for spawning BoundRow objects.

Parameters:

• data – iterable of records

• table – the Table in which the rows exist

• pinned_data – dictionary with iterable of records for top and/or bottom pinned rows.

Example

>>> pinned_data = {
...    'top': iterable,      # or None value
...    'bottom': iterable,   # or None value
... }

This is used for rows.

__getitem__(key)

Slicing returns a new BoundRows instance, indexing returns a single BoundRow instance.

__init__(data, table, pinned_data=None)

__weakref__

list of weak references to the object

generator_pinned_row(data)

Top and bottom pinned rows generator.

Parameters:

data – Iterable data for all records for top or bottom pinned rows.

Yields:

BoundPinnedRow – Top or bottom BoundPinnedRow object for single pinned record.

BoundRow

class django_tables2.rows.BoundRow(record, table)

Represents a specific row in a table.

BoundRow objects are a container that make it easy to access the final ‘rendered’ values for cells in a row. You can simply iterate over a BoundRow object and it will take care to return values rendered using the correct method (e.g. Table.render_foo methods)

To access the rendered value of each cell in a row, just iterate over it:

>>> import django_tables2 as tables
>>> class SimpleTable(tables.Table):
...     a = tables.Column()
...     b = tables.CheckBoxColumn(attrs={'name': 'my_chkbox'})
...
>>> table = SimpleTable([{'a': 1, 'b': 2}])
>>> row = table.rows[0]  # we only have one row, so let's use it
>>> for cell in row:
...     print(cell)
...
1
<input type="checkbox" name="my_chkbox" value="2" />

Alternatively you can use row.cells[0] to retrieve a specific cell:

>>> row.cells[0]
1
>>> row.cells[1]
'<input type="checkbox" name="my_chkbox" value="2" />'
>>> row.cells[2]
...
IndexError: list index out of range

Finally you can also use the column names to retrieve a specific cell:

>>> row.cells.a
1
>>> row.cells.b
'<input type="checkbox" name="my_chkbox" value="2" />'
>>> row.cells.c
...
KeyError: "Column with name 'c' does not exist; choices are: ['a', 'b']"

If you have the column name in a variable, you can also treat the cells property like a dict:

>>> key = 'a'
>>> row.cells[key]
1

Parameters:

• table – The Table in which this row exists.

• record – a single record from the table data that is used to populate the row. A record could be a Model object, a dict, or something else.

__contains__(item)

Check by both row object and column name.

__init__(record, table)

__iter__()

Iterate over the rendered values for cells in the row.

Under the hood this method just makes a call to BoundRow.__getitem__ for each cell.

__weakref__

list of weak references to the object

_call_render(bound_column, value=None)

Call the column’s render method with appropriate kwargs

_call_value(bound_column, value=None)

Call the column’s value method with appropriate kwargs

_optional_cell_arguments(bound_column, value)

Defines the arguments that will optionally be passed while calling the cell’s rendering or value getter if that function has one of these as a keyword argument.

property attrs

Return the attributes for a certain row.

get_cell(name)

Returns the final rendered html for a cell in the row, given the name of a column.

get_cell_value(name)

Returns the final rendered value (excluding any html) for a cell in the row, given the name of a column.

get_even_odd_css_class()

Return css class, alternating for odd and even records.

Returns:

even for even records, odd otherwise.

Return type:

string

items()

Returns iterator yielding (bound_column, cell) pairs.

cell is row[name] – the rendered unicode value that should be rendered within ``<td>.

property record

The data record from the data source which is used to populate this row with data.

property table

The Table this row is part of.

BoundPinnedRow

class django_tables2.rows.BoundPinnedRow(record, table)

Represents a pinned row in a table.

property attrs

Return the attributes for a certain pinned row. Add CSS classes pinned-row and odd or even to class attribute.

Returns:

Attributes for pinned rows.

Return type:

AttributeDict

TableData

class django_tables2.tables.TableData(data)

Base class for table data containers.

__getitem__(key)

Slicing returns a new TableData instance, indexing returns a single record.

__init__(data)

__iter__()

for … in … default to using this. There’s a bug in Django 1.3 with indexing into QuerySets, so this side-steps that problem (as well as just being a better way to iterate).

__weakref__

list of weak references to the object

set_table(table)

Table.__init__ calls this method to inject an instance of itself into the TableData instance. Good place to do additional checks if Table and TableData instance will work together properly.

utils

class django_tables2.utils.Sequence(iterable=(), /)

Represents a column sequence, e.g. ('first_name', '...', 'last_name')

This is used to represent Table.Meta.sequence or the Table constructors’s sequence keyword argument.

The sequence must be a list of column names and is used to specify the order of the columns on a table. Optionally a ‘…’ item can be inserted, which is treated as a catch-all for column names that are not explicitly specified.

__weakref__

list of weak references to the object

expand(columns)

Expands the '...' item in the sequence into the appropriate column names that should be placed there.

Parameters:

columns (list) – list of column names.

Returns:

The current instance.

Raises:

ValueError –

class django_tables2.utils.OrderBy(value)

A single item in an OrderByTuple object.

This class is essentially just a str with some extra properties.

static __new__(cls, value)

__weakref__

list of weak references to the object

property bare

Returns:

the bare form.

Return type:

OrderBy

The bare form is the non-prefixed form. Typically the bare form is just the ascending form.

Example: age is the bare form of -age

for_queryset()

Returns the current instance usable in Django QuerySet’s order_by arguments.

property is_ascending

Returns True if this object induces ascending ordering.

property is_descending

Returns True if this object induces descending ordering.

property opposite

Provides the opposite of the current sorting direction.

Returns:

object with an opposite sort influence.

Return type:

OrderBy

Example:

>>> order_by = OrderBy('name')
>>> order_by.opposite
'-name'

class django_tables2.utils.OrderByTuple(iterable)

Stores ordering as (as OrderBy objects).

The order_by property is always converted to an OrderByTuple object. This class is essentially just a tuple with some useful extras.

Example:

>>> x = OrderByTuple(('name', '-age'))
>>> x['age']
'-age'
>>> x['age'].is_descending
True
>>> x['age'].opposite
'age'

__contains__(name)

Determine if a column has an influence on ordering.

Example:

>>> x = OrderByTuple(('name', ))
>>> 'name' in  x
True
>>> '-name' in x
True

Parameters:

name (str) – The name of a column. (optionally prefixed)

Returns:

True if the column with name influences the ordering.

Return type:

bool

__getitem__(index)

Allows an OrderBy object to be extracted via named or integer based indexing.

When using named based indexing, it’s fine to used a prefixed named:

>>> x = OrderByTuple(('name', '-age'))
>>> x[0]
'name'
>>> x['age']
'-age'
>>> x['-age']
'-age'

Parameters:

index (int) – Index to query the ordering for.

Returns:

for the ordering at the index.

Return type:

OrderBy

static __new__(cls, iterable)

__str__()

Return str(self).

get(key, fallback)

Identical to __getitem__, but supports fallback value.

property opposite

Return version with each OrderBy prefix toggled:

>>> order_by = OrderByTuple(('name', '-age'))
>>> order_by.opposite
('-name', 'age')

class django_tables2.utils.Accessor(value, callable_args=None, callable_kwargs=None)

A string describing a path from one object to another via attribute/index accesses. For convenience, the class has an alias A to allow for more concise code.

Relations are separated by a __ character.

To support list-of-dicts from QuerySet.values(), if the context is a dictionary, and the accessor is a key in the dictionary, it is returned right away.

__init__(value, callable_args=None, callable_kwargs=None)

static __new__(cls, value, callable_args=None, callable_kwargs=None)

__weakref__

list of weak references to the object

get_field(model)

Return the django model field for model in context, following relations.

penultimate(context, quiet=True)

Split the accessor on the right-most separator (‘__’), return a tuple with:

• the resolved left part.

• the remainder

Example:

>>> Accessor("a__b__c").penultimate({"a": {"a": 1, "b": {"c": 2, "d": 4}}})
({"c": 2, "d": 4}, "c")

resolve(context, safe=True, quiet=False)

Return an object described by the accessor by traversing the attributes of context.

Lookups are attempted in the following order:

• dictionary (e.g. obj[related])

• attribute (e.g. obj.related)

• list-index lookup (e.g. obj[int(related)])

Callable objects are called, and their result is used, before proceeding with the resolving.

Example:

>>> x = Accessor("__len__")
>>> x.resolve("brad")
4
>>> x = Accessor("0__upper")
>>> x.resolve("brad")
"B"

If the context is a dictionary and the accessor-value is a key in it, the value for that key is immediately returned:

>>> x = Accessor("user__first_name")
>>> x.resolve({"user__first_name": "brad"})
"brad"

Parameters:

• context – The root/first object to traverse.

• safe (bool) – Don’t call anything with alters_data = True

• quiet (bool) – Smother all exceptions and instead return None

Returns:

target object

Raises:

• TypeError`, AttributeError, KeyError, ValueError –

• (unless quiet == True) –

class django_tables2.utils.AttributeDict

A wrapper around collections.OrderedDict that knows how to render itself as HTML style tag attributes.

Any key with value is None will be skipped.

The returned string is marked safe, so it can be used safely in a template. See as_html for a usage example.

as_html()

Render to HTML tag attributes.

Example:

>>> from django_tables2.utils import AttributeDict
>>> attrs = AttributeDict({'class': 'mytable', 'id': 'someid'})
>>> attrs.as_html()
'class="mytable" id="someid"'

returns: SafeUnicode object

django_tables2.utils.signature(fn)

Returns:

Returns a (arguments, kwarg_name)-tuple:

• the arguments (positional or keyword)

• the name of the ** kwarg catch all.

Return type:

tuple

The self-argument for methods is always removed.

django_tables2.utils.call_with_appropriate(fn, kwargs)

Calls the function fn with the keyword arguments from kwargs it expects

If the kwargs argument is defined, pass all arguments, else provide exactly the arguments wanted.

If one of the arguments of fn are not contained in kwargs, fn will not be called and None will be returned.

django_tables2.utils.computed_values(d, kwargs=None)

Returns a new dict that has callable values replaced with the return values.

Example:

>>> compute_values({'foo': lambda: 'bar'})
{'foo': 'bar'}

Arbitrarily deep structures are supported. The logic is as follows:

1. If the value is callable, call it and make that the new value.

2. If the value is an instance of dict, use ComputableDict to compute its keys.

Example:

>>> def parents():
...     return {
...         'father': lambda: 'Foo',
...         'mother': 'Bar'
...      }
...
>>> a = {
...     'name': 'Brad',
...     'parents': parents
... }
...
>>> computed_values(a)
{'name': 'Brad', 'parents': {'father': 'Foo', 'mother': 'Bar'}}

Parameters:

• d (dict) – The original dictionary.

• kwargs – any extra keyword arguments will be passed to the callables, if the callable takes an argument with such a name.

Returns:

with callable values replaced.

Return type:

dict