Built-in Django filters

Django filters are designed to format template variables. The syntax to apply Django filters is the vertical bar character | also known as 'pipe' in Unix environments (e.g.{{variable|filter}}). It's worth mentioning that it's possible to use multiple filters on the same variable (e.g.{{variable|filter|filter}}).

I'll classify each built-in Django filter into functional sections so it's easier to identify them. The functional classes I'll use are: Dates, Strings, Lists, Numbers, Dictionaries, Spacing and special characters, Development and Testing & Urls.

Dates

• date.- The date filter formats Python datetime objects and only works if the variable is this type of Python object. The date filter uses a string to specify a format. For example, if a variable contains a datetime object with the date 01/01/2022, the filter statement {{variable|date:"F jS o"}} outputs January 1st 2022. The string syntax for the date filter is based on the characters described in table 3-3.

Table 3-3. Django date & time format characters

To literally output a date character in a string statement you can use the backslash character (e.g. {{variable|date:"jS \o\f F o"}} outputs 1st of January 2022, note the escaped \o\f)

• time.- The time filter formats the time component of a Python datetime object. The time filter is similar to the date filter which uses a string to specify a time format. For example, if a variable contains a datetime object with a time of noon the filter statement {{variable|time:"g:i"}} outputs 12:00. The time filter uses the same format characters illustrated in table 3-3 related to the time of day.

• timesince.- The timesince filter outputs the time that's passed between a datetime object and the current time. The timesince filter output is expressed in seconds, minutes, hours, days or weeks. For example, if a variable contains the datetime object 01/01/2022 12:00pm and the current time is 01/01/2022 3:30pm the statement {{variable|timesince}} outputs 3 hours 30 minutes. The timesince filter can also calculate the time that's passed between two datetime object variables -- instead of the default current time -- by appending a second datetime object argument (e.g. {{variable|timesince:othervariable}}).
• timeuntil.-The timeuntil filter outputs the time that needs to elapse from the current time to a datetime object. The timeuntil filter output is expressed in seconds, minutes, hours, days or weeks. For example, if a variable contains the datetime object 01/01/2022 10:00pm and the current time is 01/01/2022 9:00pm the statement {{variable|timeuntil}} outputs 1 hour. The timeuntil filter can also calculate the time that needs to elapse between two datetime object variables -- instead of the default current time -- by appending a second datetime object argument (e.g. {{variable|timeuntil:othervariable}}).

Strings, lists and numbers

• add.- The add filter adds values. The add filter can add two variables or a hardcoded value and a variable. For example, if a variable contains 5 the filter statement {{variable|add:"3"}} outputs 8. If values can be coerced to integers -- like the last example -- the add filter performs a sum, if not the add filter concatenates. For a string variable that contains "Hello" the filter statement {{variable|add:" World"}} outputs Hello World. For a list variable that contains ['a','e','i'] and another list variable that contains ['o','u'] the filter statement {{variable|add:othervariable}} outputs ['a','e','i','o','u'].
• default.- The default filter is used to specify a default value if a variable is false, doesn't exist or is empty. For example, if a variable doesn't exist in a template, contains False or is an empty string ('') the filter statement {{variable|default:"no value"}} outputs no value.
• default_if_none.- The default filter is used to specify a default value if a variable is None. For example, if a variable contains None the filter statement {{variable|default_if_none:"No value"}} outputs No value. Note if a variable contains an empty string ('') this is not considered None and the default_if_none filter does not output its argument value.
• length.- The length filter is used to obtain the length of a value. For example, if a variable contains the string latte the filter statement {{variable|length}} outputs 5. For a list variable that contains ['a','e','i'] the filter statement {{variable|length}} outputs 3.
• length_is.- The length_is filter is used to evaluate if the length of a value is the size of a given argument. For example, if a variable contains latte the tag and filter statement {% if variable|length_is:"7" %} evaluates to false. For a list variable that contains ['a','e','i'] the tag and filter statement {% if variable|length_is:"3" %} evaluates to true.
• make_list.- The make_list filter creates a list from a string or number. For example, for the filter and tag statement {% with mycharlist="mocha"|make_list %} the mycharlist variable is assigned the list ['m', 'o', 'c', 'h', 'a']. For an integer variable that contains 724 the filter and tag statement {% with myintlist=variable|make_list %} the myintlist is assigned the list ['7', '2', '4'].
• yesno.- The yesno filter maps the value of a variable from True,False and None to the strings yes,no,maybe. For example, if a variable evaluates to True the filter statement {{variable|yesno}} outputs yes, if the variable evaluates to False the same statement outputs no and if the variable evaluates to None the same statement outputs maybe. The yesno filter also accepts custom messages as arguments. For example, if a variable evaluates to True the filter statement {{variable|yesno:"yea,nay,novote"}} outputs yea, if the variable evaluates to False the same statement outputs nay and if the variable evaluates to None the same statement outputs novote.

Numbers

• divisibleby.- The divisibleby filter returns a boolean value if a variable is divisible by a given value. For example, if a variable contains 20 the filter statement {{variable|divisibleby:"5"}} returns True.
• filesizeformat.-The filesizeformat filter converts a number of bytes into a friendly file size string. For example, if a variable contains 250 the filter statement {{variable|filesizeformat}} outputs 250 bytes, if it contains 2048 the output is 2 KB, if it contains 2000000000 the output is 1.9 GB.
• floatformat.- The floatformat filter rounds a floating-point number variable. The floatformat filter can accept a positive or negative integer argument to round a variable a specific number of decimals. If zero is the argument the variable is rounded to the nearest integer. If no argument is used, the floatformat filter rounds to one decimal place, as if the argument where -1. For example, if a variable contains 9.53253 the filter statement {{variable|floatformat}} outputs 9.5, for the same variable {{variable|floatformat:3}} outputs 9.533, for {{variable|floatformat:-3}} the output is 9.533 and for {{variable:floatformat:0}} the output is 10; if a variable contains 9.00000 the filter statement {{variable|floatformat}} outputs 9, {{variable|floatformat:3}} outputs 9.000, {{variable|floatformat:-3}} outputs 9 and {{variable|floatformat:0}} outputs 9; and if a variable contains 9.37000 the filter statement {{variable|floatformat}} outputs 9.4, {{variable|floatformat:3}} outputs 9.370, {{variable|floatformat:-3}} outputs 9.370 and {{variable|floatformat:0}} outputs 9 9.370.

  The floatformat filter also supports a g suffix added to the number argument to format the resulting number with the THOUSAND_SEPARATOR in a project's settings.py file. For example, if a variable contains 1100500.87000 the filter statement {{variable|floatformat:"g"}} outputs 1,100,500.9, for the same variable {{variable|floatformat:"3g"}} outputs 1,100,500.870, for {{variable|floatformat:"-3g"}} the output is 1,100,500.870 and for {{variable:floatformat:"0g"}} the output is 1,100,501.

Note The THOUSAND_SEPARATOR used by the g suffix is dependent on locale (e.g. If a locale is en the default THOUSAND_SEPARATOR is , since it's the convention used to format numbers with thousands in english).

• get_digit.- The get_digit filter outputs the digit of a number variable, where 1 is the last digit, 2 is the second to last digit and so on. For example, if a variable contains 10257, the filter statement {{variable|get_digit:"1"}} outputs 7 and the filter statement {{variable|get_digit:"3"}} outputs 2. If the variable or argument is not an integer or if the argument is less than 1, the get_digit filter output's the original variable value.
• phone2numeric.- The phone2numeric filter converts mnemonic letters in phone numbers to digits. For example, if a variable contains 1-800-DJANGO the filter statement {{variable|phone2numeric}} outputs 1-800-352646. A phone2numeric filter value doesn't necessarily need to process valid phone numbers, the filter simply converts letters to their equivalent telephone keypad numbers.

Strings

• capfirst.- The capfirst filter capitalizes the first character of a string variable. For example, if a variable contains hello world the filter statement {{variable|capfirst}} outputs Hello world.
• cut.- The cut filter removes all values of a given argument from a string variable. For example, if a variable contains mocha latte the filter statement {{variable|filter:"mocha"}} outputs latte. For the same variable the filter statement is {{variable|filter:" "}} outputs mochalatte.
• linenumbers.- The linenumbers filter adds line numbers to each string value separated by a new line. Listing 3-15 illustrates an example of the linenumbers filter.

Listing 3-15 Django linenumbers filter

# Variable definition 
variable = ["Downtown","Uptown","Midtown"]

# Template definition with linenumbers filter
{{variable|linenumbers}}

# Output
1.Downtown
2.Uptown
3.Midtown

• lower.- The lower filter converts all values of a string variable to lowercase. For example, if a variable contains Hello World the filter statement {{variable|lower}} outputs hello world.
• stringformat.- The stringformat filter formats a value with Python string formatting syntax^[4]. For example, if a variable contains 7 the filter statement {{variable|stringformat:"03d"}} outputs 007. Note the stringformat filter does not require the leading % used in Python string formatting syntax.
• pluralize.- The pluralize filter returns a plural suffix based on the value of an argument. For example, if the variable drink_count contains 1 the filter statement "You have {{drink_count}} drink{{pluralize|drink_count}}" outputs "You have 1 drink", if the variable contains 2 the same filter statement outputs "You have 2 drinks". By default, the pluralize filter uses the letter s which is the most common plural suffix. However, you can specify different singular and plural suffixes with additional arguments. For example, the filter statement "We have {{store_count}} business{{store_count|pluralize:"es"}}" outputs "We have 1 business" if store_count is 1 or "We have 5 businesses" if store_count is 5. Another example is the filter statement "We have {{resp_number}} responsibilit{{resp_number|pluralize:"y","ies"}}" which outputs "We have 1 responsibility" if resp_number is 1 or "We have 3 responsibilities" if resp_number is 3.
• slugify.- The slugify filter converts a string to an ASCII-type string. This means a string in converted to lowercase, removes non-word characters (alphanumerics and underscores), strips leading and trailing white space, as well as converts spaces to hyphens. For example, if a variable contains Welcome to the #1 Coffeehouse! the filter statement {{variable|slugify}} outputs welcome-to-the-1-coffeehouse. The slugify filter is typically used to normalize strings for urls and file paths.
• title.- The title filter converts all first character values of a string variable to uppercase. For example, if a variable contains hello world the filter statement {{variable|title}} outputs Hello World.
• truncatechars.- The truncatechars filter truncates a string to a given number of characters and appends an ellipsis sequence. For example, if a variable contains Coffeehouse started as a small store the filter statement {{variable|truncatechars:20}} outputs Coffeehouse started....
• truncatechars_html.- The truncatechars_html filter is similar to the truncatechars filter but is aware of HTML tags. This filter is designed for HTML content, so content isn't left with open HTML tags. For example, if a variable contains <b>Coffeehouse started as a small store</b> the filter statement {{variable|truncachars_html:20}} outputs <b>Coffeehouse start...</b>.
• truncatewords.- The truncatewords filter truncates a string to a given number of words and appends an ellipsis sequence. For example, if a variable contains Coffeehouse started as a small store the filter statement {{variable|truncatwords:3}} outputs Coffeehouse started as....
• truncatewords_html.- The truncatewords_html filter is similar to the truncatewords filter but is aware of HTML tags. This filter is designed for HTML content, so content isn't left with open HTML tags. For example, if a variable contains <b>Coffeehouse started as a small store</b> the filter statement {{variable|truncatwords_html:3}} outputs <b>Coffeehouse started as...</b>.
• upper.- The upper filter converts all values of a string variable to uppercase. For example, if a variable contains Hello World the filter statement {{variable|lower}} outputs HELLO WORLD.
• wordcount.- The wordcount filter counts the words in a string. For example, if a variable contains Coffeehouse started as a small store the filter statement {{variable|wordcount}} outputs 6.

Lists and dictionaries

• dictsort.- The dictsort filter sorts a list of dictionaries and returns new list sorted by a given key argument. For example, if a variable contains [{'name':'Downtown','city':'San Diego'}, {'name':'Uptown','city':'San Diego'},{'name':'Midtown','city':'San Diego'}] the filter and tag statement {% with newdict=variable|dictsort:"name" %} the newdict variable is assigned the list [{'name':'Downtown','city':'San Diego'},{'name':'Midtown','city':'San Diego'},{'name':'Uptown','city':'San Diego'}]. The dictsort filter can also operate on lists of tuples or lists by specify an index number (e.g. {% with otherlist=listoftuples|dictsort:0 %}) to sort by the first element of each tuple in the list).
• dictsortreversed.- The dictsortreversed filter sorts a list of dictionaries and returns new list sorted in reverse by a given key argument. The dictsortreversed filter works like dictsort except it returns the list in reverse order.
• join.- The join filter joins a list with a string. The join filter works just like Python's str.join(list). For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|join:"--"}} outputs a--e--i--o--u.
• first.- The first filter returns the first item in a list. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|first}} outputs a.
• last.- The last filter returns the last item in a list. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|last}} outputs u.
• random.- The random filter returns a random item in a list. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|random}} could output a, e, i, o or u.
• slice.- The slice filter returns the slice of a list. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|slice:":3"}} outputs ['a','e','i'].
• unordered_list.- The unordered_list outputs an HTML unordered list from a list variable. Listing 3-16 illustrates an example of the unordered_list filter.

Listing 3-16. Django unordered_list filter

# Variable definition 
variable = ["Stores",["San Diego",["Downtown","Uptown","Midtown"]]]

# Template definition with linenumbers filter
{{variable|unordered_list}}

# Output
<li>Stores
   <ul>
       <li>San Diego
          <ul>
   <li>Downtown</li>
   <li>Uptown</li>
   <li>Midtown</li>
  </ul>
       </li>
   </ul>
</li>

Spacing and special characters

• addslashes.- The addslashes filter adds slashes to all quotes (i.e. it escapes quotes). The addslashes filter is useful when Django templates are used to export data to other systems that require to escape quotes (e.g. CSV files). For example, if a variable contains Today's news the filter statement {{variable|addslashes}} outputs Today\'s news.
• center.- The center filter center aligns a value and pads it with additional white space characters until it reaches the given argument of characters. For example, if a variable contains mocha the filter statement {{variable|center:"15"}} outputs
• " mocha ". (i.e. 5 spaces to the left of mocha, 5 spaces for mocha, 5 spaces to the right of mocha.
• ljust.- The ljust filter left aligns a value and pads it with additional white space characters until it reaches the given argument of characters. For example, if a variable contains mocha the filter statement {{variable|ljust:"15"}} outputs
• "mocha ".(i.e. 5 spaces for mocha, 10 space padding).
• rjust.- The rjust filter right aligns a value and pads it with additional white space characters until it reaches the given argument of characters. For example, if a variable contains latte the filter statement {{variable|rjust:"10"}} outputs
• " latte"."(i.e. 5 space padding, 5 spaces for latte).
• escape.- The escape filter escapes HTML characters from a value. Specifically with the escape filter: < is converted to < ,> is converted to > ,' (single quote) is converted to ' ," (double quote) is converted to " and & is converted to &amp.

Tip If you use the escape filter on contiguous variables, it's easier to wrap the variables with the {% autoescape %} tag to achieve the same results.

• escapejs.- The escapejs filter escapes characters into unicode strings which are often used for JavaScript strings. Though the escapejs filter does not make a string HTML safe, it does protect against syntax errors when using templates to generate JavaScript/JSON. For example, if a variable contains "mocha\r\n \'price:2.25" the filter statement {{variable|escapejs}} outputs \u0022mocha\u000D\u000A \u0027price:2.25\u0022.
• force_escape.- The force_escape filter escapes HTML characters from a value just like the escape filter. The difference is force_escape is applied immediately and returns a new and escaped string. This is useful when you need multiple escaping or want to apply other filters to the escaped results. Normally, you'll use the escape filter.
• json_script.- The json_script filter outputs a Python object as JSON, wrapped in an HTML <script> element. The json_script requires two arguments, a reference to a Python object (e.g. dictionary, list) and a string to use as the id attribute value of the <script> element. For example, for a dictionary that contains {'Django','3.2'} the filter statement {{variable|json_script:"django-version"}} outputs <script id="django-version" id="django-version" type="application/json">{"Django":"3.2"}</script>.
• linebreaks.- The linebreaks filter replaces plain text line breaks with HTML tags, a single newline becomes an HTML line break (<br/>) and a new line followed by a blank line becomes a paragraph break (</p>). For example, if a variable contains 385 Main\nSan Diego, CA the filter statement {{variable|linebreaks}} outputs <p>385 Main<br/>San Diego, CA</p>.
• linebreaksbr.- The linebreaksbr filter converts all text variable new lines to HTML line breaks (<br/>). For example, if a variable contains 385 Main\nSan Diego, CA the filter statement {{variable|linebreaksbr}} outputs 385 Main<br/>San Diego, CA.
• striptags.- The striptags filter removes all HTML tags from a value. For example, if a variable contains <b>Coffee</b>house, the <i>best</i> <span>drinks</span> the filter statement {{variable|striptags}} outputs Coffeehouse, the best drinks.

Caution The striptags filter uses very basic logic to strip HTML tags. This means there's a possibility a convoluted piece of HTML isn't fully stripped of tags. This is why content in variables passed through the striptags filter is automatically escaped and should never be marked as safe.

• safe.- The safe filter marks a string as not requiring HTML escaping.
• safeseq.- The safeseq applies the safe filter to each element of a list. It's useful in conjunction with other filters that operate on a list, such as the join filter (e.g.{{stores|safeseq|join:", "}}). You wouldn't use the safe filter directly on list variables, as it would first convert the variable to a string, rather than working with the individual elements of a list.
• wordwrap.- The wordwrap filter wraps words at a given character line length argument. Listing 3-17 illustrates an example of the wordwrap filter.

Listing 3-17. Django wordwrap filter

# Variable definition 
Coffeehouse started as a small store
# Template definition with wordwrap filter for every 12 characters
{{variable|wordwrap:12}}
# Output
Coffeehouse 
started as a
small store

Development and testing

• pprint.- The pprint filter is a wrapper for Python's pprint.pprint(). The pprint filter is useful during development and testing because it outputs the formatted representation of an object.

Urls

• iriencode.- The iriencode filter converts an Internationalized Resource Identifier (IRI) to a string that is suitable for inclusion in a URL. This is necessary if you're trying to use strings containing non-ASCII characters in a URL. For example, if a variable contains ?type=cold&size=large the filter statement {{variable|iriencode}} outputs ?type=cold&size=large.
• urlencode.- The urlencode filter escapes a value for use in a URL. For example, if a variable contains http://localhost/drinks?type=cold&size=large the filter statement {{variable|urlencode}} outputs http%3A//localhost/drinks%3Ftype%3Dcold%26size%3Dlarge. The urlenconde filter assumes the / character is safe. The urlencode filter can accept an optional argument with the characters that should not be escaped. An empty string can be provided when all characters should be escaped (e.g.{{variable|urlencode:""}} outputs http%3A%2F%2Flocalhost%2Fdrinks%3Ftype%3Dcold%26size%3Dlarge).
• urlize.- The urlize filter converts text URLs or email addresses into clickable HTML links. This urlize filter works on links prefixed with http://, https://, or www.. Links generated by the urlize filter have a rel="nofollow" attribute added to them. For example, if a variable contains Visit http://localhost/drinks the filter statement {{variable|urlize}} outputs Visit <a href="http://localhost/drinks" rel="nofollow">http://localhost/drinks</a>; if a variables contains Contact support@coffeehouse.com the filter statement {{variable|urlize}} outputs Contact <a href="mailto:support@coffeehouse.com">support@coffeehouse.com</a>.
• urlizetrunc.- The urlizetrunc filter converts text URLs and emails into clickable HTML links -- just like the urlize filter -- except it truncates the url to a given number of characters that include an ellipsis sequence. For example, if a variable contains Visit http://localhost/drinks the filter statement {{variable|urlizetrunc:20}} outputs Visit <a href="http://localhost/drinks" rel="nofollow">http://localhost/...</a>.

4. https://docs.python.org/3/library/stdtypes.html#old-string-formatting     ↑