From 3c281d3dab5e6cf1c0a9e178e19311a3f4dfc5d7 Mon Sep 17 00:00:00 2001
From: Josh Roesslein <jroesslein@gmail.com>
Date: Sat, 8 Aug 2009 16:07:27 -0500
Subject: [PATCH] Finish up tutorial 3.

---
 tutorial/t3.py   | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 tweepy/models.py |  3 +++
 2 files changed, 63 insertions(+)

diff --git a/tutorial/t3.py b/tutorial/t3.py
index c92d865..d5c166c 100644
--- a/tutorial/t3.py
+++ b/tutorial/t3.py
@@ -8,7 +8,9 @@ models are used...
 
   Status, User, DirectMessage, Friendship,
   SavedSearch, SearchResult
+"""
 
+""" Custom Models
 A nice feature of Tweepy is that you can extend or even provide
 your own implementations of these models. Tweepy simply just sets
 the attributes and returns back an instance of your model class.
@@ -42,3 +44,61 @@ the Status model to tweepy's implementation...
 """
 tweepy.models['status'] = tweepy.Status
 
+""" Validation
+
+Tweepy's models include a method validate() which can check to
+make sure no data is missing from the model. By default the API class
+will call this method before returning the models. If the model is 
+invalid a TweepError exception will be raised. Validation is handy
+to make sure data is present which your application depends on.
+Here's a demo...
+"""
+try:
+  u = tweepy.api.get_user('twitter')
+except TweepError, e:
+  # will be raised if user is invalid OR request failed
+  print 'Failed to get user: %s' % e
+
+"""
+To disable auto validation...
+"""
+tweepy.api.validate = False
+
+""" Shortcuts
+
+Some of the models include shortcut functions for accessing
+related data from the API.
+In this next demo I will show you how to get a list of an user's
+friends by using the User model friends() shortcut...
+"""
+u = tweepy.api.get_user('twitter')
+friends = u.friends()
+for friend in friends:
+  print friend.screen_name
+
+"""
+To learn about all shortcuts check out the reference documentation.
+"""
+
+""" _api attribute
+
+Shortcuts are possible due to the _api attribute. This is a
+reference to the API instance that created the model. Normally you
+can just ignore this, but if you plan to pickle or store your models
+you must not store this reference. It will not be valid from one 
+python instance to the next. When you restore your model from storage
+you must re-link it to an API instance if you plan to use the shortcuts.
+Example:
+
+u = get_from_storage()
+u._api = my_api_instance
+
+"""
+
+""" The End
+
+This concludes the tutorial on models. You have learned how to
+implement your own models, perform validation, and using shortcuts
+to access related data.
+"""
+
diff --git a/tweepy/models.py b/tweepy/models.py
index 07d6c29..82ca9e2 100644
--- a/tweepy/models.py
+++ b/tweepy/models.py
@@ -23,6 +23,9 @@ class Model(object):
     if len(missing) > 0:
       raise TweepError('Missing required attribute(s) %s' % str(missing).strip('[]'))
 
+  def validate(self):
+    return
+
 class Status(Model):
 
   @staticmethod
-- 
2.25.1