twitterdispatch 0.0.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael Bleigh
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,37 @@
+= TwitterDispatch 
+
+TwitterDispatch is an unassuming API wrapper for Twitter based on the dispatcher from TwitterAuth. Rather than create a complex object mapping system around the simple REST API Twitter provides, TwitterDispatch simply gives you the tools to make calls directly to the API URLs and parse the results (or not).
+
+TwitterDispatch supports both OAuth and HTTP Basic authentication strategies.
+
+== Usage
+
+To use TwitterDispatch you will need different things depending on the strategy you are using:
+
+* <b>OAuth</b> - You will need to have already registered your application with Twitter (have a consumer key and secret) as well as performed the entire OAuth authentication process (have an access key and secret). If you don't know much about OAuth and are building a Rails application, I would suggest using TwitterAuth instead.
+* <b>HTTP Basic</b> - You will need to have the screen name and password for the authenticating user.
+
+Usage of TwitterDispatch is straightforward. Here are some basic examples to get you going.
+
+    # OAuth Example
+    dispatcher = TwitterDispatch.new(:oauth, 'myconsumerkey', 'myconsumersecret', 'myaccesskey', 'myaccesssecret')
+    dispatcher.get('/account/verify_credentials') # => {'screen_name' => ...}
+    dispatcher.post('/statuses/update', :status => 'Update my status.') # => {'text' => 'Update my status.' ... }
+
+    # HTTP Basic Example
+    dispatcher = TwitterDispatch.new(:basic, 'screenname', 'password')
+    dispatcher.get('/statuses/friends_timeline') # => [{'text' => ...}]
+
+    # No Auth Example
+    dispatcher = TwitterDispatch.new
+    dispatcher.get('/statuses/public_timeline') # => [{'text' => ...}]
+
+    # Search Example
+    dispatcher = TwitterDispatch.new
+    dispatcher.search('query text') # => [{'text' => ...}]
+
+TwitterDispatch is not meant to be complex or assuming, it literally just does the bare minimum to provide you with a simple and direct access to the Twitter API in Ruby.
+
+== Copyright
+
+Copyright (c) 2009 Michael Bleigh and Intridea, Inc. See LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 0
+:patch: 2

data/lib/twitter_dispatch/dispatcher.rb

@@ -0,0 +1,125 @@
+module TwitterDispatch
+  class Dispatcher
+    # Override this method to provide new defaults.
+    # The defaults are as follows:
+    #
+    # * <tt>:base_url</tt> - http://twitter.com
+    #
+    def self.default_options
+      {
+        :base_url => 'http://twitter.com',
+        :api_timeout => 10
+      }
+    end
+
+    # Initialize a dispatcher using the specified strategy. 
+    #
+    # *Strategies*
+    #
+    # * <tt>:oauth</tt> - You will need to provide four arguments before any options: the consumer key, the consumer secret, the access key, and the access secret.
+    # * <tt>:basic</tt> - You will need to provide two arguments before any options: the screen name# and the password of the authenticating user.
+    # * <tt>:none</tt> - You will not need to provide any additional arguments but will only be able to access resources that do not require authentication (such as <tt>statuses/public_timeline</tt>).
+    #
+    # *Options*
+    #
+    # * <tt>:base_url</tt> - The base URL used to make calls. This way the dispatcher can be used on Twitter-compatible APIs, not just the Twitter API.
+    #
+    def initialize(strategy = :none, *args)
+      args << {} unless args.last.is_a?(Hash)
+      @strategy = strategy
+      case @strategy
+      when :oauth
+        raise ArgumentError, "The :oauth strategy requires four arguments - consumer_key, consumer_secret, access_key and access_secret." unless args.size == 5
+        @consumer_key, @consumer_secret, @access_key, @access_secret, @options = *args
+      when :basic
+        raise ArgumentError, "The :basic strategy requires two arguments - screen_name and password." unless args.size == 3
+        @screen_name, @password, @options = *args
+      when :none
+        raise ArgumentError, "The :none strategy does not take any mandatory arguments, only options." unless args.size == 1
+        @options = *args
+      else
+        raise ArgumentError, "Valid strategies are :oauth, :basic and :none."
+      end
+
+      @options = TwitterDispatch::Dispatcher.default_options.merge(@options)
+    end
+
+    # Generates an OAuth consumer for this dispatcher given the
+    # base_url and provided access key and token.
+    def consumer
+      OAuth::Consumer.new(@consumer_key, @consumer_secret, :site => @options[:base_url])
+    end
+
+    #:nodoc:
+    def path_prefix
+      URI.parse(base_url).path
+    end
+
+    def net
+      uri = URI.parse(base_url)
+      net = Net::HTTP.new(uri.host, uri.port)
+      net.use_ssl = uri.scheme == 'https'
+      net.read_timeout = @options[:api_timeout]
+      net
+    end
+
+    attr_reader :access_token, :access_secret, :strategy, :screen_name, :password
+
+    def base_url
+      @options[:base_url]
+    end
+    
+    # Returns true if a strategy is set.
+    def strategy?
+      strategy != :none
+    end
+
+    # True if the current strategy is OAuth.
+    def oauth?
+      strategy == :oauth
+    end
+
+    # True if the current strategy is HTTP Basic.
+    def basic?
+      strategy == :basic
+    end
+    
+    def proxy
+      case strategy
+      when :oauth
+        @proxy ||= TwitterDispatch::Proxy::OAuth.new(self)
+      when :basic
+        @proxy ||= TwitterDispatch::Proxy::Basic.new(self)
+      when :none
+        @proxy ||= TwitterDispatch::Proxy::None.new(self)
+      end     
+    end
+
+    # Make a request through the dispatcher. Method
+    # can be any of the standard HTTP verbs, path
+    # is the API path such as <tt>/account/verify_credentials.json</tt>
+    def request(http_method, path, *args)
+      proxy.request(http_method, path, *args)
+    end
+
+    # Perform a GET request through the dispatcher.
+    def get(*args)
+      proxy.get(*args)
+    end
+
+    # Perform a POST request through the dispatcher.
+    def post(*args)
+      proxy.post(*args)
+    end
+
+    # Perform a PUT request through the dispatcher.
+    def put(*args)
+      proxy.put(*args)
+    end
+
+    # Perform a DELETE request through the dispatcher.
+    def delete(*args)
+      proxy.delete(*args)
+    end
+  end
+end

data/lib/twitter_dispatch/proxy/basic.rb

@@ -0,0 +1,46 @@
+require 'net/http'
+
+module TwitterDispatch 
+  module Proxy
+    class Basic
+      include TwitterDispatch::Proxy::Shared
+
+      attr_accessor :dispatcher
+
+      def initialize(dispatcher)
+        self.dispatcher = dispatcher
+      end
+
+      def request(http_method, path, body=nil, *arguments)
+        path = dispatcher.path_prefix + path
+        path = append_extension_to(path)
+
+        response = dispatcher.net.start{ |http|
+          req = eval("Net::HTTP::#{http_method.to_s.capitalize}").new(path, *arguments)
+          req.basic_auth dispatcher.screen_name, dispatcher.password if dispatcher.basic?
+          req.set_form_data(body) unless body.nil?
+          http.request(req)
+        }
+        
+        handle_response(response)      
+      end
+
+      def get(path, *arguments)
+        request(:get, path, *arguments)
+      end
+
+      def post(path, body='', *arguments)
+        request(:post, path, body, *arguments)
+      end
+
+      def put(path, body='', *arguments)
+        request(:put, path, body, *arguments)
+      end
+
+      def delete(path, *arguments)
+        request(:delete, path, *arguments)
+      end
+    end
+  end
+end
+

data/lib/twitter_dispatch/proxy/none.rb

@@ -0,0 +1,7 @@
+module TwitterDispatch
+  module Proxy
+    class None < TwitterDispatch::Proxy::Basic
+
+    end
+  end
+end

data/lib/twitter_dispatch/proxy/oauth.rb

@@ -0,0 +1,23 @@
+module TwitterDispatch
+  module Proxy
+    class OAuth < OAuth::AccessToken
+      include TwitterDispatch::Proxy::Shared
+
+      attr_accessor :dispatcher
+
+      def initialize(dispatcher)
+        self.dispatcher = dispatcher
+        super(dispatcher.consumer, dispatcher.access_token, dispatcher.access_secret)
+      end
+
+      def request(http_method, path, *arguments)
+        path = dispatcher.path_prefix + path
+        path = append_extension_to(path)
+
+        response = super
+
+        handle_response(response)
+      end
+    end
+  end
+end

data/lib/twitter_dispatch/proxy/shared.rb

@@ -0,0 +1,36 @@
+module TwitterDispatch
+  module Proxy
+    module Shared
+      def append_extension_to(path)
+        path, query_string = *(path.split("?"))
+        path << '.json' unless path.match(/\.(:?xml|json)\z/i)
+        "#{path}#{"?#{query_string}" if query_string}"
+      end
+
+      def handle_response(response)
+        case response
+        when Net::HTTPOK 
+          begin
+            JSON.parse(response.body)
+          rescue JSON::ParserError
+            response.body
+          end
+        when Net::HTTPUnauthorized
+          raise TwitterDispatch::Unauthorized, 'API Authorization failed. Check user credentials and OAuth consumer permission levels.'
+        else
+          message = begin
+            JSON.parse(response.body)['error']
+          rescue JSON::ParserError
+            if match = response.body.match(/<error>(.*)<\/error>/)
+              match[1]
+            else
+              "An unknown #{response.code} error occurred processing your API request."
+            end
+          end
+
+          raise TwitterDispatch::HTTPError, message
+        end
+      end
+    end
+  end
+end

data/lib/twitterdispatch.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'oauth'
+require 'json'
+
+module TwitterDispatch
+  def self.new(*args)
+    TwitterDispatch::Dispatcher.new(*args)
+  end
+
+  class HTTPError < StandardError; end
+  class Unauthorized < HTTPError; end
+end
+
+require 'twitter_dispatch/dispatcher'
+require 'twitter_dispatch/proxy/shared'
+require 'twitter_dispatch/proxy/oauth'
+require 'twitter_dispatch/proxy/basic'
+require 'twitter_dispatch/proxy/none'

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'spec'
+require 'fakeweb'
+
+FakeWeb.allow_net_connect = false
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'twitterdispatch'
+
+Spec::Runner.configure do |config|
+  
+end

data/spec/twitter_dispatch/proxy/basic_spec.rb

@@ -0,0 +1,79 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe TwitterDispatch::Proxy::Basic do
+  before do
+    @dispatcher = TwitterDispatch.new(:basic, 'abc', 'def')
+  end
+
+  it 'should store the dispatcher in an attr_accessor' do
+    TwitterDispatch::Proxy::Basic.new(@dispatcher).dispatcher.should == @dispatcher
+  end
+
+  describe '#request' do
+    before do
+      @proxy = TwitterDispatch::Proxy::Basic.new(@dispatcher)
+      FakeWeb.register_uri('http://twitter.com:80/fake.json', :string => {'fake' => true}.to_json)
+        FakeWeb.register_uri('http://twitter.com:80/fake.xml', :string => '<fake>true</fake>')
+    end
+    
+    it 'should automatically parse JSON if valid' do
+       @proxy.request(:get, '/fake.json').should == {'fake' => true}
+    end
+
+    it 'should return XML as a string' do
+      @proxy.request(:get, '/fake.xml').should == "<fake>true</fake>"
+    end
+
+    it 'should append .json to the path if no extension is provided' do
+      @proxy.request(:get, '/fake.json').should == @proxy.request(:get, '/fake')
+    end
+
+    %w(get post put delete).each do |method|
+      it "should build a #{method} class based on a :#{method} http_method" do
+        @req = eval("Net::HTTP::#{method.capitalize}").new('/fake.json')
+        eval("Net::HTTP::#{method.capitalize}").should_receive(:new).and_return(@req)
+        @proxy.request(method.to_sym, '/fake')
+      end
+    end
+
+    it 'should start the HTTP session' do
+      @net = @dispatcher.net
+      @dispatcher.stub!(:net).and_return(@net)
+      @net.should_receive(:start)
+      lambda{@proxy.request(:get, '/fake')}.should raise_error(NoMethodError)
+    end
+
+    it "should raise a TwitterDispatch::HTTPError if response code isn't 200" do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.json', :string => {'error' => 'bad response'}.to_json, :status => ['401', 'Unauthorized'])
+      lambda{@proxy.request(:get, '/bad_response')}.should raise_error(TwitterDispatch::HTTPError)
+    end
+
+    it 'should set the error message to the JSON message' do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.json', :string => {'error' => 'bad response'}.to_json, :status => ['403', 'Forbidden'])
+      lambda{@proxy.request(:get, '/bad_response')}.should raise_error(TwitterDispatch::HTTPError, 'bad response')
+    end
+
+    it 'should raise a TwitterDispatch::Proxy::Unauthorized on 401' do
+      FakeWeb.register_uri('http://twitter.com:80/unauthenticated_response.xml', :string => "<hash>\n<request>/unauthenticated_response.xml</request>\n<error>bad response</error>\n</hash>", :status => ['401', 'Unauthorized'])
+      lambda{@proxy.request(:get, '/unauthenticated_response.xml')}.should raise_error(TwitterDispatch::Unauthorized)
+    end
+
+    it 'should set the error message to the XML message' do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.xml', :string => "<hash>\n<request>/bad_response.xml</request>\n<error>bad response</error>\n</hash>", :status => ['403', 'Forbidden'])
+      lambda{@proxy.request(:get, '/bad_response')}.should raise_error(TwitterDispatch::HTTPError, 'bad response')
+    end
+  end
+
+  %w(get post delete put).each do |method|
+    it "should have a ##{method} method that calls request(:#{method})" do
+      dispatcher = TwitterDispatch::Proxy::Basic.new(@user)
+      if %w(get delete).include?(method)
+        dispatcher.should_receive(:request).with(method.to_sym, '/fake.json')
+      else
+        dispatcher.should_receive(:request).with(method.to_sym, '/fake.json', '')
+      end
+      dispatcher.send(method, '/fake.json')
+    end
+  end
+end
+

data/spec/twitter_dispatch/proxy/oauth_spec.rb

@@ -0,0 +1,55 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe TwitterDispatch::Proxy::OAuth do
+  describe '#request' do
+    before do
+      @dispatcher = TwitterDispatch.new(:oauth, 'abc', 'def', 'hgi', 'jkl')
+      @proxy = TwitterDispatch::Proxy::OAuth.new(@dispatcher)
+      FakeWeb.register_uri(:get, 'http://twitter.com:80/fake.json', :string => {'fake' => true}.to_json)
+      FakeWeb.register_uri(:get, 'http://twitter.com:80/fake.xml', :string => "<fake>true</fake>")
+    end
+    
+    it 'should automatically parse json' do
+      result = @proxy.request(:get, '/fake.json')
+      result.should be_a(Hash)
+      result['fake'].should be_true
+    end
+
+    it 'should return xml as a string' do
+      @proxy.request(:get, '/fake.xml').should == '<fake>true</fake>'
+    end
+
+    it 'should append .json to the path if no extension is provided' do
+      @proxy.request(:get, '/fake').should == @proxy.request(:get, '/fake.json')
+    end
+
+    it "should raise a TwitterDispatch::HTTPError if response code isn't 200" do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.json', :string => {'error' => 'bad response'}.to_json, :status => ['401', 'Unauthorized'])
+      lambda{@proxy.request(:get, '/bad_response')}.should raise_error(TwitterDispatch::HTTPError)
+    end
+
+    it 'should set the error message to the JSON message' do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.json', :string => {'error' => 'bad response'}.to_json, :status => ['403', 'Forbidden'])
+      lambda{@proxy.request(:get, '/bad_response')}.should raise_error(TwitterDispatch::HTTPError, 'bad response')
+    end
+
+    it 'should set the error message to the XML message' do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.xml', :string => "<hash>\n<request>/bad_response.xml</request>\n<error>bad response</error>\n</hash>", :status => ['403', 'Forbidden'])
+      lambda{@proxy.request(:get, '/bad_response.xml')}.should raise_error(TwitterDispatch::HTTPError, 'bad response')
+    end
+
+    it 'should still error correctly on a totally messed up response' do
+      FakeWeb.register_uri('http://twitter.com:80/bad_response.xml', :string => "aosidnaoisdnasd", :status => ['403', 'Forbidden'])
+      lambda{@proxy.request(:get, '/bad_response.xml')}.should raise_error(TwitterDispatch::HTTPError, 'An unknown 403 error occurred processing your API request.')
+    end
+
+    it 'should raise a TwitterAuth::Dispatcher::Unauthorized on 401' do
+      FakeWeb.register_uri('http://twitter.com:80/unauthenticated_response.xml', :string => "<hash>\n<request>/unauthenticated_response.xml</request>\n<error>bad response</error>\n</hash>", :status => ['401', 'Unauthorized'])
+      lambda{@proxy.request(:get, '/unauthenticated_response.xml')}.should raise_error(TwitterDispatch::Unauthorized)
+    end
+
+    it 'should work with verb methods' do
+      @proxy.get('/fake').should == @proxy.request(:get, '/fake')
+    end
+  end
+end

data/spec/twitter_dispatch/proxy/shared_spec.rb

@@ -0,0 +1,26 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe TwitterDispatch::Proxy::Shared do
+  include TwitterDispatch::Proxy::Shared
+
+  describe '#append_extension_to' do
+    it 'should leave extensions alone if they exist' do
+      append_extension_to('/fake.json').should == '/fake.json'    
+      append_extension_to('/fake.xml').should == '/fake.xml'
+    end
+
+    it 'should append .json if no extension is provided' do
+      append_extension_to('/fake').should == '/fake.json'
+      append_extension_to('/verify/fake').should == '/verify/fake.json'
+    end
+
+    it 'should leave extensions alone even with query strings' do
+      append_extension_to('/fake.json?since_id=123').should == '/fake.json?since_id=123'
+      append_extension_to('/fake.xml?since_id=123').should == '/fake.xml?since_id=123'
+    end
+
+    it 'should add an extension even with query strings' do
+      append_extension_to('/fake?since_id=123').should == '/fake.json?since_id=123'
+    end
+  end
+end

data/spec/twitter_dispatch_spec.rb

@@ -0,0 +1,47 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe TwitterDispatch do
+  describe '#new' do
+    it 'should raise an ArgumentError for non-existent strategies' do
+      lambda{TwitterDispatch.new(:bollocks)}.should raise_error(ArgumentError)  
+    end
+
+    { :oauth => 4,
+      :basic => 2,
+      :none => 0 }.each_pair do |strategy, count|
+      it "should raise an ArgumentError with the wrong number of args for #{strategy.inspect}" do
+        (0...count).each do |arg_count|
+          myargs = ['abc'] * arg_count
+          lambda{TwitterDispatch.new(strategy, *myargs)}.should raise_error(ArgumentError)
+          myargs << {:base_url => 'http://example.com'}
+          lambda{TwitterDispatch.new(strategy, *myargs)}.should raise_error(ArgumentError)
+        end
+      end
+
+      it "should not raise an ArgumentError with the correct number of arguments for #{strategy.inspect}" do
+        myargs = ['abc'] * count
+        lambda{TwitterDispatch.new(strategy, *myargs)}.should_not raise_error(ArgumentError)
+        myargs << {:base_url => 'http://example.com'}
+        lambda{TwitterDispatch.new(strategy, *myargs)}.should_not raise_error(ArgumentError)
+      end
+
+      unless strategy == :none
+        it "should set the strategy appropriately" do
+          myargs = ['abc'] * count
+          @dispatch = TwitterDispatch.new(strategy, *myargs)
+          @dispatch.strategy.should == strategy
+          @dispatch.should be_strategy
+          @dispatch.send("#{strategy}?").should be_true
+        end
+      end
+    end
+
+    it '#strategy? should be false if the :none strategy is used' do
+      TwitterDispatch.new(:none).should_not be_strategy
+    end
+
+    it '#strategy should default to none' do
+      TwitterDispatch.new.strategy.should == :none
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: twitterdispatch
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Michael Bleigh
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-07 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: 
+email: michael@intridea.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+files: 
+- README.rdoc
+- VERSION.yml
+- lib/twitter_dispatch
+- lib/twitter_dispatch/dispatcher.rb
+- lib/twitter_dispatch/proxy
+- lib/twitter_dispatch/proxy/basic.rb
+- lib/twitter_dispatch/proxy/none.rb
+- lib/twitter_dispatch/proxy/oauth.rb
+- lib/twitter_dispatch/proxy/shared.rb
+- lib/twitterdispatch.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/twitter_dispatch
+- spec/twitter_dispatch/proxy
+- spec/twitter_dispatch/proxy/basic_spec.rb
+- spec/twitter_dispatch/proxy/oauth_spec.rb
+- spec/twitter_dispatch/proxy/shared_spec.rb
+- spec/twitter_dispatch_spec.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/mbleigh/twitterdispatch
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: twitterdispatch
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: A simple Twitter API wrapper that gets out of your way and lets you access things directly.
+test_files: []
+