X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/8be9a740d44f312e774ecdfb077f5b54a39948ab..0f27320be29f6111de94f642867435b7eb59825c:/README diff --git a/README b/README index 27cb314..18de04e 100644 --- a/README +++ b/README @@ -1,4 +1,5 @@ Python Twitter Tools +==================== The Minimalist Twitter API for Python is a Python API for Twitter, everyone's favorite Web 2.0 Facebook-style status updater for people @@ -6,14 +7,284 @@ on the go. Also included is a twitter command-line tool for getting your friends' tweets and setting your own tweet from the safety and security of your -favorite shell and an IRC bot that can announce Twitter updated to an +favorite shell and an IRC bot that can announce Twitter updates to an IRC channel. -For more information: +For more information, after installing the `twitter` package: * import the `twitter` package and run help() on it * run `twitter -h` for command-line tool help - * run `twitterbot -h` for IRC bot help - * visit http://mike.verdone.ca/twitter for more info + + +twitter - The Command-Line Tool +------------------------------- + +The command-line tool lets you do some awesome things: + + * view your tweets, recent replies, and tweets in lists + * view the public timeline + * follow and unfollow (leave) friends + * various output formats for tweet information + +The bottom line: type `twitter`, receive tweets. + + + +twitterbot - The IRC Bot +------------------------ + +The IRC bot is associated with a twitter account (either your own account or an +account you create for the bot). The bot announces all tweets from friends +it is following. It can be made to follow or leave friends through IRC /msg +commands. + + +twitter-log +----------- + +`twitter-log` is a simple command-line tool that dumps all public +tweets from a given user in a simple text format. It is useful to get +a complete offsite backup of all your tweets. Run `twitter-log` and +read the instructions. + +twitter-archiver and twitter-follow +----------------------------------- + +twitter-archiver will log all the tweets posted by any user since they +started posting. twitter-follow will print a list of all of all the +followers of a user (or all the users that user follows). + + +Programming with the Twitter api classes +======================================== + + +The Twitter and TwitterStream classes are the key to building your own +Twitter-enabled applications. + + +The Twitter class +----------------- + +The minimalist yet fully featured Twitter API class. + +Get RESTful data by accessing members of this class. The result +is decoded python objects (lists and dicts). + +The Twitter API is documented at: + +**[http://dev.twitter.com/doc](http://dev.twitter.com/doc)** + + +Examples:: + +```python +from twitter import * + +# see "Authentication" section below for tokens and keys +t = Twitter( + auth=OAuth(OAUTH_TOKEN, OAUTH_SECRET, + CONSUMER_KEY, CONSUMER_SECRET) + ) + +# Get your "home" timeline +t.statuses.home_timeline() + +# Get a particular friend's timeline +t.statuses.user_timeline(screen_name="billybob") + +# to pass in GET/POST parameters, such as `count` +t.statuses.home_timeline(count=5) + +# to pass in the GET/POST parameter `id` you need to use `_id` +t.statuses.oembed(_id=1234567890) + +# Update your status +t.statuses.update( + status="Using @sixohsix's sweet Python Twitter Tools.") + +# Send a direct message +t.direct_messages.new( + user="billybob", + text="I think yer swell!") + +# Get the members of tamtar's list "Things That Are Rad" +t._("tamtar")._("things-that-are-rad").members() + +# Note how the magic `_` method can be used to insert data +# into the middle of a call. You can also use replacement: +t.user.list.members(user="tamtar", list="things-that-are-rad") + +# An *optional* `_timeout` parameter can also be used for API +# calls which take much more time than normal or twitter stops +# responding for some reasone +t.users.lookup(screen_name=','.join(A_LIST_OF_100_SCREEN_NAMES), _timeout=1) + +# Overriding Method: GET/POST +# you should not need to use this method as this library properly +# detects whether GET or POST should be used, Nevertheless +# to force a particular method, use `_method` +t.statuses.oembed(_id=1234567890, _method='GET') +``` + +Searching Twitter:: + +``` python +# Search for the latest tweets about #pycon +t.search.tweets(q="#pycon") +``` + +Using the data returned +----------------------- + +Twitter API calls return decoded JSON. This is converted into +a bunch of Python lists, dicts, ints, and strings. For example:: + +```python +x = twitter.statuses.home_timeline() + +# The first 'tweet' in the timeline +x[0] + +# The screen name of the user who wrote the first 'tweet' +x[0]['user']['screen_name'] +``` + +Getting raw XML data +-------------------- + +If you prefer to get your Twitter data in XML format, pass +format="xml" to the Twitter object when you instantiate it:: + +```python +twitter = Twitter(format="xml") +``` + +The output will not be parsed in any way. It will be a raw string +of XML. + + +The TwitterStream class +----------------------- + +The TwitterStream object is an interface to the Twitter Stream API +(stream.twitter.com). This can be used pretty much the same as the +Twitter class except the result of calling a method will be an +iterator that yields objects decoded from the stream. For +example:: + +```python +twitter_stream = TwitterStream(auth=UserPassAuth('joe', 'joespassword')) +iterator = twitter_stream.statuses.sample() + +for tweet in iterator: + # ...do something with this tweet... +``` + +The iterator will yield tweets forever and ever (until the stream +breaks at which point it raises a TwitterHTTPError.) + +The `block` parameter controls if the stream is blocking. Default +is blocking (True). When set to False, the iterator will +occasionally yield None when there is no available message. + +Per default the ``TwitterStream`` object uses +[public streams](https://dev.twitter.com/docs/streaming-apis/streams/public). +If you want to use one of the other +[streaming APIs](https://dev.twitter.com/docs/streaming-apis), specify the URL +manually: + +- [Public streams](https://dev.twitter.com/docs/streaming-apis/streams/public): stream.twitter.com +- [User streams](https://dev.twitter.com/docs/streaming-apis/streams/user): userstream.twitter.com +- [Site streams](https://dev.twitter.com/docs/streaming-apis/streams/site): sitestream.twitter.com + +Note that you require the proper +[permissions](https://dev.twitter.com/docs/application-permission-model) to +access these streams. E.g. for direct messages your +[application](https://dev.twitter.com/apps) needs the "Read, Write & Direct +Messages" permission. + +The following example demonstrates how to retreive all new direct messages +from the user stream: + +```python +auth = OAuth( + consumer_key='[your consumer key]', + consumer_secret='[your consumer secret]', + token='[your token]', + token_secret='[your token secret]' +) +twitter_userstream = TwitterStream(auth=auth, domain='userstream.twitter.com') +for msg in twitter_userstream.user(): + if 'direct_message' in msg: + print msg['direct_message']['text'] +``` + +Twitter Response Objects +------------------------ + +Response from a twitter request. Behaves like a list or a string +(depending on requested format) but it has a few other interesting +attributes. + +`headers` gives you access to the response headers as an +httplib.HTTPHeaders instance. You can do +`response.headers.getheader('h')` to retrieve a header. + +Authentication +-------------- + +You can authenticate with Twitter in three ways: NoAuth, OAuth, or +UserPassAuth. Get help() on these classes to learn how to use them. + +OAuth is probably the most useful. + + +Working with OAuth +------------------ + +Visit the Twitter developer page and create a new application: + +**[https://dev.twitter.com/apps/new](https://dev.twitter.com/apps/new)** + +This will get you a CONSUMER_KEY and CONSUMER_SECRET. + +When users run your application they have to authenticate your app +with their Twitter account. A few HTTP calls to twitter are required +to do this. Please see the twitter.oauth_dance module to see how this +is done. If you are making a command-line app, you can use the +oauth_dance() function directly. + +Performing the "oauth dance" gets you an oauth token and oauth secret +that authenticate the user with Twitter. You should save these for +later so that the user doesn't have to do the oauth dance again. + +read_token_file and write_token_file are utility methods to read and +write OAuth token and secret key values. The values are stored as +strings in the file. Not terribly exciting. + +Finally, you can use the OAuth authenticator to connect to Twitter. In +code it all goes like this:: + +```python +from twitter import * + +MY_TWITTER_CREDS = os.path.expanduser('~/.my_app_credentials') +if not os.path.exists(MY_TWITTER_CREDS): + oauth_dance("My App Name", CONSUMER_KEY, CONSUMER_SECRET, + MY_TWITTER_CREDS) + +oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS) + +twitter = Twitter(auth=OAuth( + oauth_token, oauth_secret, CONSUMER_KEY, CONSUMER_SECRET)) + +# Now work with Twitter +twitter.statuses.update(status='Hello, world!') +``` + + +License +======= Python Twitter Tools are released under an MIT License.