API Reference
=============

`.Accessor` (`.A`)
------------------

.. autoclass:: django_tables2.utils.Accessor


`.RequestConfig`
----------------

.. autoclass:: django_tables2.config.RequestConfig


`.Table`
--------

.. autoclass:: django_tables2.tables.Table
    :members: paginate, as_html


`.Table.Meta`
-------------

.. class:: Table.Meta

    Provides a way to define *global* settings for table, as opposed to
    defining them for each instance.

    .. attribute:: attrs

        Allows custom HTML attributes to be specified which will be added to
        the ``<table>`` tag of any table rendered via
        :meth:`.Table.as_html` or the
        :ref:`template-tags.render_table` template tag.

        :type: `dict`
        :default: ``{}``

        This is typically used to enable a theme for a table (which is done by
        adding a CSS class to the ``<table>`` element). i.e.::

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

                class Meta:
                    attrs = {'class': 'paleblue'}

        .. versionadded:: 0.15.0

        It's possible to use callables to create *dynamic* values. A few caveats:

        - It's not supported for ``dict`` keys, i.e. only values.
        - All values will be resolved on table instantiation.

        Consider this example where a unique ``id`` is given to each instance
        of the table::

            import itertools
            counter = itertools.count()

            class UniqueIdTable(tables.Table):
                name = tables.Column()

                class Meta:
                    attrs = {'id': lambda: 'table_%d' % next(counter)}

        .. note::

            This functionality is also available via the ``attrs`` keyword
            argument to a table's constructor.

    .. attribute:: row_attrs
        Allows custom HTML attributes to be specified which will be added to
        the ``<tr>`` tag of any table rendered.

        :type: `dict`
        :default: ``{}``

        This can be used to add each record's primary key to each row.::

            class PersonTable(tables.Table):
                class Meta:
                    model = Person
                    row_attrs = {'data-id': lambda record: record.pk}

        .. versionadded:: 1.2.0

    .. attribute:: empty_text

        Defines the text to display when the table has no rows.

        :type: `unicode`
        :default: `None`

        If the table is empty and ``bool(empty_text)`` is `True`, a row is
        displayed containing ``empty_text``. This is allows a message such as
        *There are currently no FOO.* to be displayed.

        .. note::

            This functionality is also available via the ``empty_text`` keyword
            argument to a table's constructor.

    .. attribute:: show_header

        Defines whether the table header (``<thead>``) should be displayed or
        not.

        :type: `bool`
        :default: `True`

        .. note::

            This functionality is also available via the ``show_header``
            keyword argument to a table's constructor.

    .. attribute:: exclude

        Defines which columns should be excluded from the table. This is useful
        in subclasses to exclude columns in a parent.

        :type: tuple of `unicode`
        :default: ``()``

        Example::

            >>> class Person(tables.Table):
            ...     first_name = tables.Column()
            ...     last_name = tables.Column()
            ...
            >>> Person.base_columns
            {'first_name': <django_tables2.columns.Column object at 0x10046df10>,
            'last_name': <django_tables2.columns.Column object at 0x10046d8d0>}
            >>> class ForgetfulPerson(Person):
            ...     class Meta:
            ...         exclude = ('last_name', )
            ...
            >>> ForgetfulPerson.base_columns
            {'first_name': <django_tables2.columns.Column object at 0x10046df10>}

        .. note::

            This functionality is also available via the ``exclude`` keyword
            argument to a table's constructor.

            However, unlike some of the other `.Table.Meta` options, providing the
            ``exclude`` keyword to a table's constructor **won't override** the
            `.Meta.exclude`. Instead, it will be effectively be *added*
            to it. i.e. you can't use the constructor's ``exclude`` argument to
            *undo* an exclusion.

    .. attribute:: fields

        Used in conjunction with `~.Table.Meta.model`, specifies which fields
        should have columns in the table.

        :type: tuple of `unicode` or `None`
        :default: `None`

        If `None`, all fields are used, otherwise only those named.

        Example::

            # models.py
            class Person(models.Model):
                first_name = models.CharField(max_length=200)
                last_name = models.CharField(max_length=200)

            # tables.py
            class PersonTable(tables.Table):
                class Meta:
                    model = Person
                    fields = ('first_name', )

    .. attribute:: model

        A model to inspect and automatically create corresponding columns.

        :type: Django model
        :default: `None`

        This option allows a Django model to be specified to cause the table to
        automatically generate columns that correspond to the fields in a
        model.

    .. attribute:: order_by

        The default ordering. e.g. ``('name', '-age')``. A hyphen ``-`` can be
        used to prefix a column name to indicate *descending* order.

        :type: `tuple`
        :default: ``()``

        .. note::

            This functionality is also available via the ``order_by`` keyword
            argument to a table's constructor.

    .. attribute:: sequence

        The sequence of the table columns. This allows the default order of
        columns (the order they were defined in the Table) to be overridden.

        :type: any iterable (e.g. `tuple` or `list`)
        :default: ``()``

        The special item ``'...'`` can be used as a placeholder that will be
        replaced with all the columns that weren't explicitly listed. This
        allows you to add columns to the front or back when using inheritance.

        Example::

            >>> class Person(tables.Table):
            ...     first_name = tables.Column()
            ...     last_name = tables.Column()
            ...
            ...     class Meta:
            ...         sequence = ('last_name', '...')
            ...
            >>> Person.base_columns.keys()
            ['last_name', 'first_name']

        The ``"..."`` item can be used at most once in the sequence value. If
        it's not used, every column *must* be explicitly included. e.g. in the
        above example, ``sequence = ("last_name", )`` would be **invalid**
        because neither ``"..."`` or ``"first_name"`` were included.

        .. note::

            This functionality is also available via the ``sequence`` keyword
            argument to a table's constructor.

    .. attribute:: orderable

        Default value for column's *orderable* attribute.

        :type: `bool`
        :default: `True`

        If the table and column don't specify a value, a column's ``orderable``
        value will fallback to this. This provides an easy mechanism to disable
        ordering on an entire table, without adding ``orderable=False`` to each
        column in a table.

        .. note::

            This functionality is also available via the ``orderable`` keyword
            argument to a table's constructor.

    .. attribute:: template

        The default template to use when rendering the table.

        :type: `unicode`
        :default: ``"django_tables2/table.html"``

        .. note::

            This functionality is also available via the *template* keyword
            argument to a table's constructor.


    .. attribute:: localize

        Specifies which fields should be localized in the table.
        Read :ref:`localization-control` for more information.

        :type: tuple of `unicode`
        :default: empty tuple


    .. attribute:: unlocalize

        Specifies which fields should be unlocalized in the table.
        Read :ref:`localization-control` for more information.

        :type: tuple of `unicode`
        :default: empty tuple


`.BooleanColumn`
----------------

.. autoclass:: django_tables2.columns.BooleanColumn


`.Column`
---------

.. autoclass:: django_tables2.columns.Column


`.CheckBoxColumn`
-----------------

.. autoclass:: django_tables2.columns.CheckBoxColumn
    :members:


`.DateColumn`
-------------

.. autoclass:: django_tables2.columns.DateColumn
    :members:


`.DateTimeColumn`
-----------------

.. autoclass:: django_tables2.columns.DateTimeColumn
    :members:


`.EmailColumn`
--------------

.. autoclass:: django_tables2.columns.EmailColumn
    :members:


`.FileColumn`
-------------

.. autoclass:: django_tables2.columns.FileColumn
    :members:


`.LinkColumn`
-------------

.. autoclass:: django_tables2.columns.LinkColumn
    :members:

`.RelatedLinkColumn`
--------------------

.. autoclass:: django_tables2.columns.RelatedLinkColumn
    :members:


`.TemplateColumn`
-----------------

.. autoclass:: django_tables2.columns.TemplateColumn
    :members:


`.URLColumn`
------------

.. autoclass:: django_tables2.columns.URLColumn
    :members:


See :doc:`internal` for internal classes.