Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Built-in template tests used with the ``is`` operator."""
3import operator
4import typing as t
5from collections import abc
6from numbers import Number
8from .runtime import Undefined
9from .utils import pass_environment
11if t.TYPE_CHECKING:
12 from .environment import Environment
15def test_odd(value: int) -> bool:
16 """Return true if the variable is odd."""
17 return value % 2 == 1
20def test_even(value: int) -> bool:
21 """Return true if the variable is even."""
22 return value % 2 == 0
25def test_divisibleby(value: int, num: int) -> bool:
26 """Check if a variable is divisible by a number."""
27 return value % num == 0
30def test_defined(value: t.Any) -> bool:
31 """Return true if the variable is defined:
33 .. sourcecode:: jinja
35 {% if variable is defined %}
36 value of variable: {{ variable }}
37 {% else %}
38 variable is not defined
39 {% endif %}
41 See the :func:`default` filter for a simple way to set undefined
42 variables.
43 """
44 return not isinstance(value, Undefined)
47def test_undefined(value: t.Any) -> bool:
48 """Like :func:`defined` but the other way round."""
49 return isinstance(value, Undefined)
52@pass_environment
53def test_filter(env: "Environment", value: str) -> bool:
54 """Check if a filter exists by name. Useful if a filter may be
55 optionally available.
57 .. code-block:: jinja
59 {% if 'markdown' is filter %}
60 {{ value | markdown }}
61 {% else %}
62 {{ value }}
63 {% endif %}
65 .. versionadded:: 3.0
66 """
67 return value in env.filters
70@pass_environment
71def test_test(env: "Environment", value: str) -> bool:
72 """Check if a test exists by name. Useful if a test may be
73 optionally available.
75 .. code-block:: jinja
77 {% if 'loud' is test %}
78 {% if value is loud %}
79 {{ value|upper }}
80 {% else %}
81 {{ value|lower }}
82 {% endif %}
83 {% else %}
84 {{ value }}
85 {% endif %}
87 .. versionadded:: 3.0
88 """
89 return value in env.tests
92def test_none(value: t.Any) -> bool:
93 """Return true if the variable is none."""
94 return value is None
97def test_boolean(value: t.Any) -> bool:
98 """Return true if the object is a boolean value.
100 .. versionadded:: 2.11
101 """
102 return value is True or value is False
105def test_false(value: t.Any) -> bool:
106 """Return true if the object is False.
108 .. versionadded:: 2.11
109 """
110 return value is False
113def test_true(value: t.Any) -> bool:
114 """Return true if the object is True.
116 .. versionadded:: 2.11
117 """
118 return value is True
121# NOTE: The existing 'number' test matches booleans and floats
122def test_integer(value: t.Any) -> bool:
123 """Return true if the object is an integer.
125 .. versionadded:: 2.11
126 """
127 return isinstance(value, int) and value is not True and value is not False
130# NOTE: The existing 'number' test matches booleans and integers
131def test_float(value: t.Any) -> bool:
132 """Return true if the object is a float.
134 .. versionadded:: 2.11
135 """
136 return isinstance(value, float)
139def test_lower(value: str) -> bool:
140 """Return true if the variable is lowercased."""
141 return str(value).islower()
144def test_upper(value: str) -> bool:
145 """Return true if the variable is uppercased."""
146 return str(value).isupper()
149def test_string(value: t.Any) -> bool:
150 """Return true if the object is a string."""
151 return isinstance(value, str)
154def test_mapping(value: t.Any) -> bool:
155 """Return true if the object is a mapping (dict etc.).
157 .. versionadded:: 2.6
158 """
159 return isinstance(value, abc.Mapping)
162def test_number(value: t.Any) -> bool:
163 """Return true if the variable is a number."""
164 return isinstance(value, Number)
167def test_sequence(value: t.Any) -> bool:
168 """Return true if the variable is a sequence. Sequences are variables
169 that are iterable.
170 """
171 try:
172 len(value)
173 value.__getitem__ # noqa B018
174 except Exception:
175 return False
177 return True
180def test_sameas(value: t.Any, other: t.Any) -> bool:
181 """Check if an object points to the same memory address than another
182 object:
184 .. sourcecode:: jinja
186 {% if foo.attribute is sameas false %}
187 the foo attribute really is the `False` singleton
188 {% endif %}
189 """
190 return value is other
193def test_iterable(value: t.Any) -> bool:
194 """Check if it's possible to iterate over an object."""
195 try:
196 iter(value)
197 except TypeError:
198 return False
200 return True
203def test_escaped(value: t.Any) -> bool:
204 """Check if the value is escaped."""
205 return hasattr(value, "__html__")
208def test_in(value: t.Any, seq: t.Container[t.Any]) -> bool:
209 """Check if value is in seq.
211 .. versionadded:: 2.10
212 """
213 return value in seq
216TESTS = {
217 "odd": test_odd,
218 "even": test_even,
219 "divisibleby": test_divisibleby,
220 "defined": test_defined,
221 "undefined": test_undefined,
222 "filter": test_filter,
223 "test": test_test,
224 "none": test_none,
225 "boolean": test_boolean,
226 "false": test_false,
227 "true": test_true,
228 "integer": test_integer,
229 "float": test_float,
230 "lower": test_lower,
231 "upper": test_upper,
232 "string": test_string,
233 "mapping": test_mapping,
234 "number": test_number,
235 "sequence": test_sequence,
236 "iterable": test_iterable,
237 "callable": callable,
238 "sameas": test_sameas,
239 "escaped": test_escaped,
240 "in": test_in,
241 "==": operator.eq,
242 "eq": operator.eq,
243 "equalto": operator.eq,
244 "!=": operator.ne,
245 "ne": operator.ne,
246 ">": operator.gt,
247 "gt": operator.gt,
248 "greaterthan": operator.gt,
249 "ge": operator.ge,
250 ">=": operator.ge,
251 "<": operator.lt,
252 "lt": operator.lt,
253 "lessthan": operator.lt,
254 "<=": operator.le,
255 "le": operator.le,
256}