X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/e9a751290580e33e4f9a2aacf8b80d6435f7d983..51e0b8f18c733f6095d76c39ba80e8886f8235a7:/README diff --git a/README b/README index 3d6b180..a54c88b 100644 --- a/README +++ b/README @@ -18,9 +18,9 @@ For more information, after installing the `twitter` package: * visit http://mike.verdone.ca/twitter for more info - -The Command-Line Tool -===================== + +twitter - The Command-Line Tool +------------------------------- The command-line tool currently supports the following things: @@ -31,13 +31,13 @@ The command-line tool currently supports the following things: * view tweets from lists * various output formats for tweet information * read your username and password from a config file - + The bottom line: type `twitter`, receive tweets. -The IRC Bot -=========== +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 @@ -45,9 +45,8 @@ 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 @@ -55,4 +54,172 @@ a complete offsite backup of all your tweets. Run `twitter-log` and read the instructions. +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 + + +Examples:: + + twitter = Twitter( + auth=OAuth(token, token_key, con_secret, con_secret_key))) + + # Get the public timeline + twitter.statuses.public_timeline() + + # Get a particular friend's timeline + twitter.statuses.friends_timeline(id="billybob") + + # Also supported (but totally weird) + twitter.statuses.friends_timeline.billybob() + + # Send a direct message + twitter.direct_messages.new( + user="billybob", + text="I think yer swell!") + + # Get the members of a particular list of a particular friend + twitter.user.listname.members(user="billybob", listname="billysbuds") + + +Searching Twitter:: + + twitter_search = Twitter(domain="search.twitter.com") + + # Find the latest search trends + twitter_search.trends() + + # Search for the latest News on #gaza + twitter_search.search(q="#gaza") + + +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:: + + x = twitter.statuses.public_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:: + + 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:: + + 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. + +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 + +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 ouath 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:: + + 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_token_secret, CONSUMER_KEY, CONSUMER_SECRET)) + + # Now work with Twitter + twitter.statuses.update('Hello, world!') + + + +License +======= + Python Twitter Tools are released under an MIT License.