Sybren Stüvel avatar Sybren Stüvel committed 0c0db8e

more work on documentation, added TODOs

Comments (0)

Files changed (3)

 Authentication has been re-written to use OAuth. See the documentation
 on how to use this. Some results are:
   
-    - The token cache is now based on SQLite3, and contains not only the
-      authentication tokens, but also the user's full name, username
-      and NSID.
+    - You always have to pass both the API key and secret. In 1.x you
+      could choose to pass only the API key, but this no longer works
+      with OAuth.
 
-    - For non-web applications, a local HTTP server is started to receive
-      the verification code. This means that the user does not have to copy
-      and paste the verification code to the application.
+    - The token cache is now based on SQLite3, and contains not only
+      the authentication tokens, but also the user's full name,
+      username and NSID.
+
+    - For non-web applications, a local HTTP server is started to
+      receive the verification code. This means that the user does not
+      have to copy and paste the verification code to the application.
 
     - The authentication callback functionality is gone. I'm not sure
       how many people still need this now that we've moved to OAuth.
 
     - Persistent connections have been dropped.
 
-Flickr functions can be called with dotted notation. For example:
+Flickr functions can be called with dotted notation. For example::
     
     flickr.photos_getInfo(photo_id='123') now becomes:
     flickr.photos.getInfo(photo_id='123')
 The Flickr document `User Authentication`_ explains the authentication
 process; it's good to know what's in there before you go on. The Python
 Flickr API takes care of most of the OAuth details, but still it is
-important to know the authentication flow.
+important to know the authentication flow. In short:
 
-Here is a simple example::
+ 1. Get a request token from Flickr.
+ 2. Send the user's web browser to Flickr to log in and authorize the
+     application.
+ 3. The browser is redirected to the application's callback URL to
+     pass the application a verification code.
+ 4. Use the verification code to trade the request token for an access
+     token.
+ 5. The access token can be stored by the application, so that future
+     calls don't have to follow these steps.
+
+Here is a simple example that does all the above in one simple call to
+``authenticate_via_browser``::
 
     import flickrapi
 
     flickr.authenticate_via_browser(perms='read')
 
 The ``api_key`` and ``api_secret`` can be obtained from
-http://www.flickr.com/services/api/keys/.
+http://www.flickr.com/services/api/keys/. Every application should use
+its own key and secret.
 
-The call to ``flickr.authenticate_via_browser(...)`` does a lot of things.
-First, it checks the on-disk token cache. After all, the application
-may be authenticated already. If a token is found, it is checked with
-Flickr for validity. If it is valid, it is used for all
+The call to ``flickr.authenticate_via_browser(...)`` does a lot of
+things.  First, it checks the on-disk token cache. After all, the
+application may be authenticated already. If a token is found, it is
+checked with Flickr for validity. If it is valid, it is used for all
 following calls and the authentication process is complete.
 
 If the application isn't authenticated yet, a browser opens the Flickr
 page, on which the user can grant the application the appropriate
 access. When the user presses the "OK, I'LL AUTHORIZE IT" button, the
-browser will be redirected to a local web server to pass a
-verification code to the application. When this code has been received,
-the token is stored in the token cache and the authentication process is complete.
+browser will be redirected to a callback URL or display a verification
+code. The code is passed then to the application. When this code has
+been received, the token is stored in the token cache and the
+authentication process is complete.
 
 .. _`User Authentication`: http://www.flickr.com/services/api/auth.oauth.html
 
+Non-web applications
+--------------------------------------------------
+
+OAuth was designed for web-based applications. After authorizing the
+application the browser is sent to an papplication-specific callback
+URL with a verification code appended. When your application is not
+web-based, you have two options:
+
+ 1. Use "oob" as the callback URL. Flickr displays the verification
+     code, which the user has to copy-and-paste to your application.
+     This is described in `Authenticating without local web server`_.
+
+ 2. Use Python Flickr API's local webserver. It is only available on
+     the machine the application is running on, and listens on a
+     random port. This is described in the rest of this section.
+
+Python Flickr API uses a local web server by default, and this is by
+far the easiest way to authorize desktop applications.
+
+.. todo:: more explanation; include timeout and GUI examples.
+
 Authenticating without local web server
 ----------------------------------------------------------------------
 
 
 When working with web applications, things are a bit different. The
 user using the application (through a browser) is likely to be
-different from the user running the server-side software.
+different from the user running the server-side software. You can pass
+a username to the ``FlickrAPI`` constructor, so that access tokens
+from different users won't be mixed up.
 
-We'll assume you're following Flickr's `Web Applications How-To`_, and
-just tell you how things are splified when working with the Python
-Flickr API.
-
-    3. Create a login link. Use ``flickr.web_login_url(perms)``` for
-       that.  It'll return the login link for you, given the
-       permissions you passed in the ``perms`` parameter.
-
-    5. Don't bother understanding the signing process; the
-       ``FlickrAPI`` module takes care of that for you. Once you
-       received the frob from Flickr, use
-       ``flickr.get_token("the_frob")``. The FlickrAPI module will
-       remember the token for you.
-
-    6. You can safely skip this, and just use the FlickrAPI module as
-       usual. Only read this if you want to understand how the
-       FlickrAPI module signs method calls for you.
+.. todo:: web flow
 
 Token handling in web applications
 ----------------------------------------------------------------------
 to that user. It will keep track of the authentication token for that
 user, and there's nothing special you'll have to do.
 
-When working with anonymous users, you'll have to store the
-authentication token in a cookie. In step 5. above, use this::
+When working with anonymous users, you'll have to store their access
+token in a cookie.
 
-    token = flickr.get_token("the_frob")
+.. todo:: concrete examples
 
-Then use your web framework to store the token in a cookie. When
-reading a token from a cookie, pass it on to the FlickrAPI constructor
 like this::
 
     flickr = flickrapi.FlickrAPI(api_key, api_secret, token=token)
 Preventing usage of on-disk token cache
 ----------------------------------------------------------------------
 
-Another way of preventing the storage of tokens is to pass
-``store_token=False`` as the constructor parameter. Use this if you
-want to be absolutely sure that the FlickrAPI instance doesn't use any
-previously stored tokens, nor that it will store new tokens.
+If for any reason you want to make sure the access token is not
+stored, pass ``store_token=False`` as constructor parameter. Use this
+if you want to be absolutely sure that the FlickrAPI instance doesn't
+use any previously stored tokens, nor that it will store new tokens.
 
 Controlling the location of the on-disk token cache
 ----------------------------------------------------------------------
 
+.. todo:: allow changing the OAuth token DB location
+
 By default the authentication tokens are stored in the directory
 ``~/.flickr``. If you want to change this directory, you can do so
 by changing the ``flickr.token.path`` variable after you have created
 Multiple processes using the same key
 ----------------------------------------------------------------------
 
-By default the token is stored on the filesystem in
-``somepath/<authentication key>/auth.token``. When multiple
-processes use the same authentication key a race condition can occur
-where the authentication token is removed. To circumvent this, use the
-``LockingTokenCache`` instead::
-
-    from flickrapi import FlickrAPI
-    from flickrapi.tokencache import LockingTokenCache
-    
-    flickr = flickrapi.FlickrAPI(api_key, secret)
-    
-    flickr.token_cache = LockingTokenCache(api_key)
-    # -- or --
-    flickr.token_cache = LockingTokenCache(api_key, username)
-
-This cache ensures that only one process at the time can use the token
-cache. It does not forsee in multi-threading.
-
-As the locking mechanism causes additional disk I/O and performs more
-checks, it is slower than the regular cache. Since not that many
-people use the same key in parallel on one machine (or a shared
-filesystem on which the token is stored) the default token cache does
-not use locking.
+The token database uses SQLite3, so it should be safe to access using
+mutiple processes at the same time.
 
 Example using Django
 ----------------------------------------------------------------------
 
+.. todo:: Update this example.
+
+.. todo:: add an example using Flask, as it's smaller and simpler.
+
 Here is a simple example in `Django <https://www.djangoproject.com/>`_::
 
  import flickrapi
 callback URL as defined in your Flickr API key. The key and secret
 should be configured in your settings.py, in the properties
 ``FLICKR_API_KEY`` and ``FLICKR_API_SECRET``.
+
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
+
+todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.