From: David Lord <davidism@gmail.com>
Date: Fri, 18 Oct 2019 18:53:33 +0000 (-0700)
Subject: document formatting methods in format filter
X-Git-Tag: 2.11.0~38^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=edc0aa2264148006649ae171394ba85fbce792d9;p=thirdparty%2Fjinja.git

document formatting methods in format filter
closes #566
---

diff --git a/jinja2/filters.py b/jinja2/filters.py
index 40dbfcb3..19f38641 100644
--- a/jinja2/filters.py
+++ b/jinja2/filters.py
@@ -743,13 +743,24 @@ def do_float(value, default=0.0):
 
 
 def do_format(value, *args, **kwargs):
-    """
-    Apply python string formatting on an object:
+    """Apply the given values to a `printf-style`_ format string, like
+    ``string % values``.
 
     .. sourcecode:: jinja
 
-        {{ "%s - %s"|format("Hello?", "Foo!") }}
-            -> Hello? - Foo!
+        {{ "%s, %s!"|format(greeting, name) }}
+        Hello, World!
+
+    In most cases it should be more convenient and efficient to use the
+    ``%`` operator or :meth:`str.format`.
+
+    .. code-block:: text
+
+        {{ "%s, %s!" % (greeting, name) }}
+        {{ "{}, {}!".format(greeting, name) }}
+
+    .. _printf-style: https://docs.python.org/library/stdtypes.html
+        #printf-style-string-formatting
     """
     if args and kwargs:
         raise FilterArgumentError('can\'t handle positional and keyword '