Permalink
Browse files

updating docs, README, and CHANGELOG

  • Loading branch information...
maxcountryman committed Mar 3, 2013
1 parent c6447dd commit c590a5247477438091df2180b212d8595eb7c5bd
Showing with 52 additions and 59 deletions.
  1. +4 −4 CHANGELOG
  2. +21 −26 README.markdown
  3. +10 −6 docs/index.rst
  4. +17 −23 docs/upgrading.rst
View
@@ -8,9 +8,11 @@ Changes in Version 0.5.0
* Updated README
+ * All HTTP methods moved to Session objects
+
* Added get_session method to service wrappers
- * Added automatic access token setting to OAuth1 and OAuth2Service
+ * Added get_auth_session method to service wrappers
* Added get_raw_access token to OAuth1 and OAuth2Service
@@ -38,13 +40,11 @@ Changes in Version 0.5.0
* Default basic auth removed from OAuth2Service.get_access_token
- * Calls to service wrapper request method without tokens are now okay
-
* Service wrapper API unified
* hook module removed, replaced by session module
- * Add unified Requests Session wrappers for each respective service
+ * Added unified Requests Session wrappers for each respective service
* Default connection timeouts moved into Session module logic
View
@@ -6,23 +6,24 @@ of Requests.
[![build status](https://secure.travis-ci.org/litl/rauth.png?branch=master)](https://travis-ci.org/#!/litl/rauth)
-## Installation
+## Features
-Install the module with one of the following commands::
+* Supports OAuth 1.0/a, 2.0 and [Ofly](http://www.shutterfly.com/documentation/start.sfly)
+* Service wrappers for convenient connection initialization
+* Authenticated session objects providing nifty things like keep-alive
+* Well tested (100% coverage)
+* Built on [Requests](https://github.com/kennethreitz/requests) (v1.x)
- $ pip install rauth
-Or if you must::
+## Installation
- $ easy_install rauth
+To install:
+ $ pip install rauth
-## Features
+Or if you must:
-* Built on [Requests](https://github.com/kennethreitz/requests)
-* Supports OAuth 1.0, 1.0a, 2.0 and [Ofly](http://www.shutterfly.com/documentation/start.sfly)
-* Service wrappers for convenient connection initialization
-* Well tested (100% coverage)
+ $ easy_install rauth
## Example Usage
@@ -60,14 +61,13 @@ print 'Visit this URL in your browser: ' + authorize_url
pin = raw_input('Enter PIN from browser: ')
```
-Exchange the authorized request token for an access token:
+Exchange the authorized request token for an authenticated `OAuth1Session`:
```python
-access_token, access_token_secret = \
- twitter.get_access_token(method='POST',
- request_token=request_token,
- request_token_secret=request_token_secret,
- data={'oauth_verifier': pin})
+session = twitter.get_auth_session(request_token,
+ request_token_secret,
+ method='POST',
+ data={'oauth_verifier': pin})
```
And now we can fetch our Twitter timeline!
@@ -76,18 +76,15 @@ And now we can fetch our Twitter timeline!
params = {'include_rts': 1, # Include retweets
'count': 10} # 10 tweets
-r = twitter.get('statuses/home_timeline.json',
- params=params,
- access_token=access_token,
- access_token_secret=access_token_secret)
+r = session.get('statuses/home_timeline.json', params=params)
for i, tweet in enumerate(r.json(), 1):
handle = tweet['user']['screen_name'].encode('utf-8')
text = tweet['text'].encode('utf-8')
print '{0}. @{1} - {2}'.format(i, handle, text)
```
-The full example is in [examples/twitter-timeline-cli.py](https://github.com/litl/rauth/blob/master/examples/twitter-timeline-cli.py).
+Here's the full example: [examples/twitter-timeline-cli.py](https://github.com/litl/rauth/blob/master/examples/twitter-timeline-cli.py).
## Documentation
@@ -104,11 +101,9 @@ Basically there's just a few steps to getting started:
2. Make your changes and write a test for them
3. Add yourself to the AUTHORS file and submit a pull request!
-Note: it's important that the code base remain well-tested so to this end it's
-generaly advisable to include a unit test. To make sure that we retain 100%
-coverage run `python setup.py test` before making a pull request. You'll need
-to make sure you have pyflakes, pep8, coverage, mock, and nose installed;
-`pip install pyflakes pep8 coverage mock nose`.
+Note: Before you make a pull request, please run `make check`. If your code
+passes then you should be good to go! Requirements for running tests are in
+`requirements.txt`.
## Copyright and License
View
@@ -34,7 +34,7 @@ simply import the service container object:
facebook = OAuth2Service(
client_id='440483442642551',
- client_secret='cd54f1ace848fa2a7ac89a31ed9c1b61'
+ client_secret='cd54f1ace848fa2a7ac89a31ed9c1b61',
name='facebook',
authorize_url='https://graph.facebook.com/oauth/authorize',
access_token_url='https://graph.facebook.com/oauth/access_token',
@@ -46,9 +46,10 @@ authorization URL:
.. code-block:: python
+ redirect_uri = 'https://www.facebook.com/connect/login_success.html'
params = {'scope': 'read_stream',
'response_type': 'code',
- 'redirect_uri': 'http://example.com/'}
+ 'redirect_uri': redirect_uri}
url = facebook.get_authorize_url(**params)
@@ -58,8 +59,11 @@ application an access token can be obtained:
.. code-block:: python
# the code should be returned upon the redirect from the authorize step,
- # be sure to use it here
- token = facebook.get_access_token(code='foobar')
+ # be sure to use it here (hint: it's in the URL!)
+ sesssion = facebook.get_auth_session(data={'code': 'foo',
+ 'redirect_uri': redirect_uri})
+
+ print session.get('me').json()['username']
Here is an example using the OAuth 1.0/a service wrapper:
@@ -78,7 +82,7 @@ Here is an example using the OAuth 1.0/a service wrapper:
Now it's possible to obtain request tokens via
`request_token = twitter.get_request_token()`, generate authorization URIs
-`twitter.get_authorize_url(request_token)`, and finally obtain access
-tokens `twitter.get_access_token(request_token, request_token_secret)`.
+`twitter.get_authorize_url(request_token)`, and finally obtain an authenticated
+session `twitter.get_auth_session(request_token, request_token_secret)`.
.. include:: contents.rst.inc
View
@@ -21,17 +21,19 @@ This release will bring support for Requests v1.x to rauth. The changes in
Requests API are fairly significant and as a direct result the changes to the
rauth API in this release are extensive.
-First and foremost Requests v1.x largely does away with hooks (and does away
-with the specific hook rauth was previously relying on). As such we have
-completely moved away from the hook infrastructure and have replaced it with
-custom Session objects. These objects offer some nice benefits such as
-keep-alive.
+First and foremost Requests v1.x largely does away with hooks (and removes the
+specific hook rauth was previously relying on). As such we have completely
+moved away from the hook infrastructure and have replaced it with custom
+Session objects. These objects offer some nice benefits such as keep-alive.
Service wrappers have been restructured to produce instances of their
respective Session objects. This is done via the :meth:`Session.get_session`
-method. Much of this happens behind the scenes, in a way that's opaque to the
-API consumer. That is, making a call over the request method will automatically
-generate or retrieve an appropriately initialized `Session` instance.
+and :meth:`Session.get_auth_session` methods. In particular, `get_auth_session`
+should be used where possible to retrieve an access token over a `Session`
+instance. This method returns a session object which is used to make requests.
+This is in contrast to previous versions of rauth which provided a `request`
+method on the `Service` wrappers. This method is now gone and all HTTP methods
+are provided by the `Session` objects instead.
OAuth2Service no longer accepts `consumer_id` and `consumer_secret` in place of
`client_id` and `client_secret`. You must update your code if you were using
@@ -48,22 +50,14 @@ Specifically there are cases where some parameters are required but others
where these parameters become optional: we can't resonably handle every case in
the library. Instead the consumer should try to manage this themselves by
passing in the required parameters explicitly. This is mostly only applicable
-to OAuth2. That said some may be added back in where appropriate. While
-porting code, be aware that you must be explicit about these parameters.
-
-Access tokens are always passed in as named arguments now. Whereas previously
-this was inconsistent between wrappers and methods. (Note: Ofly does not use
-access tokens, but does use an oflyUserid parameter in its place.) If you do
-not provide an access token for OAuth1 and OAuth2, the wrapper will attempt to
-use the value bound to :attr:`Session.access_token`. Passing in a `None`-type
-token is valid, to allow for request and access token calls on OAuth1 and
-OAuth2, respectively.
-
-Ofly now requires a `user_id` parameter when invoking the `request` method.
-This is because there are no valid calls made over the Ofly protocol that
-exclude this parameter. (There is no request token and no access token and the
-initial authorize URL is built client-side.)
+to OAuth2. That said some of these may be added back in where appropriate.
+While porting code, be aware that you must be explicit about these parameters.
Additionally there are changes to Requests itself which are mostly beyond the
scope of this document. However it is worth noting you can parse a JSON
response via `r.json()`. The examples have been updated to demonstrate this.
+
+It may be instructive to reference the examples when updating your applications
+for use with rauth 0.5.0. There are examples for OAuth 1.0/a and OAuth 2.0
+which should be fully functional and which you can run yourself and experiment
+with.

0 comments on commit c590a52

Please sign in to comment.