X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/a5aab114c7336ba11de71550d36957302e04d994..99407dab6c2455664a46e0c171972cfd7b61f43b:/README diff --git a/README b/README index eb7f034..8150170 100644 --- a/README +++ b/README @@ -73,61 +73,69 @@ is decoded python objects (lists and dicts). The Twitter API is documented at: - http://dev.twitter.com/doc +**[http://dev.twitter.com/doc](http://dev.twitter.com/doc)** Examples:: - - from twitter import * - # see "Authentication" section below for tokens and keys - t = Twitter( - auth=OAuth(OAUTH_TOKEN, OAUTH_SECRET, - CONSUMER_KEY, CONSUMER_SECRET))) +```python +from twitter import * - # Get the public timeline - t.statuses.public_timeline() +# see "Authentication" section below for tokens and keys +t = Twitter( + auth=OAuth(OAUTH_TOKEN, OAUTH_SECRET, + CONSUMER_KEY, CONSUMER_SECRET) + ) - # Get a particular friend's timeline - t.statuses.friends_timeline(id="billybob") +# Get your "home" timeline +t.statuses.home_timeline() - # Also supported (but totally weird) - t.statuses.friends_timeline.billybob() +# Get a particular friend's timeline +t.statuses.friends_timeline(id="billybob") - # Update your status - t.statuses.update( - status="Using @sixohsix's sweet Python Twitter Tools.") +# Also supported (but totally weird) +t.statuses.friends_timeline.billybob() - # Send a direct message - t.direct_messages.new( - user="billybob", - text="I think yer swell!") +# to pass in GET/POST parameters, such as `count` +t.statuses.home_timeline(count=5) - # Get the members of tamtar's list "Things That Are Rad" - t._("tamtar")._("things-that-are-rad").members() +# to pass in the GET/POST parameter `id` you need to use `_id` +t.statuses.oembed(_id=1234567890) - # 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") +# Update your status +t.statuses.update( + status="Using @sixohsix's sweet Python Twitter Tools.") - # 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) +# 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() -Searching Twitter:: - - from twitter import * +# 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") - twitter_search = Twitter(domain="search.twitter.com") +# 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) - # Find the latest search trends - twitter_search.trends() +# 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') +``` - # Search for the latest News on #gaza - twitter_search.search(q="#gaza") +Searching Twitter:: +``` python +# Search for the latest tweets about #pycon +t.search.tweets(q="#pycon") +``` Using the data returned ----------------------- @@ -135,14 +143,15 @@ 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() +```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'] +# 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 -------------------- @@ -150,7 +159,9 @@ 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") +```python +twitter = Twitter(format="xml") +``` The output will not be parsed in any way. It will be a raw string of XML. @@ -165,11 +176,13 @@ 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() +```python +twitter_stream = TwitterStream(auth=UserPassAuth('joe', 'joespassword')) +iterator = twitter_stream.statuses.sample() - for tweet in iterator: - ...do something with this tweet... +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.) @@ -178,6 +191,38 @@ 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 ------------------------ @@ -203,7 +248,7 @@ 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](https://dev.twitter.com/apps/new)** This will get you a CONSUMER_KEY and CONSUMER_SECRET. @@ -224,21 +269,22 @@ 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:: - 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) +```python +from twitter import * - oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS) +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) - twitter = Twitter(auth=OAuth( - oauth_token, oauth_secret, CONSUMER_KEY, CONSUMER_SECRET)) +oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS) - # Now work with Twitter - twitter.statuses.update('Hello, world!') +twitter = Twitter(auth=OAuth( + oauth_token, oauth_secret, CONSUMER_KEY, CONSUMER_SECRET)) +# Now work with Twitter +twitter.statuses.update(status='Hello, world!') +``` License