Add docs & explict tests

3 files changed, 66 insertions, 2 deletions

diff --git a/docs/api/authentication.rst b/docs/api/authentication.rst
index 19d08618b..de2c73491 100644
--- a/docs/api/authentication.rst
+++ b/docs/api/authentication.rst
@@ -35,4 +35,7 @@ Helper Classes
      :members:
 
 
+Helper Functions
+~~~~~~~~~~~~~~~~
 
+  .. autofunction:: extract_http_basic_credentials
diff --git a/pyramid/authentication.py b/pyramid/authentication.py
index 712cef08e..46909d84e 100644
--- a/pyramid/authentication.py
+++ b/pyramid/authentication.py
@@ -1120,10 +1120,10 @@ class _SimpleSerializer(object):
 
 def extract_http_basic_credentials(request):
     """ A helper function for extraction of HTTP Basic credentials
-    from a given `request`.
+    from a given :term:`request`.
 
     ``request``
-        The request object
+        The :term:`request` object
     """
     authorization = request.headers.get('Authorization')
     if not authorization:
diff --git a/pyramid/tests/test_authentication.py b/pyramid/tests/test_authentication.py
index 0a22e5965..53747b6f0 100644
--- a/pyramid/tests/test_authentication.py
+++ b/pyramid/tests/test_authentication.py
@@ -1476,6 +1476,67 @@ class TestBasicAuthAuthenticationPolicy(unittest.TestCase):
         self.assertEqual(policy.forget(None), [
             ('WWW-Authenticate', 'Basic realm="SomeRealm"')])
 
+
+class TestExtractHTTPBasicCredentials(unittest.TestCase):
+    def _get_func(self):
+        from pyramid.authentication import extract_http_basic_credentials
+        return extract_http_basic_credentials
+
+    def test_no_auth_header(self):
+        request = testing.DummyRequest()
+        fn = self._get_func()
+
+        self.assertIsNone(fn(request))
+
+    def test_invalid_payload(self):
+        import base64
+        request = testing.DummyRequest()
+        request.headers['Authorization'] = 'Basic %s' % base64.b64encode(
+            bytes_('chrisrpassword')).decode('ascii')
+        fn = self._get_func()
+        self.assertIsNone(fn(request))
+
+    def test_not_a_basic_auth_scheme(self):
+        import base64
+        request = testing.DummyRequest()
+        request.headers['Authorization'] = 'OtherScheme %s' % base64.b64encode(
+            bytes_('chrisr:password')).decode('ascii')
+        fn = self._get_func()
+        self.assertIsNone(fn(request))
+
+    def test_no_base64_encoding(self):
+        request = testing.DummyRequest()
+        request.headers['Authorization'] = 'Basic ...'
+        fn = self._get_func()
+        self.assertIsNone(fn(request))
+
+    def test_latin1_payload(self):
+        import base64
+        request = testing.DummyRequest()
+        inputs = (b'm\xc3\xb6rk\xc3\xb6:'
+                  b'm\xc3\xb6rk\xc3\xb6password').decode('utf-8')
+        request.headers['Authorization'] = 'Basic %s' % (
+            base64.b64encode(inputs.encode('latin-1')).decode('latin-1'))
+        fn = self._get_func()
+        self.assertEqual(fn(request), (
+            b'm\xc3\xb6rk\xc3\xb6'.decode('utf-8'),
+            b'm\xc3\xb6rk\xc3\xb6password'.decode('utf-8')
+        ))
+
+    def test_utf8_payload(self):
+        import base64
+        request = testing.DummyRequest()
+        inputs = (b'm\xc3\xb6rk\xc3\xb6:'
+                  b'm\xc3\xb6rk\xc3\xb6password').decode('utf-8')
+        request.headers['Authorization'] = 'Basic %s' % (
+            base64.b64encode(inputs.encode('utf-8')).decode('latin-1'))
+        fn = self._get_func()
+        self.assertEqual(fn(request), (
+            b'm\xc3\xb6rk\xc3\xb6'.decode('utf-8'),
+            b'm\xc3\xb6rk\xc3\xb6password'.decode('utf-8')
+        ))
+
+
 class TestSimpleSerializer(unittest.TestCase):
     def _makeOne(self):
         from pyramid.authentication import _SimpleSerializer