mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-04-05 05:56:42 +00:00
Code Issues 32 Releases Wiki Activity

Added examples in Python

Browse Source 
This does most of the register.filter(is_safe=True) methods
This commit is contained in:
Ryan Cheley 2024-10-19 11:12:44 -07:00
parent 4ded307bcc
commit 758538963c
1 changed files with 338 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

363
docs/ref/templates/builtins.txt
View File

@ -2,6 +2,8 @@
Built-in template tags and filters
==================================
.. module:: django.template.defaultfilters
This document describes Django's built-in template tags and filters. It is
recommended that you use the :doc:`automatic documentation
</ref/contrib/admin/admindocs>`, if available, as this will also include
@ -1567,7 +1569,7 @@ output will be ``[1, 2, 3, 4, 5, 6]``.
Adds slashes before quotes. Useful for escaping strings in CSV, for example.
For example:
For example in a template:
.. code-block:: html+django
@ -1576,6 +1578,16 @@ For example:
If ``value`` is ``"I'm using Django"``, the output will be
``"I\'m using Django"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import addslashes
sometext = addslashes("I'm using Django")
If ``value`` is ``"I'm using Django"``, the output will be
``"I\\'m using Django"``.
.. templatefilter:: capfirst
``capfirst``
@ -1584,7 +1596,7 @@ If ``value`` is ``"I'm using Django"``, the output will be
Capitalizes the first character of the value. If the first character is not
a letter, this filter has no effect.
For example:
For example in a template:
.. code-block:: html+django
@ -1592,6 +1604,15 @@ For example:
If ``value`` is ``"django"``, the output will be ``"Django"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import capfirst
sometext = capfirst("django")
If ``value`` is ``"django"``, the output will be ``"Django"``.
.. templatefilter:: center
``center``
@ -1599,7 +1620,7 @@ If ``value`` is ``"django"``, the output will be ``"Django"``.
Centers the value in a field of a given width.
For example:
For example in a template:
.. code-block:: html+django
@ -1607,6 +1628,15 @@ For example:
If ``value`` is ``"Django"``, the output will be ``" Django "``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import center
sometext = center("Django", 15)
If ``value`` is ``"Django"``, the output will be ``" Django "``.
.. templatefilter:: cut
``cut``
@ -1727,7 +1757,7 @@ Format character Description Example output
(January 1 1970 00:00:00 UTC).
================ ======================================== =====================
For example:
For example in a template:
.. code-block:: html+django
@ -1771,6 +1801,65 @@ representation of a ``datetime`` value. E.g.:
{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}
For example in Python:
.. code-block:: python
from django.template.defaultfilters import date
formatted_date = date(value, "D d M Y")
If ``value`` is a :py:class:`~datetime.datetime` object (e.g., the result of
``datetime.datetime.now()``), the output will be the string
``'Wed 09 Jan 2008'``.
The format passed can be one of the predefined ones :setting:`DATE_FORMAT`,
:setting:`DATETIME_FORMAT`, :setting:`SHORT_DATE_FORMAT` or
:setting:`SHORT_DATETIME_FORMAT`, or a custom format that uses the format
specifiers shown in the table above. Note that predefined formats may vary
depending on the current locale.
Assuming that :setting:`LANGUAGE_CODE` is, for example, ``"es"``, then for:
.. code-block:: python
from django.template.defaultfilters import date
formatted_date = date(value, "SHORT_DATE_FORMAT")
the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"``
format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``).
When used without a format string, the ``DATE_FORMAT`` format specifier is
used. Assuming the same settings as the previous example:
.. code-block:: html+django
from django.template.defaultfilters import date
formatted_date = date(value)
outputs ``9 de Enero de 2008`` (the ``DATE_FORMAT`` format specifier for the
``es`` locale is ``r'j \d\e F \d\e Y'``). Both "d" and "e" are
backslash-escaped, because otherwise each is a format string that displays the
day and the timezone name, respectively.
You can combine ``date`` with the :tfilter:`time` filter to render a full
representation of a ``datetime`` value. E.g.:
.. code-block:: html+django
from django.template.defaultfilters import date
from django.template.defaultfilters import time
formatted_date = date(value, "D d M Y")
formatted_time = time(value, "H:i")
formatted_datetime = f"{formatted_date} {formatted_time}"
.. function:: date(value, arg=None)
This function formats a date according to the given format.
.. templatefilter:: default
``default``
@ -1992,7 +2081,9 @@ For example:
Applies the :tfilter:`escape` filter to each element of a sequence. Useful in
conjunction with other filters that operate on sequences, such as
:tfilter:`join`. For example:
:tfilter:`join`.
For example in a template:
.. code-block:: html+django
@ -2000,6 +2091,19 @@ conjunction with other filters that operate on sequences, such as
{{ my_list|escapeseq|join:", " }}
{% endautoescape %}
For example in Python:
.. code-block:: python
from django.template.defaultfilters import escapeseq
from django.template.defaultfilters import join
my_list = ["<b>first</b>", "<i>second</i>"]
escaped_list = escapeseq(my_list)
joined_list = join(escaped_list, ", ")
The output will be ``"&lt;b&gt;first&lt;/b&gt;, &lt;i&gt;second&lt;/i&gt;"``.
.. templatefilter:: filesizeformat
``filesizeformat``
@ -2008,7 +2112,7 @@ conjunction with other filters that operate on sequences, such as
Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``,
``'4.1 MB'``, ``'102 bytes'``, etc.).
For example:
For example in a template:
.. code-block:: html+django
@ -2016,6 +2120,15 @@ For example:
If ``value`` is 123456789, the output would be ``117.7 MB``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import filesizeformat
formatted_size = filesizeformat(123456789)
The value of ``formatted_size`` will be ``'117.7\xa0MB'``.
.. admonition:: File sizes and SI units
Strictly speaking, ``filesizeformat`` does not conform to the International
@ -2116,6 +2229,15 @@ locale is ``pl`` (Polish):
Using ``floatformat`` with no argument is equivalent to using ``floatformat``
with an argument of ``-1``.
This can also be used in Python by doing the following:
.. code-block:: python
from django.template.defaultfilters import floatformat
formatted_float = floatformat(34.23234, 3)
The example table above used for the templates will return the same results.
.. templatefilter:: force_escape
``force_escape``
@ -2166,7 +2288,7 @@ strings containing non-ASCII characters in a URL.
It's safe to use this filter on a string that has already gone through the
:tfilter:`urlencode` filter.
For example:
For example in a template:
.. code-block:: html+django
@ -2175,6 +2297,16 @@ For example:
If ``value`` is ``"?test=I ♥ Django"``, the output will be
``"?test=I%20%E2%99%A5%20Django"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import iriencode
url = iriencode("?test=I ♥ Django")
If ``value`` is ``"?test=I ♥ Django"``, the output will be
``"?test=I%20%E2%99%A5%20Django"``.
.. templatefilter:: join
``join``
@ -2237,7 +2369,7 @@ executable code.
Returns the last item in a list.
For example:
For example in a template:
.. code-block:: html+django
@ -2246,6 +2378,15 @@ For example:
If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the
string ``"d"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import last
last_item = last(['a', 'b', 'c', 'd'])
The value of ``last_item`` will be ``"d"``.
.. templatefilter:: length
``length``
@ -2306,7 +2447,7 @@ slug``.
Displays text with line numbers.
For example:
For example in a template:
.. code-block:: html+django
@ -2328,6 +2469,19 @@ the output will be:
2. two
3. three
for example in Python:
.. code-block:: python
from django.template.defaultfilters import linenumbers
numbered_text = linenumbers("one\ntwo\nthree")
the output will be:
.. code-block:: python
"1. one\n2. two\n3. three"
.. templatefilter:: ljust
``ljust``
@ -2337,7 +2491,7 @@ Left-aligns the value in a field of a given width.
**Argument:** field size
For example:
For example in a template:
.. code-block:: html+django
@ -2345,6 +2499,15 @@ For example:
If ``value`` is ``Django``, the output will be ``"Django "``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import ljust
left_aligned = ljust("Django", 10)
The output will be ``"Django "``.
.. templatefilter:: lower
``lower``
@ -2352,7 +2515,7 @@ If ``value`` is ``Django``, the output will be ``"Django "``.
Converts a string into all lowercase.
For example:
For example in a template:
.. code-block:: html+django
@ -2361,6 +2524,15 @@ For example:
If ``value`` is ``Totally LOVING this Album!``, the output will be
``totally loving this album!``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import lower
lowercased = lower("Totally LOVING this Album!")
The output will be ``"totally loving this album!"``.
.. templatefilter:: make_list
``make_list``
@ -2390,7 +2562,7 @@ equivalent.
The input doesn't have to be a valid phone number. This will happily convert
any string.
For example:
For example in a template:
.. code-block:: html+django
@ -2449,7 +2621,7 @@ A wrapper around :func:`pprint.pprint` -- for debugging, really.
Returns a random item from the given list.
For example:
For example in a template:
.. code-block:: html+django
@ -2457,6 +2629,15 @@ For example:
If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import random
random_item = random(['a', 'b', 'c', 'd'])
The value of ``random_item`` will be a random item from the list.
.. templatefilter:: rjust
``rjust``
@ -2466,7 +2647,7 @@ Right-aligns the value in a field of a given width.
**Argument:** field size
For example:
For example in a template:
.. code-block:: html+django
@ -2474,6 +2655,15 @@ For example:
If ``value`` is ``Django``, the output will be ``" Django"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import rjust
right_aligned = rjust("Django", 10)
The output will be ``" Django"``.
.. templatefilter:: safe
``safe``
@ -2537,7 +2727,7 @@ Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't
alphanumerics, underscores, or hyphens. Converts to lowercase. Also strips
leading and trailing whitespace.
For example:
For example in a template:
.. code-block:: html+django
@ -2545,6 +2735,15 @@ For example:
If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import slugify
slug = slugify("Joel is a slug")
The value of ``slug`` will be ``"joel-is-a-slug"``.
.. templatefilter:: stringformat
``stringformat``
@ -2554,7 +2753,7 @@ Formats the variable according to the argument, a string formatting specifier.
This specifier uses the :ref:`old-string-formatting` syntax, with the exception
that the leading "%" is dropped.
For example:
For example in a template:
.. code-block:: html+django
@ -2562,6 +2761,15 @@ For example:
If ``value`` is ``10``, the output will be ``1.000000E+01``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import stringformat
formatted_value = stringformat(10, "E")
The value of ``formatted_value`` will be ``"1.000000E+01"``.
.. templatefilter:: striptags
``striptags``
@ -2569,7 +2777,7 @@ If ``value`` is ``10``, the output will be ``1.000000E+01``.
Makes all possible efforts to strip all [X]HTML tags.
For example:
For example in a template:
.. code-block:: html+django
@ -2578,6 +2786,15 @@ For example:
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the
output will be ``"Joel is a slug"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import striptags
stripped_value = striptags("<b>Joel</b> <button>is</button> a <span>slug</span>")
The value of ``stripped_value`` will be ``"Joel is a slug"``.
.. admonition:: No safety guarantee
Note that ``striptags`` doesn't give any guarantee about its output being
@ -2596,12 +2813,21 @@ Given format can be the predefined one :setting:`TIME_FORMAT`, or a custom
format, same as the :tfilter:`date` filter. Note that the predefined format
is locale-dependent.
For example:
For example in a template:
.. code-block:: html+django
{{ value|time:"H:i" }}
Or in Python:
.. code-block:: python
from django.template.defaultfilters import time
formatted_time = time(value, "H:i")
If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be
the string ``"01:23"``.
@ -2610,13 +2836,24 @@ Note that you can backslash-escape a format string if you want to use the
otherwise each is a format string that displays the hour and the month,
respectively:
Template example:
.. code-block:: html+django
{{ value|time:"H\h i\m" }}
Python example:
.. code-block:: python
from django.template.defaultfilters import time
formatted_time = time(value, "H\h i\m")
This would display as "01h 23m".
Another example:
Another example in a template:
Assuming that :setting:`LANGUAGE_CODE` is, for example, ``"de"``, then for:
@ -2624,6 +2861,14 @@ Assuming that :setting:`LANGUAGE_CODE` is, for example, ``"de"``, then for:
{{ value|time:"TIME_FORMAT" }}
Or in Python:
.. code-block:: python
from django.template.defaultfilters import time
formatted_time = time(value, "TIME_FORMAT")
the output will be the string ``"01:23"`` (The ``"TIME_FORMAT"`` format
specifier for the ``de`` locale as shipped with Django is ``"H:i"``).
@ -2651,6 +2896,25 @@ is the same as:
{{ value|time:"TIME_FORMAT" }}
The above example in Python:
.. code-block:: python
from django.template.defaultfilters import time
formatted_time = time(value)
would be the same as:
.. code-block:: python
from django.template.defaultfilters import time
formatted_time = time(value, "TIME_FORMAT")
.. function:: time(value, arg=None)
This function formats a time according to the given format.
.. templatefilter:: timesince
``timesince``
@ -2705,7 +2969,7 @@ Converts a string into titlecase by making words start with an uppercase
character and the remaining characters lowercase. This tag makes no effort to
keep "trivial words" in lowercase.
For example:
For example in a template:
.. code-block:: html+django
@ -2713,6 +2977,15 @@ For example:
If ``value`` is ``"my FIRST post"``, the output will be ``"My First Post"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import title
titled = title("my FIRST post")
The output of ``titled`` will be ``"My First Post"``.
.. templatefilter:: truncatechars
``truncatechars``
@ -2739,7 +3012,7 @@ For example in Python:
truncated = truncatechars("Joel is a slug", 7)
If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel i…"``.
The output of ``truncated`` will be ``"Joel i…"``.
.. function:: truncatechars(value, arg)
@ -2754,7 +3027,7 @@ Similar to :tfilter:`truncatechars`, except that it is aware of HTML tags. Any
tags that are opened in the string and not closed before the truncation point
are closed immediately after the truncation.
For example:
For example in a template:
.. code-block:: html+django
@ -2763,6 +3036,16 @@ For example:
If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be
``"<p>Joel i…</p>"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import truncatechars_html
truncated = truncatechars_html("<p>Joel is a slug</p>", 7)
The output of ``truncated`` will be ``"<p>Joel i…</p>"``.
Newlines in the HTML content will be preserved.
.. admonition:: Size of input string
@ -2780,7 +3063,7 @@ Truncates a string after a certain number of words.
**Argument:** Number of words to truncate after
For example:
For example in a template:
.. code-block:: html+django
@ -2788,6 +3071,16 @@ For example:
If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is …"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import truncatewords
truncated = truncatewords("Joel is a slug", 2)
The output of ``truncated`` will be ``"Joel is …"``.
Newlines within the string will be removed.
.. templatefilter:: truncatewords_html
@ -2802,7 +3095,7 @@ are closed immediately after the truncation.
This is less efficient than :tfilter:`truncatewords`, so should only be used
when it is being passed HTML text.
For example:
For example in a template:
.. code-block:: html+django
@ -2811,6 +3104,16 @@ For example:
If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be
``"<p>Joel is …</p>"``.
For example in Python:
.. code-block:: python
from django.template.defaultfilters import truncatewords_html
truncated = truncatewords_html("<p>Joel is a slug</p>", 2)
The output of ``truncated`` will be ``"<p>Joel is …</p>"``.
Newlines in the HTML content will be preserved.
.. admonition:: Size of input string
@ -2994,7 +3297,7 @@ Wraps words at specified line length.
**Argument:** number of characters at which to wrap the text
For example:
For example in a template:
.. code-block:: html+django
@ -3008,6 +3311,16 @@ If ``value`` is ``Joel is a slug``, the output would be:
is a
slug
For example in Python:
.. code-block:: python
from django.template.defaultfilters import wordwrap
wrapped = wordwrap("Joel is a slug", 5)
The output of ``wrapped`` will be ``'Joel\nis a\nslug'``.
.. templatefilter:: yesno
``yesno``