Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 342 lines (241 sloc) 10.909 kb
fdbae01 last minute 0.4 stuff
mverdone authored
1 Python Twitter Tools
a65893e Mike Verdone Documentation improved
authored
2 ====================
fdbae01 last minute 0.4 stuff
mverdone authored
3
bcd1bc9 Hugo Coverage badge points to sixohsix [CI skip]
hugovk authored
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)
9ae71d4 Hugo Add Travis CI build badge [CI skip]
hugovk authored
5
f1a8ed6 Heading for 0.4.1. Use stdlib json module if available, remove a 2.6 dep...
mverdone authored
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
8 on the go.
fdbae01 last minute 0.4 stuff
mverdone authored
9
f1a8ed6 Heading for 0.4.1. Use stdlib json module if available, remove a 2.6 dep...
mverdone authored
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
5b8b1ea 0.4.3 - fix for broken POST requests
mverdone authored
12 favorite shell and an IRC bot that can announce Twitter updates to an
f1a8ed6 Heading for 0.4.1. Use stdlib json module if available, remove a 2.6 dep...
mverdone authored
13 IRC channel.
fdbae01 last minute 0.4 stuff
mverdone authored
14
5f47b30 Mike Verdone Documentation.
authored
15 For more information, after installing the `twitter` package:
fdbae01 last minute 0.4 stuff
mverdone authored
16
17 * import the `twitter` package and run help() on it
18 * run `twitter -h` for command-line tool help
a65893e Mike Verdone Documentation improved
authored
19
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
20
21 twitter - The Command-Line Tool
22 -------------------------------
a65893e Mike Verdone Documentation improved
authored
23
30913a4 Mike Verdone Still tweaking the README.
authored
24 The command-line tool lets you do some awesome things:
a65893e Mike Verdone Documentation improved
authored
25
30913a4 Mike Verdone Still tweaking the README.
authored
26 * view your tweets, recent replies, and tweets in lists
a65893e Mike Verdone Documentation improved
authored
27 * view the public timeline
28 * follow and unfollow (leave) friends
29 * various output formats for tweet information
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
30
a65893e Mike Verdone Documentation improved
authored
31 The bottom line: type `twitter`, receive tweets.
32
33
34
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
35 twitterbot - The IRC Bot
36 ------------------------
a65893e Mike Verdone Documentation improved
authored
37
38 The IRC bot is associated with a twitter account (either your own account or an
39 account you create for the bot). The bot announces all tweets from friends
40 it is following. It can be made to follow or leave friends through IRC /msg
41 commands.
42
5f47b30 Mike Verdone Documentation.
authored
43
44 twitter-log
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
45 -----------
5f47b30 Mike Verdone Documentation.
authored
46
47 `twitter-log` is a simple command-line tool that dumps all public
48 tweets from a given user in a simple text format. It is useful to get
49 a complete offsite backup of all your tweets. Run `twitter-log` and
50 read the instructions.
51
30913a4 Mike Verdone Still tweaking the README.
authored
52 twitter-archiver and twitter-follow
53 -----------------------------------
54
55 twitter-archiver will log all the tweets posted by any user since they
56 started posting. twitter-follow will print a list of all of all the
57 followers of a user (or all the users that user follows).
58
5f47b30 Mike Verdone Documentation.
authored
59
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
60 Programming with the Twitter api classes
61 ========================================
62
63 The Twitter and TwitterStream classes are the key to building your own
64 Twitter-enabled applications.
65
66
67 The Twitter class
68 -----------------
69
70 The minimalist yet fully featured Twitter API class.
71
72 Get RESTful data by accessing members of this class. The result
73 is decoded python objects (lists and dicts).
74
75 The Twitter API is documented at:
76
76bb736 Hugo Fix reference to Twitter API doc URL
hugovk authored
77 **[https://dev.twitter.com/overview/documentation](https://dev.twitter.com/overview/documentation)**
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
78
d4f3123 Mike Verdone Clean up documentation and README
authored
79 Examples:
bcbd4e2 Justin Clift Trivial typo fixes
justinclift authored
80 ```python
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
81 from twitter import *
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
82
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
83 t = Twitter(
bdad9dd tpltnt tiny syntax fix
tpltnt authored
84 auth=OAuth(token, token_key, con_secret, con_secret_key))
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
85
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
86 # Get your "home" timeline
87 t.statuses.home_timeline()
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
88
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
89 # Get a particular friend's timeline
aaf199d Justin Clift Update README with friends_timeline() replacement
justinclift authored
90 t.statuses.user_timeline(screen_name="billybob")
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
91
ae2bf88 Hatem Nassrat Adding _id and _method docs to README
pykler authored
92 # to pass in GET/POST parameters, such as `count`
93 t.statuses.home_timeline(count=5)
94
95 # to pass in the GET/POST parameter `id` you need to use `_id`
96 t.statuses.oembed(_id=1234567890)
97
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
98 # Update your status
99 t.statuses.update(
100 status="Using @sixohsix's sweet Python Twitter Tools.")
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
101
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
102 # Send a direct message
103 t.direct_messages.new(
104 user="billybob",
105 text="I think yer swell!")
d09c0dd Mike Verdone Updated the examples in the documentation.
authored
106
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
107 # Get the members of tamtar's list "Things That Are Rad"
fec0468 Hugo Update docs to reflect current Twitter API
hugovk authored
108 t.lists.members(owner_screen_name="tamtar", slug="things-that-are-rad")
a5aab11 Irfan Ahmad Fixes #99. Introduced an optional timeout parameter for each API call
erfaan authored
109
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
110 # An *optional* `_timeout` parameter can also be used for API
d4f3123 Mike Verdone Clean up documentation and README
authored
111 # calls which take much more time than normal or twitter stops
112 # responding for some reason:
113 t.users.lookup(
114 screen_name=','.join(A_LIST_OF_100_SCREEN_NAMES), _timeout=1)
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
115
ae2bf88 Hatem Nassrat Adding _id and _method docs to README
pykler authored
116 # Overriding Method: GET/POST
117 # you should not need to use this method as this library properly
118 # detects whether GET or POST should be used, Nevertheless
119 # to force a particular method, use `_method`
120 t.statuses.oembed(_id=1234567890, _method='GET')
5a412b3 Benjamin Ooghe-Tabanou add doc to send tweets with images in README + consolidate api.py/README
RouxRC authored
121
122 # Send a tweet with an image included (or set your banner or logo similarily)
d4f3123 Mike Verdone Clean up documentation and README
authored
123 # by just reading your image from the web or a file in a string:
5702c7b Benjamin Ooghe-Tabanou handle non unicode text status for twitpic with py2.x for coherence mean...
RouxRC authored
124 status = "PTT ★"
5a412b3 Benjamin Ooghe-Tabanou add doc to send tweets with images in README + consolidate api.py/README
RouxRC authored
125 with open("example.png", "rb") as imagefile:
880418b Benjamin Ooghe-Tabanou update img sending doc
RouxRC authored
126 params = {"media[]": imagefile.read(), "status": status}
5a412b3 Benjamin Ooghe-Tabanou add doc to send tweets with images in README + consolidate api.py/README
RouxRC authored
127 t.statuses.update_with_media(**params)
d4f3123 Mike Verdone Clean up documentation and README
authored
128
129 # Or by sending a base64 encoded image:
880418b Benjamin Ooghe-Tabanou update img sending doc
RouxRC authored
130 params = {"media[]": base64_image, "status": status, "_base64": True}
5a412b3 Benjamin Ooghe-Tabanou add doc to send tweets with images in README + consolidate api.py/README
RouxRC authored
131 t.statuses.update_with_media(**params)
ae2bf88 Hatem Nassrat Adding _id and _method docs to README
pykler authored
132 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
133
d4f3123 Mike Verdone Clean up documentation and README
authored
134 Searching Twitter:
135 ```python
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
136 # Search for the latest tweets about #pycon
137 t.search.tweets(q="#pycon")
138 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
139
16c4e7d Beat Bolli Add documentation for retry=True
bbolli authored
140
141 Retrying after reaching the API rate limit
142 ------------------------------------------
143
144 Simply create the `Twitter` instance with the argument `retry=True`, then the
145 HTTP error codes 429, 502, 503 and 504 will cause a retry of the last request.
73a242d Beat Bolli Allow to set the number of retries
bbolli authored
146 If retry is an integer, it defines the number of retries attempted.
16c4e7d Beat Bolli Add documentation for retry=True
bbolli authored
147
148
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
149 Using the data returned
150 -----------------------
151
152 Twitter API calls return decoded JSON. This is converted into
d4f3123 Mike Verdone Clean up documentation and README
authored
153 a bunch of Python lists, dicts, ints, and strings. For example:
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
154
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
155 ```python
156 x = twitter.statuses.home_timeline()
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
157
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
158 # The first 'tweet' in the timeline
159 x[0]
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
160
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
161 # The screen name of the user who wrote the first 'tweet'
162 x[0]['user']['screen_name']
163 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
164
165 Getting raw XML data
166 --------------------
167
168 If you prefer to get your Twitter data in XML format, pass
d4f3123 Mike Verdone Clean up documentation and README
authored
169 format="xml" to the Twitter object when you instantiate it:
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
170
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
171 ```python
172 twitter = Twitter(format="xml")
173 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
174
175 The output will not be parsed in any way. It will be a raw string
176 of XML.
177
178
179 The TwitterStream class
180 -----------------------
181
d4f3123 Mike Verdone Clean up documentation and README
authored
182 The TwitterStream object is an interface to the Twitter Stream
183 API. This can be used pretty much the same as the Twitter class
184 except the result of calling a method will be an iterator that
185 yields objects decoded from the stream. For example::
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
186
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
187 ```python
d4f3123 Mike Verdone Clean up documentation and README
authored
188 twitter_stream = TwitterStream(auth=OAuth(...))
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
189 iterator = twitter_stream.statuses.sample()
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
190
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
191 for tweet in iterator:
d4f3123 Mike Verdone Clean up documentation and README
authored
192 ...do something with this tweet...
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
193 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
194
84e6e1e lumbric add some documentation for streams
lumbric authored
195 Per default the ``TwitterStream`` object uses
196 [public streams](https://dev.twitter.com/docs/streaming-apis/streams/public).
197 If you want to use one of the other
198 [streaming APIs](https://dev.twitter.com/docs/streaming-apis), specify the URL
199 manually:
200
201 - [Public streams](https://dev.twitter.com/docs/streaming-apis/streams/public): stream.twitter.com
202 - [User streams](https://dev.twitter.com/docs/streaming-apis/streams/user): userstream.twitter.com
203 - [Site streams](https://dev.twitter.com/docs/streaming-apis/streams/site): sitestream.twitter.com
204
205 Note that you require the proper
206 [permissions](https://dev.twitter.com/docs/application-permission-model) to
207 access these streams. E.g. for direct messages your
208 [application](https://dev.twitter.com/apps) needs the "Read, Write & Direct
209 Messages" permission.
210
9ae71d4 Hugo Add Travis CI build badge [CI skip]
hugovk authored
211 The following example demonstrates how to retrieve all new direct messages
84e6e1e lumbric add some documentation for streams
lumbric authored
212 from the user stream:
213
214 ```python
215 auth = OAuth(
216 consumer_key='[your consumer key]',
217 consumer_secret='[your consumer secret]',
218 token='[your token]',
219 token_secret='[your token secret]'
220 )
221 twitter_userstream = TwitterStream(auth=auth, domain='userstream.twitter.com')
222 for msg in twitter_userstream.user():
223 if 'direct_message' in msg:
224 print msg['direct_message']['text']
225 ```
226
d4f3123 Mike Verdone Clean up documentation and README
authored
227 The iterator will yield until the TCP connection breaks. When the
228 connection breaks, the iterator yields `{'hangup': True}`, and
229 raises `StopIteration` if iterated again.
230
231 Similarly, if the stream does not produce heartbeats for more than
232 90 seconds, the iterator yields `{'hangup': True,
233 'heartbeat_timeout': True}`, and raises `StopIteration` if
234 iterated again.
235
236 The `timeout` parameter controls the maximum time between
237 yields. If it is nonzero, then the iterator will yield either
238 stream data or `{'timeout': True}` within the timeout period. This
239 is useful if you want your program to do other stuff in between
240 waiting for tweets.
241
242 The `block` parameter sets the stream to be fully non-blocking. In
243 this mode, the iterator always yields immediately. It returns
244 stream data, or `None`. Note that `timeout` supercedes this
925431e Orakaro Update README
DTVD authored
245 argument, so it should also be set `None` to use this mode,
246 and non-blocking can potentially lead to 100% CPU usage.
d4f3123 Mike Verdone Clean up documentation and README
authored
247
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
248 Twitter Response Objects
249 ------------------------
250
d4f3123 Mike Verdone Clean up documentation and README
authored
251 Response from a twitter request. Behaves like a list or a string
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
252 (depending on requested format) but it has a few other interesting
253 attributes.
254
255 `headers` gives you access to the response headers as an
256 httplib.HTTPHeaders instance. You can do
d4f3123 Mike Verdone Clean up documentation and README
authored
257 `response.headers.get('h')` to retrieve a header.
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
258
259 Authentication
260 --------------
261
262 You can authenticate with Twitter in three ways: NoAuth, OAuth, or
d4f3123 Mike Verdone Clean up documentation and README
authored
263 OAuth2 (app-only). Get help() on these classes to learn how to use them.
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
264
d4f3123 Mike Verdone Clean up documentation and README
authored
265 OAuth and OAuth2 are probably the most useful.
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
266
267
268 Working with OAuth
269 ------------------
270
271 Visit the Twitter developer page and create a new application:
272
5d5d68c Mickael GOETZ GitHub doesn't handle empty links
MrMitch authored
273 **[https://dev.twitter.com/apps/new](https://dev.twitter.com/apps/new)**
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
274
275 This will get you a CONSUMER_KEY and CONSUMER_SECRET.
276
277 When users run your application they have to authenticate your app
d4f3123 Mike Verdone Clean up documentation and README
authored
278 with their Twitter account. A few HTTP calls to twitter are required
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
279 to do this. Please see the twitter.oauth_dance module to see how this
280 is done. If you are making a command-line app, you can use the
281 oauth_dance() function directly.
282
d4f3123 Mike Verdone Clean up documentation and README
authored
283 Performing the "oauth dance" gets you an ouath token and oauth secret
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
284 that authenticate the user with Twitter. You should save these for
285 later so that the user doesn't have to do the oauth dance again.
286
287 read_token_file and write_token_file are utility methods to read and
288 write OAuth token and secret key values. The values are stored as
289 strings in the file. Not terribly exciting.
290
291 Finally, you can use the OAuth authenticator to connect to Twitter. In
d4f3123 Mike Verdone Clean up documentation and README
authored
292 code it all goes like this:
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
293
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
294 ```python
295 from twitter import *
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
296
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
297 MY_TWITTER_CREDS = os.path.expanduser('~/.my_app_credentials')
298 if not os.path.exists(MY_TWITTER_CREDS):
299 oauth_dance("My App Name", CONSUMER_KEY, CONSUMER_SECRET,
300 MY_TWITTER_CREDS)
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
301
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
302 oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS)
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
303
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
304 twitter = Twitter(auth=OAuth(
d4f3123 Mike Verdone Clean up documentation and README
authored
305 oauth_token, oauth_token_secret, CONSUMER_KEY, CONSUMER_SECRET))
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
306
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
307 # Now work with Twitter
04e76c4 Chris Seymour Used named argument to avoid TypeError: __call__() takes exactly 1 argum...
iiSeymour authored
308 twitter.statuses.update(status='Hello, world!')
814d84f Mickael GOETZ Make code blocks use syntax highlighting in README
MrMitch authored
309 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
310
d4f3123 Mike Verdone Clean up documentation and README
authored
311 Working with OAuth2
312 -------------------
313
314 Twitter only supports the application-only flow of OAuth2 for certain
315 API endpoints. This OAuth2 authenticator only supports the application-only
316 flow right now.
317
318 To authenticate with OAuth2, visit the Twitter developer page and create a new
319 application:
320
321 **[https://dev.twitter.com/apps/new](https://dev.twitter.com/apps/new)**
322
323 This will get you a CONSUMER_KEY and CONSUMER_SECRET.
324
325 Exchange your CONSUMER_KEY and CONSUMER_SECRET for a bearer token using the
326 oauth2_dance function.
327
328 Finally, you can use the OAuth2 authenticator and your bearer token to connect
329 to Twitter. In code it goes like this::
330
331 ```python
332 twitter = Twitter(auth=OAuth2(bearer_token=BEARER_TOKEN))
333
334 # Now work with Twitter
335 twitter.search.tweets(q='keyword')
336 ```
51e0b8f Mike Verdone Dump the full documentation into the README and markdownify it.
authored
337
338 License
339 =======
340
8be9a74 README updates
mverdone authored
341 Python Twitter Tools are released under an MIT License.
Something went wrong with that request. Please try again.