Skip to main content

A python wrapper around the Twitter API

Project description

=Python Twitter=

_A Python wrapper around the Twitter API_

Author: `The Python-Twitter Developers <>`


This library provides a pure Python interface for the Twitter API.

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.


*From source:*

Install the dependencies:


SimpleGeo's OAuth2 or

HTTPLib2 (installed along with oauth2 if you use setuptools)

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==

View the trunk at:

Check out the latest development version anonymously with:

$ hg clone python-twitter
$ cd python-twitter
$ hg update dev


View the last release API documentation at:


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

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.

To create an instance of the twitter.Api class:

>>> import twitter
>>> api = twitter.Api()

To create an instance of the twitter.Api with login credentials (many API
calls required the client to be authenticated.)

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.

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

To see if your credentials are successful:
NOTE - much more than the small sample given here will print

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

To fetch the most recently posted public Twitter status messages:

>>> statuses = api.GetPublicTimeline()
>>> print [ for s in statuses]
[u'DeWitt', u'Kesuke Miyagi', u'ev', u'Buzz Andersen', u'Biz Stone']

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


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 for more discussion.


Additional thanks to Pierre-Jean Coudert, Omar Kilani, Jodok Batlogg,
edleaf, glen.tregoning, Brad Choate, Jim Cortez, Jason Lemoine, Thomas
Dyson, Robert Laquey, Hameedullah Khan, Mike Taylor, DeWitt Clinton,
and the rest of the python-twitter mailing list.


Copyright 2007 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.


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-twitter-0.8.2.tar.gz (63.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page