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
-----------------------
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
--------------------
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.
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.)
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
------------------------
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.
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
projects / z_archive / twitter.git / blobdiff