Added tutorial part 1.

diff --git a/README b/README
index 364ce341da5860601fc233c4f115901fc4078073..7e52ba5c8c5cad5dfcfbb9dfa392718b278e6309 100644 (file)
--- a/README
+++ b/README
@@ -15,6 +15,9 @@ Features:
   Python 3 support. (See py3k branch)
   Streaming API
 
+Getting started:
+  Check out the tutorial folder to get started with Tweepy.
+
 Author: Joshua Roesslein
 License: MIT
 Dependencies:

diff --git a/example.py b/example.py
deleted file mode 100644 (file)
index ab3caaf..0000000
--- a/example.py
+++ /dev/null
@@ -1,43 +0,0 @@
-from getpass import getpass
-
-import tweepy
-
-print 'An example of using the Tweepy library...'
-
-# We need an authentication handler to tell twitter who we are.
-# First let's make one using basic auth.
-username = raw_input('Username: ')
-password = getpass('Password: ')
-basic_auth = tweepy.BasicAuthHandler(username, password)
-
-# Now a handler for oauth.
-oauth_auth = tweepy.OAuthHandler('consumer_key', 'consumer_secrete')
-
-# Create an instance of the API object and use the basic auth handler.
-api = tweepy.API(basic_auth)
-
-# Let's get a list of the statuses on the public timeline
-# and print the texts to the console.
-public_timeline = api.public_timeline()
-for status in public_timeline:
-  print '%s:  %s\n   from %s posted at %s' % (
-      status.user.screen_name, status.text, status.source, status.created_at)
-
-# Now we will update our twitter status
-# and print the text to the console.
-update = api.update_status(status='hello!')
-print 'Update: %s' % update.text
-
-# Get the timeline for the 'twitter' user.
-twitter_timeline = api.user_timeline(screen_name='twitter')
-
-# You can also setup up a cache.
-# Here we will use an in-memory cache with a timeout of 60 seconds.
-cached_api = tweepy.API(basic_auth, cache=tweepy.MemoryCache(timeout=60))
-
-# First request here will not be cached
-s = cached_api.get_status(id=123)
-
-# Now this request will be cached and won't require a trip to twitter's server.
-s_again = cached_api.get_status(id=123)
-

diff --git a/tutorial/1.py b/tutorial/1.py
new file mode 100644 (file)
index 0000000..c161d76
--- /dev/null
+++ b/tutorial/1.py
@@ -0,0 +1,77 @@
+from getpass import getpass
+import tweepy
+
+""" Tutorial 1 -- Authentication
+
+Tweepy supports both basic auth and OAuth authentication. It is 
+recommended you use OAuth so you can be more secure and also 
+set a custom "from xxx" for you application.
+
+Authentication is handled by AuthHandler instances. You must either
+create a BasicAuthHandler or OAuthHandler which we will pass into our 
+api instance to let twitter know who we are.
+
+First let's try creating an basic auth handler.
+"""
+username = raw_input('Twitter username: ')
+password = getpass('Twitter password: ')
+basic_auth = tweepy.BasicAuthHandler(username, password)
+
+"""
+Now for an OAuth handler...
+
+You must supply the handler both your consumer key and secret which
+twitter supplies you with at http://twitter.com/oauth_clients
+You may also supply a callback URL as an optional parameter.
+"""
+consumer_key = ''
+consumer_secret = ''
+oauth_auth = tweepy.OAuthHandler(consumer_key, consumer_secret)
+oauth_auth_callback = tweepy.OAuthHandler(consumer_key, consumer_secret
+                                            'http://test.com/my/callback/url')
+
+"""
+We must redirect the user to twitter so they can authorize us.
+To do this you will ask the OAuthHandler for the authorization URL
+which you will then display to the user OR open their browser to that URL.
+For this example we will just print the URL to the console.
+"""
+print 'Please authorize us: %s' % oauth_auth.get_authorization_url()
+
+"""
+Now that we have been authorized, we must fetch the access token.
+To do this the user must either supply us with a PIN OR if we are using a callback
+we must wait for that and grab the verifier number from the request.
+For this example we will ask the user for the PIN.
+"""
+verifier = raw_input('PIN: ').strip()
+oauth_auth.get_access_token()
+
+"""
+Okay we are all set then with OAuth. If you want to store the access
+token for later use, here's how...
+"""
+access_token_to_store = oauth_auth.access_token
+
+"""
+And to re-create the OAuthHandler with that access token later on...
+"""
+oauth_auth = tweepy.OAuthHandler('consumer_key', 'consumer_secret')
+oauth_auth.access_token = access_token_from_storage
+
+"""
+Now let's plugin our newly created auth handler into an API instance
+so we can start playing with the Twitter API. :)
+"""
+api_via_basic = tweepy.API(basic_auth)
+api_via_oath = tweepy.API(oauth_auth)
+
+""" The End
+
+That wraps up this first tutorial. You have learned how to setup
+authentication and create an API instance which can then be used
+to interact with the Twitter API.
+
+We are now ready for Tutorial 2.
+"""
+