4 [![Build Status](https://travis-ci.org/sixohsix/twitter.svg)](https://travis-ci.org/sixohsix/twitter) [![Coverage Status](https://coveralls.io/repos/sixohsix/twitter/badge.png?branch=master)](https://coveralls.io/r/sixohsix/twitter?branch=master)
6 The Minimalist Twitter API for Python is a Python API for Twitter,
7 everyone's favorite Web 2.0 Facebook-style status updater for people
10 Also included is a Twitter command-line tool for getting your friends'
11 tweets and setting your own tweet from the safety and security of your
12 favorite shell and an IRC bot that can announce Twitter updates to an
15 For more information, after installing the `twitter` package:
17 * import the `twitter` package and run `help()` on it
18 * run `twitter -h` for command-line tool help
20 twitter - The Command-Line Tool
21 -------------------------------
23 The command-line tool lets you do some awesome things:
25 * view your tweets, recent replies, and tweets in lists
26 * view the public timeline
27 * follow and unfollow (leave) friends
28 * various output formats for tweet information
30 The bottom line: type `twitter`, receive tweets.
32 twitterbot - The IRC Bot
33 ------------------------
35 The IRC bot is associated with a Twitter account (either your own account or an
36 account you create for the bot). The bot announces all tweets from friends
37 it is following. It can be made to follow or leave friends through IRC /msg
44 `twitter-log` is a simple command-line tool that dumps all public
45 tweets from a given user in a simple text format. It is useful to get
46 a complete offsite backup of all your tweets. Run `twitter-log` and
47 read the instructions.
49 `twitter-archiver` and `twitter-follow`
50 ---------------------------------------
52 twitter-archiver will log all the tweets posted by any user since they
53 started posting. twitter-follow will print a list of all of all the
54 followers of a user (or all the users that user follows).
57 Programming with the Twitter API classes
58 ========================================
60 The `Twitter` and `TwitterStream` classes are the key to building your own
61 Twitter-enabled applications.
67 The minimalist yet fully featured Twitter API class.
69 Get RESTful data by accessing members of this class. The result
70 is decoded python objects (lists and dicts).
72 The Twitter API is documented at:
74 **[https://dev.twitter.com/overview/documentation](https://dev.twitter.com/overview/documentation)**
82 auth=OAuth(token, token_key, con_secret, con_secret_key))
84 # Get your "home" timeline
85 t.statuses.home_timeline()
87 # Get a particular friend's timeline
88 t.statuses.user_timeline(screen_name="billybob")
90 # to pass in GET/POST parameters, such as `count`
91 t.statuses.home_timeline(count=5)
93 # to pass in the GET/POST parameter `id` you need to use `_id`
94 t.statuses.oembed(_id=1234567890)
98 status="Using @sixohsix's sweet Python Twitter Tools.")
100 # Send a direct message
101 t.direct_messages.new(
103 text="I think yer swell!")
105 # Get the members of tamtar's list "Things That Are Rad"
106 t.lists.members(owner_screen_name="tamtar", slug="things-that-are-rad")
108 # An *optional* `_timeout` parameter can also be used for API
109 # calls which take much more time than normal or twitter stops
110 # responding for some reason:
112 screen_name=','.join(A_LIST_OF_100_SCREEN_NAMES), _timeout=1)
114 # Overriding Method: GET/POST
115 # you should not need to use this method as this library properly
116 # detects whether GET or POST should be used, Nevertheless
117 # to force a particular method, use `_method`
118 t.statuses.oembed(_id=1234567890, _method='GET')
120 # Send images along with your tweets:
121 # - first just read images from the web or from files the regular way:
122 with open("example.png", "rb") as imagefile:
123 imagedata = imagefile.read()
124 # - then upload medias one by one on Twitter's dedicated server
125 # and collect each one's id:
126 t_up = Twitter(domain='upload.twitter.com',
127 auth=OAuth(token, token_key, con_secret, con_secret_key))
128 id_img1 = t_up.media.upload(media=imagedata)["media_id_string"]
129 id_img2 = t_up.media.upload(media=imagedata)["media_id_string"]
130 # - finally send your tweet with the list of media ids:
131 t.statuses.update(status="PTT ★", media_ids=",".join([id_img1, id_img2]))
133 # Or send a tweet with an image (or set a logo/banner similarily)
134 # using the old deprecated method that will probably disappear some day
135 params = {"media[]": imagedata, "status": "PTT ★"}
136 # Or for an image encoded as base64:
137 params = {"media[]": base64_image, "status": "PTT ★", "_base64": True}
138 t.statuses.update_with_media(**params)
143 # Search for the latest tweets about #pycon
144 t.search.tweets(q="#pycon")
148 Retrying after reaching the API rate limit
149 ------------------------------------------
151 Simply create the `Twitter` instance with the argument `retry=True`, then the
152 HTTP error codes `429`, `502`, `503`, and `504` will cause a retry of the last
155 If `retry` is an integer, it defines the maximum number of retry attempts.
158 Using the data returned
159 -----------------------
161 Twitter API calls return decoded JSON. This is converted into
162 a bunch of Python lists, dicts, ints, and strings. For example:
165 x = twitter.statuses.home_timeline()
167 # The first 'tweet' in the timeline
170 # The screen name of the user who wrote the first 'tweet'
171 x[0]['user']['screen_name']
177 If you prefer to get your Twitter data in XML format, pass
178 `format="xml"` to the `Twitter` object when you instantiate it:
181 twitter = Twitter(format="xml")
184 The output will not be parsed in any way. It will be a raw string
187 The `TwitterStream` class
188 -------------------------
190 The `TwitterStream` object is an interface to the Twitter Stream
191 API. This can be used pretty much the same as the `Twitter` class,
192 except the result of calling a method will be an iterator that
193 yields objects decoded from the stream. For example::
196 twitter_stream = TwitterStream(auth=OAuth(...))
197 iterator = twitter_stream.statuses.sample()
199 for tweet in iterator:
200 ...do something with this tweet...
203 Per default the `TwitterStream` object uses
204 [public streams](https://dev.twitter.com/docs/streaming-apis/streams/public).
205 If you want to use one of the other
206 [streaming APIs](https://dev.twitter.com/docs/streaming-apis), specify the URL
209 - [Public streams](https://dev.twitter.com/docs/streaming-apis/streams/public): stream.twitter.com
210 - [User streams](https://dev.twitter.com/docs/streaming-apis/streams/user): userstream.twitter.com
211 - [Site streams](https://dev.twitter.com/docs/streaming-apis/streams/site): sitestream.twitter.com
213 Note that you require the proper
214 [permissions](https://dev.twitter.com/docs/application-permission-model) to
215 access these streams. (E.g., for direct messages, your
216 [application](https://dev.twitter.com/apps) needs the "Read, Write & Direct
217 Messages" permission.)
219 The following example demonstrates how to retrieve all new direct messages
220 from the user stream:
224 consumer_key='[your consumer key]',
225 consumer_secret='[your consumer secret]',
226 token='[your token]',
227 token_secret='[your token secret]'
229 twitter_userstream = TwitterStream(auth=auth, domain='userstream.twitter.com')
230 for msg in twitter_userstream.user():
231 if 'direct_message' in msg:
232 print msg['direct_message']['text']
235 The iterator will `yield` until the TCP connection breaks. When the
236 connection breaks, the iterator yields `{'hangup': True}` (and
237 raises `StopIteration` if iterated again).
239 Similarly, if the stream does not produce heartbeats for more than
240 90 seconds, the iterator yields `{'hangup': True,
241 'heartbeat_timeout': True}` (and raises `StopIteration` if
244 The `timeout` parameter controls the maximum time between
245 yields. If it is nonzero, then the iterator will yield either
246 stream data or `{'timeout': True}` within the timeout period. This
247 is useful if you want your program to do other stuff in between
250 The `block` parameter sets the stream to be fully non-blocking.
251 In this mode, the iterator always yields immediately. It returns
252 stream data, or `None`.
254 Note that `timeout` supercedes this argument, so it should also be
255 set `None` to use this mode, and non-blocking can potentially lead
258 Twitter `Response` Objects
259 --------------------------
261 Response from a Twitter request. Behaves like a list or a string
262 (depending on requested format), but it has a few other interesting
265 `headers` gives you access to the response headers as an
266 `httplib.HTTPHeaders` instance. Use `response.headers.get('h')`
267 to retrieve a header.
272 You can authenticate with Twitter in three ways: NoAuth, OAuth, or
273 OAuth2 (app-only). Get `help()` on these classes to learn how to use them.
275 OAuth and OAuth2 are probably the most useful.
281 Visit the Twitter developer page and create a new application:
283 **[https://dev.twitter.com/apps/new](https://dev.twitter.com/apps/new)**
285 This will get you a `CONSUMER_KEY` and `CONSUMER_SECRET`.
287 When users run your application they have to authenticate your app
288 with their Twitter account. A few HTTP calls to Twitter are required
289 to do this. Please see the `twitter.oauth_dance` module to see how this
290 is done. If you are making a command-line app, you can use the
291 `oauth_dance()` function directly.
293 Performing the "oauth dance" gets you an oauth token and oauth secret
294 that authenticate the user with Twitter. You should save these for
295 later, so that the user doesn't have to do the oauth dance again.
297 `read_token_file` and `write_token_file` are utility methods to read and
298 write OAuth `token` and `secret` key values. The values are stored as
299 strings in the file. Not terribly exciting.
301 Finally, you can use the `OAuth` authenticator to connect to Twitter. In
302 code it all goes like this:
305 from twitter import *
307 MY_TWITTER_CREDS = os.path.expanduser('~/.my_app_credentials')
308 if not os.path.exists(MY_TWITTER_CREDS):
309 oauth_dance("My App Name", CONSUMER_KEY, CONSUMER_SECRET,
312 oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS)
314 twitter = Twitter(auth=OAuth(
315 oauth_token, oauth_token_secret, CONSUMER_KEY, CONSUMER_SECRET))
317 # Now work with Twitter
318 twitter.statuses.update(status='Hello, world!')
321 Working with `OAuth2`
322 ---------------------
324 Twitter only supports the application-only flow of OAuth2 for certain
325 API endpoints. This OAuth2 authenticator only supports the application-only
328 To authenticate with OAuth2, visit the Twitter developer page and create a new
331 **[https://dev.twitter.com/apps/new](https://dev.twitter.com/apps/new)**
333 This will get you a `CONSUMER_KEY` and `CONSUMER_SECRET`.
335 Exchange your `CONSUMER_KEY` and `CONSUMER_SECRET` for a bearer token using the
336 `oauth2_dance` function.
338 Finally, you can use the `OAuth2` authenticator and your bearer token to connect
339 to Twitter. In code it goes like this::
342 twitter = Twitter(auth=OAuth2(bearer_token=BEARER_TOKEN))
344 # Now work with Twitter
345 twitter.search.tweets(q='keyword')
351 Python Twitter Tools are released under an MIT License.