X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/5b8b1ead1da0efc7d9362beee75a8a71944a5c11..51e0b8f18c733f6095d76c39ba80e8886f8235a7:/README diff --git a/README b/README index e28beb3..a54c88b 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 @@ -9,11 +10,216 @@ tweets and setting your own tweet from the safety and security of your 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 currently supports the following things: + + * view your friends' recent tweets + * view your recent replies + * view the public timeline + * follow and unfollow (leave) friends + * 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. + + + +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. + + +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.