From 4933d8c47d24d4f6b054cdd0382e72aa4917fc84 Mon Sep 17 00:00:00 2001 From: Ryan Cheley Date: Sun, 24 Nov 2024 09:08:20 -0800 Subject: [PATCH] add examples for is safe False register.filter --- docs/ref/templates/builtins.txt | 275 ++++++++++++++++++++++++++++++-- 1 file changed, 261 insertions(+), 14 deletions(-) diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index e9b28d51d4..71a132bc42 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -1535,7 +1535,7 @@ Built-in filter reference Adds the argument to the value. -For example: +For example in a template: .. code-block:: html+django @@ -1543,12 +1543,21 @@ For example: If ``value`` is ``4``, then the output will be ``6``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import add + sometext = add(4, 2) + +The value of ``sometext`` will be ``6``. + This filter will first try to coerce both values to integers. If this fails, it'll attempt to add the values together anyway. This will work on some data types (strings, list, etc.) and fail on others. If it fails, the result will be an empty string. -For example, if we have: +For example in a template: .. code-block:: html+django @@ -1557,6 +1566,15 @@ For example, if we have: and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the output will be ``[1, 2, 3, 4, 5, 6]``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import add + sometext = add([1, 2, 3], [4, 5, 6]) + +The output of ``sometext`` will be ``[1, 2, 3, 4, 5, 6]``. + .. warning:: Strings that can be coerced to integers will be **summed**, not @@ -1868,7 +1886,7 @@ representation of a ``datetime`` value. E.g.: If value evaluates to ``False``, uses the given default. Otherwise, uses the value. -For example: +For example in a template: .. code-block:: html+django @@ -1876,6 +1894,15 @@ For example: If ``value`` is ``""`` (the empty string), the output will be ``nothing``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import default + sometext = default("", "nothing") + +The output of ``sometext`` will be ``nothing``. + .. templatefilter:: default_if_none ``default_if_none`` @@ -1887,7 +1914,7 @@ value. Note that if an empty string is given, the default value will *not* be used. Use the :tfilter:`default` filter if you want to fallback for empty strings. -For example: +For example in a template: .. code-block:: html+django @@ -1895,6 +1922,15 @@ For example: If ``value`` is ``None``, the output will be ``nothing``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import default_if_none + sometext = default_if_none(None, "nothing") + +The output of ``sometext`` will be ``nothing``. + .. templatefilter:: dictsort ``dictsort`` @@ -1903,6 +1939,9 @@ If ``value`` is ``None``, the output will be ``nothing``. Takes a list of dictionaries and returns that list sorted by the key given in the argument. +Template Examples +================= + For example: .. code-block:: html+django @@ -1989,6 +2028,78 @@ produce empty output: {{ values|dictsort:"0" }} +Python Examples +=============== + +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import dictsort + sorted_list = dictsort([ + {"name": "zed", "age": 19}, + {"name": "amy", "age": 22}, + {"name": "joe", "age": 31}, + ], "name") + +The value of ``sorted_list`` will be: + +.. code-block:: python + + [ + {"name": "amy", "age": 22}, + {"name": "joe", "age": 31}, + {"name": "zed", "age": 19}, + ] + +You can also do more complicated things like: + +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import dictsort + sorted_list = dictsort([ + {"title": "1984", "author": {"name": "George", "age": 45}}, + {"title": "Timequake", "author": {"name": "Kurt", "age": 75}}, + {"title": "Alice", "author": {"name": "Lewis", "age": 33}}, + ], "author.age") + +The value of ``sorted_list`` will be: + +.. code-block:: python + + [ + {"title": "Alice", "author": {"name": "Lewis", "age": 33}}, + {"title": "1984", "author": {"name": "George", "age": 45}}, + {"title": "Timequake", "author": {"name": "Kurt", "age": 75}}, + ] + +``dictsort`` can also order a list of lists (or any other object implementing +``__getitem__()``) by elements at specified index. For example: + + +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import dictsort + sorted_list = dictsort([ + ("a", "42"), + ("c", "string"), + ("b", "foo"), + ], 0) + +The value of ``sorted_list`` will be: + +.. code-block:: python + + [ + ("a", "42"), + ("b", "foo"), + ("c", "string"), + ] + Ordering by elements at specified index is not supported on dictionaries. .. templatefilter:: dictsortreversed @@ -2007,7 +2118,7 @@ but the returned value will be in reverse order. Returns ``True`` if the value is divisible by the argument. -For example: +For example in a template: .. code-block:: html+django @@ -2015,6 +2126,15 @@ For example: If ``value`` is ``21``, the output would be ``True``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import divisibleby + is_divisible = divisibleby(21, 3) + +The value of ``is_divisible`` will be ``True``. + .. templatefilter:: escape ``escape`` @@ -2144,7 +2264,7 @@ The value of ``formatted_size`` will be ``'117.7\xa0MB'``. Returns the first item in a list. -For example: +For example in a template: .. code-block:: html+django @@ -2152,6 +2272,15 @@ For example: If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import first + first_item = first(['a', 'b', 'c']) + +The value of ``first_item`` will be ``'a'``. + .. templatefilter:: floatformat ``floatformat`` @@ -2268,7 +2397,7 @@ digit, 2 is the second-right-most digit, etc. Returns the original value for invalid input (if input or argument is not an integer, or if argument is less than 1). Otherwise, output is always an integer. -For example: +For example in a template: .. code-block:: html+django @@ -2276,6 +2405,15 @@ For example: If ``value`` is ``123456789``, the output will be ``8``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import get_digit + digit = get_digit(123456789, 2) + +The output of ``digit`` will be ``8``. + .. templatefilter:: iriencode ``iriencode`` @@ -2394,7 +2532,7 @@ The value of ``last_item`` will be ``"d"``. Returns the length of the value. This works for both strings and lists. -For example: +For example in a template: .. code-block:: html+django @@ -2403,6 +2541,15 @@ For example: If ``value`` is ``['a', 'b', 'c', 'd']`` or ``"abcd"``, the output will be ``4``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import length + length_of_value = length(['a', 'b', 'c', 'd']) + +The value of ``length_of_value`` will be ``4``. + The filter returns ``0`` for an undefined variable. .. templatefilter:: linebreaks @@ -2541,7 +2688,7 @@ The output will be ``"totally loving this album!"``. Returns the value turned into a list. For a string, it's a list of characters. For an integer, the argument is cast to a string before creating a list. -For example: +For example in a template: .. code-block:: html+django @@ -2551,6 +2698,15 @@ If ``value`` is the string ``"Joel"``, the output would be the list ``['J', 'o', 'e', 'l']``. If ``value`` is ``123``, the output will be the list ``['1', '2', '3']``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import make_list + list_of_chars = make_list("Joel") + +The output will be the list ``['J', 'o', 'e', 'l']``. + .. templatefilter:: phone2numeric ``phone2numeric`` @@ -2578,6 +2734,9 @@ If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``. Returns a plural suffix if the value is not ``1``, ``'1'``, or an object of length 1. By default, this suffix is ``'s'``. +Template Examples +================= + Example: .. code-block:: html+django @@ -2605,6 +2764,42 @@ Example: You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}. +Python Examples +=============== + +.. code-block:: python + + from django.template.defaultfilters import pluralize + single_message = f"You have 1 message{{pluralize(1)}}" + multiple_messages = f"You have 2 messages{{pluralize(2)}}" + +The output of ``single_message`` will be ``You have 1 message``. The output of +``multiple_messages`` will be ``'You have 2 messages'``. + +For words that require a suffix other than ``'s'``, you can provide an alternate +suffix as a parameter to the filter. + +.. code-block:: python + + from django.template.defaultfilters import pluralize + single_walrus = f"You have 1 walrus{pluralize(1, "es")}" + multiple_walrus = f"You have 1 walrus{pluralize(2, "es")}" + +The output of ``single_walrus`` will be ``'You have 1 walrus'``. The output of +``multiple_walrus`` will be ``'You have 2 walruses'``. + +For words that don't pluralize by simple suffix, you can specify +both a singular and plural suffix, separated by a comma. + +.. code-block:: python + + from django.template.defaultfilters import pluralize + cherry_singular = f"You have 1 cherr{pluralize(1, "y,ies")}" + cherry_pluralized = f"You have 1 cherr{pluralize(2, "y,ies")}" + +The output of ``cherry_singular`` will be ``'You have 1 cherry'``. The output of +``cherry_pluralized`` will be ``'You have 2 cherries'``. + .. note:: Use :ttag:`blocktranslate` to pluralize translated strings. .. templatefilter:: pprint @@ -3155,7 +3350,7 @@ contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then Converts a string into all uppercase. -For example: +For example in a template: .. code-block:: html+django @@ -3163,6 +3358,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 upper + uppercased = upper("Joel is a slug") + +The output of ``uppercased`` will be ``"JOEL IS A SLUG"``. + .. templatefilter:: urlencode ``urlencode`` @@ -3170,7 +3374,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``. Escapes a value for use in a URL. -For example: +For example in a template: .. code-block:: html+django @@ -3179,11 +3383,23 @@ For example: If ``value`` is ``"https://www.example.org/foo?a=b&c=d"``, the output will be ``"https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import urlencode + + escaped = urlencode("https://www.example.org/foo?a=b&c=d") + +The output of ``escaped`` will be ``"https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``. + An optional argument containing the characters which should not be escaped can be provided. If not provided, the '/' character is assumed safe. An empty string can be -provided when *all* characters should be escaped. For example: +provided when *all* characters should be escaped. + +For example in a template: .. code-block:: html+django @@ -3192,6 +3408,16 @@ provided when *all* characters should be escaped. For example: If ``value`` is ``"https://www.example.org/"``, the output will be ``"https%3A%2F%2Fwww.example.org%2F"``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import urlencode + + escaped = urlencode("https://www.example.org/", "") + +The output of ``escaped`` will be ``"https%3A%2F%2Fwww.example.org%2F"``. + .. templatefilter:: urlize ``urlize`` @@ -3280,7 +3506,7 @@ As with urlize_, this filter should only be applied to plain text. Returns the number of words. -For example: +For example in a template: .. code-block:: html+django @@ -3288,6 +3514,16 @@ For example: If ``value`` is ``"Joel is a slug"``, the output will be ``4``. +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import wordcount + + count = wordcount("Joel is a slug") + +The output of ``count`` will be ``4``. + .. templatefilter:: wordwrap ``wordwrap`` @@ -3330,12 +3566,23 @@ Maps values for ``True``, ``False``, and (optionally) ``None``, to the strings "yes", "no", "maybe", or a custom mapping passed as a comma-separated list, and returns one of those strings according to the value: -For example: +For example in a template: .. code-block:: html+django {{ value|yesno:"yeah,no,maybe" }} +For example in Python: + +.. code-block:: python + + from django.template.defaultfilters import yesno + + result = yesno(True, "yeah,no,maybe") + +The table below shows the possible inputs and outputs for both template usage +and Python usage: + ========== ====================== =========================================== Value Argument Outputs ========== ====================== ===========================================