birdy 0.3.2

Features

• Future proof dynamic API with full REST and Streaming API coverage

• OAuth1 (user) and OAuth2 (app) authentication workflows

• Automatic JSON decoding, JSONObject

• ApiResponse, StreamResponse objects

• Informative exceptions

• Easily customizable through subclassing

• Built on top of the excellent requests and requests-ouathlib libraries

Installation

The easiest and recommended way to install birdy is from PyPI

pip install birdy

Usage

Import client and initialize it:

from birdy.twitter import UserClient
client = UserClient(CONSUMER_KEY,
                    CONSUMER_SECRET,
                    ACCESS_TOKEN,
                    ACCESS_TOKEN_SECRET)

GET example (GET users/show):

response = client.api.users.show.get(screen_name='twitter')
response.data

POST example (POST statuses/update):

response = client.api.statuses.update.post(status='Hello @pybirdy!')

Dynamic URL example (POST statuses/destroy/:id):

response = client.api.statuses.destroy['240854986559455234'].post()

Streaming API example (Public Stream POST statuses/filter):

response = client.stream.statuses.filter.post(track='twitter')

for data in response.stream():
    print data

Is Streaming API supported as well?

Sure, since version 0.2, birdy comes with full support for Streaming API out of the box. Access to the Streaming API is provided by a special StreamClient.

StreamClient can’t be used to obtain access tokens, but you can use UserClient to get them.

To work with the Streaming API, first import the client and initialize it.

from birdy.twitter import StreamClient
client = StreamClient(CONSUMER_KEY,
                    CONSUMER_SECRET,
                    ACCESS_TOKEN,
                    ACCESS_TOKEN_SECRET)

To access resources on the Public stream, like POST statuses/filter (Twitter docs)

resource = client.stream.statuses.filter.post(track='twitter')

For User stream resource GET user (Twitter docs)

resource = client.userstream.user.get()

And for Site stream resource GET site (Twitter docs)

resource = client.sitestream.site.get()

To access the data in the stream you iterate over resource.stream() like this

for data in resource.stream():
   print data

OAuth1 workflow for user authenticated requests (UserClient)

from birdy.twitter import UserClient

CONSUMER_KEY = 'YOUR_APPS_CONSUMER_KEY'
CONSUMER_SECRET = 'YOUR_APPS_CONSUMER_SECRET'
CALLBACK_URL = 'https://127.0.0.1:8000/callback'

client = UserClient(CONSUMER_KEY, CONSUMER_SECRET)

token = client.get_signin_token(CALLBACK_URL)

token = client.get_authorize_token(CALLBACK_URL)

ACCESS_TOKEN = token.oauth_token
ACCESS_TOKEN_SECRET = token.oauth_token_secret

#Django
OAUTH_VERIFIER = request.GET['oauth_verifier']

#Flash
OAUTH_VERIFIER = request.args.get('oauth_verifier')

client = UserClient(CONSUMER_KEY, CONSUMER_SECRET,
                    ACCESS_TOKEN, ACCESS_TOKEN_SECRET)

token = client.get_access_token(OAUTH_VERIFIER)

response = client.api.statuses.home_timeline.get()
response.data

OAuth2 workflow for app authenticated requests (AppClient)

from birdy.twitter import AppClient

CONSUMER_KEY = 'YOUR_APPS_CONSUMER_KEY'
CONSUMER_SECRET = 'YOUR_APPS_CONSUMER_SECRET'

client = AppClient(CONSUMER_KEY, CONSUMER_SECRET)

access_token = client.get_access_token()

client = AppClient(CONSUMER_KEY, CONSUMER_SECRET, SAVED_ACCESS_TOKEN)

Automatic JSON decoding

JSON data returned by the REST and Streaming API is automatically decoded to native Python objects, no extra coding necessary, start using the data right away.

JSONObject

When decoding JSON data, objects are, instead of a regular Python dictionary, converted to a JSONObject, which is dictionary subclass with attribute style access in addition to regular dictionary lookup style, for convenience. The following code produces the same result

followers_count = response.data['followers_count']

followers_count = response.data.followers_count

ApiResponse

Calls to REST API resources return a ApiResponse, which in addition to returned data, also gives you access to response headers (useful for checking rate limits) and resource URL.

response.data           # decoded JSON data
response.resource_url   # resource URL
response.headers        # dictionary containing response HTTP headers

StreamResponse

StreamResponse is returned when calling Streaming API resources and provides the stream() method which returns an iterator used to receive JSON decoded streaming data. Like ApiResponse it also gives you access to response headers and resource URL.

response.stream()       # a generator method used to iterate over the stream

for data in response.stream():
    print data

Informative exceptions

There are 4 types of exceptions in birdy all subclasses of base BirdyException (which is never directly raised).

• TwitterClientError raised for connection and access token retrieval errors

• TwitterApiError raised when Twitter returns an error

• TwitterAuthError raised when authentication fails, TwitterApiError subclass

• TwitterRateLimitError raised when rate limit for resource is reached, TwitterApiError subclass

TwitterApiError and TwitterClientError instances (exepct for access token retrieval errors) provide a informative error description which includes the resource URL and request method used (very handy when tracking errors in logs), also available is the following:

exception.request_method    # HTTP method used to make the request (GET or POST)
exception.resource_url      # URL of the API resource called
exception.status_code       # HTTP status code returned by Twitter
exception.error_code        # error code returned by Twitter
exception.headers           # dictionary containing response HTTP headers

Customize and extend through subclassing

birdy was built with subclassing in mind, if you wish to change the way it works, all you have to do is subclass one of the clients and override some methods and you are good to go.

Subclassing a client and then using the subclass instance in your codeis actually the recommended way of using birdy.

For example, if you don’t wish to use JSONObject you have to override get_json_object_hook() method.

from birdy.twitter import UserClient

class MyClient(UserClient):
    @staticmethod
    def get_json_object_hook(data):
        return data

client = MyClient(...)
response = client.api.users.show.get(screen_name='twitter')

Or maybe, if you want global error handling for common errors, just override handle_response() method.

class MyClient(UserClient):
    def handle_response(self, method, response):
        try:
            response = super(MyClient, self).handle_response(method, response)
        except TwitterApiError, e:
            ...
            # Your error handling code
            ...
        return response

Another use of subclassing is configuration of requests.Session instance (docs) used to make HTTP requests, to configure it, you override the configure_oauth_session() method.

class MyClient(UserClient):
    def configure_oauth_session(self, session):
        session = super(MyClient, self).configure_oauth_session(session)
        session.proxies = {'http': 'foo.bar:3128'}
    return session