README

   1 Python Twitter Tools
   2 ====================
   3
   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)
   5
   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.
   9
  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
  13 IRC channel.
  14
  15 For more information, after installing the `twitter` package:
  16
  17  * import the `twitter` package and run help() on it
  18  * run `twitter -h` for command-line tool help
  19
  20
  21 twitter - The Command-Line Tool
  22 -------------------------------
  23
  24 The command-line tool lets you do some awesome things:
  25
  26  * view your tweets, recent replies, and tweets in lists
  27  * view the public timeline
  28  * follow and unfollow (leave) friends
  29  * various output formats for tweet information
  30
  31 The bottom line: type `twitter`, receive tweets.
  32
  33
  34
  35 twitterbot - The IRC Bot
  36 ------------------------
  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
  43
  44 twitter-log
  45 -----------
  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
  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
  59
  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
  77 **[https://dev.twitter.com/overview/documentation](https://dev.twitter.com/overview/documentation)**
  78
  79 Examples:
  80 ```python
  81 from twitter import *
  82
  83 t = Twitter(
  84     auth=OAuth(token, token_key, con_secret, con_secret_key))
  85
  86 # Get your "home" timeline
  87 t.statuses.home_timeline()
  88
  89 # Get a particular friend's timeline
  90 t.statuses.user_timeline(screen_name="billybob")
  91
  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
  98 # Update your status
  99 t.statuses.update(
 100     status="Using @sixohsix's sweet Python Twitter Tools.")
 101
 102 # Send a direct message
 103 t.direct_messages.new(
 104     user="billybob",
 105     text="I think yer swell!")
 106
 107 # Get the members of tamtar's list "Things That Are Rad"
 108 t.lists.members(owner_screen_name="tamtar", slug="things-that-are-rad")
 109
 110 # An *optional* `_timeout` parameter can also be used for API
 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)
 115
 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')
 121
 122 # Send a tweet with an image included (or set your banner or logo similarily)
 123 # by just reading your image from the web or a file in a string:
 124 status = "PTT ★"
 125 with open("example.png", "rb") as imagefile:
 126     params = {"media[]": imagefile.read(), "status": status}
 127 t.statuses.update_with_media(**params)
 128
 129 # Or by sending a base64 encoded image:
 130 params = {"media[]": base64_image, "status": status, "_base64": True}
 131 t.statuses.update_with_media(**params)
 132 ```
 133
 134 Searching Twitter:
 135 ```python
 136 # Search for the latest tweets about #pycon
 137 t.search.tweets(q="#pycon")
 138 ```
 139
 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.
 146 If retry is an integer, it defines the number of retries attempted.
 147
 148
 149 Using the data returned
 150 -----------------------
 151
 152 Twitter API calls return decoded JSON. This is converted into
 153 a bunch of Python lists, dicts, ints, and strings. For example:
 154
 155 ```python
 156 x = twitter.statuses.home_timeline()
 157
 158 # The first 'tweet' in the timeline
 159 x[0]
 160
 161 # The screen name of the user who wrote the first 'tweet'
 162 x[0]['user']['screen_name']
 163 ```
 164
 165 Getting raw XML data
 166 --------------------
 167
 168 If you prefer to get your Twitter data in XML format, pass
 169 format="xml" to the Twitter object when you instantiate it:
 170
 171 ```python
 172 twitter = Twitter(format="xml")
 173 ```
 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
 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::
 186
 187 ```python
 188 twitter_stream = TwitterStream(auth=OAuth(...))
 189 iterator = twitter_stream.statuses.sample()
 190
 191 for tweet in iterator:
 192     ...do something with this tweet...
 193 ```
 194
 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
 211 The following example demonstrates how to retrieve all new direct messages
 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
 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
 245 argument, so it should also be set `None` to use this mode,
 246 and non-blocking can potentially lead to 100% CPU usage.
 247
 248 Twitter Response Objects
 249 ------------------------
 250
 251 Response from a twitter request. Behaves like a list or a string
 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
 257 `response.headers.get('h')` to retrieve a header.
 258
 259 Authentication
 260 --------------
 261
 262 You can authenticate with Twitter in three ways: NoAuth, OAuth, or
 263 OAuth2 (app-only). Get help() on these classes to learn how to use them.
 264
 265 OAuth and OAuth2 are probably the most useful.
 266
 267
 268 Working with OAuth
 269 ------------------
 270
 271 Visit the Twitter developer page and create a new application:
 272
 273 **[https://dev.twitter.com/apps/new](https://dev.twitter.com/apps/new)**
 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
 278 with their Twitter account. A few HTTP calls to twitter are required
 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
 283 Performing the "oauth dance" gets you an ouath token and oauth secret
 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
 292 code it all goes like this:
 293
 294 ```python
 295 from twitter import *
 296
 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)
 301
 302 oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS)
 303
 304 twitter = Twitter(auth=OAuth(
 305     oauth_token, oauth_token_secret, CONSUMER_KEY, CONSUMER_SECRET))
 306
 307 # Now work with Twitter
 308 twitter.statuses.update(status='Hello, world!')
 309 ```
 310
 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 ```
 337
 338 License
 339 =======
 340
 341 Python Twitter Tools are released under an MIT License.