twittertype 0.1.0

data/README.rdoc

@@ -0,0 +1,36 @@
+= Overview
+TwitterType is a basic utility that analyses a Twitter user's tweets and
+determine what type of Tweeter the user is.  The set of types identified are:
+
+[:+chatter+] most tweets are in response to tweets by other Twitter users
+[:+linker+] most tweets include links to URLs
+[:+retweeter+] most tweets are forwarding on other people's tweets
+[:+originator+] most tweets are original content, not containing links, retweets or responses
+[:+unknown_inconclusive+] no strong trends to base type on.
+[:+unknown_silent+] no tweets found in last 7 days
+[:+unknown_protected_user+] user has not granted public access to tweets
+
+= Usage
+
+Simply run the twitter_type.rb file passing the Twitter screen name of the person you wish to analyse.
+The analysis of this persons most tweets from the last 7 days will be displayed.
+
+For example:
+
+  ruby twitter_type.rb APlusK
+  APlusK: type :linker, #tweets 20, #replies 1, #retweets 5, #links 7
+
+To analyse multiple Twitter user's, simply pass each on the command line.  For example:
+
+  ruby twitter_type.rb APlusK BillGates EvaLongoria
+  APlusK: type :originator, #tweets 20, #replies 1, #retweets 5, #links 6
+  BillGates: type :linker, #tweets 19, #replies 1, #retweets 2, #links 11
+  EvaLongoria: type :linker, #tweets 19, #replies 3, #retweets 1, #links 11
+
+= Notes
+
+* The Twitter screen name parameter is case insensitive.
+* Each tweet will only be classified as one of a link, retweet, reply or original tweet.  For example, a retweet containing a link is just a retweet and not both.
+
+= Copyright
+Copyright (c) 2010 Andy Marks, released under the MIT license

data/lib/profilefactory.rb

@@ -0,0 +1,25 @@
+require 'tweeterprofile'
+
+module TwitterType
+
+class ProfileFactory
+
+  def initialize(user)
+    raise ArgumentError.new("No user name supplied") if user.nil? or !user.is_a?(String)
+    @user = user
+  end
+
+  def build(tweets)
+    raise ArgumentError.new("No tweets to analyse") if tweets.nil?
+    raise ArgumentError.new("Tweets are not enumerable") if !tweets.is_a?(Enumerable)
+
+    profile = TweeterProfile.new(@user)
+    tweets.each do |tweet|
+      profile.update_from(tweet)
+    end
+
+    return profile
+  end
+end
+
+end

data/lib/tweeterprofile.rb

@@ -0,0 +1,84 @@
+module TwitterType
+
+  class TweeterProfile
+    attr_accessor :screen_name,
+                  :tweet_count,
+                  :reply_count,
+                  :retweet_count,
+                  :link_count,
+                  :inferred_type
+
+    def initialize(screen_name)
+      @tweet_count = 0
+      @reply_count = 0
+      @retweet_count = 0
+      @link_count = 0
+      @screen_name = screen_name
+    end
+
+    def update_from(tweet)
+      begin
+        @tweet_count = @tweet_count + 1
+
+        if tweet.text.slice(0, 1) == '@'
+          @reply_count = @reply_count + 1
+          return
+        end
+
+        @retweet_count = @retweet_count + 1 if tweet.text.slice(0, 2) == 'RT'
+        @link_count = @link_count + 1 if tweet.text.index('http://') != nil
+      rescue NoMethodError => root
+        raise ArgumentError.new("Missing method responses in tweet structure:" + root.to_s)
+      end
+    end
+
+    def to_s
+      type_to_s = (@inferred_type ? "type " + @inferred_type.inspect + ", " : "")
+      @screen_name + ": " + type_to_s + "#tweets " + @tweet_count.to_s + ", #replies " + @reply_count.to_s + ", #retweets " + @retweet_count.to_s + ", #links " + @link_count.to_s + "\n"
+    end
+
+    def ==(other)
+      result = @screen_name == other.screen_name
+      result = result && @tweet_count == other.tweet_count
+      result = result && @reply_count == other.reply_count
+      result = result && @retweet_count == other.retweet_count
+      result = result && @link_count == other.link_count
+
+      return result
+    end
+
+    def infer_type
+
+      attributes = [@retweet_count, @link_count, @reply_count]
+      highest_count = attributes.max
+
+      raise ArgumentError if @tweet_count < highest_count
+
+      @inferred_type = set_type(highest_count)
+
+      return @inferred_type
+    end
+
+    private
+    def set_type(highest_count)
+      return :unknown_silent if @tweet_count == 0
+      
+      non_original_tweet_count = @retweet_count + @link_count + @reply_count
+      original_tweets = @tweet_count - non_original_tweet_count
+      return :originator if original_tweets > highest_count
+
+      return :unknown_inconclusive if equal_highest?(highest_count, @retweet_count, @link_count)
+      return :unknown_inconclusive if equal_highest?(highest_count, @retweet_count, @reply_count)
+      return :unknown_inconclusive if equal_highest?(highest_count, @link_count, @reply_count)
+
+      return :retweeter if highest_count == @retweet_count
+      return :linker if highest_count == @link_count
+      return :chatter if highest_count == @reply_count
+    end
+
+    def equal_highest?(highest_count, first, second)
+      highest_count == first and highest_count == second
+    end
+
+  end
+end

data/lib/twitter_type.rb

@@ -0,0 +1,11 @@
+require 'twittertypeinferrer'
+
+module TwitterType
+
+  inferrer = TwitterType::TypeInferrer.new()
+
+  ARGV.each do |screen_name|
+    inferrer.infer(screen_name)
+    print inferrer.profile
+  end
+end

data/lib/twitterclient.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'twitter'
+
+module TwitterType
+
+  class TwitterClient
+    def gather_recent_tweets_for (screen_name)
+      raise ArgumentError if screen_name.nil? or screen_name.strip.size == 0
+      
+      Twitter::Client.new.timeline_for(:user, :id => screen_name)
+    end
+  end
+end

data/lib/twitterclientwrapper.rb

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'twitterclient'
+
+module TwitterType
+
+  class TwitterClientWrapper < TwitterClient
+
+    attr_reader :client
+    
+    def initialize(client = TwitterClient.new)
+      @client = client
+    end
+    
+    def gather_recent_tweets_for (screen_name)
+      begin
+        @client.gather_recent_tweets_for(screen_name)
+      rescue Twitter::RESTError => error
+        raise ProtectedUserAccessError.new(error.to_s) if ProtectedUserAccessError.fits(error)
+        raise TwitterClientError.new(error.to_s)
+      end
+    end
+  end
+
+  class TwitterClientError < StandardError
+    attr :message
+
+    def initialize(message)
+      @message = message
+    end
+  end
+
+  class ProtectedUserAccessError < TwitterClientError
+    CODE = "401"
+
+    def self.fits(error)
+      return !error.code.index(CODE).nil?
+    end
+  end
+end

data/lib/twittertypeinferrer.rb

@@ -0,0 +1,29 @@
+require "twitterclientwrapper"
+require "profilefactory"
+
+module TwitterType
+
+  class TypeInferrer
+    attr_writer :client
+    attr_reader :profile
+
+    def initialize()
+      @client = TwitterClientWrapper.new
+    end
+
+    def infer(user)
+      begin
+        tweets = @client.gather_recent_tweets_for(user)
+        @profile = ProfileFactory.new(user).build(tweets)
+        @profile.infer_type
+      rescue TwitterType::ProtectedUserAccessError => error
+        @profile = ProfileFactory.new(user).build([])
+        @profile.inferred_type = :unknown_protected_user
+      end
+
+      self
+    end
+
+  end
+
+end

data/test/functional/twittertypeinferrer_spec.rb

@@ -0,0 +1,12 @@
+require 'spec'
+require 'twittertypeinferrer'
+require 'twitterclient'
+
+include TwitterType
+
+describe TypeInferrer do
+
+  it "should pass a basic smoke test" do
+    TypeInferrer.new.infer("andee_marks")
+  end
+end

data/test/unit/profilefactory_spec.rb

@@ -0,0 +1,56 @@
+require "spec"
+require "profilefactory"
+require 'tweeterprofile'
+
+describe TwitterType::ProfileFactory do
+  before(:each) do
+    @empty_profile = TweeterProfile.new("user")
+    @factory = TwitterType::ProfileFactory.new(@empty_profile.screen_name)
+  end
+
+  def setup_valid_fields_in_tweet
+    mock_valid_tweet = mock()
+    mock_valid_tweet.stub!(:to_user).and_return("user")
+    mock_valid_tweet.stub!(:text).and_return("RT textm http://www.cool.com")
+    mock_valid_tweet.stub!(:id).and_return(12345678)
+
+    return mock_valid_tweet
+  end
+  
+  it "should fail construction without a user" do
+    lambda {ProfileFactory.new}.should raise_error(ArgumentError)
+    lambda {ProfileFactory.new(nil)}.should raise_error(ArgumentError)
+    lambda {ProfileFactory.new(1)}.should raise_error(ArgumentError)
+    
+    ProfileFactory.new("user")
+  end
+  
+  it "should fail if it cannot enumerate tweets" do
+    lambda {@factory.build()}.should raise_error(ArgumentError)
+    lambda {@factory.build(nil)}.should raise_error(ArgumentError)
+    lambda {@factory.build("tweets")}.should raise_error(ArgumentError)
+    lambda {@factory.build([1, 2, 3])}.should raise_error(ArgumentError)
+    
+    @factory.build(Array.new())
+  end
+  
+  it "should return an empty profile if no tweets are supplied" do
+    @factory.build(Array.new()).should == @empty_profile
+  end
+  
+  it "should take a tweet with a valid set of fields" do
+    lambda {@factory.build(Array.new(1, "tweet"))}.should raise_error(ArgumentError)
+
+    mock_valid_tweet = setup_valid_fields_in_tweet()
+
+    @factory.build(Array.new(1, mock_valid_tweet))
+  end
+  
+  it "needs the tweet text to be a string" do
+    tweet_with_non_string_text = mock()
+    tweet_with_non_string_text.stub!(:to_user).and_return(nil)
+    tweet_with_non_string_text.stub!(:text).and_return(1)
+    
+    lambda {@factory.build(Array.new(1, tweet_with_non_string_text))}.should raise_error(ArgumentError)
+  end
+end

data/test/unit/tweeterprofile_spec.rb

@@ -0,0 +1,177 @@
+require 'spec'
+require 'tweeterprofile'
+
+describe TwitterType::TweeterProfile, " before update" do
+
+  before(:each) do
+    @profile = TweeterProfile.new("andy")
+  end
+
+  it "should provide a valid string representation for a newly created profile" do
+    TweeterProfile.new("andy").to_s.should eql("andy: #tweets 0, #replies 0, #retweets 0, #links 0\n")
+  end
+
+  it "should be equal to another profile with the same values" do
+    first = TweeterProfile.new("user")
+    first.link_count = 1
+    first.retweet_count = 2
+    first.reply_count = 3
+    first.tweet_count = 4
+
+    second = TweeterProfile.new(first.screen_name)
+    second.link_count = first.link_count
+    second.retweet_count = first.retweet_count
+    second.reply_count = first.reply_count
+    second.tweet_count = first.tweet_count
+
+    first.equal?(second).should == false
+    (first == second).should == true
+  end
+
+  it "should provide a valid string representation for an updated profile" do
+    @profile.tweet_count = 1
+    @profile.reply_count = 2
+    @profile.retweet_count = 3
+    @profile.link_count = 4
+
+    @profile.to_s.should eql("andy: #tweets 1, #replies 2, #retweets 3, #links 4\n")
+
+  end
+
+end
+
+describe TwitterType::TweeterProfile, " being updated" do
+
+  before(:each) do
+    @profile = TweeterProfile.new("andy")
+  end
+
+  Tweet = Struct.new(:text, :to_user)
+
+  it "should fail when asked to update itself from a nil tweet" do
+    lambda {@profile.update_from(nil)}.should raise_error(ArgumentError)
+  end
+
+  it "should increase the tweet count for each tweet found" do
+    @profile.tweet_count.should == 0
+
+    @profile.update_from(Tweet.new("text"))
+    @profile.tweet_count.should == 1
+
+    @profile.update_from(Tweet.new("text"))
+    @profile.tweet_count.should == 2
+
+  end
+
+  it "should increase the reply count for each tweet sent to a user" do
+    @profile.reply_count.should == 0
+
+    @profile.update_from(Tweet.new("@user text"))
+    @profile.reply_count.should == 1
+
+    @profile.update_from(Tweet.new("@user text"))
+    @profile.reply_count.should == 2
+
+    @profile.update_from(Tweet.new("text"))
+    @profile.reply_count.should == 2
+  end
+
+  it "should let a reply take precedence over a retweet" do
+    @profile.reply_count.should == 0
+    @profile.update_from(Tweet.new("@user text"))
+    @profile.reply_count.should == 1
+    @profile.retweet_count.should == 0
+  end
+
+  it "should increase the retweet count for each tweet forwarded from a user" do
+    @profile.retweet_count.should == 0
+
+    @profile.update_from(Tweet.new("RT text"))
+    @profile.retweet_count.should == 1
+
+    @profile.update_from(Tweet.new("RT text"))
+    @profile.retweet_count.should == 2
+
+    @profile.update_from(Tweet.new("text"))
+    @profile.retweet_count.should == 2
+  end
+
+  it "should increase the link count for each tweet mentioning an URL" do
+    @profile.link_count.should == 0
+
+    @profile.update_from(Tweet.new("text http://www.twitter.com", nil))
+    @profile.link_count.should == 1
+
+    @profile.update_from(Tweet.new("text http://www.twitter.com", nil))
+    @profile.link_count.should == 2
+
+    @profile.update_from(Tweet.new("text"))
+    @profile.link_count.should == 2
+  end
+
+end
+
+describe TwitterType::TweeterProfile, " inferring a type" do
+  before(:each) do
+    @cut = TweeterProfile.new("user")
+  end
+
+  it "should fail to infer a profile which has less tweets than possible given other attributes" do
+    setup_profile({:retweet_count => 1, :link_count => 0, :reply_count => 0, :tweet_count => 0})
+    lambda{@cut.infer_type}.should raise_error(ArgumentError)
+
+    setup_profile({:retweet_count => 0, :link_count => 1, :reply_count => 0, :tweet_count => 0})
+    lambda{@cut.infer_type}.should raise_error(ArgumentError)
+
+    setup_profile({:retweet_count => 0, :link_count => 0, :reply_count => 1, :tweet_count => 0})
+    lambda{@cut.infer_type}.should raise_error(ArgumentError)
+  end
+
+  it "should infer retweeter from a profile with predominantly retweets" do
+    setup_profile({:retweet_count => 1, :link_count => 0, :reply_count => 0, :tweet_count => 1})
+    @cut.infer_type.should == :retweeter
+  end
+
+  it "should included the inferred type in the string representation" do
+    setup_profile({:retweet_count => 1, :link_count => 0, :reply_count => 0, :tweet_count => 1})
+    @cut.infer_type
+    @cut.to_s.should eql("user: type :retweeter, #tweets 1, #replies 0, #retweets 1, #links 0\n")
+  end
+
+  it "should infer linker from a profile with only links" do
+    setup_profile({:retweet_count => 0, :link_count => 1, :reply_count => 0, :tweet_count => 1})
+    @cut.infer_type.should == :linker
+  end
+
+  it "should infer linker from a profile with predominantly links" do
+    setup_profile({:retweet_count => 0, :link_count => 15, :reply_count => 0, :tweet_count => 20})
+    @cut.infer_type.should == :linker
+  end
+
+  it "should infer chatter from a profile with predominantly replies" do
+    setup_profile({:retweet_count => 0, :link_count => 0, :reply_count => 1, :tweet_count => 1})
+    @cut.infer_type.should == :chatter
+  end
+
+  it "should infer originator from a profile with predominantly original tweets" do
+    setup_profile({:retweet_count => 1, :link_count => 1, :reply_count => 1, :tweet_count => 10})
+    @cut.infer_type.should == :originator
+  end
+
+  it "should infer no clear type from a profile with no clear trends" do
+    setup_profile({:retweet_count => 1, :link_count => 1, :reply_count => 1, :tweet_count => 3})
+    @cut.infer_type.should == :unknown_inconclusive
+  end
+
+  it "should infer no clear type from an empty profile" do
+    setup_profile({:retweet_count => 0, :link_count => 0, :reply_count => 0, :tweet_count => 0})
+    @cut.infer_type.should == :unknown_silent
+  end
+
+  def setup_profile(return_values)
+    @cut.retweet_count = return_values[:retweet_count]
+    @cut.link_count = return_values[:link_count]
+    @cut.reply_count = return_values[:reply_count]
+    @cut.tweet_count = return_values[:tweet_count]
+  end
+end

data/test/unit/twitterclient_spec.rb

@@ -0,0 +1,12 @@
+require "spec"
+require "twitterclient"
+
+describe TwitterType::TwitterClient do
+
+  it "should fail with an empty or nil user name" do
+    lambda{TwitterClient.new.gather_recent_tweets_for(nil)}.should raise_error(ArgumentError)
+    lambda{TwitterClient.new.gather_recent_tweets_for("")}.should raise_error(ArgumentError)
+    lambda{TwitterClient.new.gather_recent_tweets_for("   ")}.should raise_error(ArgumentError)
+    lambda{TwitterClient.new.gather_recent_tweets_for(' ')}.should raise_error(ArgumentError)
+  end
+end

data/test/unit/twitterclientwrapper_spec.rb

@@ -0,0 +1,37 @@
+require "spec"
+require "twitterclientwrapper"
+
+describe TwitterType::TwitterClientWrapper do
+
+  it "should subclass TwitterClient" do
+    TwitterClientWrapper.superclass.should == TwitterClient
+  end
+
+  it "should allow injection of a TwitterClient" do
+    TwitterClientWrapper.new(TwitterClient.new)
+  end
+
+  it "should default the client to a TwitterClient instance" do
+    TwitterClientWrapper.new.client.class.should == TwitterClient
+  end
+
+  it "should turn raise a custom exception when an attempt to access a protected user's tweets is made" do
+    protected_user_access_error = Twitter::RESTError.new
+    protected_user_access_error.code = "401"
+
+    client = mock    
+    client.stub!(:gather_recent_tweets_for).with("protected_user").and_raise(protected_user_access_error)
+
+    lambda{TwitterClientWrapper.new(client).gather_recent_tweets_for("protected_user")}.should raise_error(ProtectedUserAccessError)
+  end
+
+  it "should turn any other exceptiona raised by client into a generci exception" do
+    access_error = Twitter::RESTError.new
+    access_error.code = "404"
+
+    client = mock
+    client.stub!(:gather_recent_tweets_for).with("dodgy_user").and_raise(access_error)
+
+    lambda{TwitterClientWrapper.new(client).gather_recent_tweets_for("dodgy_user")}.should raise_error(TwitterClientError)
+  end
+end

data/test/unit/twittertypeinferrer_spec.rb

@@ -0,0 +1,47 @@
+require 'spec'
+require 'twittertypeinferrer'
+require 'twitterclient'
+
+include TwitterType
+
+describe TypeInferrer do
+
+  VALID_TWITTER_USER = "andee_marks"
+
+  Tweet = Struct.new(:text, :to_user)
+
+  before(:each) do
+    @cut = TypeInferrer.new
+    @mock_client = mock()
+  end
+
+  it "should fail gracefully if the Twitter client fails in some way" do
+    @mock_client.stub!(:gather_recent_tweets_for).with(VALID_TWITTER_USER).and_raise(TwitterClientError.new(nil))
+    @cut.client = @mock_client
+
+    @cut.profile.should == nil
+    lambda {@cut.infer(VALID_TWITTER_USER)}.should raise_error(TwitterClientError)
+    @cut.profile.should == nil
+  end
+
+  it "should use an unknown_unauthorised type for any protected screen name" do
+    @mock_client.stub!(:gather_recent_tweets_for).with(VALID_TWITTER_USER).and_raise(ProtectedUserAccessError.new(nil))
+    @cut.client = @mock_client
+
+    @cut.profile.should == nil
+    @cut.infer(VALID_TWITTER_USER)
+    @cut.profile.inferred_type.should == :unknown_protected_user
+
+  end
+
+  it "should infer a type for a Twitter User" do
+    tweets = Array.new(1) {|i| Tweet.new("test", "to user")}
+    @mock_client.stub!(:gather_recent_tweets_for).with(VALID_TWITTER_USER).and_return(tweets)
+
+    @cut.client = @mock_client
+
+    @cut.profile.should == nil
+    @cut.infer(VALID_TWITTER_USER)
+    @cut.profile.inferred_type.should_not == :undetermined
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: twittertype
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Andy Marks
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-01 00:00:00 +11:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: twitter4r
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 3
+        - 2
+        version: 0.3.2
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: andy@corvine.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/profilefactory.rb
+- lib/tweeterprofile.rb
+- lib/twitter_type.rb
+- lib/twitterclient.rb
+- lib/twitterclientwrapper.rb
+- lib/twittertypeinferrer.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/andeemarks/Twitter-Type
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A utility for analysing Twitter user tweet patterns
+test_files: 
+- test/functional/twittertypeinferrer_spec.rb
+- test/unit/profilefactory_spec.rb
+- test/unit/tweeterprofile_spec.rb
+- test/unit/twitterclient_spec.rb
+- test/unit/twitterclientwrapper_spec.rb
+- test/unit/twittertypeinferrer_spec.rb