1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
|
# -*- coding: utf-8 -*-
import copy
from django.conf import settings
from django.core.paginator import Paginator
from django.http import Http404
from django.utils.datastructures import SortedDict
from django.template import RequestContext
from django.template.loader import get_template
from django.utils.encoding import StrAndUnicode
import itertools
import sys
import warnings
from .utils import Accessor, AttributeDict, OrderBy, OrderByTuple, Sequence
from .rows import BoundRows
from .columns import BoundColumns, Column
QUERYSET_ACCESSOR_SEPARATOR = '__'
class TableData(object):
"""
Exposes a consistent API for :term:`table data`.
:param data: iterable containing data for each row
:type data: :class:`QuerySet` or :class:`list` of :class:`dict`
:param table: :class:`.Table` object
"""
def __init__(self, data, table):
self.table = table
# data may be a QuerySet-like objects with count() and order_by()
if (hasattr(data, 'count') and callable(data.count) and
hasattr(data, 'order_by') and callable(data.order_by)):
self.queryset = data
# otherwise it must be convertable to a list
else:
try:
self.list = list(data)
except:
raise ValueError('data must be QuerySet-like (have count and '
'order_by) or support list(data) -- %s is '
'neither' % type(data).__name__)
def __len__(self):
# Use the queryset count() method to get the length, instead of
# loading all results into memory. This allows, for example,
# smart paginators that use len() to perform better.
return (self.queryset.count() if hasattr(self, 'queryset')
else len(self.list))
def order_by(self, aliases):
"""
Order the data based on order by aliases (prefixed column names) in the
table.
:param aliases: optionally prefixed names of columns ('-' indicates
descending order) in order of significance with
regard to data ordering.
:type aliases: :class:`~.utils.OrderByTuple`
"""
accessors = self._translate_aliases_to_accessors(aliases)
if hasattr(self, 'queryset'):
translate = lambda accessor: accessor.replace(Accessor.SEPARATOR, QUERYSET_ACCESSOR_SEPARATOR)
self.queryset = self.queryset.order_by(*(translate(a) for a in accessors))
else:
self.list.sort(cmp=accessors.cmp)
def _translate_aliases_to_accessors(self, aliases):
"""
Translate from order by aliases to column accessors.
"""
columns = (self.table.columns[OrderBy(alias).bare] for alias in aliases)
return OrderByTuple(itertools.chain(*(c.order_by for c in columns)))
def __iter__(self):
"""
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).
"""
return iter(self.list) if hasattr(self, 'list') else iter(self.queryset)
def __getitem__(self, key):
"""
Slicing returns a new :class:`.TableData` instance, indexing returns a
single record.
"""
data = (self.list if hasattr(self, 'list') else self.queryset)[key]
if isinstance(key, slice):
return type(self)(data, self.table)
else:
return data
class DeclarativeColumnsMetaclass(type):
"""
Metaclass that converts Column attributes on the class to a dictionary
called ``base_columns``, taking into account parent class ``base_columns``
as well.
"""
def __new__(cls, name, bases, attrs):
attrs["_meta"] = opts = TableOptions(attrs.get("Meta", None))
# extract declared columns
columns = [(name_, attrs.pop(name_)) for name_, column in attrs.items()
if isinstance(column, Column)]
columns.sort(lambda x, y: cmp(x[1].creation_counter,
y[1].creation_counter))
# If this class is subclassing other tables, add their fields as
# well. Note that we loop over the bases in *reverse* - this is
# necessary to preserve the correct order of columns.
parent_columns = []
for base in bases[::-1]:
if hasattr(base, "base_columns"):
parent_columns = base.base_columns.items() + parent_columns
# Start with the parent columns
attrs["base_columns"] = SortedDict(parent_columns)
# Possibly add some generated columns based on a model
if opts.model:
# We explicitly pass in verbose_name, so that if the table is
# instantiated with non-queryset data, model field verbose_names
# are used anyway.
extra = SortedDict(((f.name, Column(verbose_name=f.verbose_name))
for f in opts.model._meta.fields))
attrs["base_columns"].update(extra)
# Explicit columns override both parent and generated columns
attrs["base_columns"].update(SortedDict(columns))
# Apply any explicit exclude setting
for exclusion in opts.exclude:
if exclusion in attrs["base_columns"]:
attrs["base_columns"].pop(exclusion)
# Now reorder the columns based on explicit sequence
if opts.sequence:
opts.sequence.expand(attrs["base_columns"].keys())
attrs["base_columns"] = SortedDict(((x, attrs["base_columns"][x]) for x in opts.sequence))
return super(DeclarativeColumnsMetaclass, cls).__new__(cls, name, bases, attrs)
class TableOptions(object):
"""
Extracts and exposes options for a :class:`.Table` from a ``class Meta``
when the table is defined. See ``Table`` for documentation on the impact of
variables in this class.
:param options: options for a table
:type options: :class:`Meta` on a :class:`.Table`
"""
def __init__(self, options=None):
super(TableOptions, self).__init__()
self.attrs = AttributeDict(getattr(options, "attrs", {}))
self.empty_text = getattr(options, "empty_text", None)
self.exclude = getattr(options, "exclude", ())
order_by = getattr(options, "order_by", None)
if isinstance(order_by, basestring):
order_by = (order_by, )
self.order_by = OrderByTuple(order_by) if order_by is not None else None
self.order_by_field = getattr(options, "order_by_field", "sort")
self.page_field = getattr(options, "page_field", "page")
self.per_page = getattr(options, "per_page", 25)
self.per_page_field = getattr(options, "per_page_field", "per_page")
self.prefix = getattr(options, "prefix", "")
self.sequence = Sequence(getattr(options, "sequence", ()))
if hasattr(options, "sortable"):
warnings.warn("`Table.Meta.sortable` is deprecated, use `orderable` instead",
DeprecationWarning)
self.orderable = self.sortable = getattr(options, "orderable", getattr(options, "sortable", True))
self.model = getattr(options, "model", None)
self.template = getattr(options, "template", "django_tables2/table.html")
class Table(StrAndUnicode):
"""
A collection of columns, plus their associated data rows.
:type attrs: dict
:param attrs: A mapping of attributes to values that will be added to the
HTML ``<table>`` tag.
:type data: list or QuerySet-like
:param data: The :term:`table data`.
:type exclude: iterable
:param exclude: A list of columns to be excluded from this table.
:type order_by: None, tuple or string
:param order_by: sort the table based on these columns prior to display.
(default :attr:`.Table.Meta.order_by`)
:type order_by_field: string or None
:param order_by_field: The name of the querystring field used to control
the table ordering.
:type page_field: string or None
:param page_field: The name of the querystring field used to control which
page of the table is displayed (used when a table is paginated).
:type per_page_field: string or None
:param per_page_field: The name of the querystring field used to control
how many records are displayed on each page of the table.
:type prefix: string
:param prefix: A prefix used on querystring arguments to allow multiple
tables to be used on a single page, without having conflicts
between querystring arguments. Depending on how the table is
rendered, will determine how the prefix is used. For example ``{%
render_table %}`` uses ``<prefix>-<argument>``.
:type sequence: iterable
:param sequence: The sequence/order of columns the columns (from left to
right). Items in the sequence must be column names, or the
*remaining items* symbol marker ``"..."`` (string containing three
periods). If this marker is used, not all columns need to be
defined.
:type orderable: bool
:param orderable: Enable/disable column ordering on this table
:type template: string
:param template: the template to render when using {% render_table %}
(default ``django_tables2/table.html``)
:type empty_text: string
:param empty_text: Empty text to render when the table has no data.
(default :attr:`.Table.Meta.empty_text`)
"""
__metaclass__ = DeclarativeColumnsMetaclass
TableDataClass = TableData
def __init__(self, data, order_by=None, orderable=None, empty_text=None,
exclude=None, attrs=None, sequence=None, prefix=None,
order_by_field=None, page_field=None, per_page_field=None,
template=None, sortable=None):
super(Table, self).__init__()
self.data = self.TableDataClass(data=data, table=self)
self.rows = BoundRows(self.data)
self.columns = BoundColumns(self)
self.attrs = attrs
self.empty_text = empty_text
if sortable is not None:
warnings.warn("`sortable` is deprecated, use `orderable` instead.",
DeprecationWarning)
if orderable is None:
orderable = sortable
self.orderable = orderable
self.prefix = prefix
self.order_by_field = order_by_field
self.page_field = page_field
self.per_page_field = per_page_field
# Make a copy so that modifying this will not touch the class
# definition. Note that this is different from forms, where the
# copy is made available in a ``fields`` attribute.
self.base_columns = copy.deepcopy(type(self).base_columns)
self.exclude = exclude or ()
self.sequence = sequence
# `None` value for order_by means no order is specified. This means we
# `shouldn't touch our data's ordering in any way. *However*
# `table.order_by = None` means "remove any ordering from the data"
# (it's equivalent to `table.order_by = ()`).
if order_by is None and self._meta.order_by is not None:
order_by = self._meta.order_by
if order_by is None:
self._order_by = None
else:
self.order_by = order_by
self.template = template
def __unicode__(self):
return unicode(repr(self))
def as_html(self):
"""
Render the table to a simple HTML table.
If this method is used in the request/response cycle, any links
generated will clobber the querystring of the request. Use the
``{% render_table %}`` template tag instead.
"""
from django.test.client import RequestFactory
request = RequestFactory().get('/')
template = get_template(self.template)
return template.render(RequestContext(request, {'table': self}))
@property
def attrs(self):
"""
The attributes that should be applied to the ``<table>`` tag when
rendering HTML.
:rtype: :class:`~.utils.AttributeDict` object.
"""
return self._attrs if self._attrs is not None else self._meta.attrs
@attrs.setter
def attrs(self, value):
self._attrs = value
@property
def empty_text(self):
return (self._empty_text if self._empty_text is not None
else self._meta.empty_text)
@empty_text.setter
def empty_text(self, value):
self._empty_text = value
@property
def order_by(self):
return self._order_by
@order_by.setter
def order_by(self, value):
"""
Order the rows of the table based columns. ``value`` must be a sequence
of column names.
"""
# collapse empty values to ()
order_by = () if not value else value
# accept string
order_by = order_by.split(',') if isinstance(order_by, basestring) else order_by
valid = []
# everything's been converted to a iterable, accept iterable!
for o in order_by:
name = OrderBy(o).bare
if name in self.columns and self.columns[name].orderable:
valid.append(o)
self._order_by = OrderByTuple(valid)
self.data.order_by(self._order_by)
@property
def order_by_field(self):
return (self._order_by_field if self._order_by_field is not None
else self._meta.order_by_field)
@order_by_field.setter
def order_by_field(self, value):
self._order_by_field = value
@property
def page_field(self):
return (self._page_field if self._page_field is not None
else self._meta.page_field)
@page_field.setter
def page_field(self, value):
self._page_field = value
def paginate(self, klass=Paginator, per_page=None, page=1, *args, **kwargs):
"""
Paginates the table using a paginator and creates a ``page`` property
containing information for the current page.
:type klass: Paginator ``class``
:param klass: a paginator class to paginate the results
:type per_page: ``int``
:param per_page: how many records are displayed on each page
:type page: ``int``
:param page: which page should be displayed.
"""
per_page = per_page or self._meta.per_page
self.paginator = klass(self.rows, per_page, *args, **kwargs)
self._page_number = page
@property
def page(self):
if hasattr(self, '_page_number'):
try:
return self.paginator.page(self._page_number)
except:
if settings.DEBUG:
raise
else:
raise Http404(sys.exc_info()[1])
@property
def per_page_field(self):
return (self._per_page_field if self._per_page_field is not None
else self._meta.per_page_field)
@per_page_field.setter
def per_page_field(self, value):
self._per_page_field = value
@property
def prefix(self):
return (self._prefix if self._prefix is not None
else self._meta.prefix)
@prefix.setter
def prefix(self, value):
self._prefix = value
@property
def prefixed_order_by_field(self):
return u"%s%s" % (self.prefix, self.order_by_field)
@property
def prefixed_page_field(self):
return u"%s%s" % (self.prefix, self.page_field)
@property
def prefixed_per_page_field(self):
return u"%s%s" % (self.prefix, self.per_page_field)
@property
def sequence(self):
return (self._sequence if self._sequence is not None
else self._meta.sequence)
@sequence.setter
def sequence(self, value):
if value:
value = Sequence(value)
value.expand(self.base_columns.keys())
self._sequence = value
@property
def orderable(self):
return (self._orderable if self._orderable is not None
else self._meta.orderable)
@orderable.setter
def orderable(self, value):
self._orderable = value
@property
def sortable(self):
warnings.warn("`sortable` is deprecated, use `orderable` instead.",
DeprecationWarning)
return self.orderable
@sortable.setter
def sortable(self, value):
warnings.warn("`sortable` is deprecated, use `orderable` instead.",
DeprecationWarning)
self.orderable = value
@property
def template(self):
return (self._template if self._template is not None
else self._meta.template)
@template.setter
def template(self, value):
self._template = value
|