document and test p.encode.urlencode(quote_via=...)

2 files changed, 21 insertions, 9 deletions

diff --git a/pyramid/encode.py b/pyramid/encode.py
index 62f96938b..73ff14e62 100644
--- a/pyramid/encode.py
+++ b/pyramid/encode.py
@@ -25,11 +25,10 @@ def quote_plus(val, safe=''):
 
 def urlencode(query, doseq=True, quote_via=quote_plus):
     """
-    An alternate implementation of Python's stdlib `urllib.urlencode
-    function <http://docs.python.org/library/urllib.html>`_ which
-    accepts unicode keys and values within the ``query``
-    dict/sequence; all Unicode keys and values are first converted to
-    UTF-8 before being used to compose the query string.
+    An alternate implementation of Python's stdlib
+    :func:`urllib.parse.urlencode` function which accepts unicode keys and
+    values within the ``query`` dict/sequence; all Unicode keys and values are
+    first converted to UTF-8 before being used to compose the query string.
 
     The value of ``query`` must be a sequence of two-tuples
     representing key/value pairs *or* an object (often a dictionary)
@@ -44,12 +43,18 @@ def urlencode(query, doseq=True, quote_via=quote_plus):
     the ``doseq=True`` mode, no matter what the value of the second
     argument.
 
-    See the Python stdlib documentation for ``urllib.urlencode`` for
-    more information.
+    Both the key and value are encoded using the ``quote_via`` function which
+    by default is using a similar algorithm to :func:`urllib.parse.quote_plus`
+    which converts spaces into '+' characters and '/' into '%2F'.
 
     .. versionchanged:: 1.5
        In a key/value pair, if the value is ``None`` then it will be
        dropped from the resulting output.
+
+    .. versionchanged:: 1.9
+       Added the ``quote_via`` argument to allow alternate quoting algorithms
+       to be used.
+
     """
     try:
         # presumed to be a dictionary
diff --git a/pyramid/tests/test_encode.py b/pyramid/tests/test_encode.py
index 8fb766d88..d3a9f7095 100644
--- a/pyramid/tests/test_encode.py
+++ b/pyramid/tests/test_encode.py
@@ -5,9 +5,9 @@ from pyramid.compat import (
     )
 
 class UrlEncodeTests(unittest.TestCase):
-    def _callFUT(self, query, doseq=False):
+    def _callFUT(self, query, doseq=False, **kw):
         from pyramid.encode import urlencode
-        return urlencode(query, doseq)
+        return urlencode(query, doseq, **kw)
 
     def test_ascii_only(self):
         result = self._callFUT([('a',1), ('b',2)])
@@ -53,6 +53,13 @@ class UrlEncodeTests(unittest.TestCase):
         result = self._callFUT([('a', '1'), ('b', None), ('c', None)])
         self.assertEqual(result, 'a=1&b=&c=')
 
+    def test_quote_via(self):
+        def my_quoter(value):
+            return 'xxx' + value
+        result = self._callFUT([('a', '1'), ('b', None), ('c', None)],
+                               quote_via=my_quoter)
+        self.assertEqual(result, 'xxxa=xxx1&xxxb=&xxxc=')
+
 class URLQuoteTests(unittest.TestCase):
     def _callFUT(self, val, safe=''):
         from pyramid.encode import url_quote