skip to navigation
skip to content

Not Logged In

python-twitter 1.3.1

A Python wrapper around the Twitter API

# Python Twitter

**A Python wrapper around the Twitter API.**

Author: The Python-Twitter Developers <>

## Introduction

This library provides a pure Python interface for the [Twitter API]( It works with Python versions from 2.5 to 2.7. Python 3 support is under development.

[Twitter]( provides a service that allows people to connect via the web, IM, and SMS. Twitter exposes a [web services API]( and this library is intended to make it even easier for Python programmers to use.

## Building

From source:

Install the dependencies:

- [Requests](
- [SimpleJson](
- [Requests OAuthlib](

Alternatively use `pip`:

    $ pip install -r requirements.txt

Download the latest `python-twitter` library from:

Extract the source distribution and run:

$ python build
$ python install


With setuptools installed:

$ python test

Without setuptools installed:

$ python

## Getting the code

The code is hosted at [Github](

Check out the latest development version anonymously with:

 $ git clone git://
 $ cd python-twitter

## Documentation

View the last release API documentation at: [](

## Using

The library provides a Python wrapper around the Twitter API and the Twitter data model.


The three model classes are `twitter.Status`, `twitter.User`, and `twitter.DirectMessage`. The API methods return instances of these classes.

To read the full API for `twitter.Status`, `twitter.User`, or `twitter.DirectMessage`, run:

$ pydoc twitter.Status
$ pydoc twitter.User
$ pydoc twitter.DirectMessage


The API is exposed via the `twitter.Api` class.

The python-twitter library now only supports oAuth authentication as the Twitter devs have indicated that OAuth is the only method that will be supported moving forward.

To create an instance of the `twitter.Api` with login credentials (Twitter now requires an oAuth Access Token for all API calls)

>>> import twitter
>>> api = twitter.Api(consumer_key='consumer_key',

To see if your credentials are successful:

>>> print api.VerifyCredentials()
{"id": 16133, "location": "Philadelphia", "name": "bear"}

**NOTE -** much more than the small sample given here will print

To fetch a single user's public status messages, where `user` is either
a Twitter *short name* or their user id.

>>> statuses = api.GetUserTimeline(user)
>>> print [s.text for s in statuses]

To fetch a list a user's friends (requires authentication):

>>> users = api.GetFriends()
>>> print [ for u in users]

To post a Twitter status message (requires authentication):

>>> status = api.PostUpdate('I love python-twitter!')
>>> print status.text
I love python-twitter!

There are many more API methods, to read the full API documentation:

$ pydoc twitter.Api

## Todo

Patches and bug reports are [welcome](, just please keep the style consistent with the original source.

Add more example scripts.

The twitter.Status and `twitter.User` classes are going to be hard to keep in sync with the API if the API changes. More of the code could probably be written with introspection.

Statement coverage of `twitter_test` is only about 80% of

The `twitter.Status` and `twitter.User` classes could perform more validation on the property setters.

## More Information

Please visit [the google group]( for more discussion.

## Contributors

Originally two libraries by DeWitt Clinton and Mike Taylor which was then merged into python-twitter.

Now it's a full-on open source project with many contributors over time:

* Jodok Batlogg,
* Kyle Bock,
* Brad Choate,
* Robert Clarke,
* Jim Cortez,
* Pierre-Jean Coudert,
* Aish Raj Dahal,
* Thomas Dyson,
* Jim Easterbrook
* Yoshinori Fukushima,
* Hameedullah Khan,
* Osama Khalid,
* Omar Kilani,
* Domen Kožar,
* Robert Laquey,
* Jason Lemoine,
* Pradeep Nayak,
* Ian Ozsvald,
* Nicolas Perriault,
* Glen Tregoning,
* Lars Weiler,
* Sebastian Wiesinger,
* Jake Robinson,
* abloch,
* cahlan,
* dpslwk,
* edleaf,
* ecesena,
* git-matrix,
* sbywater,
* thefinn93,
* themylogin,

and the rest of the python-twitter mailing list.

## License

Copyright 2007-2013 The Python-Twitter Developers

Licensed under the Apache License, Version 2.0 (the 'License');
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an 'AS IS' BASIS,
See the License for the specific language governing permissions and
limitations under the License.

  changed version to 1.3 and then to 1.3.1 because I forgot to include CHANGES
  fix Issue 143 - GetStatusOembed() url parameter was being stomped on
  fix debugHTTP in a brute force way but it works again
  Add id_str to Status class
  Added LookupFriendship() method for checking follow status
    pull request from lucas
  Fix bug of GetListMembers when specifying `owner_screen_name`
    pull request from shichao-an

  backfilling varioius lists endpoints
  added a basic user stream call

  changed to version 1.2
  fixed python 3 issue in (print statements)
  fixed error in CreateList(), changed count default for GetFollowers to 200 and added a GetFollowersPaged() method

need to backfill commit log entries!

  changed version to 1.1
  The following changes have been made since the 1.0.1 release

  Remove from ParseTweet the Python 2.7 only dict comprehension item
  Fix GetListTimeline condition to enable owner_screen_name based fetching
  Many fixes for readability and PEP8
  Cleaning up some of the package importing. Only importing the functions that are needed
  Also added first build of the sphinx documentation. Copied some info from the readme to the index page
  Added lines to to help the user troubleshoot install problems. #109
  Removed the OAuth2 lines from the readme
  Removed OAuth2 library requirements
  Added GetListMembers()

  changed version to 1.0.1
  added README bit about Python version requirement

  changed version to 1.0
  removed doc directory until we can update docs for v1.1 API
  added to package the testdata directory

  bumped version to 1.0rc1
  merged in api_v1.1 branch

  The library is now only for Twitter API v1.1

  bumped version to 0.8.7

  removed GetPublicTimeline from the docs so as to stop confusing
  new folks since it was the first example given ... d'oh!

  bumped version to 0.8.6

  update requirements.txt to remove distribute reference
  github commit 3b9214a879e5fbd03036a7d4ae86babc03784846

  Merge pull request #33 from iElectric/profile_image_url_https
  github commit 67cbb8390701c945a48094795474ca485f092049
  patch by iElectric on github

  Change User.NewFromJsonDict so that it will pull from either
  profile_image_url_https or profile_image_url to keep older code
  working properly if they have stored older json data

  bumped version to 0.8.5
  lots of changes have been happening on Github and i've been
  very remiss in documenting them here in the Changes file :(

  this version is the last v1.0 API release and it's being made
  to push to PyPI and other places

  all work now will be on getting the v1.1 API supported

  Api.UserLookUp() throws attribute error when corresponding screen_name is not found
  Merge pull request #5 from thefinn93/master crashes because the README file is now named

  Update .gitignore to add the PyCharm data directory

 Patch by
 Add exclude_replies parameter to GetUserTimeline
 Bug reported by michaelmior on github attempts Web auth

 Comment by qfuxiang to the above changeset
 The base url was wrong for the Followers API calls
 Add include_entities parameter to GetStatus()
 Patch by gaelenh
 Change PostUpdate() so that it takes the shortened link into
 account.  Small tweak to the patch provided to make the
 shortened-link length set by a API value instead of a constant.
 Patch by ceesjan.ytec
 AttributeError handles the fact that win* doesn't implement
 Patch by yaleman
 As described at,
 GET trends (corresponding to Api.GetTrendsCurrent) is now
 deprecated in favor of GET trends/:woeid. GET trends also now
 requires authentication, while trends/:woeid doesn't.
 Patch and excellent description by jessica.mckellar
 Currently, two Trends containing the same information
 (name, query, and timestamp) aren't considered equal because
 __eq__ isn't overridden, like it is for Status, User, and the
 other Twitter objects.
 Patch and excellent description by jessica.mckellar
 All variations on a theme - basically Twitter is returning
 something different for an error payload.  Changed code to
 check for both 'error' and 'errors'.

 A comment in this issue made me realize that the parameter sanity
 check for max_id was missing in GetMentions() - added

 First pass at working in some of the cursor support that has been
 in the Twitter API but we haven't made full use of - still working
 out the small issues.


 bumped version to 0.8.3
 released 0.8.2 to PyPI
 bumped version to 0.8.2

 Issue 193
 Missing retweet_count field on Status object
 Patch (with minor tweaks) by from alissonp

 Issue 181
 Add oauth2 to install_requires parameter list and also updated
 README to note that the oauth2 lib can be found in two locations

 Issue 182, Issue 137, Issue 93, Issue 190
 language value missing from User object
 Added 'lang' item and also some others that were needed:
   verified, notifications, contributors_enabled and listed_count
 patches by wreinerat, apetresc, jpwigan and ghills


 Issue 166
 Added a basic, but sadly needed, check when parsing the json
 returned by Twitter as Twitter has a habit of returning the
 failwhale HTML page for a json api call :(
 Patch (with minor tweaks) by adam.aviv

 Issue 187
 Applied patch by edward.hades to fix issue where MaximumHitFrequency
 returns 0 when requests are maxed out

 Issue 184
 Applied patch by jmstaley to put into the GetUserTimeline API
 parameter list the max_id value (it was being completely ignored)


 Added retweeted to Status class
 Fixed Status class to return Hashtags list in AsDict() call

 Issue 185
 Added retweeted_status to Status class - patch by edward.hades

 Issue 183
 Removed errant print statement - reported by ProgVal


 Setting version to 0.8.1

 Issue 179
 Added to give sdist some clues as to what
 files to include in the tarball


 Setting version to 0.8 for a bit as having a branch for this is
 really overkill, i'll just take DeWitt advice and tag it when
 the release is out the door

 Issue 175
 Added geo_enabled to User class - basic parts of patch provided
 by adam.aviv with other bits added by me to allow it to pass tests

 Issue 174
 Added parts of adam.aviv's patch - the bits that add new field items
 to the Status class.

 Issue 159
 Added patch form adam.aviv to make the term parameter for GetSearch()
 optional if geocode parameter is supplied


 Ran pydoc to generate docs


 Fixed bad date in previous CHANGES entry

 Fixed source of the python-oauth2 library we use: from brosner
 to simplegeo

 I made a pass thru the docstrings and updated many to be the
 text from the current Twitter API docs.  Also fixed numerous
 whitespace issues and did a s/[optional]/[Optional]/ change.

 Imported work by Colin Howe that he did to get the tests working.

 Issue 169
 Patch by yaemog which adds missing Trends support.

 Issue 168
 Only cache successful results as suggested by yaemog.

 Issue 111
 Added a new GetUserRetweets() call as suggested by yash888
 Patch given was adjusted to reflect the current code requirements.

 Issue 110
 Added a VerifyCredentials() sample call to the README example

 Issue 105
 Added support for the page parameter to GetFriendsTimeline()
 as requested by jauderho.
 I also updated GetFriendsTimeline() to follow the current
 Twitter API documentation

 Somewhere in the patch frenzy of today an extra GetStatus()
 def was introduced!?! Luckily it was caught by the tests.
 wooo tests! \m/

 Setting version to 0.8

 r0.8 branch created and trunk set to version 0.9-devel


 Issue 150
 Patch by blhobbes which removes a double quoting issue that
 was happening for GetSearch()
 Reported by huubhuubbarbatruuk

 Issue 160
 Patch by yaemog which adds support for include_rts and
 include_entities support to GetUserTimeline and GetPublicTimeline
 Small tweaks post-patch

 Applied docstring tweak suggested by dclinton in revision comment
 Thanks for the catch!

 Issue 164
 Patch by yaemog which adds GetRetweets support.
 Small tweaks and two typo fixes post-patch.

 Issue 165
 Patch by yaemog which adds GetStatus support.
 Small tweaks post-patch

 Issue 163
 Patch by yaemog which adds users/lookup support.
 Small tweaks to docstring only post-patch.

 Changed username/password parameter to Api class to be
 consumer_key/consumer_secret to better match the new
 oAuth only world that Twitter has demanded.

 Added debugHTTP to the parameter list to Api class to
 control if/when the urllib debug output is displayed.


 First pass at adding list support.
 Added a new List class and also added to the Api class
 new methods for working with lists:

   CreateList(self, user, name, mode=None, description=None)
   DestroyList(self, user, id)
   CreateSubscription(self, owner, list)
   DestroySubscription(self, owner, list)
   GetSubscriptions(self, user, cursor=-1)
   GetLists(self, user, cursor=-1)


 Fixed introduced bug in the Destroy* and Create* API calls
 where any of the routines were passing in an empty dict for
 POST data.  Before the oAuth change that was enough to tell
 _FetchUrl() to use POST instead of GET but now a non-empty
 dict is required.

 Issue 144
 GetFriends() where it was failing with a 'unicode object has
 no attribute get'. This was caused when Twitter changed how
 they return the JSON data. It used to be a straight list but
 now there are some elements *and* then the list.


 Applied the json/simplejson part of the patch found
 in Issue 64 (
 Patch provided by Thomas Bohmbach

 Applied patch provided by liris.pp in Issue 147
 Ensures that during a PostStatus we count the length using a unicode aware
 len() routine.  Tweaked patch slightly to take into account that the
 twitter.Api() instance may have been setup with None for input_encoding.


 Fixed error in the POST path for _FetchUrl() where by
 I show to the world that yes, I do make last minute
 changes and completely forget to test them :(
 Thanks to Peter Sanchez for finding and pointing to
 working code that showed the fix


 Added more help text (I hope it helps) to the README
 and also to

 Added doctext notes to twitter.Api() parameter list
 to explain more about oAuth.

 Added import exception handling for parse_qs() and
 parse_qsl() as it seems those funcitons moved between
 2.5 and 2.6 so the oAuth update broke the lib under
 python2.5.  Thanks to Rich for the bug find (sorry
 it had to be found the hard way!)

 from changeset 184:60315000989c by DeWitt
 Update the generated docs to match the trunk


 Fixed silly typo in _FetchUrl() when doing a POST
 Thanks to Peter Sanchez for the find and fix!

 Added some really basic text to the
 startup output that explains why, for now, you need to
 visit Twitter and get an Application key/secret to use
 this library


 Updated code to use python-oauth2 library for authentication.
 Twitter has set a deadline, 2010-08-16 as of this change, for
 the switch from Basic to oAuth.

 The oAuth integration was inspired by the work done by
 Hameedullah Khan and others.

 The change to using python-oauth2 library was done purely to
 align python-twitter with an oauth library that was maintained
 and had tests to try and minimize grief moving forward.

 Slipped into GetFriendsTimeline() a new parameter, retweets, to
 allow the call to pull from the "friends_timeline" or the

 Fixed some typos and white-space issues and also updated the
 README to point to the new Twitter Dev site.


 Updated copyright information.


 Applied changeset from nicdumz repo nicdumz-cleaner-python-twitter
   datetime is required for MaximumHitFrequency

 Applied changeset from nicdumz repo nicdumz-cleaner-python-twitter
   update source URLs in README

 Applied changeset from nicdumz repo nicdumz-cleaner-python-twitter
   adjust tests to reflect -> change

 Applied changeset from nicdumz repo nicdumz-cleaner-python-twitter
   tests: add .info() method to objects returned by our Mockup handler
   This is required to completely mimick urllib, and have successful
   response.headers attribute accesses.

 Applied partial patch for Issue 113

   The partial bit means we changed the parameter from "page" to "cursor"
   so the call would work.  What was left out was a more direct way
   to return the cursor value *after* the call and also in the patch
   they also changed the method to return an iterator.


 Issue 50
 Applied patch by that implements a new method to return
 the Rate Limit Status and also adds the new method MaximumHitFrequency

 Multiple typo, indent and whitespace tweaks

 Issue 60
 Pulled out new GetFavorites and GetMentions methods from the patch
 submitted by joegermuska

 Issue 62
 Applied patch from lukev123 that adds gzip compression to the GET
 requests sent to Twitter. The patch was modified to default gzip to
 False and to allow the twitter.API class instantiation to set the
 value to True.  This was done to not change current default
 behaviour radically.

 Issue 80
 Fixed PostUpdate() call example in the README


 Issue 19
 TinyURL example and the idea for this comes from a bug filed by
 acolorado with patch provided by ghills.

 Issue 37
 Added base_url to the twitter.API class init call to allow the user
 to override the default base.  Since Twitter now
 supports https for all calls I (bear) changed the patch to default to
 https instead of http.
 Original issue by kotecha.ravi, patch by wiennat and with implementation
 tweaks by bear.

 Issue 45
 Two grammar fixes for relative_created_at property
 Patches by thomasdyson and chris.boardman07


 Applying patch submitted to fix Issue 70

 The patch was originally submitted by user ghills, adapted by livibetter and
 adapted even further by JimMoefoe (read the comments for the full details :) )

 Applying patch submitted by markus.magnuson to add new method GetFriendIDs
 Issue 94


 Releasing 0.6 to help people avoid the Twitpocalypse.


 Support hashlib in addition to the older md5 library.


 Added page parameter to GetReplies, GetFriends, GetFollowers, and GetDirectMessages


  Added count parameter to GetFriendsTimeline

  Add PostUpdates, which automatically splits long text into multiple updates.


  Add in_reply_to_status_id to api.PostUpdate


  Wrap any error responses in a TwitterError
  Add since_id to GetFriendsTimeline and GetUserTimeline


  Added since and since_id to Api.GetReplies


  Added new properties to User and Status classes.
  Removed spurious self-import of the twitter module
  Added a NOTICE file
  Require simplejson 2.x or later
  Added get/create/destroy favorite flags for status messages.
  Bug fix for non-tty devices.


  Unset the executable bit on README.


  Released version 0.5.
  Added back support for setuptools (conditionally)
  Added support for X-Twitter-* HTTP headers
  Fixed the tests to work across all timezones
  Removed the 140 character limit from PostUpdate
  Added support for per-user tmp cache directories


  Released 0.4.
  Fixed a unicode error that prevented from working.
  Added DestroyStatus
  Added DestroyDirectMessage
  Added CreateFriendship
  Added DestoryFriendship


  Fixed the bug that prevented unicode strings being posted
  Username and password now set on twitter.Api, not individual method calls
  Added SetCredentials and ClearCredentials
  Added GetUser ("users/show" in the twitter web api)
  Added GetFeatured
  Added GetDirectMessages
  Added GetStatus ("statuses/show" in the twitter web api)
  Added GetReplies
  Added optional since_id parameter on GetPublicTimeline
  Added optional since parameter on GetUserTimeline
  Added optional since and user parameters on GetFriendsTimeline
  Added optional user parameter on GetFriends


  Modified examples/ to handle unicode
  Dropped dependency on setuptools (too complicated/buggy)
  Added unicode test cases
  Fixed issue 2 "Rename needs an unlink in front"


  Released 0.3.
  Use gmtime not localtime to calculate relative_created_at.


  Released 0.2
  GetUserTimeline can accept userid or username.


  Calculate relative_created_at on the fly


  Released 0.1
  Initial checkin of python-twitter
File Type Py Version Uploaded on Size
python-twitter-1.3.1.tar.gz (md5) Source 2014-02-18 92KB
  • Downloads (All Versions):
  • 158 downloads in the last day
  • 2326 downloads in the last week
  • 8804 downloads in the last month