Context Navigation

Back to Ticket #17135

Ticket #17135: 17135.2.patch

File 17135.2.patch, 12.5 KB (added by Aymeric Augustin, 13 years ago)

docs/howto/custom-template-tags.txt

 If you leave off the ``name`` argument, as in the second example above, Django
 will use the function's name as the filter name.
-Template filters that expect strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you're writing a template filter that only expects a string as the first
-argument, you should use the decorator ``stringfilter``. This will
-convert an object to its string value before being passed to your function:
-.. code-block:: python
-    from django import template
-    from django.template.defaultfilters import stringfilter
-    register = template.Library()
-    @register.filter
-    @stringfilter
-    def lower(value):
-        return value.lower()
-This way, you'll be able to pass, say, an integer to this filter, and it
-won't cause an ``AttributeError`` (because integers don't have ``lower()``
-methods).
 Filters and auto-escaping
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 …
    handle the auto-escaping issues and return a safe string, the
    ``is_safe`` attribute won't change anything either way.
+Template filters that expect strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you're writing a template filter that only expects a string as the first
+argument, you should use the decorator ``stringfilter``. This will
+convert an object to its string value before being passed to your function:
+.. code-block:: python
+    from django import template
+    from django.template.defaultfilters import stringfilter
+    register = template.Library()
+    @register.filter
+    @stringfilter
+    def lower(value):
+        return value.lower()
+This way, you'll be able to pass, say, an integer to this filter, and it
+won't cause an ``AttributeError`` (because integers don't have ``lower()``
+methods).
+If you want to set the ``is_safe`` or ``needs_autoescape`` attributes on your
+filter, pass them as keyword arguments to ``stringfilter``, like this::
+    @register.filter
+    @stringfilter(is_safe=True)
+    def lower(value):
+        return value.lower()
+.. warning::
+    Setting ``is_safe`` or ``needs_autoescape`` directly on a function decorated
+    by ``stringfilter`` does not work.
 Writing custom template tags
 ----------------------------

django/template/defaultfilters.py

 # STRING DECORATOR    #
 #######################
 def stringfilter(func):
+def stringfilter(func=None, **flags):
     """
     Decorator for filters which should only receive unicode objects. The object
     passed as the first positional argument will be converted to a unicode
     object.
     """
+    if func is None:
+        # @stringfilter(is_safe=..., needs_autoescape=...)
+        return lambda f: _stringfilter(f, **flags)
+    else:
+        # @stringfilter
+        return _stringfilter(func)
+def _stringfilter(func, **flags):
     def _dec(*args, **kwargs):
         if args:
             args = list(args)
 …
     # arguments by the template parser).
     _dec._decorated_function = getattr(func, '_decorated_function', func)
     for attr in ('is_safe', 'needs_autoescape'):
+        if hasattr(func, attr):
+        if attr in flags:
+            setattr(func, attr, flags[attr])
+            setattr(_dec, attr, flags[attr])
+        elif hasattr(func, attr):
             setattr(_dec, attr, getattr(func, attr))
     return wraps(func)(_dec)
 …
 ###################
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def addslashes(value):
     """
     Adds slashes before quotes. Useful for escaping strings in CSV, for
 …
     filter instead.
     """
     return value.replace('\\', '\\\\').replace('"', '\\"').replace("'", "\\'")
-addslashes.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def capfirst(value):
     """Capitalizes the first character of the value."""
     return value and value[0].upper() + value[1:]
-capfirst.is_safe = True
 @register.filter("escapejs")
 @stringfilter
 …
     return escapejs(value)
 @register.filter("fix_ampersands")
 @stringfilter
+@stringfilter(is_safe=True)
 def fix_ampersands_filter(value):
     """Replaces ampersands with ``&amp;`` entities."""
     return fix_ampersands(value)
-fix_ampersands_filter.is_safe = True
 # Values for testing floatformat input against infinity and NaN representations,
 # which differ across platforms and Python versions.  Some (i.e. old Windows
 …
 floatformat.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def iriencode(value):
     """Escapes an IRI value for use in a URL."""
     return force_unicode(iri_to_uri(value))
-iriencode.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True, needs_autoescape=True)
 def linenumbers(value, autoescape=None):
     """Displays text with line numbers."""
     lines = value.split(u'\n')
 …
         for i, line in enumerate(lines):
             lines[i] = (u"%0" + width  + u"d. %s") % (i + 1, escape(line))
     return mark_safe(u'\n'.join(lines))
-linenumbers.is_safe = True
-linenumbers.needs_autoescape = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def lower(value):
     """Converts a string into all lowercase."""
     return value.lower()
-lower.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=False)
 def make_list(value):
     """
     Returns the value turned into a list.
 …
     For a string, it's a list of characters.
     """
     return list(value)
-make_list.is_safe = False
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def slugify(value):
     """
     Normalizes string, converts to lowercase, removes non-alpha characters,
 …
     value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore')
     value = unicode(re.sub('[^\w\s-]', '', value).strip().lower())
     return mark_safe(re.sub('[-\s]+', '-', value))
-slugify.is_safe = True
 @register.filter
 def stringformat(value, arg):
 …
 stringformat.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def title(value):
     """Converts a string into titlecase."""
     t = re.sub("([a-z])'([A-Z])", lambda m: m.group(0).lower(), value.title())
     return re.sub("\d([A-Z])", lambda m: m.group(0).lower(), t)
-title.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def truncatechars(value, arg):
     """
     Truncates a string after a certain number of characters.
 …
     except ValueError: # Invalid literal for int().
         return value # Fail silently.
     return Truncator(value).chars(length)
-truncatechars.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def truncatewords(value, arg):
     """
     Truncates a string after a certain number of words.
 …
     except ValueError: # Invalid literal for int().
         return value # Fail silently.
     return Truncator(value).words(length, truncate=' ...')
-truncatewords.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def truncatewords_html(value, arg):
     """
     Truncates HTML after a certain number of words.
 …
     except ValueError: # invalid literal for int()
         return value # Fail silently.
     return Truncator(value).words(length, html=True, truncate=' ...')
-truncatewords_html.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=False)
 def upper(value):
     """Converts a string into all uppercase."""
     return value.upper()
-upper.is_safe = False
 @register.filter
 @stringfilter
+@stringfilter(is_safe=False)
 def urlencode(value, safe=None):
     """
     Escapes a value for use in a URL.
 …
     if safe is not None:
         kwargs['safe'] = safe
     return urlquote(value, **kwargs)
-urlencode.is_safe = False
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True, needs_autoescape=True)
 def urlize(value, autoescape=None):
     """Converts URLs in plain text into clickable links."""
     return mark_safe(urlize_impl(value, nofollow=True, autoescape=autoescape))
-urlize.is_safe = True
-urlize.needs_autoescape = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True, needs_autoescape=True)
 def urlizetrunc(value, limit, autoescape=None):
     """
     Converts URLs into clickable links, truncating URLs to the given character
 …
     """
     return mark_safe(urlize_impl(value, trim_url_limit=int(limit), nofollow=True,
                             autoescape=autoescape))
-urlizetrunc.is_safe = True
-urlizetrunc.needs_autoescape = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=False)
 def wordcount(value):
     """Returns the number of words."""
     return len(value.split())
-wordcount.is_safe = False
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def wordwrap(value, arg):
     """
     Wraps words at specified line length.
 …
     Argument: number of characters to wrap the text at.
     """
     return wrap(value, int(arg))
-wordwrap.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def ljust(value, arg):
     """
     Left-aligns the value in a field of a given width.
 …
     Argument: field size.
     """
     return value.ljust(int(arg))
-ljust.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def rjust(value, arg):
     """
     Right-aligns the value in a field of a given width.
 …
     Argument: field size.
     """
     return value.rjust(int(arg))
-rjust.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def center(value, arg):
     """Centers the value in a field of a given width."""
     return value.center(int(arg))
-center.is_safe = True
 @register.filter
 @stringfilter
 …
 ###################
 @register.filter("escape")
 @stringfilter
+@stringfilter(is_safe=True)
 def escape_filter(value):
     """
     Marks the value as a string that should not be auto-escaped.
     """
     return mark_for_escaping(value)
-escape_filter.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def force_escape(value):
     """
     Escapes a string's HTML. This returns a new string containing the escaped
 …
     possible escaping).
     """
     return mark_safe(escape(value))
-force_escape.is_safe = True
 @register.filter("linebreaks")
 @stringfilter
+@stringfilter(is_safe=True, needs_autoescape=True)
 def linebreaks_filter(value, autoescape=None):
     """
     Replaces line breaks in plain text with appropriate HTML; a single
 …
     """
     autoescape = autoescape and not isinstance(value, SafeData)
     return mark_safe(linebreaks(value, autoescape))
-linebreaks_filter.is_safe = True
-linebreaks_filter.needs_autoescape = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True, needs_autoescape=True)
 def linebreaksbr(value, autoescape=None):
     """
     Converts all newlines in a piece of plain text to HTML line breaks
 …
     if autoescape:
         value = escape(value)
     return mark_safe(value.replace('\n', '<br />'))
-linebreaksbr.is_safe = True
-linebreaksbr.needs_autoescape = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def safe(value):
     """
     Marks the value as a string that should not be auto-escaped.
     """
     return mark_safe(value)
-safe.is_safe = True
 @register.filter
 def safeseq(value):
 …
 safeseq.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def removetags(value, tags):
     """Removes a space separated list of [X]HTML tags from the output."""
     tags = [re.escape(tag) for tag in tags.split()]
 …
     value = starttag_re.sub(u'', value)
     value = endtag_re.sub(u'', value)
     return value
-removetags.is_safe = True
 @register.filter
 @stringfilter
+@stringfilter(is_safe=True)
 def striptags(value):
     """Strips all [X]HTML tags."""
     return strip_tags(value)
-striptags.is_safe = True
 ###################
 # LISTS           #

Download in other formats:

Original Format

Issues

Context Navigation

Ticket #17135: 17135.2.patch

docs/howto/custom-template-tags.txt

django/template/defaultfilters.py

Download in other formats:

Django Links

Learn More

Get Involved

Get Help

Follow Us

Support Us