filters.py 40 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382
  1. # -*- coding: utf-8 -*-
  2. """Built-in template filters used with the ``|`` operator."""
  3. import math
  4. import random
  5. import re
  6. import warnings
  7. from collections import namedtuple
  8. from itertools import chain
  9. from itertools import groupby
  10. from markupsafe import escape
  11. from markupsafe import Markup
  12. from markupsafe import soft_unicode
  13. from ._compat import abc
  14. from ._compat import imap
  15. from ._compat import iteritems
  16. from ._compat import string_types
  17. from ._compat import text_type
  18. from .exceptions import FilterArgumentError
  19. from .runtime import Undefined
  20. from .utils import htmlsafe_json_dumps
  21. from .utils import pformat
  22. from .utils import unicode_urlencode
  23. from .utils import urlize
  24. _word_re = re.compile(r"\w+", re.UNICODE)
  25. _word_beginning_split_re = re.compile(r"([-\s\(\{\[\<]+)", re.UNICODE)
  26. def contextfilter(f):
  27. """Decorator for marking context dependent filters. The current
  28. :class:`Context` will be passed as first argument.
  29. """
  30. f.contextfilter = True
  31. return f
  32. def evalcontextfilter(f):
  33. """Decorator for marking eval-context dependent filters. An eval
  34. context object is passed as first argument. For more information
  35. about the eval context, see :ref:`eval-context`.
  36. .. versionadded:: 2.4
  37. """
  38. f.evalcontextfilter = True
  39. return f
  40. def environmentfilter(f):
  41. """Decorator for marking environment dependent filters. The current
  42. :class:`Environment` is passed to the filter as first argument.
  43. """
  44. f.environmentfilter = True
  45. return f
  46. def ignore_case(value):
  47. """For use as a postprocessor for :func:`make_attrgetter`. Converts strings
  48. to lowercase and returns other types as-is."""
  49. return value.lower() if isinstance(value, string_types) else value
  50. def make_attrgetter(environment, attribute, postprocess=None, default=None):
  51. """Returns a callable that looks up the given attribute from a
  52. passed object with the rules of the environment. Dots are allowed
  53. to access attributes of attributes. Integer parts in paths are
  54. looked up as integers.
  55. """
  56. attribute = _prepare_attribute_parts(attribute)
  57. def attrgetter(item):
  58. for part in attribute:
  59. item = environment.getitem(item, part)
  60. if default and isinstance(item, Undefined):
  61. item = default
  62. if postprocess is not None:
  63. item = postprocess(item)
  64. return item
  65. return attrgetter
  66. def make_multi_attrgetter(environment, attribute, postprocess=None):
  67. """Returns a callable that looks up the given comma separated
  68. attributes from a passed object with the rules of the environment.
  69. Dots are allowed to access attributes of each attribute. Integer
  70. parts in paths are looked up as integers.
  71. The value returned by the returned callable is a list of extracted
  72. attribute values.
  73. Examples of attribute: "attr1,attr2", "attr1.inner1.0,attr2.inner2.0", etc.
  74. """
  75. attribute_parts = (
  76. attribute.split(",") if isinstance(attribute, string_types) else [attribute]
  77. )
  78. attribute = [
  79. _prepare_attribute_parts(attribute_part) for attribute_part in attribute_parts
  80. ]
  81. def attrgetter(item):
  82. items = [None] * len(attribute)
  83. for i, attribute_part in enumerate(attribute):
  84. item_i = item
  85. for part in attribute_part:
  86. item_i = environment.getitem(item_i, part)
  87. if postprocess is not None:
  88. item_i = postprocess(item_i)
  89. items[i] = item_i
  90. return items
  91. return attrgetter
  92. def _prepare_attribute_parts(attr):
  93. if attr is None:
  94. return []
  95. elif isinstance(attr, string_types):
  96. return [int(x) if x.isdigit() else x for x in attr.split(".")]
  97. else:
  98. return [attr]
  99. def do_forceescape(value):
  100. """Enforce HTML escaping. This will probably double escape variables."""
  101. if hasattr(value, "__html__"):
  102. value = value.__html__()
  103. return escape(text_type(value))
  104. def do_urlencode(value):
  105. """Quote data for use in a URL path or query using UTF-8.
  106. Basic wrapper around :func:`urllib.parse.quote` when given a
  107. string, or :func:`urllib.parse.urlencode` for a dict or iterable.
  108. :param value: Data to quote. A string will be quoted directly. A
  109. dict or iterable of ``(key, value)`` pairs will be joined as a
  110. query string.
  111. When given a string, "/" is not quoted. HTTP servers treat "/" and
  112. "%2F" equivalently in paths. If you need quoted slashes, use the
  113. ``|replace("/", "%2F")`` filter.
  114. .. versionadded:: 2.7
  115. """
  116. if isinstance(value, string_types) or not isinstance(value, abc.Iterable):
  117. return unicode_urlencode(value)
  118. if isinstance(value, dict):
  119. items = iteritems(value)
  120. else:
  121. items = iter(value)
  122. return u"&".join(
  123. "%s=%s" % (unicode_urlencode(k, for_qs=True), unicode_urlencode(v, for_qs=True))
  124. for k, v in items
  125. )
  126. @evalcontextfilter
  127. def do_replace(eval_ctx, s, old, new, count=None):
  128. """Return a copy of the value with all occurrences of a substring
  129. replaced with a new one. The first argument is the substring
  130. that should be replaced, the second is the replacement string.
  131. If the optional third argument ``count`` is given, only the first
  132. ``count`` occurrences are replaced:
  133. .. sourcecode:: jinja
  134. {{ "Hello World"|replace("Hello", "Goodbye") }}
  135. -> Goodbye World
  136. {{ "aaaaargh"|replace("a", "d'oh, ", 2) }}
  137. -> d'oh, d'oh, aaargh
  138. """
  139. if count is None:
  140. count = -1
  141. if not eval_ctx.autoescape:
  142. return text_type(s).replace(text_type(old), text_type(new), count)
  143. if (
  144. hasattr(old, "__html__")
  145. or hasattr(new, "__html__")
  146. and not hasattr(s, "__html__")
  147. ):
  148. s = escape(s)
  149. else:
  150. s = soft_unicode(s)
  151. return s.replace(soft_unicode(old), soft_unicode(new), count)
  152. def do_upper(s):
  153. """Convert a value to uppercase."""
  154. return soft_unicode(s).upper()
  155. def do_lower(s):
  156. """Convert a value to lowercase."""
  157. return soft_unicode(s).lower()
  158. @evalcontextfilter
  159. def do_xmlattr(_eval_ctx, d, autospace=True):
  160. """Create an SGML/XML attribute string based on the items in a dict.
  161. All values that are neither `none` nor `undefined` are automatically
  162. escaped:
  163. .. sourcecode:: html+jinja
  164. <ul{{ {'class': 'my_list', 'missing': none,
  165. 'id': 'list-%d'|format(variable)}|xmlattr }}>
  166. ...
  167. </ul>
  168. Results in something like this:
  169. .. sourcecode:: html
  170. <ul class="my_list" id="list-42">
  171. ...
  172. </ul>
  173. As you can see it automatically prepends a space in front of the item
  174. if the filter returned something unless the second parameter is false.
  175. """
  176. rv = u" ".join(
  177. u'%s="%s"' % (escape(key), escape(value))
  178. for key, value in iteritems(d)
  179. if value is not None and not isinstance(value, Undefined)
  180. )
  181. if autospace and rv:
  182. rv = u" " + rv
  183. if _eval_ctx.autoescape:
  184. rv = Markup(rv)
  185. return rv
  186. def do_capitalize(s):
  187. """Capitalize a value. The first character will be uppercase, all others
  188. lowercase.
  189. """
  190. return soft_unicode(s).capitalize()
  191. def do_title(s):
  192. """Return a titlecased version of the value. I.e. words will start with
  193. uppercase letters, all remaining characters are lowercase.
  194. """
  195. return "".join(
  196. [
  197. item[0].upper() + item[1:].lower()
  198. for item in _word_beginning_split_re.split(soft_unicode(s))
  199. if item
  200. ]
  201. )
  202. def do_dictsort(value, case_sensitive=False, by="key", reverse=False):
  203. """Sort a dict and yield (key, value) pairs. Because python dicts are
  204. unsorted you may want to use this function to order them by either
  205. key or value:
  206. .. sourcecode:: jinja
  207. {% for key, value in mydict|dictsort %}
  208. sort the dict by key, case insensitive
  209. {% for key, value in mydict|dictsort(reverse=true) %}
  210. sort the dict by key, case insensitive, reverse order
  211. {% for key, value in mydict|dictsort(true) %}
  212. sort the dict by key, case sensitive
  213. {% for key, value in mydict|dictsort(false, 'value') %}
  214. sort the dict by value, case insensitive
  215. """
  216. if by == "key":
  217. pos = 0
  218. elif by == "value":
  219. pos = 1
  220. else:
  221. raise FilterArgumentError('You can only sort by either "key" or "value"')
  222. def sort_func(item):
  223. value = item[pos]
  224. if not case_sensitive:
  225. value = ignore_case(value)
  226. return value
  227. return sorted(value.items(), key=sort_func, reverse=reverse)
  228. @environmentfilter
  229. def do_sort(environment, value, reverse=False, case_sensitive=False, attribute=None):
  230. """Sort an iterable using Python's :func:`sorted`.
  231. .. sourcecode:: jinja
  232. {% for city in cities|sort %}
  233. ...
  234. {% endfor %}
  235. :param reverse: Sort descending instead of ascending.
  236. :param case_sensitive: When sorting strings, sort upper and lower
  237. case separately.
  238. :param attribute: When sorting objects or dicts, an attribute or
  239. key to sort by. Can use dot notation like ``"address.city"``.
  240. Can be a list of attributes like ``"age,name"``.
  241. The sort is stable, it does not change the relative order of
  242. elements that compare equal. This makes it is possible to chain
  243. sorts on different attributes and ordering.
  244. .. sourcecode:: jinja
  245. {% for user in users|sort(attribute="name")
  246. |sort(reverse=true, attribute="age") %}
  247. ...
  248. {% endfor %}
  249. As a shortcut to chaining when the direction is the same for all
  250. attributes, pass a comma separate list of attributes.
  251. .. sourcecode:: jinja
  252. {% for user users|sort(attribute="age,name") %}
  253. ...
  254. {% endfor %}
  255. .. versionchanged:: 2.11.0
  256. The ``attribute`` parameter can be a comma separated list of
  257. attributes, e.g. ``"age,name"``.
  258. .. versionchanged:: 2.6
  259. The ``attribute`` parameter was added.
  260. """
  261. key_func = make_multi_attrgetter(
  262. environment, attribute, postprocess=ignore_case if not case_sensitive else None
  263. )
  264. return sorted(value, key=key_func, reverse=reverse)
  265. @environmentfilter
  266. def do_unique(environment, value, case_sensitive=False, attribute=None):
  267. """Returns a list of unique items from the given iterable.
  268. .. sourcecode:: jinja
  269. {{ ['foo', 'bar', 'foobar', 'FooBar']|unique|list }}
  270. -> ['foo', 'bar', 'foobar']
  271. The unique items are yielded in the same order as their first occurrence in
  272. the iterable passed to the filter.
  273. :param case_sensitive: Treat upper and lower case strings as distinct.
  274. :param attribute: Filter objects with unique values for this attribute.
  275. """
  276. getter = make_attrgetter(
  277. environment, attribute, postprocess=ignore_case if not case_sensitive else None
  278. )
  279. seen = set()
  280. for item in value:
  281. key = getter(item)
  282. if key not in seen:
  283. seen.add(key)
  284. yield item
  285. def _min_or_max(environment, value, func, case_sensitive, attribute):
  286. it = iter(value)
  287. try:
  288. first = next(it)
  289. except StopIteration:
  290. return environment.undefined("No aggregated item, sequence was empty.")
  291. key_func = make_attrgetter(
  292. environment, attribute, postprocess=ignore_case if not case_sensitive else None
  293. )
  294. return func(chain([first], it), key=key_func)
  295. @environmentfilter
  296. def do_min(environment, value, case_sensitive=False, attribute=None):
  297. """Return the smallest item from the sequence.
  298. .. sourcecode:: jinja
  299. {{ [1, 2, 3]|min }}
  300. -> 1
  301. :param case_sensitive: Treat upper and lower case strings as distinct.
  302. :param attribute: Get the object with the min value of this attribute.
  303. """
  304. return _min_or_max(environment, value, min, case_sensitive, attribute)
  305. @environmentfilter
  306. def do_max(environment, value, case_sensitive=False, attribute=None):
  307. """Return the largest item from the sequence.
  308. .. sourcecode:: jinja
  309. {{ [1, 2, 3]|max }}
  310. -> 3
  311. :param case_sensitive: Treat upper and lower case strings as distinct.
  312. :param attribute: Get the object with the max value of this attribute.
  313. """
  314. return _min_or_max(environment, value, max, case_sensitive, attribute)
  315. def do_default(value, default_value=u"", boolean=False):
  316. """If the value is undefined it will return the passed default value,
  317. otherwise the value of the variable:
  318. .. sourcecode:: jinja
  319. {{ my_variable|default('my_variable is not defined') }}
  320. This will output the value of ``my_variable`` if the variable was
  321. defined, otherwise ``'my_variable is not defined'``. If you want
  322. to use default with variables that evaluate to false you have to
  323. set the second parameter to `true`:
  324. .. sourcecode:: jinja
  325. {{ ''|default('the string was empty', true) }}
  326. .. versionchanged:: 2.11
  327. It's now possible to configure the :class:`~jinja2.Environment` with
  328. :class:`~jinja2.ChainableUndefined` to make the `default` filter work
  329. on nested elements and attributes that may contain undefined values
  330. in the chain without getting an :exc:`~jinja2.UndefinedError`.
  331. """
  332. if isinstance(value, Undefined) or (boolean and not value):
  333. return default_value
  334. return value
  335. @evalcontextfilter
  336. def do_join(eval_ctx, value, d=u"", attribute=None):
  337. """Return a string which is the concatenation of the strings in the
  338. sequence. The separator between elements is an empty string per
  339. default, you can define it with the optional parameter:
  340. .. sourcecode:: jinja
  341. {{ [1, 2, 3]|join('|') }}
  342. -> 1|2|3
  343. {{ [1, 2, 3]|join }}
  344. -> 123
  345. It is also possible to join certain attributes of an object:
  346. .. sourcecode:: jinja
  347. {{ users|join(', ', attribute='username') }}
  348. .. versionadded:: 2.6
  349. The `attribute` parameter was added.
  350. """
  351. if attribute is not None:
  352. value = imap(make_attrgetter(eval_ctx.environment, attribute), value)
  353. # no automatic escaping? joining is a lot easier then
  354. if not eval_ctx.autoescape:
  355. return text_type(d).join(imap(text_type, value))
  356. # if the delimiter doesn't have an html representation we check
  357. # if any of the items has. If yes we do a coercion to Markup
  358. if not hasattr(d, "__html__"):
  359. value = list(value)
  360. do_escape = False
  361. for idx, item in enumerate(value):
  362. if hasattr(item, "__html__"):
  363. do_escape = True
  364. else:
  365. value[idx] = text_type(item)
  366. if do_escape:
  367. d = escape(d)
  368. else:
  369. d = text_type(d)
  370. return d.join(value)
  371. # no html involved, to normal joining
  372. return soft_unicode(d).join(imap(soft_unicode, value))
  373. def do_center(value, width=80):
  374. """Centers the value in a field of a given width."""
  375. return text_type(value).center(width)
  376. @environmentfilter
  377. def do_first(environment, seq):
  378. """Return the first item of a sequence."""
  379. try:
  380. return next(iter(seq))
  381. except StopIteration:
  382. return environment.undefined("No first item, sequence was empty.")
  383. @environmentfilter
  384. def do_last(environment, seq):
  385. """
  386. Return the last item of a sequence.
  387. Note: Does not work with generators. You may want to explicitly
  388. convert it to a list:
  389. .. sourcecode:: jinja
  390. {{ data | selectattr('name', '==', 'Jinja') | list | last }}
  391. """
  392. try:
  393. return next(iter(reversed(seq)))
  394. except StopIteration:
  395. return environment.undefined("No last item, sequence was empty.")
  396. @contextfilter
  397. def do_random(context, seq):
  398. """Return a random item from the sequence."""
  399. try:
  400. return random.choice(seq)
  401. except IndexError:
  402. return context.environment.undefined("No random item, sequence was empty.")
  403. def do_filesizeformat(value, binary=False):
  404. """Format the value like a 'human-readable' file size (i.e. 13 kB,
  405. 4.1 MB, 102 Bytes, etc). Per default decimal prefixes are used (Mega,
  406. Giga, etc.), if the second parameter is set to `True` the binary
  407. prefixes are used (Mebi, Gibi).
  408. """
  409. bytes = float(value)
  410. base = binary and 1024 or 1000
  411. prefixes = [
  412. (binary and "KiB" or "kB"),
  413. (binary and "MiB" or "MB"),
  414. (binary and "GiB" or "GB"),
  415. (binary and "TiB" or "TB"),
  416. (binary and "PiB" or "PB"),
  417. (binary and "EiB" or "EB"),
  418. (binary and "ZiB" or "ZB"),
  419. (binary and "YiB" or "YB"),
  420. ]
  421. if bytes == 1:
  422. return "1 Byte"
  423. elif bytes < base:
  424. return "%d Bytes" % bytes
  425. else:
  426. for i, prefix in enumerate(prefixes):
  427. unit = base ** (i + 2)
  428. if bytes < unit:
  429. return "%.1f %s" % ((base * bytes / unit), prefix)
  430. return "%.1f %s" % ((base * bytes / unit), prefix)
  431. def do_pprint(value, verbose=False):
  432. """Pretty print a variable. Useful for debugging.
  433. With Jinja 1.2 onwards you can pass it a parameter. If this parameter
  434. is truthy the output will be more verbose (this requires `pretty`)
  435. """
  436. return pformat(value, verbose=verbose)
  437. @evalcontextfilter
  438. def do_urlize(
  439. eval_ctx, value, trim_url_limit=None, nofollow=False, target=None, rel=None
  440. ):
  441. """Converts URLs in plain text into clickable links.
  442. If you pass the filter an additional integer it will shorten the urls
  443. to that number. Also a third argument exists that makes the urls
  444. "nofollow":
  445. .. sourcecode:: jinja
  446. {{ mytext|urlize(40, true) }}
  447. links are shortened to 40 chars and defined with rel="nofollow"
  448. If *target* is specified, the ``target`` attribute will be added to the
  449. ``<a>`` tag:
  450. .. sourcecode:: jinja
  451. {{ mytext|urlize(40, target='_blank') }}
  452. .. versionchanged:: 2.8+
  453. The *target* parameter was added.
  454. """
  455. policies = eval_ctx.environment.policies
  456. rel = set((rel or "").split() or [])
  457. if nofollow:
  458. rel.add("nofollow")
  459. rel.update((policies["urlize.rel"] or "").split())
  460. if target is None:
  461. target = policies["urlize.target"]
  462. rel = " ".join(sorted(rel)) or None
  463. rv = urlize(value, trim_url_limit, rel=rel, target=target)
  464. if eval_ctx.autoescape:
  465. rv = Markup(rv)
  466. return rv
  467. def do_indent(s, width=4, first=False, blank=False, indentfirst=None):
  468. """Return a copy of the string with each line indented by 4 spaces. The
  469. first line and blank lines are not indented by default.
  470. :param width: Number of spaces to indent by.
  471. :param first: Don't skip indenting the first line.
  472. :param blank: Don't skip indenting empty lines.
  473. .. versionchanged:: 2.10
  474. Blank lines are not indented by default.
  475. Rename the ``indentfirst`` argument to ``first``.
  476. """
  477. if indentfirst is not None:
  478. warnings.warn(
  479. "The 'indentfirst' argument is renamed to 'first' and will"
  480. " be removed in version 3.0.",
  481. DeprecationWarning,
  482. stacklevel=2,
  483. )
  484. first = indentfirst
  485. indention = u" " * width
  486. newline = u"\n"
  487. if isinstance(s, Markup):
  488. indention = Markup(indention)
  489. newline = Markup(newline)
  490. s += newline # this quirk is necessary for splitlines method
  491. if blank:
  492. rv = (newline + indention).join(s.splitlines())
  493. else:
  494. lines = s.splitlines()
  495. rv = lines.pop(0)
  496. if lines:
  497. rv += newline + newline.join(
  498. indention + line if line else line for line in lines
  499. )
  500. if first:
  501. rv = indention + rv
  502. return rv
  503. @environmentfilter
  504. def do_truncate(env, s, length=255, killwords=False, end="...", leeway=None):
  505. """Return a truncated copy of the string. The length is specified
  506. with the first parameter which defaults to ``255``. If the second
  507. parameter is ``true`` the filter will cut the text at length. Otherwise
  508. it will discard the last word. If the text was in fact
  509. truncated it will append an ellipsis sign (``"..."``). If you want a
  510. different ellipsis sign than ``"..."`` you can specify it using the
  511. third parameter. Strings that only exceed the length by the tolerance
  512. margin given in the fourth parameter will not be truncated.
  513. .. sourcecode:: jinja
  514. {{ "foo bar baz qux"|truncate(9) }}
  515. -> "foo..."
  516. {{ "foo bar baz qux"|truncate(9, True) }}
  517. -> "foo ba..."
  518. {{ "foo bar baz qux"|truncate(11) }}
  519. -> "foo bar baz qux"
  520. {{ "foo bar baz qux"|truncate(11, False, '...', 0) }}
  521. -> "foo bar..."
  522. The default leeway on newer Jinja versions is 5 and was 0 before but
  523. can be reconfigured globally.
  524. """
  525. if leeway is None:
  526. leeway = env.policies["truncate.leeway"]
  527. assert length >= len(end), "expected length >= %s, got %s" % (len(end), length)
  528. assert leeway >= 0, "expected leeway >= 0, got %s" % leeway
  529. if len(s) <= length + leeway:
  530. return s
  531. if killwords:
  532. return s[: length - len(end)] + end
  533. result = s[: length - len(end)].rsplit(" ", 1)[0]
  534. return result + end
  535. @environmentfilter
  536. def do_wordwrap(
  537. environment,
  538. s,
  539. width=79,
  540. break_long_words=True,
  541. wrapstring=None,
  542. break_on_hyphens=True,
  543. ):
  544. """Wrap a string to the given width. Existing newlines are treated
  545. as paragraphs to be wrapped separately.
  546. :param s: Original text to wrap.
  547. :param width: Maximum length of wrapped lines.
  548. :param break_long_words: If a word is longer than ``width``, break
  549. it across lines.
  550. :param break_on_hyphens: If a word contains hyphens, it may be split
  551. across lines.
  552. :param wrapstring: String to join each wrapped line. Defaults to
  553. :attr:`Environment.newline_sequence`.
  554. .. versionchanged:: 2.11
  555. Existing newlines are treated as paragraphs wrapped separately.
  556. .. versionchanged:: 2.11
  557. Added the ``break_on_hyphens`` parameter.
  558. .. versionchanged:: 2.7
  559. Added the ``wrapstring`` parameter.
  560. """
  561. import textwrap
  562. if not wrapstring:
  563. wrapstring = environment.newline_sequence
  564. # textwrap.wrap doesn't consider existing newlines when wrapping.
  565. # If the string has a newline before width, wrap will still insert
  566. # a newline at width, resulting in a short line. Instead, split and
  567. # wrap each paragraph individually.
  568. return wrapstring.join(
  569. [
  570. wrapstring.join(
  571. textwrap.wrap(
  572. line,
  573. width=width,
  574. expand_tabs=False,
  575. replace_whitespace=False,
  576. break_long_words=break_long_words,
  577. break_on_hyphens=break_on_hyphens,
  578. )
  579. )
  580. for line in s.splitlines()
  581. ]
  582. )
  583. def do_wordcount(s):
  584. """Count the words in that string."""
  585. return len(_word_re.findall(soft_unicode(s)))
  586. def do_int(value, default=0, base=10):
  587. """Convert the value into an integer. If the
  588. conversion doesn't work it will return ``0``. You can
  589. override this default using the first parameter. You
  590. can also override the default base (10) in the second
  591. parameter, which handles input with prefixes such as
  592. 0b, 0o and 0x for bases 2, 8 and 16 respectively.
  593. The base is ignored for decimal numbers and non-string values.
  594. """
  595. try:
  596. if isinstance(value, string_types):
  597. return int(value, base)
  598. return int(value)
  599. except (TypeError, ValueError):
  600. # this quirk is necessary so that "42.23"|int gives 42.
  601. try:
  602. return int(float(value))
  603. except (TypeError, ValueError):
  604. return default
  605. def do_float(value, default=0.0):
  606. """Convert the value into a floating point number. If the
  607. conversion doesn't work it will return ``0.0``. You can
  608. override this default using the first parameter.
  609. """
  610. try:
  611. return float(value)
  612. except (TypeError, ValueError):
  613. return default
  614. def do_format(value, *args, **kwargs):
  615. """Apply the given values to a `printf-style`_ format string, like
  616. ``string % values``.
  617. .. sourcecode:: jinja
  618. {{ "%s, %s!"|format(greeting, name) }}
  619. Hello, World!
  620. In most cases it should be more convenient and efficient to use the
  621. ``%`` operator or :meth:`str.format`.
  622. .. code-block:: text
  623. {{ "%s, %s!" % (greeting, name) }}
  624. {{ "{}, {}!".format(greeting, name) }}
  625. .. _printf-style: https://docs.python.org/library/stdtypes.html
  626. #printf-style-string-formatting
  627. """
  628. if args and kwargs:
  629. raise FilterArgumentError(
  630. "can't handle positional and keyword arguments at the same time"
  631. )
  632. return soft_unicode(value) % (kwargs or args)
  633. def do_trim(value, chars=None):
  634. """Strip leading and trailing characters, by default whitespace."""
  635. return soft_unicode(value).strip(chars)
  636. def do_striptags(value):
  637. """Strip SGML/XML tags and replace adjacent whitespace by one space."""
  638. if hasattr(value, "__html__"):
  639. value = value.__html__()
  640. return Markup(text_type(value)).striptags()
  641. def do_slice(value, slices, fill_with=None):
  642. """Slice an iterator and return a list of lists containing
  643. those items. Useful if you want to create a div containing
  644. three ul tags that represent columns:
  645. .. sourcecode:: html+jinja
  646. <div class="columnwrapper">
  647. {%- for column in items|slice(3) %}
  648. <ul class="column-{{ loop.index }}">
  649. {%- for item in column %}
  650. <li>{{ item }}</li>
  651. {%- endfor %}
  652. </ul>
  653. {%- endfor %}
  654. </div>
  655. If you pass it a second argument it's used to fill missing
  656. values on the last iteration.
  657. """
  658. seq = list(value)
  659. length = len(seq)
  660. items_per_slice = length // slices
  661. slices_with_extra = length % slices
  662. offset = 0
  663. for slice_number in range(slices):
  664. start = offset + slice_number * items_per_slice
  665. if slice_number < slices_with_extra:
  666. offset += 1
  667. end = offset + (slice_number + 1) * items_per_slice
  668. tmp = seq[start:end]
  669. if fill_with is not None and slice_number >= slices_with_extra:
  670. tmp.append(fill_with)
  671. yield tmp
  672. def do_batch(value, linecount, fill_with=None):
  673. """
  674. A filter that batches items. It works pretty much like `slice`
  675. just the other way round. It returns a list of lists with the
  676. given number of items. If you provide a second parameter this
  677. is used to fill up missing items. See this example:
  678. .. sourcecode:: html+jinja
  679. <table>
  680. {%- for row in items|batch(3, '&nbsp;') %}
  681. <tr>
  682. {%- for column in row %}
  683. <td>{{ column }}</td>
  684. {%- endfor %}
  685. </tr>
  686. {%- endfor %}
  687. </table>
  688. """
  689. tmp = []
  690. for item in value:
  691. if len(tmp) == linecount:
  692. yield tmp
  693. tmp = []
  694. tmp.append(item)
  695. if tmp:
  696. if fill_with is not None and len(tmp) < linecount:
  697. tmp += [fill_with] * (linecount - len(tmp))
  698. yield tmp
  699. def do_round(value, precision=0, method="common"):
  700. """Round the number to a given precision. The first
  701. parameter specifies the precision (default is ``0``), the
  702. second the rounding method:
  703. - ``'common'`` rounds either up or down
  704. - ``'ceil'`` always rounds up
  705. - ``'floor'`` always rounds down
  706. If you don't specify a method ``'common'`` is used.
  707. .. sourcecode:: jinja
  708. {{ 42.55|round }}
  709. -> 43.0
  710. {{ 42.55|round(1, 'floor') }}
  711. -> 42.5
  712. Note that even if rounded to 0 precision, a float is returned. If
  713. you need a real integer, pipe it through `int`:
  714. .. sourcecode:: jinja
  715. {{ 42.55|round|int }}
  716. -> 43
  717. """
  718. if method not in {"common", "ceil", "floor"}:
  719. raise FilterArgumentError("method must be common, ceil or floor")
  720. if method == "common":
  721. return round(value, precision)
  722. func = getattr(math, method)
  723. return func(value * (10 ** precision)) / (10 ** precision)
  724. # Use a regular tuple repr here. This is what we did in the past and we
  725. # really want to hide this custom type as much as possible. In particular
  726. # we do not want to accidentally expose an auto generated repr in case
  727. # people start to print this out in comments or something similar for
  728. # debugging.
  729. _GroupTuple = namedtuple("_GroupTuple", ["grouper", "list"])
  730. _GroupTuple.__repr__ = tuple.__repr__
  731. _GroupTuple.__str__ = tuple.__str__
  732. @environmentfilter
  733. def do_groupby(environment, value, attribute):
  734. """Group a sequence of objects by an attribute using Python's
  735. :func:`itertools.groupby`. The attribute can use dot notation for
  736. nested access, like ``"address.city"``. Unlike Python's ``groupby``,
  737. the values are sorted first so only one group is returned for each
  738. unique value.
  739. For example, a list of ``User`` objects with a ``city`` attribute
  740. can be rendered in groups. In this example, ``grouper`` refers to
  741. the ``city`` value of the group.
  742. .. sourcecode:: html+jinja
  743. <ul>{% for city, items in users|groupby("city") %}
  744. <li>{{ city }}
  745. <ul>{% for user in items %}
  746. <li>{{ user.name }}
  747. {% endfor %}</ul>
  748. </li>
  749. {% endfor %}</ul>
  750. ``groupby`` yields namedtuples of ``(grouper, list)``, which
  751. can be used instead of the tuple unpacking above. ``grouper`` is the
  752. value of the attribute, and ``list`` is the items with that value.
  753. .. sourcecode:: html+jinja
  754. <ul>{% for group in users|groupby("city") %}
  755. <li>{{ group.grouper }}: {{ group.list|join(", ") }}
  756. {% endfor %}</ul>
  757. .. versionchanged:: 2.6
  758. The attribute supports dot notation for nested access.
  759. """
  760. expr = make_attrgetter(environment, attribute)
  761. return [
  762. _GroupTuple(key, list(values))
  763. for key, values in groupby(sorted(value, key=expr), expr)
  764. ]
  765. @environmentfilter
  766. def do_sum(environment, iterable, attribute=None, start=0):
  767. """Returns the sum of a sequence of numbers plus the value of parameter
  768. 'start' (which defaults to 0). When the sequence is empty it returns
  769. start.
  770. It is also possible to sum up only certain attributes:
  771. .. sourcecode:: jinja
  772. Total: {{ items|sum(attribute='price') }}
  773. .. versionchanged:: 2.6
  774. The `attribute` parameter was added to allow suming up over
  775. attributes. Also the `start` parameter was moved on to the right.
  776. """
  777. if attribute is not None:
  778. iterable = imap(make_attrgetter(environment, attribute), iterable)
  779. return sum(iterable, start)
  780. def do_list(value):
  781. """Convert the value into a list. If it was a string the returned list
  782. will be a list of characters.
  783. """
  784. return list(value)
  785. def do_mark_safe(value):
  786. """Mark the value as safe which means that in an environment with automatic
  787. escaping enabled this variable will not be escaped.
  788. """
  789. return Markup(value)
  790. def do_mark_unsafe(value):
  791. """Mark a value as unsafe. This is the reverse operation for :func:`safe`."""
  792. return text_type(value)
  793. def do_reverse(value):
  794. """Reverse the object or return an iterator that iterates over it the other
  795. way round.
  796. """
  797. if isinstance(value, string_types):
  798. return value[::-1]
  799. try:
  800. return reversed(value)
  801. except TypeError:
  802. try:
  803. rv = list(value)
  804. rv.reverse()
  805. return rv
  806. except TypeError:
  807. raise FilterArgumentError("argument must be iterable")
  808. @environmentfilter
  809. def do_attr(environment, obj, name):
  810. """Get an attribute of an object. ``foo|attr("bar")`` works like
  811. ``foo.bar`` just that always an attribute is returned and items are not
  812. looked up.
  813. See :ref:`Notes on subscriptions <notes-on-subscriptions>` for more details.
  814. """
  815. try:
  816. name = str(name)
  817. except UnicodeError:
  818. pass
  819. else:
  820. try:
  821. value = getattr(obj, name)
  822. except AttributeError:
  823. pass
  824. else:
  825. if environment.sandboxed and not environment.is_safe_attribute(
  826. obj, name, value
  827. ):
  828. return environment.unsafe_undefined(obj, name)
  829. return value
  830. return environment.undefined(obj=obj, name=name)
  831. @contextfilter
  832. def do_map(*args, **kwargs):
  833. """Applies a filter on a sequence of objects or looks up an attribute.
  834. This is useful when dealing with lists of objects but you are really
  835. only interested in a certain value of it.
  836. The basic usage is mapping on an attribute. Imagine you have a list
  837. of users but you are only interested in a list of usernames:
  838. .. sourcecode:: jinja
  839. Users on this page: {{ users|map(attribute='username')|join(', ') }}
  840. You can specify a ``default`` value to use if an object in the list
  841. does not have the given attribute.
  842. .. sourcecode:: jinja
  843. {{ users|map(attribute="username", default="Anonymous")|join(", ") }}
  844. Alternatively you can let it invoke a filter by passing the name of the
  845. filter and the arguments afterwards. A good example would be applying a
  846. text conversion filter on a sequence:
  847. .. sourcecode:: jinja
  848. Users on this page: {{ titles|map('lower')|join(', ') }}
  849. Similar to a generator comprehension such as:
  850. .. code-block:: python
  851. (u.username for u in users)
  852. (u.username or "Anonymous" for u in users)
  853. (do_lower(x) for x in titles)
  854. .. versionchanged:: 2.11.0
  855. Added the ``default`` parameter.
  856. .. versionadded:: 2.7
  857. """
  858. seq, func = prepare_map(args, kwargs)
  859. if seq:
  860. for item in seq:
  861. yield func(item)
  862. @contextfilter
  863. def do_select(*args, **kwargs):
  864. """Filters a sequence of objects by applying a test to each object,
  865. and only selecting the objects with the test succeeding.
  866. If no test is specified, each object will be evaluated as a boolean.
  867. Example usage:
  868. .. sourcecode:: jinja
  869. {{ numbers|select("odd") }}
  870. {{ numbers|select("odd") }}
  871. {{ numbers|select("divisibleby", 3) }}
  872. {{ numbers|select("lessthan", 42) }}
  873. {{ strings|select("equalto", "mystring") }}
  874. Similar to a generator comprehension such as:
  875. .. code-block:: python
  876. (n for n in numbers if test_odd(n))
  877. (n for n in numbers if test_divisibleby(n, 3))
  878. .. versionadded:: 2.7
  879. """
  880. return select_or_reject(args, kwargs, lambda x: x, False)
  881. @contextfilter
  882. def do_reject(*args, **kwargs):
  883. """Filters a sequence of objects by applying a test to each object,
  884. and rejecting the objects with the test succeeding.
  885. If no test is specified, each object will be evaluated as a boolean.
  886. Example usage:
  887. .. sourcecode:: jinja
  888. {{ numbers|reject("odd") }}
  889. Similar to a generator comprehension such as:
  890. .. code-block:: python
  891. (n for n in numbers if not test_odd(n))
  892. .. versionadded:: 2.7
  893. """
  894. return select_or_reject(args, kwargs, lambda x: not x, False)
  895. @contextfilter
  896. def do_selectattr(*args, **kwargs):
  897. """Filters a sequence of objects by applying a test to the specified
  898. attribute of each object, and only selecting the objects with the
  899. test succeeding.
  900. If no test is specified, the attribute's value will be evaluated as
  901. a boolean.
  902. Example usage:
  903. .. sourcecode:: jinja
  904. {{ users|selectattr("is_active") }}
  905. {{ users|selectattr("email", "none") }}
  906. Similar to a generator comprehension such as:
  907. .. code-block:: python
  908. (u for user in users if user.is_active)
  909. (u for user in users if test_none(user.email))
  910. .. versionadded:: 2.7
  911. """
  912. return select_or_reject(args, kwargs, lambda x: x, True)
  913. @contextfilter
  914. def do_rejectattr(*args, **kwargs):
  915. """Filters a sequence of objects by applying a test to the specified
  916. attribute of each object, and rejecting the objects with the test
  917. succeeding.
  918. If no test is specified, the attribute's value will be evaluated as
  919. a boolean.
  920. .. sourcecode:: jinja
  921. {{ users|rejectattr("is_active") }}
  922. {{ users|rejectattr("email", "none") }}
  923. Similar to a generator comprehension such as:
  924. .. code-block:: python
  925. (u for user in users if not user.is_active)
  926. (u for user in users if not test_none(user.email))
  927. .. versionadded:: 2.7
  928. """
  929. return select_or_reject(args, kwargs, lambda x: not x, True)
  930. @evalcontextfilter
  931. def do_tojson(eval_ctx, value, indent=None):
  932. """Dumps a structure to JSON so that it's safe to use in ``<script>``
  933. tags. It accepts the same arguments and returns a JSON string. Note that
  934. this is available in templates through the ``|tojson`` filter which will
  935. also mark the result as safe. Due to how this function escapes certain
  936. characters this is safe even if used outside of ``<script>`` tags.
  937. The following characters are escaped in strings:
  938. - ``<``
  939. - ``>``
  940. - ``&``
  941. - ``'``
  942. This makes it safe to embed such strings in any place in HTML with the
  943. notable exception of double quoted attributes. In that case single
  944. quote your attributes or HTML escape it in addition.
  945. The indent parameter can be used to enable pretty printing. Set it to
  946. the number of spaces that the structures should be indented with.
  947. Note that this filter is for use in HTML contexts only.
  948. .. versionadded:: 2.9
  949. """
  950. policies = eval_ctx.environment.policies
  951. dumper = policies["json.dumps_function"]
  952. options = policies["json.dumps_kwargs"]
  953. if indent is not None:
  954. options = dict(options)
  955. options["indent"] = indent
  956. return htmlsafe_json_dumps(value, dumper=dumper, **options)
  957. def prepare_map(args, kwargs):
  958. context = args[0]
  959. seq = args[1]
  960. default = None
  961. if len(args) == 2 and "attribute" in kwargs:
  962. attribute = kwargs.pop("attribute")
  963. default = kwargs.pop("default", None)
  964. if kwargs:
  965. raise FilterArgumentError(
  966. "Unexpected keyword argument %r" % next(iter(kwargs))
  967. )
  968. func = make_attrgetter(context.environment, attribute, default=default)
  969. else:
  970. try:
  971. name = args[2]
  972. args = args[3:]
  973. except LookupError:
  974. raise FilterArgumentError("map requires a filter argument")
  975. def func(item):
  976. return context.environment.call_filter(
  977. name, item, args, kwargs, context=context
  978. )
  979. return seq, func
  980. def prepare_select_or_reject(args, kwargs, modfunc, lookup_attr):
  981. context = args[0]
  982. seq = args[1]
  983. if lookup_attr:
  984. try:
  985. attr = args[2]
  986. except LookupError:
  987. raise FilterArgumentError("Missing parameter for attribute name")
  988. transfunc = make_attrgetter(context.environment, attr)
  989. off = 1
  990. else:
  991. off = 0
  992. def transfunc(x):
  993. return x
  994. try:
  995. name = args[2 + off]
  996. args = args[3 + off :]
  997. def func(item):
  998. return context.environment.call_test(name, item, args, kwargs)
  999. except LookupError:
  1000. func = bool
  1001. return seq, lambda item: modfunc(func(transfunc(item)))
  1002. def select_or_reject(args, kwargs, modfunc, lookup_attr):
  1003. seq, func = prepare_select_or_reject(args, kwargs, modfunc, lookup_attr)
  1004. if seq:
  1005. for item in seq:
  1006. if func(item):
  1007. yield item
  1008. FILTERS = {
  1009. "abs": abs,
  1010. "attr": do_attr,
  1011. "batch": do_batch,
  1012. "capitalize": do_capitalize,
  1013. "center": do_center,
  1014. "count": len,
  1015. "d": do_default,
  1016. "default": do_default,
  1017. "dictsort": do_dictsort,
  1018. "e": escape,
  1019. "escape": escape,
  1020. "filesizeformat": do_filesizeformat,
  1021. "first": do_first,
  1022. "float": do_float,
  1023. "forceescape": do_forceescape,
  1024. "format": do_format,
  1025. "groupby": do_groupby,
  1026. "indent": do_indent,
  1027. "int": do_int,
  1028. "join": do_join,
  1029. "last": do_last,
  1030. "length": len,
  1031. "list": do_list,
  1032. "lower": do_lower,
  1033. "map": do_map,
  1034. "min": do_min,
  1035. "max": do_max,
  1036. "pprint": do_pprint,
  1037. "random": do_random,
  1038. "reject": do_reject,
  1039. "rejectattr": do_rejectattr,
  1040. "replace": do_replace,
  1041. "reverse": do_reverse,
  1042. "round": do_round,
  1043. "safe": do_mark_safe,
  1044. "select": do_select,
  1045. "selectattr": do_selectattr,
  1046. "slice": do_slice,
  1047. "sort": do_sort,
  1048. "string": soft_unicode,
  1049. "striptags": do_striptags,
  1050. "sum": do_sum,
  1051. "title": do_title,
  1052. "trim": do_trim,
  1053. "truncate": do_truncate,
  1054. "unique": do_unique,
  1055. "upper": do_upper,
  1056. "urlencode": do_urlencode,
  1057. "urlize": do_urlize,
  1058. "wordcount": do_wordcount,
  1059. "wordwrap": do_wordwrap,
  1060. "xmlattr": do_xmlattr,
  1061. "tojson": do_tojson,
  1062. }