referee 0.4.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.4.0 (Aug. 26, 2010)
+  - inital re-release

data/LICENSE

@@ -0,0 +1,6 @@
+Referee is licensed under the
+Creative Commons Share-Alike
+3.0 license. <http://is.gd/eF8mg>
+
+HTTParty Icebox is under
+the GPL license.

data/Manifest

@@ -0,0 +1,10 @@
+CHANGELOG
+LICENSE
+Manifest
+README.rdoc
+Rakefile
+lib/referee.rb
+lib/referee/httparty/icebox.rb
+lib/referee/player.rb
+lib/referee/shot.rb
+referee.gemspec

data/README.rdoc

@@ -0,0 +1,41 @@
+= Referee.
+
+Referee is an easy way to communicate with the Dribbble API.
+
+== Installation
+
+  (sudo) gem install httparty referee
+
+== Usage
+
+Use Referee as a class. For example.
+
+  player = Referee::Player.info(42)
+  puts player['name'] #=> Jeffrey Zeldman
+
+It's that easy.
+
+== Method List
+
+Anything in curly brackets ({}) are optional.
+
+=== Shots
+
+  Referee::Shot.info(id) #=> Returns the information about the given shot.
+  Referee::Shot.list(id{, :page => #, :per_page => #}) #=> Returns one of the special lists (everyone, debut, popular). Supports pagination.
+  
+=== Players
+
+  Referee::Player.shots(id{, :page => #, :per_page => #}) #=> Returns the latest shots from the given player. Supports pagination.
+  Referee::Player.shots_from_following(id{, :page => #, :per_page => #}) # => Returns the latest shots from the players the given player is following. Supports pagination.
+  Referee::Player.info(id) #=> Returns information about the given player.
+  Referee::Player.followers(id) #=> Returns a list of players that are following the given player.
+  Referee::Player.following(id) #=> Returns a list of players that the given player are following.
+  Referee::Player.drafted(id) #=> Returns a list of players that the given player drafted.
+
+== Attributes
+
+To get any attributes from a method, just use standard JSON object parsing.
+
+  zeldman = Referee::Player.info(42)
+  zeldman['name'] #=> Jeffrey Zeldman

data/Rakefile

@@ -0,0 +1,16 @@
+### Referee.
+###   file: Rakefile
+
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('referee', '0.4.0') do |p|
+  p.description = 'An easy way to communicate with the Dribbble API.'
+  p.summary = 'A Ruby wrapper for the Dribbble API.'
+  p.url = 'http://github.com/eturk/referee'
+  p.author = 'Ethan Turkeltaub'
+  p.email = 'ethan.turkeltaub@gmail.com'
+  p.ignore_pattern = []
+  p.development_dependencies = ['httparty >=0.6.1']
+end

data/lib/referee/httparty/icebox.rb

@@ -0,0 +1,259 @@
+# = Icebox : Caching for HTTParty
+# 
+# Cache responses in HTTParty models [http://github.com/jnunemaker/httparty]
+# 
+# === Usage
+#
+#   class Foo
+#     include HTTParty
+#     include HTTParty::Icebox
+#     cache :store => 'file', :timeout => 600, :location => MY_APP_ROOT.join('tmp', 'cache')
+#   end
+#
+# Modeled after Martyn Loughran's APICache [http://github.com/newbamboo/api_cache]
+# and Ruby On Rails's caching [http://api.rubyonrails.org/classes/ActiveSupport/Cache.html]
+#
+# Author: Karel Minarik [www.karmi.cz]
+# 
+# === Notes
+# 
+# Thanks to Amit Chakradeo to point out objects have to be stored marhalled on FS
+# Thanks to Marlin Forbes to point out query parameters have to be include in the cache key
+# 
+# 
+
+require 'logger'
+require 'ftools'
+require 'tmpdir'
+require 'pathname'
+require 'digest/md5'
+
+module HTTParty #:nodoc:
+  module Icebox
+
+    module ClassMethods
+
+      # Enable caching and set cache options
+      # Returns memoized cache object
+      #
+      # Following options are available, default values are in []:
+      #
+      # +store+::       Storage mechanism for cached data (memory, filesystem, your own) [memory]
+      # +timeout+::     Cache expiration in seconds [60]
+      # +logger+::      Path to logfile or logger instance [STDOUT]
+      # 
+      # Any additional options are passed to the Cache constructor
+      #
+      # Usage:
+      #
+      #   # Enable caching in HTTParty, in memory, for 1 minute
+      #   cache # Use default values
+      #
+      #   # Enable caching in HTTParty, on filesystem (/tmp), for 10 minutes
+      #   cache :store => 'file', :timeout => 600, :location => '/tmp/'
+      #
+      #   # Use your own cache store (see AbstractStore class below)
+      #   cache :store => 'memcached', :timeout => 600, :server => '192.168.1.1:1001'
+      #
+      def cache(options={})
+        options[:store]   ||= 'memory'
+        options[:timeout] ||= 60
+        logger = options[:logger]
+        @cache ||= Cache.new( options.delete(:store), options )
+      end
+
+    end
+
+    # When included, extend class with +cache+ method
+    # and redefine +get+ method to use cache
+    # 
+    def self.included(receiver) #:nodoc:
+      receiver.extend ClassMethods
+      receiver.class_eval do
+
+        # Get reponse from network
+        # TODO: Why alias :new :old is not working here? Returns NoMethodError
+        # 
+        def self.get_without_caching(path, options={})
+          perform_request Net::HTTP::Get, path, options
+        end
+
+        # Get response from cache, if available
+        # 
+        def self.get_with_caching(path, options={})
+          key = path.clone
+          key << options[:query].to_s if defined? options[:query]
+          
+          if cache.exists?(key) and not cache.stale?(key)
+            Cache.logger.debug "CACHE -- GET #{path}#{options[:query]}"
+            return cache.get(key)
+          else
+            Cache.logger.debug "/!\\ NETWORK -- GET #{path}#{options[:query]}"
+            response = get_without_caching(path, options)
+            cache.set(key, response) if response.code == 200
+            return response
+          end
+        end
+
+        # Redefine original HTTParty +get+ method to use cache
+        # 
+        def self.get(path, options={})
+          self.get_with_caching(path, options)
+        end
+
+      end
+    end
+
+    # === Cache container
+    # 
+    # Pass a store name ('memory', etc) to initializer
+    # 
+    class Cache
+      attr_accessor :store
+
+      def initialize(store, options={})
+        self.class.logger = options[:logger]
+        @store = self.class.lookup_store(store).new(options)
+      end
+
+      def get(key);            @store.get encode(key) unless stale?(key);        end
+      def set(key, value);     @store.set encode(key), value;                    end
+      def exists?(key);        @store.exists? encode(key);                       end
+      def stale?(key);         @store.stale?  encode(key);                       end
+
+      def self.logger; @logger || default_logger; end
+      def self.default_logger; logger = ::Logger.new(STDERR); end
+
+      # Pass a filename (String), IO object, Logger instance or +nil+ to silence the logger
+      def self.logger=(device); @logger = device.kind_of?(::Logger) ? device : ::Logger.new(device); end
+
+      private
+
+      # Return store class based on passed name
+      def self.lookup_store(name)
+        store_name = "#{name.capitalize}Store"
+        return Store::const_get(store_name)
+      rescue NameError => e
+        raise Store::StoreNotFound, "The cache store '#{store_name}' was not found. Did you loaded any such class?"
+      end
+
+      def encode(key); Digest::MD5.hexdigest(key); end
+    end
+
+
+    # === Cache stores
+    # 
+    module Store
+
+      class StoreNotFound < StandardError; end #:nodoc:
+
+      # ==== Abstract Store
+      # Inherit your store from this class
+      # *IMPORTANT*: Do not forget to call +super+ in your +initialize+ method!
+      # 
+      class AbstractStore
+        def initialize(options={})
+          raise ArgumentError, "You need to set the :timeout parameter" unless options[:timeout]
+          @timeout = options[:timeout]
+          message =  "Cache: Using #{self.class.to_s.split('::').last}"
+          message << " in location: #{options[:location]}" if options[:location]
+          message << " with timeout #{options[:timeout]} sec"
+          Cache.logger.info message unless options[:logger].nil?
+          return self
+        end
+        %w{set get exists? stale?}.each do |method_name|
+          define_method(method_name) { raise NoMethodError, "Please implement method set in your store class" }
+        end
+      end
+
+      # ===== Store objects in memory
+      #
+      Struct.new("Response", :code, :body, :headers) { def to_s; self.body; end }
+      class MemoryStore < AbstractStore
+        def initialize(options={})
+          super; @store = {}; self
+        end
+        def set(key, value)
+          Cache.logger.info("Cache: set (#{key})")
+          @store[key] = [Time.now, value]; true
+        end
+        def get(key)
+          data = @store[key][1]
+          Cache.logger.info("Cache: #{data.nil? ? "miss" : "hit"} (#{key})")
+          data
+        end
+        def exists?(key)
+          !@store[key].nil?
+        end
+        def stale?(key)
+          return true unless exists?(key)
+          Time.now - created(key) > @timeout
+        end
+        private
+        def created(key)
+          @store[key][0]
+        end
+      end
+
+      # ===== Store objects on the filesystem
+      # 
+      class FileStore < AbstractStore
+        def initialize(options={})
+          super
+          options[:location] ||= Dir::tmpdir
+          @path = Pathname.new( options[:location] )
+          FileUtils.mkdir_p( @path )
+          self
+        end
+        def set(key, value)
+          Cache.logger.info("Cache: set (#{key})")
+          File.open( @path.join(key), 'w' ) { |file| file << Marshal.dump(value)  }
+          true
+        end
+        def get(key)
+          data = Marshal.load(File.read( @path.join(key)))
+          Cache.logger.info("Cache: #{data.nil? ? "miss" : "hit"} (#{key})")
+          data
+        end
+        def exists?(key)
+          File.exists?( @path.join(key) )
+        end
+        def stale?(key)
+          return true unless exists?(key)
+          Time.now - created(key) > @timeout
+        end
+        private
+        def created(key)
+          File.mtime( @path.join(key) )
+        end
+      end
+    end
+
+  end
+end
+
+
+# Major parts of this code are based on architecture of ApiCache.
+# Copyright (c) 2008 Martyn Loughran
+# 
+# Other parts are inspired by the ActiveSupport::Cache in Ruby On Rails.
+# Copyright (c) 2005-2009 David Heinemeier Hansson
+# 
+# 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/lib/referee/player.rb

@@ -0,0 +1,40 @@
+### Referee.
+###   file: lib/referee/player.rb
+
+module Referee
+
+  class Player < Base
+    
+    # Returns most recent shots for the specified player. Supports pagination.
+    def self.shots(id, options={})
+      get('/players/' + id.to_s + '/shots', :query => options)
+    end
+    
+    # Returns most recent shots from the players the specified player is following. Supports pagination.
+    def self.shots_from_following(id, options={})
+      get('/players/' + id.to_s + '/shots/following', :query => options)
+    end
+    
+    # Returns the information for the specified player.
+    def self.info(id)
+      get('/players/' + id.to_s)
+    end
+    
+    # Returns a list of followers of the specified player.
+    def self.followers(id)
+      get('/players/' + id.to_s + '/followers')
+    end
+    
+    # Returns a list of the players following the specified player.
+    def self.following(id)
+      get('/players/' + id.to_s + '/following')
+    end
+    
+    # Returns a list of players the specified player drafted.
+    def self.draftees(id)
+      get('/players/' + id.to_s + '/draftees')
+    end
+    
+  end
+
+end

data/lib/referee/shot.rb

@@ -0,0 +1,20 @@
+### Referee.
+###   file: lib/referee/shot.rb
+
+module Referee
+
+  class Shot < Base
+  
+    # Returns information for the given shot.
+    def self.info(id)
+      get('/shots/' + id.to_s)
+    end
+    
+    # Returns one of the lists (debuts, everyone, popular). Supports pagination.
+    def self.list(id, options={})
+      get('/shots/' + id.to_s, :query => options)
+    end
+  
+  end
+
+end

data/lib/referee.rb

@@ -0,0 +1,25 @@
+### Referee.
+###   file: lib/referee.rb
+
+require 'httparty'
+
+directory = File.expand_path(File.dirname(__FILE__))
+require File.join(directory, 'referee', 'httparty', 'icebox')
+
+module Referee
+
+  class Base
+  
+    include HTTParty
+    include HTTParty::Icebox
+    
+    cache :store => 'memory', :timeout => 0.5, :logger => Logger.new(STDOUT)
+    
+    base_uri 'api.dribbble.com'
+  
+  end
+
+end
+
+require File.join(directory, 'referee', 'shot')
+require File.join(directory, 'referee', 'player')

data/referee.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{referee}
+  s.version = "0.4.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ethan Turkeltaub"]
+  s.date = %q{2010-08-26}
+  s.description = %q{An easy way to communicate with the Dribbble API.}
+  s.email = %q{ethan.turkeltaub@gmail.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.rdoc", "lib/referee.rb", "lib/referee/httparty/icebox.rb", "lib/referee/player.rb", "lib/referee/shot.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.rdoc", "Rakefile", "lib/referee.rb", "lib/referee/httparty/icebox.rb", "lib/referee/player.rb", "lib/referee/shot.rb", "referee.gemspec"]
+  s.homepage = %q{http://github.com/eturk/referee}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Referee", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{referee}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A Ruby wrapper for the Dribbble API.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<httparty>, [">= 0.6.1"])
+    else
+      s.add_dependency(%q<httparty>, [">= 0.6.1"])
+    end
+  else
+    s.add_dependency(%q<httparty>, [">= 0.6.1"])
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification 
+name: referee
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 0
+  - 4
+  - 0
+  version: 0.4.0
+platform: ruby
+authors: 
+- Ethan Turkeltaub
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-26 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 0
+        - 6
+        - 1
+        version: 0.6.1
+  type: :development
+  version_requirements: *id001
+description: An easy way to communicate with the Dribbble API.
+email: ethan.turkeltaub@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- LICENSE
+- README.rdoc
+- lib/referee.rb
+- lib/referee/httparty/icebox.rb
+- lib/referee/player.rb
+- lib/referee/shot.rb
+files: 
+- CHANGELOG
+- LICENSE
+- Manifest
+- README.rdoc
+- Rakefile
+- lib/referee.rb
+- lib/referee/httparty/icebox.rb
+- lib/referee/player.rb
+- lib/referee/shot.rb
+- referee.gemspec
+has_rdoc: true
+homepage: http://github.com/eturk/referee
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Referee
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: referee
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A Ruby wrapper for the Dribbble API.
+test_files: []
+