Add function for retrieving user permissions

docs/api.rst

@@ -311,8 +311,28 @@ Generates Facebook login URL to request access token and permissions.
 **Example**
 
 .. code-block:: python
+
     app_id = 1231241241
     canvas_url = 'https://domain.com/that-handles-auth-response/'
     perms = ['manage_pages','publish_pages']
     fb_login_url = graph.auth_url(app_id, canvas_url, perms)
     print(fb_login_url)
+
+get_permissions
+^^^^^^^^^^^^^
+
+https://developers.facebook.com/docs/graph-api/reference/user/permissions/
+
+Returns the permissions granted to the app by the user with the given ID as a
+``dict``.
+
+**Parameters**
+
+* ``user_id`` - A ``string`` or an ``int`` that is a unique ID for a user.
+
+**Example**
+
+.. code-block:: python
+
+    permissions = graph.get_permissions(user_id=12345)
+    print(permissions["public_profile"])

facebook/__init__.py

@@ -102,6 +102,15 @@ def __init__(self, access_token=None, timeout=None, version=None,
         else:
             self.version = "v" + default_version
 
+    def get_permissions(self, user_id):
+        """Fetches the permissions object from the graph."""
+        response = self.request(
+            "{0}/{1}/permissions".format(self.version, user_id), {}
+            )["data"]
+        result = dict((x["permission"], x["status"] == "granted")
+                      for x in response)
+        return result
+
     def get_object(self, id, **args):
         """Fetches the given object from the graph."""
         return self.request("{0}/{1}".format(self.version, id), args)

test/test_facebook.py

@@ -299,5 +299,32 @@ def test_request_access_tokens_are_unique_to_instances(self):
         self.assertEqual(graph2.request.__defaults__[0], None)
 
 
+class TestGetUserPermissions(FacebookTestCase):
+    """
+    Test if user permissions are retrieved correctly.
+
+    Note that this only tests if the returned JSON object exists and is
+    structured as expected, not whether any specific scope is included
+    (other than the default `public_profile` scope).
+
+    """
+    def test_get_user_permissions_node(self):
+        token = facebook.GraphAPI().get_app_access_token(
+            self.app_id, self.secret)
+        graph = facebook.GraphAPI(access_token=token)
+        self.create_test_users(self.app_id, graph, 1)
+        permissions = graph.get_permissions(self.test_users[0]['id'])
+        self.assertIsNotNone(permissions)
+        self.assertEqual(permissions['public_profile'], True)
+        self.assertEqual(permissions['user_friends'], True)
+        self.assertFalse('email' in permissions)
+
+    def test_get_user_permissions_nonexistant_user(self):
+        token = facebook.GraphAPI().get_app_access_token(
+            self.app_id, self.secret)
+        with self.assertRaises(facebook.GraphAPIError):
+            facebook.GraphAPI(token).get_permissions(1)
+
+
 if __name__ == '__main__':
     unittest.main()