# 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__()

    Alias of `itervisible` (for convenience).

  __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()

    `BoundColumns.all` filtered for whether they can be ordered.

    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()

    Return `iterorderable` filtered by visibility.

    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

    Return the default value for this column.

  property footer

    The contents of the footer cell for this column.

  get_td_class(td_attrs)

    Return the HTML class attribute for a data cell in this column.

  get_th_class(th_attrs)

    Return 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_replace table.prefixed_order_by_field=column.order_by_alias.opposite %}
        {% else %}
            {% querystring_replace 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)

    Return a new `BoundRows` instance for a slice, a single `BoundRow` instance for an index.

  __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)

    Arguments that will optionally be passed while rendering cells.

  property attrs

    Return the attributes for a certain row.

  get_cell(name)

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

  get_cell_value(name)

    Return 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()

    Return an 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)

  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__()

    Iterate over the table data (for … in … defaults 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=(), /)

  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)

    Expand 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

    Return the bare form, without the direction prefix.

    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()

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

  property is_ascending

    Return `True` if this object induces ascending ordering.

  property is_descending

    Return `True` if this object induces descending ordering.

  property opposite

    Provide 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)

  Store 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)

    Extract an `OrderBy` item by index.

    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)

  Return an (arguments, kwargs)-tuple.

  > - the arguments (positional or keyword)

  > - the name of the ** kwarg catch all.

  The self-argument for methods is always removed.

django_tables2.utils.call_with_appropriate(fn, kwargs)

  Call 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)

  Return 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