Add some more documentation and rename some option variables

README.md

@@ -1,5 +1,4 @@
-fbconsole
-=========
+# fbconsole #
 
 fbconsole is a small facebook api client for use in python scripts.
 
@@ -8,18 +7,17 @@ You can install fbconsole using pip:
     pip install fbconsole
 
 
-Quick Start Guide
------------------
+## Quick Start Guide ##
 
-**Authentication**
+
+### Authentication ###
 
 For many api calls, you will need to authenticate your script with Facebook.
 fbconsole makes this easy by providing an `authenticate` function.  If your
 script needs extended permissions, for example to post a status update, you can
 specify which extended permissions to request with the AUTH_SCOPE setting.  For
 example:
 
-
     import fbconsole
 
     fbconsole.AUTH_SCOPE = ['publish_stream', 'publish_checkins']
@@ -32,7 +30,9 @@ During the authentication process, a browser window will be opened where you can
 enter in your facebook login credentials.  After logging in, you can close the
 browser window.  Your script will continue executing in the background.
 
-**Graph API Basics**
+
+### Graph API Basics ###
+
 
 You can make HTTP POST requests using the `post` function.  Here is how
 you would update your status:
@@ -60,3 +60,48 @@ Finally, you can also make
     friends = fbconsole.fql("SELECT name FROM user WHERE uid IN "
                             "(SELECT uid2 FROM friend WHERE uid1 = me())")
 
+
+### More Authentication Options ###
+
+By default, fbconsole will make all it's requests as the fbconsole facebook app.
+If you want the requests to be made by your own facebook application, you must
+modify the APP_ID setting.  For example:
+
+    fbconsole.APP_ID = '<your-app-id>'
+    fbconsole.authenticate()
+
+For the authentication flow to work, you must configure your Facebook
+application correctly by setting the "Site URL" option to http://127.0.0.1:8080
+
+If you don't want to change your application settings, you can also specify an
+access token to use directly, in which case you can skip authentication
+altogether:
+
+    fbconsole.ACCESS_TOKEN = '<your-access-token>'
+
+
+### Other Options ###
+
+There are two other options you can specify.
+
+- `SERVER_PORT` controls which port the local server runs on.  If you modify
+     this, make sure your applications settings on Facebook, specifically "Site
+     URL", reflect the port number you are using.  The default is 8080.
+
+- `ACCESS_TOKEN_FILE` controls where the access token gets stored on the file
+  system.  The default is `.fb_access_token`.
+
+
+## Feedback ##
+
+For issues pertaining to fbconsole only, use
+[the issue tracker on github](https://github.com/facebook/fbconsole/issues).
+For issues with the graph api or other aspects of Facebook's platform, please
+refer to [the developer docs](https://developers.facebook.com/docs/) and
+[the Facebook Platform bug tracker](http://bugs.developers.facebook.net/).
+
+
+## License Information ##
+
+fbconsole is licensed under the [Apache License, Version
+2.0](http://www.apache.org/licenses/LICENSE-2.0.html)

src/fbconsole.py

@@ -33,9 +33,8 @@
 
 APP_ID = '179745182062082'
 SERVER_PORT = 8080
-REDIRECT_URI = 'http://127.0.0.1:%s/' % SERVER_PORT
 ACCESS_TOKEN = None
-LOCAL_FILE = '.fb_access_token'
+ACCESS_TOKEN_FILE = '.fb_access_token'
 AUTH_SCOPE = []
 
 __all__ = [
@@ -50,7 +49,7 @@
     'SERVER_PORT',
     'ACCESS_TOKEN',
     'AUTH_SCOPE',
-    'LOCAL_FILE']
+    'ACCESS_TOKEN_FILE']
 
 def _get_url(path, args=None, graph=True):
     args = args or {}
@@ -126,7 +125,7 @@ def do_GET(self):
         if ACCESS_TOKEN:
             data = {'scope': AUTH_SCOPE,
                     'access_token': ACCESS_TOKEN}
-            open(LOCAL_FILE,'w').write(json.dumps(data))
+            open(ACCESS_TOKEN_FILE,'w').write(json.dumps(data))
             self.wfile.write("You have successfully logged in to facebook with fbconsole. "
                              "You can close this window now.")
         else:
@@ -159,8 +158,8 @@ def authenticate():
     """
     global ACCESS_TOKEN
     needs_auth = True
-    if os.path.exists(LOCAL_FILE):
-        data = json.loads(open(LOCAL_FILE).read())
+    if os.path.exists(ACCESS_TOKEN_FILE):
+        data = json.loads(open(ACCESS_TOKEN_FILE).read())
         if set(data['scope']).issuperset(AUTH_SCOPE):
             ACCESS_TOKEN = data['access_token']
             needs_auth = False
@@ -169,7 +168,7 @@ def authenticate():
         print "Logging you in to facebook..."
         webbrowser.open('https://www.facebook.com/dialog/oauth?' +
                         urlencode({'client_id':APP_ID,
-                                   'redirect_uri':REDIRECT_URI,
+                                   'redirect_uri':'http://127.0.0.1:%s/' % SERVER_PORT,
                                    'response_type':'token',
                                    'scope':','.join(AUTH_SCOPE)}))