Merge pull request milesrichardson#81 from mcastle/session_tokens

Enable Session Tokens to be used to access ACL-protected objects.

README.mkd

@@ -501,4 +501,23 @@ admin_role.save()
 
 This, for example, creates a role with the name 'moderators', with an ACL that allows the public to read but not write to this role object.
 
+
+Session Tokens
+---------------
+When querying or updating an object protected by an ACL, parse.com requires the session token of the user with read and write privileges, respectively. You can pass the session token to such queries and updates by using the `parse_rest.connection.SessionToken` class.
+
+~~~~~ {python}
+from parse_rest.connection import SessionToken
+from parse_rest.user import User
+
+u = User.login('dhelmet', '12345')
+token = u.sessionToken
+
+with SessionToken(token):
+    collectedItem = CollectedItem.Query.get(type="Sword") # Get a collected item, Sword, that is protected by ACL
+    print collectedItem
+~~~~~
+
+Assuming the CollectedItem 'Sword' is read-protected from the public by an ACL and is readable only by the user, SessionToken allows the user to bypass the ACL and get the 'Sword' item.
+
 That's it! This is a first try at a Python library for Parse, and is probably not bug-free. If you run into any issues, please get in touch -- dgrtwo@princeton.edu. Thanks!

parse_rest/connection.py

@@ -26,6 +26,7 @@
 # Connection can sometimes hang forever on SSL handshake
 CONNECTION_TIMEOUT = 60
 
+
 def register(app_id, rest_key, **kw):
     global ACCESS_KEYS
     ACCESS_KEYS = {
@@ -35,6 +36,18 @@ def register(app_id, rest_key, **kw):
     ACCESS_KEYS.update(**kw)
 
 
+class SessionToken:
+    def __init__(self, token):
+        global ACCESS_KEYS
+        self.token = token
+
+    def __enter__(self):
+        ACCESS_KEYS.update({'session_token': self.token})
+
+    def __exit__(self, type, value, traceback):
+        ACCESS_KEYS['session_token']
+
+
 def master_key_required(func):
     '''decorator describing methods that require the master key'''
     def ret(obj, *args, **kw):
@@ -90,6 +103,9 @@ def execute(cls, uri, http_verb, extra_headers=None, batch=False, body=None, **k
         headers.update(extra_headers or {})
 
         request = Request(url, data, headers)
+
+        if ACCESS_KEYS.get('session_token'):
+            request.add_header('X-Parse-Session-Token', ACCESS_KEYS.get('session_token'))
 
         if master_key and 'X-Parse-Session-Token' not in headers.keys():
             request.add_header('X-Parse-Master-Key', master_key)