"""
+from textwrap import dedent
+
from .api import Twitter, TwitterError, TwitterHTTPError, TwitterResponse
from .auth import NoAuth, UserPassAuth
-from .oauth import OAuth, read_token_file, write_token_file
+from .oauth import (OAuth, read_token_file, write_token_file,
+ __doc__ as oauth_doc)
from .stream import TwitterStream
-
+from .oauth_dance import oauth_dance
# Who needs Sphinx? Not me!
The Twitter class
=================
"""
-__doc__ += Twitter.__doc__
+__doc__ += dedent(Twitter.__doc__)
__doc__ += """
The TwitterStream class
=======================
"""
-__doc__ += TwitterStream.__doc__
+__doc__ += dedent(TwitterStream.__doc__)
__doc__ += """
Twitter Response Objects
========================
"""
-__doc__ += TwitterResponse.__doc__
+__doc__ += dedent(TwitterResponse.__doc__)
__doc__ += """
-Authentication Objects
-======================
+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.
-Other things
-============
-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.
+Working with OAuth
+==================
"""
+__doc__ += dedent(oauth_doc)
+
__all__ = ["Twitter", "TwitterStream", "TwitterResponse", "TwitterError",
"TwitterHTTPError", "NoAuth", "OAuth", "UserPassAuth",
- "read_token_file", "write_token_file"]
+ "read_token_file", "write_token_file", "oauth_dance"]
-from __future__ import print_function
+"""
+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::
-from twitter.auth import Auth
+ 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!')
+
+"""
+
+from __future__ import print_function
from time import time
from random import getrandbits
import hmac
import base64
+from .auth import Auth
def write_token_file(filename, oauth_token, oauth_token_secret):
Provide the name of your app in `app_name`, your consumer_key, and
consumer_secret. This function will open a web browser to let the
- user Allow your app to access their Twitter account. PIN
+ user allow your app to access their Twitter account. PIN
authentication is used.
If a token_filename is given, the oauth tokens will be written to
class TwitterStream(TwitterStreamCall):
"""
- 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::
+ 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()