app/django/template/defaultfilters.py

   1 """Default variable filters."""
   2
   3 import re
   4 import random as random_module
   5 try:
   6     from functools import wraps
   7 except ImportError:
   8     from django.utils.functional import wraps  # Python 2.3, 2.4 fallback.
   9
  10 from django.template import Variable, Library
  11 from django.conf import settings
  12 from django.utils.translation import ugettext, ungettext
  13 from django.utils.encoding import force_unicode, iri_to_uri
  14 from django.utils.safestring import mark_safe, SafeData
  15
  16 register = Library()
  17
  18 #######################
  19 # STRING DECORATOR    #
  20 #######################
  21
  22 def stringfilter(func):
  23     """
  24     Decorator for filters which should only receive unicode objects. The object
  25     passed as the first positional argument will be converted to a unicode
  26     object.
  27     """
  28     def _dec(*args, **kwargs):
  29         if args:
  30             args = list(args)
  31             args[0] = force_unicode(args[0])
  32             if isinstance(args[0], SafeData) and getattr(func, 'is_safe', False):
  33                 return mark_safe(func(*args, **kwargs))
  34         return func(*args, **kwargs)
  35
  36     # Include a reference to the real function (used to check original
  37     # arguments by the template parser).
  38     _dec._decorated_function = getattr(func, '_decorated_function', func)
  39     for attr in ('is_safe', 'needs_autoescape'):
  40         if hasattr(func, attr):
  41             setattr(_dec, attr, getattr(func, attr))
  42     return wraps(func)(_dec)
  43
  44 ###################
  45 # STRINGS         #
  46 ###################
  47
  48
  49 def addslashes(value):
  50     """
  51     Adds slashes before quotes. Useful for escaping strings in CSV, for
  52     example. Less useful for escaping JavaScript; use the ``escapejs``
  53     filter instead.
  54     """
  55     return value.replace('\\', '\\\\').replace('"', '\\"').replace("'", "\\'")
  56 addslashes.is_safe = True
  57 addslashes = stringfilter(addslashes)
  58
  59 def capfirst(value):
  60     """Capitalizes the first character of the value."""
  61     return value and value[0].upper() + value[1:]
  62 capfirst.is_safe=True
  63 capfirst = stringfilter(capfirst)
  64
  65 _base_js_escapes = (
  66     ('\\', r'\x5C'),
  67     ('\'', r'\x27'),
  68     ('"', r'\x22'),
  69     ('>', r'\x3E'),
  70     ('<', r'\x3C'),
  71     ('&', r'\x26'),
  72     ('=', r'\x3D'),
  73     ('-', r'\x2D'),
  74     (';', r'\x3B')
  75 )
  76
  77 # Escape every ASCII character with a value less than 32.
  78 _js_escapes = (_base_js_escapes +
  79                tuple([('%c' % z, '\\x%02X' % z) for z in range(32)]))
  80
  81 def escapejs(value):
  82     """Hex encodes characters for use in JavaScript strings."""
  83     for bad, good in _js_escapes:
  84         value = value.replace(bad, good)
  85     return value
  86 escapejs = stringfilter(escapejs)
  87
  88 def fix_ampersands(value):
  89     """Replaces ampersands with ``&amp;`` entities."""
  90     from django.utils.html import fix_ampersands
  91     return fix_ampersands(value)
  92 fix_ampersands.is_safe=True
  93 fix_ampersands = stringfilter(fix_ampersands)
  94
  95 def floatformat(text, arg=-1):
  96     """
  97     Displays a float to a specified number of decimal places.
  98
  99     If called without an argument, it displays the floating point number with
 100     one decimal place -- but only if there's a decimal place to be displayed:
 101
 102     * num1 = 34.23234
 103     * num2 = 34.00000
 104     * num3 = 34.26000
 105     * {{ num1|floatformat }} displays "34.2"
 106     * {{ num2|floatformat }} displays "34"
 107     * {{ num3|floatformat }} displays "34.3"
 108
 109     If arg is positive, it will always display exactly arg number of decimal
 110     places:
 111
 112     * {{ num1|floatformat:3 }} displays "34.232"
 113     * {{ num2|floatformat:3 }} displays "34.000"
 114     * {{ num3|floatformat:3 }} displays "34.260"
 115
 116     If arg is negative, it will display arg number of decimal places -- but
 117     only if there are places to be displayed:
 118
 119     * {{ num1|floatformat:"-3" }} displays "34.232"
 120     * {{ num2|floatformat:"-3" }} displays "34"
 121     * {{ num3|floatformat:"-3" }} displays "34.260"
 122     """
 123     try:
 124         f = float(text)
 125     except (ValueError, TypeError):
 126         return u''
 127     try:
 128         d = int(arg)
 129     except ValueError:
 130         return force_unicode(f)
 131     try:
 132         m = f - int(f)
 133     except OverflowError:
 134         return force_unicode(f)
 135     if not m and d < 0:
 136         return mark_safe(u'%d' % int(f))
 137     else:
 138         formatstr = u'%%.%df' % abs(d)
 139         return mark_safe(formatstr % f)
 140 floatformat.is_safe = True
 141
 142 def iriencode(value):
 143     """Escapes an IRI value for use in a URL."""
 144     return force_unicode(iri_to_uri(value))
 145 iriencode.is_safe = True
 146 iriencode = stringfilter(iriencode)
 147
 148 def linenumbers(value, autoescape=None):
 149     """Displays text with line numbers."""
 150     from django.utils.html import escape
 151     lines = value.split(u'\n')
 152     # Find the maximum width of the line count, for use with zero padding
 153     # string format command
 154     width = unicode(len(unicode(len(lines))))
 155     if not autoescape or isinstance(value, SafeData):
 156         for i, line in enumerate(lines):
 157             lines[i] = (u"%0" + width  + u"d. %s") % (i + 1, line)
 158     else:
 159         for i, line in enumerate(lines):
 160             lines[i] = (u"%0" + width  + u"d. %s") % (i + 1, escape(line))
 161     return mark_safe(u'\n'.join(lines))
 162 linenumbers.is_safe = True
 163 linenumbers.needs_autoescape = True
 164 linenumbers = stringfilter(linenumbers)
 165
 166 def lower(value):
 167     """Converts a string into all lowercase."""
 168     return value.lower()
 169 lower.is_safe = True
 170 lower = stringfilter(lower)
 171
 172 def make_list(value):
 173     """
 174     Returns the value turned into a list.
 175
 176     For an integer, it's a list of digits.
 177     For a string, it's a list of characters.
 178     """
 179     return list(value)
 180 make_list.is_safe = False
 181 make_list = stringfilter(make_list)
 182
 183 def slugify(value):
 184     """
 185     Normalizes string, converts to lowercase, removes non-alpha characters,
 186     and converts spaces to hyphens.
 187     """
 188     import unicodedata
 189     value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore')
 190     value = unicode(re.sub('[^\w\s-]', '', value).strip().lower())
 191     return mark_safe(re.sub('[-\s]+', '-', value))
 192 slugify.is_safe = True
 193 slugify = stringfilter(slugify)
 194
 195 def stringformat(value, arg):
 196     """
 197     Formats the variable according to the arg, a string formatting specifier.
 198
 199     This specifier uses Python string formating syntax, with the exception that
 200     the leading "%" is dropped.
 201
 202     See http://docs.python.org/lib/typesseq-strings.html for documentation
 203     of Python string formatting
 204     """
 205     try:
 206         return (u"%" + unicode(arg)) % value
 207     except (ValueError, TypeError):
 208         return u""
 209 stringformat.is_safe = True
 210
 211 def title(value):
 212     """Converts a string into titlecase."""
 213     return re.sub("([a-z])'([A-Z])", lambda m: m.group(0).lower(), value.title())
 214 title.is_safe = True
 215 title = stringfilter(title)
 216
 217 def truncatewords(value, arg):
 218     """
 219     Truncates a string after a certain number of words.
 220
 221     Argument: Number of words to truncate after.
 222     """
 223     from django.utils.text import truncate_words
 224     try:
 225         length = int(arg)
 226     except ValueError: # Invalid literal for int().
 227         return value # Fail silently.
 228     return truncate_words(value, length)
 229 truncatewords.is_safe = True
 230 truncatewords = stringfilter(truncatewords)
 231
 232 def truncatewords_html(value, arg):
 233     """
 234     Truncates HTML after a certain number of words.
 235
 236     Argument: Number of words to truncate after.
 237     """
 238     from django.utils.text import truncate_html_words
 239     try:
 240         length = int(arg)
 241     except ValueError: # invalid literal for int()
 242         return value # Fail silently.
 243     return truncate_html_words(value, length)
 244 truncatewords_html.is_safe = True
 245 truncatewords_html = stringfilter(truncatewords_html)
 246
 247 def upper(value):
 248     """Converts a string into all uppercase."""
 249     return value.upper()
 250 upper.is_safe = False
 251 upper = stringfilter(upper)
 252
 253 def urlencode(value):
 254     """Escapes a value for use in a URL."""
 255     from django.utils.http import urlquote
 256     return urlquote(value)
 257 urlencode.is_safe = False
 258 urlencode = stringfilter(urlencode)
 259
 260 def urlize(value, autoescape=None):
 261     """Converts URLs in plain text into clickable links."""
 262     from django.utils.html import urlize
 263     return mark_safe(urlize(value, nofollow=True, autoescape=autoescape))
 264 urlize.is_safe=True
 265 urlize.needs_autoescape = True
 266 urlize = stringfilter(urlize)
 267
 268 def urlizetrunc(value, limit, autoescape=None):
 269     """
 270     Converts URLs into clickable links, truncating URLs to the given character
 271     limit, and adding 'rel=nofollow' attribute to discourage spamming.
 272
 273     Argument: Length to truncate URLs to.
 274     """
 275     from django.utils.html import urlize
 276     return mark_safe(urlize(value, trim_url_limit=int(limit), nofollow=True,
 277                             autoescape=autoescape))
 278 urlizetrunc.is_safe = True
 279 urlizetrunc.needs_autoescape = True
 280 urlizetrunc = stringfilter(urlizetrunc)
 281
 282 def wordcount(value):
 283     """Returns the number of words."""
 284     return len(value.split())
 285 wordcount.is_safe = False
 286 wordcount = stringfilter(wordcount)
 287
 288 def wordwrap(value, arg):
 289     """
 290     Wraps words at specified line length.
 291
 292     Argument: number of characters to wrap the text at.
 293     """
 294     from django.utils.text import wrap
 295     return wrap(value, int(arg))
 296 wordwrap.is_safe = True
 297 wordwrap = stringfilter(wordwrap)
 298
 299 def ljust(value, arg):
 300     """
 301     Left-aligns the value in a field of a given width.
 302
 303     Argument: field size.
 304     """
 305     return value.ljust(int(arg))
 306 ljust.is_safe = True
 307 ljust = stringfilter(ljust)
 308
 309 def rjust(value, arg):
 310     """
 311     Right-aligns the value in a field of a given width.
 312
 313     Argument: field size.
 314     """
 315     return value.rjust(int(arg))
 316 rjust.is_safe = True
 317 rjust = stringfilter(rjust)
 318
 319 def center(value, arg):
 320     """Centers the value in a field of a given width."""
 321     return value.center(int(arg))
 322 center.is_safe = True
 323 center = stringfilter(center)
 324
 325 def cut(value, arg):
 326     """
 327     Removes all values of arg from the given string.
 328     """
 329     safe = isinstance(value, SafeData)
 330     value = value.replace(arg, u'')
 331     if safe and arg != ';':
 332         return mark_safe(value)
 333     return value
 334 cut = stringfilter(cut)
 335
 336 ###################
 337 # HTML STRINGS    #
 338 ###################
 339
 340 def escape(value):
 341     """
 342     Marks the value as a string that should not be auto-escaped.
 343     """
 344     from django.utils.safestring import mark_for_escaping
 345     return mark_for_escaping(value)
 346 escape.is_safe = True
 347 escape = stringfilter(escape)
 348
 349 def force_escape(value):
 350     """
 351     Escapes a string's HTML. This returns a new string containing the escaped
 352     characters (as opposed to "escape", which marks the content for later
 353     possible escaping).
 354     """
 355     from django.utils.html import escape
 356     return mark_safe(escape(value))
 357 force_escape = stringfilter(force_escape)
 358 force_escape.is_safe = True
 359
 360 def linebreaks(value, autoescape=None):
 361     """
 362     Replaces line breaks in plain text with appropriate HTML; a single
 363     newline becomes an HTML line break (``<br />``) and a new line
 364     followed by a blank line becomes a paragraph break (``</p>``).
 365     """
 366     from django.utils.html import linebreaks
 367     autoescape = autoescape and not isinstance(value, SafeData)
 368     return mark_safe(linebreaks(value, autoescape))
 369 linebreaks.is_safe = True
 370 linebreaks.needs_autoescape = True
 371 linebreaks = stringfilter(linebreaks)
 372
 373 def linebreaksbr(value, autoescape=None):
 374     """
 375     Converts all newlines in a piece of plain text to HTML line breaks
 376     (``<br />``).
 377     """
 378     if autoescape and not isinstance(value, SafeData):
 379         from django.utils.html import escape
 380         value = escape(value)
 381     return mark_safe(value.replace('\n', '<br />'))
 382 linebreaksbr.is_safe = True
 383 linebreaksbr.needs_autoescape = True
 384 linebreaksbr = stringfilter(linebreaksbr)
 385
 386 def safe(value):
 387     """
 388     Marks the value as a string that should not be auto-escaped.
 389     """
 390     from django.utils.safestring import mark_safe
 391     return mark_safe(value)
 392 safe.is_safe = True
 393 safe = stringfilter(safe)
 394
 395 def removetags(value, tags):
 396     """Removes a space separated list of [X]HTML tags from the output."""
 397     tags = [re.escape(tag) for tag in tags.split()]
 398     tags_re = u'(%s)' % u'|'.join(tags)
 399     starttag_re = re.compile(ur'<%s(/?>|(\s+[^>]*>))' % tags_re, re.U)
 400     endtag_re = re.compile(u'</%s>' % tags_re)
 401     value = starttag_re.sub(u'', value)
 402     value = endtag_re.sub(u'', value)
 403     return value
 404 removetags.is_safe = True
 405 removetags = stringfilter(removetags)
 406
 407 def striptags(value):
 408     """Strips all [X]HTML tags."""
 409     from django.utils.html import strip_tags
 410     return strip_tags(value)
 411 striptags.is_safe = True
 412 striptags = stringfilter(striptags)
 413
 414 ###################
 415 # LISTS           #
 416 ###################
 417
 418 def dictsort(value, arg):
 419     """
 420     Takes a list of dicts, returns that list sorted by the property given in
 421     the argument.
 422     """
 423     var_resolve = Variable(arg).resolve
 424     decorated = [(var_resolve(item), item) for item in value]
 425     decorated.sort()
 426     return [item[1] for item in decorated]
 427 dictsort.is_safe = False
 428
 429 def dictsortreversed(value, arg):
 430     """
 431     Takes a list of dicts, returns that list sorted in reverse order by the
 432     property given in the argument.
 433     """
 434     var_resolve = Variable(arg).resolve
 435     decorated = [(var_resolve(item), item) for item in value]
 436     decorated.sort()
 437     decorated.reverse()
 438     return [item[1] for item in decorated]
 439 dictsortreversed.is_safe = False
 440
 441 def first(value):
 442     """Returns the first item in a list."""
 443     try:
 444         return value[0]
 445     except IndexError:
 446         return u''
 447 first.is_safe = False
 448
 449 def join(value, arg):
 450     """Joins a list with a string, like Python's ``str.join(list)``."""
 451     try:
 452         data = arg.join(map(force_unicode, value))
 453     except AttributeError: # fail silently but nicely
 454         return value
 455     safe_args = reduce(lambda lhs, rhs: lhs and isinstance(rhs, SafeData),
 456             value, True)
 457     if safe_args:
 458         return mark_safe(data)
 459     else:
 460         return data
 461 join.is_safe = True
 462
 463 def last(value):
 464     "Returns the last item in a list"
 465     try:
 466         return value[-1]
 467     except IndexError:
 468         return u''
 469 last.is_safe = True
 470
 471 def length(value):
 472     """Returns the length of the value - useful for lists."""
 473     return len(value)
 474 length.is_safe = True
 475
 476 def length_is(value, arg):
 477     """Returns a boolean of whether the value's length is the argument."""
 478     return len(value) == int(arg)
 479 length_is.is_safe = True
 480
 481 def random(value):
 482     """Returns a random item from the list."""
 483     return random_module.choice(value)
 484 random.is_safe = True
 485
 486 def slice_(value, arg):
 487     """
 488     Returns a slice of the list.
 489
 490     Uses the same syntax as Python's list slicing; see
 491     http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
 492     for an introduction.
 493     """
 494     try:
 495         bits = []
 496         for x in arg.split(u':'):
 497             if len(x) == 0:
 498                 bits.append(None)
 499             else:
 500                 bits.append(int(x))
 501         return value[slice(*bits)]
 502
 503     except (ValueError, TypeError):
 504         return value # Fail silently.
 505 slice_.is_safe = True
 506
 507 def unordered_list(value, autoescape=None):
 508     """
 509     Recursively takes a self-nested list and returns an HTML unordered list --
 510     WITHOUT opening and closing <ul> tags.
 511
 512     The list is assumed to be in the proper format. For example, if ``var``
 513     contains: ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``,
 514     then ``{{ var|unordered_list }}`` would return::
 515
 516         <li>States
 517         <ul>
 518                 <li>Kansas
 519                 <ul>
 520                         <li>Lawrence</li>
 521                         <li>Topeka</li>
 522                 </ul>
 523                 </li>
 524                 <li>Illinois</li>
 525         </ul>
 526         </li>
 527     """
 528     if autoescape:
 529         from django.utils.html import conditional_escape
 530         escaper = conditional_escape
 531     else:
 532         escaper = lambda x: x
 533     def convert_old_style_list(list_):
 534         """
 535         Converts old style lists to the new easier to understand format.
 536
 537         The old list format looked like:
 538             ['Item 1', [['Item 1.1', []], ['Item 1.2', []]]
 539
 540         And it is converted to:
 541             ['Item 1', ['Item 1.1', 'Item 1.2]]
 542         """
 543         if not isinstance(list_, (tuple, list)) or len(list_) != 2:
 544             return list_, False
 545         first_item, second_item = list_
 546         if second_item == []:
 547             return [first_item], True
 548         old_style_list = True
 549         new_second_item = []
 550         for sublist in second_item:
 551             item, old_style_list = convert_old_style_list(sublist)
 552             if not old_style_list:
 553                 break
 554             new_second_item.extend(item)
 555         if old_style_list:
 556             second_item = new_second_item
 557         return [first_item, second_item], old_style_list
 558     def _helper(list_, tabs=1):
 559         indent = u'\t' * tabs
 560         output = []
 561
 562         list_length = len(list_)
 563         i = 0
 564         while i < list_length:
 565             title = list_[i]
 566             sublist = ''
 567             sublist_item = None
 568             if isinstance(title, (list, tuple)):
 569                 sublist_item = title
 570                 title = ''
 571             elif i < list_length - 1:
 572                 next_item = list_[i+1]
 573                 if next_item and isinstance(next_item, (list, tuple)):
 574                     # The next item is a sub-list.
 575                     sublist_item = next_item
 576                     # We've processed the next item now too.
 577                     i += 1
 578             if sublist_item:
 579                 sublist = _helper(sublist_item, tabs+1)
 580                 sublist = '\n%s<ul>\n%s\n%s</ul>\n%s' % (indent, sublist,
 581                                                          indent, indent)
 582             output.append('%s<li>%s%s</li>' % (indent,
 583                     escaper(force_unicode(title)), sublist))
 584             i += 1
 585         return '\n'.join(output)
 586     value, converted = convert_old_style_list(value)
 587     return mark_safe(_helper(value))
 588 unordered_list.is_safe = True
 589 unordered_list.needs_autoescape = True
 590
 591 ###################
 592 # INTEGERS        #
 593 ###################
 594
 595 def add(value, arg):
 596     """Adds the arg to the value."""
 597     return int(value) + int(arg)
 598 add.is_safe = False
 599
 600 def get_digit(value, arg):
 601     """
 602     Given a whole number, returns the requested digit of it, where 1 is the
 603     right-most digit, 2 is the second-right-most digit, etc. Returns the
 604     original value for invalid input (if input or argument is not an integer,
 605     or if argument is less than 1). Otherwise, output is always an integer.
 606     """
 607     try:
 608         arg = int(arg)
 609         value = int(value)
 610     except ValueError:
 611         return value # Fail silently for an invalid argument
 612     if arg < 1:
 613         return value
 614     try:
 615         return int(str(value)[-arg])
 616     except IndexError:
 617         return 0
 618 get_digit.is_safe = False
 619
 620 ###################
 621 # DATES           #
 622 ###################
 623
 624 def date(value, arg=None):
 625     """Formats a date according to the given format."""
 626     from django.utils.dateformat import format
 627     if not value:
 628         return u''
 629     if arg is None:
 630         arg = settings.DATE_FORMAT
 631     return format(value, arg)
 632 date.is_safe = False
 633
 634 def time(value, arg=None):
 635     """Formats a time according to the given format."""
 636     from django.utils.dateformat import time_format
 637     if value in (None, u''):
 638         return u''
 639     if arg is None:
 640         arg = settings.TIME_FORMAT
 641     return time_format(value, arg)
 642 time.is_safe = False
 643
 644 def timesince(value, arg=None):
 645     """Formats a date as the time since that date (i.e. "4 days, 6 hours")."""
 646     from django.utils.timesince import timesince
 647     if not value:
 648         return u''
 649     try:
 650         if arg:
 651             return timesince(value, arg)
 652         return timesince(value)
 653     except (ValueError, TypeError):
 654         return u''
 655 timesince.is_safe = False
 656
 657 def timeuntil(value, arg=None):
 658     """Formats a date as the time until that date (i.e. "4 days, 6 hours")."""
 659     from django.utils.timesince import timeuntil
 660     from datetime import datetime
 661     if not value:
 662         return u''
 663     try:
 664         return timeuntil(value, arg)
 665     except (ValueError, TypeError):
 666         return u''
 667 timeuntil.is_safe = False
 668
 669 ###################
 670 # LOGIC           #
 671 ###################
 672
 673 def default(value, arg):
 674     """If value is unavailable, use given default."""
 675     return value or arg
 676 default.is_safe = False
 677
 678 def default_if_none(value, arg):
 679     """If value is None, use given default."""
 680     if value is None:
 681         return arg
 682     return value
 683 default_if_none.is_safe = False
 684
 685 def divisibleby(value, arg):
 686     """Returns True if the value is devisible by the argument."""
 687     return int(value) % int(arg) == 0
 688 divisibleby.is_safe = False
 689
 690 def yesno(value, arg=None):
 691     """
 692     Given a string mapping values for true, false and (optionally) None,
 693     returns one of those strings accoding to the value:
 694
 695     ==========  ======================  ==================================
 696     Value       Argument                Outputs
 697     ==========  ======================  ==================================
 698     ``True``    ``"yeah,no,maybe"``     ``yeah``
 699     ``False``   ``"yeah,no,maybe"``     ``no``
 700     ``None``    ``"yeah,no,maybe"``     ``maybe``
 701     ``None``    ``"yeah,no"``           ``"no"`` (converts None to False
 702                                         if no mapping for None is given.
 703     ==========  ======================  ==================================
 704     """
 705     if arg is None:
 706         arg = ugettext('yes,no,maybe')
 707     bits = arg.split(u',')
 708     if len(bits) < 2:
 709         return value # Invalid arg.
 710     try:
 711         yes, no, maybe = bits
 712     except ValueError:
 713         # Unpack list of wrong size (no "maybe" value provided).
 714         yes, no, maybe = bits[0], bits[1], bits[1]
 715     if value is None:
 716         return maybe
 717     if value:
 718         return yes
 719     return no
 720 yesno.is_safe = False
 721
 722 ###################
 723 # MISC            #
 724 ###################
 725
 726 def filesizeformat(bytes):
 727     """
 728     Formats the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB,
 729     102 bytes, etc).
 730     """
 731     try:
 732         bytes = float(bytes)
 733     except TypeError:
 734         return u"0 bytes"
 735
 736     if bytes < 1024:
 737         return ungettext("%(size)d byte", "%(size)d bytes", bytes) % {'size': bytes}
 738     if bytes < 1024 * 1024:
 739         return ugettext("%.1f KB") % (bytes / 1024)
 740     if bytes < 1024 * 1024 * 1024:
 741         return ugettext("%.1f MB") % (bytes / (1024 * 1024))
 742     return ugettext("%.1f GB") % (bytes / (1024 * 1024 * 1024))
 743 filesizeformat.is_safe = True
 744
 745 def pluralize(value, arg=u's'):
 746     """
 747     Returns a plural suffix if the value is not 1. By default, 's' is used as
 748     the suffix:
 749
 750     * If value is 0, vote{{ value|pluralize }} displays "0 votes".
 751     * If value is 1, vote{{ value|pluralize }} displays "1 vote".
 752     * If value is 2, vote{{ value|pluralize }} displays "2 votes".
 753
 754     If an argument is provided, that string is used instead:
 755
 756     * If value is 0, class{{ value|pluralize:"es" }} displays "0 classes".
 757     * If value is 1, class{{ value|pluralize:"es" }} displays "1 class".
 758     * If value is 2, class{{ value|pluralize:"es" }} displays "2 classes".
 759
 760     If the provided argument contains a comma, the text before the comma is
 761     used for the singular case and the text after the comma is used for the
 762     plural case:
 763
 764     * If value is 0, cand{{ value|pluralize:"y,ies" }} displays "0 candies".
 765     * If value is 1, cand{{ value|pluralize:"y,ies" }} displays "1 candy".
 766     * If value is 2, cand{{ value|pluralize:"y,ies" }} displays "2 candies".
 767     """
 768     if not u',' in arg:
 769         arg = u',' + arg
 770     bits = arg.split(u',')
 771     if len(bits) > 2:
 772         return u''
 773     singular_suffix, plural_suffix = bits[:2]
 774
 775     try:
 776         if int(value) != 1:
 777             return plural_suffix
 778     except ValueError: # Invalid string that's not a number.
 779         pass
 780     except TypeError: # Value isn't a string or a number; maybe it's a list?
 781         try:
 782             if len(value) != 1:
 783                 return plural_suffix
 784         except TypeError: # len() of unsized object.
 785             pass
 786     return singular_suffix
 787 pluralize.is_safe = False
 788
 789 def phone2numeric(value):
 790     """Takes a phone number and converts it in to its numerical equivalent."""
 791     from django.utils.text import phone2numeric
 792     return phone2numeric(value)
 793 phone2numeric.is_safe = True
 794
 795 def pprint(value):
 796     """A wrapper around pprint.pprint -- for debugging, really."""
 797     from pprint import pformat
 798     try:
 799         return pformat(value)
 800     except Exception, e:
 801         return u"Error in formatting: %s" % force_unicode(e, errors="replace")
 802 pprint.is_safe = True
 803
 804 # Syntax: register.filter(name of filter, callback)
 805 register.filter(add)
 806 register.filter(addslashes)
 807 register.filter(capfirst)
 808 register.filter(center)
 809 register.filter(cut)
 810 register.filter(date)
 811 register.filter(default)
 812 register.filter(default_if_none)
 813 register.filter(dictsort)
 814 register.filter(dictsortreversed)
 815 register.filter(divisibleby)
 816 register.filter(escape)
 817 register.filter(escapejs)
 818 register.filter(filesizeformat)
 819 register.filter(first)
 820 register.filter(fix_ampersands)
 821 register.filter(floatformat)
 822 register.filter(force_escape)
 823 register.filter(get_digit)
 824 register.filter(iriencode)
 825 register.filter(join)
 826 register.filter(last)
 827 register.filter(length)
 828 register.filter(length_is)
 829 register.filter(linebreaks)
 830 register.filter(linebreaksbr)
 831 register.filter(linenumbers)
 832 register.filter(ljust)
 833 register.filter(lower)
 834 register.filter(make_list)
 835 register.filter(phone2numeric)
 836 register.filter(pluralize)
 837 register.filter(pprint)
 838 register.filter(removetags)
 839 register.filter(random)
 840 register.filter(rjust)
 841 register.filter(safe)
 842 register.filter('slice', slice_)
 843 register.filter(slugify)
 844 register.filter(stringformat)
 845 register.filter(striptags)
 846 register.filter(time)
 847 register.filter(timesince)
 848 register.filter(timeuntil)
 849 register.filter(title)
 850 register.filter(truncatewords)
 851 register.filter(truncatewords_html)
 852 register.filter(unordered_list)
 853 register.filter(upper)
 854 register.filter(urlencode)
 855 register.filter(urlize)
 856 register.filter(urlizetrunc)
 857 register.filter(wordcount)
 858 register.filter(wordwrap)
 859 register.filter(yesno)