Repository files navigation

birdy is a super awesome Twitter API client for Python in just a little under 400 LOC.

• 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

The easiest and recommended way to installbirdy is fromPyPI

pipinstallbirdy

Import the client and initialize it:

frombirdy.twitterimportUserClientclient=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')fordatainresponse.stream():printdata

birdy works with bothpython2 (2.7+) andpython3 (3.4+).

The concept behindbirdy is so simple and awesome that it just had to be done. The result is a super light weight and easy to use API client, that covers the whole Twitter REST API in just a little under 400 lines of code.

To achieve this,birdy relies on established, battle-tested Python libraries likerequests andrequests-ouathlib to do the heavy lifting. But more importantly it relies on Python's dynamic nature to automatically construct API calls (no individual wrapper functions for API resources needed). This allowsbirdy to cover all existing Twitter API resources and any future additions, without the need to updatebirdy itself.

Includes full support for bothOAuth1 (user) andOAuth2 (application) authentication workflows.

Finally,birdy is simple and explicit by design. Besides error handling and JSON decoding it doesn't process the returned data in any way. That is left for you to handle. (Who'd know better what to do with it?!)

The easiest way to show you is by example. Let's say you want to query Twitter for @twitter user information. The Twitter API resource for this isGET users/show (Twitter docs).

First you will need to import a client. Here we import UserClient (OAuth1) and than initialize it.

frombirdy.twitterimportUserClientclient=UserClient(CONSUMER_KEY,CONSUMER_SECRET,ACCESS_TOKEN,ACCESS_TOKEN_SECRET)

To query theGET /users/show API resource and pass in the parameter screen_name='twitter' you do this.

resource=client.api.users.showresponse=resource.get(screen_name='twitter')

What happens here is very simple.birdy translates theusers.show part afterclient.api into the appropriate API resource path ('users/show'). Then when you call get() on the resource,birdy constructs a full resource URL, appends any parameters passed to get() to it and makes a GET request to that URL and returns the result.

Usually the above example would be shortened to just one line like this.

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

Making a post request is similar. If for example, you would like to post a status update, this is how to do it. The API resource isPOST statuses/update (Twitter docs).

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

Like before, the part afterclient.api gets converted to the correct path, only this time post() is called instead of get(), sobirdy makes a POST request and passes parameters (and files) as part of the request body.

For cases when dynamic values are part of the API resource URL, like when deleting a tweet atPOST statuses/destroy/:id (Twitter docs),birdy supports an alternative, dictionary lookup like syntax. For example, deleting a tweet with id '240854986559455234' looks like this.

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

By now it should be clear what happens above.birdy builds the API resource path and then makes a POST request. The only difference is that part of the API path is provided like a dictionary key lookup.

Actually, any call can be written in this alternative syntax. Use whichever you prefer. Both syntax forms can be freely combined as in the example above. Some more examples:

response=client.api['users/show'].get(screen_name='twitter')response=client.api['users']['show'].get(screen_name='twitter')response=client.api['statuses/destroy']['240854986559455234'].post()

Sure! Since version 0.2birdy comes with full support for Streaming API out of the box. Access to the Streaming API is provided by a specialStreamClient.

StreamClient can't be used to obtain access tokens, but you can useUserClient to get them.

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

frombirdy.twitterimportStreamClientclient=StreamClient(CONSUMER_KEY,CONSUMER_SECRET,ACCESS_TOKEN,ACCESS_TOKEN_SECRET)

To access resources on thePublic stream, likePOST statuses/filter (Twitter docs)

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

ForUser stream resourceGET user (Twitter docs)

resource=client.userstream.user.get()

And forSite stream resourceGET site (Twitter docs)

resource=client.sitestream.site.get()

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

fordatainresource.stream():printdata

birdy supports bothOAuth1 andOAuth2 authentication workflows by providing two different clients, aUserClient andAppClient respectively. While requests to API resources, like in above examples are the same in both clients, the workflow for obtaining access tokens is slightly different.

Before you get started, you will need toregister your application with Twitter, to obtain your application'sCONSUMER_KEY andCONSUMER_SECRET.

First you need to import theUserClient and create an instance with your appsCONSUMER_KEY andCONSUMER_SECRET.

frombirdy.twitterimportUserClientCONSUMER_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)

Passcallback_url only if you have a Web app. Desktop and Mobile appsdo not require it.

Next you need to fetch request token from Twitter. If you are building aSign-in with Twitter type application it's done like this.

token=client.get_signin_token(CALLBACK_URL)

Otherwise like this.

token=client.get_authorize_token(CALLBACK_URL)

Savetoken.oauth_token andtoken.oauth_token_secret for later use, as these are not the final token and secret.

ACCESS_TOKEN=token.oauth_tokenACCESS_TOKEN_SECRET=token.oauth_token_secret

Direct the user to the Twitter authorization URL obtained fromtoken.auth_url.

If you have a Desktop or Mobile app,OAUTH_VERIFIER is the PIN code. You can skip the part about extraction.

After authorizing your application on Twitter, the user will be redirected back to thecallback_url provided during client initialization inStep 1.

You will need to extract theOAUTH_VERIFIER from the URL. Most web frameworks provide an easy way of doing this or you can parse the URL yourself usingurlparse module (if that is your thing).

Django and Flask examples:

#DjangoOAUTH_VERIFIER=request.GET['oauth_verifier']#FlaskOAUTH_VERIFIER=request.args.get('oauth_verifier')

Once you have theOAUTH_VERIFIER you can use it to obtain the final access token and secret. To do that you will need to create a new instance ofUserClient, this time also passing inACCESS_TOKEN andACCESS_TOKEN_SECRET obtained inStep 2 and then fetch the tokens.

client=UserClient(CONSUMER_KEY,CONSUMER_SECRET,ACCESS_TOKEN,ACCESS_TOKEN_SECRET)token=client.get_access_token(OAUTH_VERIFIER)

Now that you have the final access token and secret, you can savetoken.oauth_token andtoken.oauth_token_secret to the database for later use. You can also use the client to start making API request immediately. For example, you can retrieve the user's home timeline like this.

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

That's it. You have successfully authorized the user, retrieved the tokens and can now make API calls on their behalf.

For OAuth2 you will be using theAppClient, so first you need to import it and create an instance with your appsCONSUMER_KEY andCONSUMER_SECRET.

frombirdy.twitterimportAppClientCONSUMER_KEY='YOUR_APPS_CONSUMER_KEY'CONSUMER_SECRET='YOUR_APPS_CONSUMER_SECRET'client=AppClient(CONSUMER_KEY,CONSUMER_SECRET)

OAuth2 workflow is much simpler compared to OAuth1. To obtain the access token you simply do this.

access_token=client.get_access_token()

That's it. You can start using the client immediately to make API request on behalf of the app. It's recommended you save theaccess_token for later use. You initialize the client with a saved token like this.

client=AppClient(CONSUMER_KEY,CONSUMER_SECRET,SAVED_ACCESS_TOKEN)

Keep in mind that OAuth2 authenticated requests areread-only and not all API resources are available. CheckTwitter docs for more information.

Of course,birdy comes with some handy features to ease your development right out of the box. Let's take a look at some of the goodies.

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.

When decoding JSON data,objects are, instead of a regular Python dictionary, converted to aJSONObject, 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

Calls to REST API resources return aApiResponse, 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 dataresponse.resource_url# resource URLresponse.headers# dictionary containing response HTTP headers

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

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

There are 4 types of exceptions inbirdy. They are all subclasses of the base classBirdyException (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 andTwitterClientError instances (except 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 calledexception.status_code# HTTP status code returned by Twitterexception.error_code# error code returned by Twitterexception.headers# dictionary containing response HTTP headers

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 code is actuallythe recommended way of usingbirdy.

For example, if you don't wish to useJSONObject you have to overrideget_json_object_hook() method.

frombirdy.twitterimportUserClientclassMyClient(UserClient):@staticmethoddefget_json_object_hook(data):returndataclient=MyClient(...)response=client.api.users.show.get(screen_name='twitter')

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

classMyClient(UserClient):defhandle_response(self,method,response):try:response=super(MyClient,self).handle_response(method,response)exceptTwitterApiError,e:            ...# Your error handling code            ...returnresponse

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

classMyClient(UserClient):defconfigure_oauth_session(self,session):session=super(MyClient,self).configure_oauth_session(session)session.proxies= {'http':'foo.bar:3128'}returnsession

Yes, both contributions (including feedback) and feature requests are welcome. The proper way in both cases is to first open an issue onGitHub and we will take it from there.

Keep in mind that I work on this project in my free time, so I might not be able to respond right away.

birdy would not exist if it weren't for the excellentrequests andrequests-oauthlib libraries and the wonderfulPython programming language.

If you need to contact me, you can find me on Twitter (@sect2k).