This article is part of in the series
Last Updated: Wednesday 14th August 2013

Python is great language for all sorts of things. Very active developer community creates many libraries which extend the language and make it easier to use various services. One of those libraries is tweepy. Tweepy is open-sourced, hosted on GitHub and enables Python to communicate with Twitter platform and use its API. For an introduction on the library Twython - check out this article.

At the time of writing, the current version of tweepy is 1.13. It was released on January 17, and offers various bug fixes and new functionality compared to the previous version. The 2.x version is being developed but it is currently unstable so a huge majority of the users should use the regular version.

Installing tweepy is easy, it can be cloned from the Github repository:

Or using easy install:

Either way provides you with the latest version.

Using tweepy

Tweepy supports accessing Twitter via Basic Authentication and the newer method, OAuth. Twitter has stopped accepting Basic Authentication so OAuth is now the only way to use the Twitter API.

Here is a sample of how to access the Twitter API using tweepy with OAuth:

The result of this code is the following:
Tweepy Hello World Status

The main difference between Basic and OAuth authentication are the consumer and access keys. With Basic Authentication, it was possible to provide a username and password and access the API, but since 2010 when the Twitter started requiring OAuth, the process is a bit more complicated. An app has to be created at dev.twitter.com.

OAuth is a bit more complicated initially than Basic Auth, since it requires more effort, but the benefits it offers are very lucrative:

  • Tweets can be customized to have a string which identifies the app which was used.
  • It doesn’t reveal user password, making it more secure.
  • It's easier to manage the permissions, for example a set of tokens and keys can be generated that only allows reading from the timelines, so in case someone obtains those credentials, he/she won’t be able to write or send direct messages, minimizing the risk.
  • The application doesn't reply on a password, so even if the user changes it, the application will still work.

After logging in to the portal, and going to "Applications", a new application can be created which will provide the needed data for communicating with Twitter API.

Twiter OAuth Dashboard

This is a screen which has all of the data needed to talk to Twitter network. It is important to note that by default, the app has no access to direct messages, so by going to the settings and changing the appropriate option to “Read, write and direct messages”, you can enable your app to have access to every Twitter feature.

Twitter API

Tweepy provides access to the well documented Twitter API. With tweepy, it's possible to get any object and use any method that the official Twitter API offers. For example, a User object has its documentation at https://dev.twitter.com/docs/platform-objects/users and following those guidelines, tweepy can get the appropriate information.

Main Model classes in the Twitter API are Tweets, Users, Entities and Places. Access to each returns a JSON-formatted response and traversing through information is very easy in Python.

Gives us the following output:

All of the API methods are documented here: http://packages.python.org/tweepy/html/api.html

Tweepy StreamingAPI

One of the main usage cases of tweepy is monitoring for tweets and doing actions when some event happens. Key component of that is the StreamListener object, which monitors tweets in real time and catches them.

StreamListener has several methods, with on_data() and on_status() being the most useful ones. Here is a sample program which implements this behavior:

So, this program has a StreamListener implemented and the code is set up to use OAuth. The Stream object is created, which uses that listener as output. Stream, being another important object in tweepy also has many methods, in this case filter() is used with parameters passed. "follow" is a list of followers whose tweets are monitored, and "track" is a list of hashtags which will trigger the StreamListener.

In this example, we have used my user ID to follow and the #pythoncentral hashtag as a condition. After running the program and tweeting this status:

Tweepy "Hello World" with hashtag

The program almost instantly catches the tweet, and calls the on_status() method, which produces the following output in the console:

Besides printing the tweet, in the on_status() method there are some additional things which illustrate the number of possibilities that can be done with the tweet data:

This code traverses through entities, picks the "hashtags" one and for each hashtag the tweet contains, it prints its value. This is just a sample; a complete list of tweet entities is located here: https://dev.twitter.com/docs/tweet-entities.


To sum up, tweepy is a great open-source library which provides access to the Twitter API for Python. Although the documentation for tweepy is a bit scarce and doesn't have many examples, the fact that it heavily relies on the Twitter API, which has excellent documentation, makes it probably the best Twitter library for Python, especially when considering the Streaming API support, which is where tweepy excels. Other libraries like python-twitter provide many functions too, but the tweepy has most active community and most commits to the code in the last year.

Additional resources used for tweepy can be obtained here:

About The Author