net-flickr 0.0.1

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2007-2008 Ryan Grove <ryan@wonko.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of this project nor the names of its contributors may be
+      used to endorse or promote products derived from this software without
+      specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/net/flickr.rb

@@ -0,0 +1,218 @@
+#--
+# Copyright (c) 2007-2008 Ryan Grove <ryan@wonko.com>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of this project nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+# Append this file's directory to the include path if it's not there already.
+$:.unshift(File.dirname(__FILE__))
+$:.uniq!
+
+# stdlib includes
+require 'digest/md5'
+require 'net/http'
+require 'uri'
+
+# RubyGems includes
+require 'rubygems'
+require 'hpricot'
+
+# Net::Flickr includes
+require 'flickr/auth'
+require 'flickr/errors'
+require 'flickr/list'
+require 'flickr/people'
+require 'flickr/person'
+require 'flickr/photo'
+require 'flickr/photolist'
+require 'flickr/photos'
+require 'flickr/tag'
+
+module Net
+
+  # = Net::Flickr
+  # 
+  # This library implements Flickr's REST API. Its usage should be pretty
+  # straightforward. See below for examples.
+  # 
+  # Author::    Ryan Grove (mailto:ryan@wonko.com)
+  # Version::   0.0.1
+  # Copyright:: Copyright (c) 2007-2008 Ryan Grove. All rights reserved.
+  # License::   New BSD License (http://opensource.org/licenses/bsd-license.php)
+  # Website::   http://code.google.com/p/net-flickr/
+  # 
+  # == APIs not yet implemented
+  # 
+  # * activity
+  # * blogs
+  # * contacts
+  # * favorites
+  # * groups
+  # * groups.pools
+  # * interestingness
+  # * photos.comments
+  # * photos.geo
+  # * photos.licenses
+  # * photos.notes
+  # * photos.transform
+  # * photos.upload
+  # * photosets
+  # * photosets.comments
+  # * reflection
+  # * tags
+  # * test
+  # * urls
+  # 
+  class Flickr
+    AUTH_URL      = 'http://flickr.com/services/auth/'.freeze
+    REST_ENDPOINT = 'http://api.flickr.com/services/rest/'.freeze
+    VERSION       = '0.0.1'.freeze
+
+    attr_accessor :timeout
+    attr_reader :api_key, :api_secret
+    
+    # Creates a new Net::Flickr object that will use the specified _api_key_ and
+    # _api_secret_ to connect to Flickr. If you don't already have a Flickr API
+    # key, you can get one at http://flickr.com/services/api/keys.
+    # 
+    # If you don't provide an _api_secret_, you won't be able to make API calls
+    # requiring authentication.
+    def initialize(api_key, api_secret = nil)
+      @api_key    = api_key
+      @api_secret = api_secret
+      
+      # Initialize dependent classes.
+      @auth   = Auth.new(self)
+      @people = People.new(self)
+      @photos = Photos.new(self)
+    end
+    
+    # Returns a Net::Flickr::Auth instance.
+    def auth
+      @auth
+    end
+    
+    # Parses the specified Flickr REST response. If the response indicates a
+    # successful request, the response block will be returned as an Hpricot
+    # element. Otherwise, an error will be raised.
+    def parse_response(response_xml)
+      begin
+        xml = Hpricot::XML(response_xml)
+      rescue => e
+        raise InvalidResponse, 'Invalid Flickr API response'
+      end
+      
+      unless rsp = xml.at('/rsp')
+        raise InvalidResponse, 'Invalid Flickr API response'
+      end
+      
+      if rsp['stat'] == 'ok'
+        return rsp
+      elsif rsp['stat'] == 'fail'
+        raise APIError, rsp.at('/err')['msg']
+      else
+        raise InvalidResponse, 'Invalid Flickr API response'
+      end
+    end
+    
+    # Returns a Net::Flickr::People instance.
+    def people
+      @people
+    end
+    
+    # Returns a Net::Flickr::Photos instance.
+    def photos
+      @photos
+    end
+    
+    # Calls the specified Flickr REST API _method_ with the supplied arguments
+    # and returns a Flickr REST response in XML format. If an API secret is set,
+    # the request will be properly signed.
+    def request(method, args = {})
+      params  = args.merge({'method' => method, 'api_key' => @api_key})      
+      url     = URI.parse(REST_ENDPOINT)
+      http    = Net::HTTP.new(url.host, url.port)
+      request = sign_request(Net::HTTP::Post.new(url.path), params)
+      
+      http.start do |http|
+        if block_given?
+          http.request(request) {|response| yield response }
+        else
+          response = http.request(request)
+        
+          # Raise a Net::HTTP error if the HTTP request failed.
+          unless response.is_a?(Net::HTTPSuccess) || 
+              response.is_a?(Net::HTTPRedirection)
+            response.error!
+          end
+          
+          # Return the parsed response.
+          return parse_response(response.body)
+        end
+      end
+    end
+    
+    # Signs a Flickr API request with the API secret if set.
+    def sign_request(request, params)
+      # If the secret isn't set, we can't sign anything.
+      if @api_secret.nil?
+        request.set_form_data(params)
+        return request
+      end
+      
+      # Add auth_token to the param list if we're already authenticated.
+      params['auth_token'] = @auth.token unless @auth.token.nil?
+      
+      # Build a sorted, concatenated parameter list as described at
+      # http://flickr.com/services/api/auth.spec.html
+      paramlist = ''
+      params.keys.sort.each {|key| paramlist << key << 
+          URI.escape(params[key].to_s) }
+      
+      # Sign the request with a hash of the secret key and the concatenated
+      # parameter list.
+      params['api_sig'] = Digest::MD5.hexdigest(@api_secret + paramlist)
+      request.set_form_data(params)
+      
+      return request      
+    end
+    
+    # Signs a Flickr URL with the API secret if set.
+    def sign_url(url)
+      return url if @api_secret.nil?
+
+      uri = URI.parse(url)
+
+      params = uri.query.split('&')
+      params << 'api_sig=' + Digest::MD5.hexdigest(@api_secret +
+          params.sort.join('').gsub('=', ''))
+
+      uri.query = params.join('&')
+
+      return uri.to_s
+    end
+  end
+
+end

data/lib/net/flickr/auth.rb

@@ -0,0 +1,139 @@
+#--
+# Copyright (c) 2007-2008 Ryan Grove <ryan@wonko.com>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of this project nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+module Net; class Flickr
+
+  # Implements the Flickr authentication API. Please see
+  # http://flickr.com/services/api/auth.spec.html for details on how to use this
+  # API in your application.
+  # 
+  # Don't instantiate this class yourself. Instead, create an instance of the
+  # +Flickr+ class and then user <tt>Flickr.auth</tt> to access this class,
+  # like so:
+  # 
+  #   require 'net/flickr'
+  #   
+  #   flickr = Net::Flickr.new('524266cbd9d3c2xa2679fee8b337fip2',
+  #       '835hae5d6j0sd47a')
+  #   
+  #   puts flickr.auth.url_desktop
+  # 
+  class Auth
+    PERM_NONE   = :none
+    PERM_READ   = :read
+    PERM_WRITE  = :write
+    PERM_DELETE = :delete
+  
+    attr_reader :frob, :perms, :token, :user_id, :user_name, :user_fullname
+    
+    def initialize(flickr)
+      @flickr = flickr
+
+      @frob          = nil
+      @perms         = PERM_NONE
+      @token         = nil
+      @user_id       = nil
+      @user_name     = nil
+      @user_fullname = nil
+    end
+    
+    #--
+    # Public Instance Methods
+    #++
+    
+    # Updates this Auth object with the credentials attached to the specified
+    # authentication _token_. If the _token_ is not valid, an APIError will be
+    # raised.
+    def check_token(token = @token)
+      update_auth(@flickr.request('flickr.auth.checkToken',
+          'auth_token' => token))
+      return true
+    end
+    
+    # Gets the full authentication token for the specified _mini_token_.
+    def full_token(mini_token)
+      update_auth(@flickr.request('flickr.auth.getFullToken',
+          'mini_token' => mini_token))
+      return @token
+    end
+    
+    # Gets a frob to be used during authentication.
+    def get_frob
+      response = @flickr.request('flickr.auth.getFrob').at('frob')
+      return @frob = response.inner_text
+    end
+  
+    # Updates this Auth object with the credentials for the specified _frob_ and
+    # returns an auth token. If the _frob_ is not valid, an APIError will be
+    # raised.
+    def get_token(frob = @frob)
+      update_auth(@flickr.request('flickr.auth.getToken', 'frob' => frob))
+      return @token
+    end
+    
+    # Gets a signed URL that can by used by a desktop application to show the
+    # user a Flickr authentication screen. Once the user has visited this URL
+    # and authorized your application, you can call get_token to authenticate.
+    def url_desktop(perms)
+      get_frob if @frob.nil?
+      url = Flickr::AUTH_URL +
+          "?api_key=#{@flickr.api_key}&perms=#{perms}&frob=#{@frob}"
+      
+      return @flickr.sign_url(url)
+    end
+    
+    # Gets a signed URL that can be used by a web application to show the user a
+    # Flickr authentication screen. Once the user has visited this URL and
+    # authorized your application, you can call get_token with the frob provided
+    # by Flickr to authenticate.
+    def url_webapp(perms)
+      return @flickr.sign_url(Flickr::AUTH_URL +
+          "?api_key=#{@flickr.api_key}&perms=#{perms}")
+    end
+    
+    #--
+    # Private Instance Methods
+    #++
+    
+    private
+    
+    # Updates this Auth object with the credentials in the specified XML
+    # _response_.
+    def update_auth(response)
+      auth = response.at('auth')
+      user = auth.at('user')
+      
+      @perms         = auth.at('perms').inner_text.to_sym
+      @token         = auth.at('token').inner_text
+      @user_id       = user['nsid']
+      @user_name     = user['username']
+      @user_fullname = user['fullname']
+    end
+  end
+
+end; end

data/lib/net/flickr/errors.rb

@@ -0,0 +1,35 @@
+#--
+# Copyright (c) 2007-2008 Ryan Grove <ryan@wonko.com>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of this project nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+module Net; class Flickr
+  
+  class APIError < StandardError; end
+  class InvalidResponse < StandardError; end
+  class ListError < StandardError; end
+
+end; end

data/lib/net/flickr/list.rb

@@ -0,0 +1,135 @@
+#--
+# Copyright (c) 2007-2008 Ryan Grove <ryan@wonko.com>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of this project nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+module Net; class Flickr
+
+  # Base class for paginated lists.
+  # 
+  # Don't instantiate this class yourself. It's a base class extended by
+  # +PhotoList+ and others.
+  class List
+    include Enumerable
+    
+    attr_reader :page, :pages, :per_page, :total
+    
+    def initialize(flickr, load_method, load_args)
+      @flickr      = flickr
+      @load_method = load_method
+      @load_args   = load_args
+      
+      update_list
+    end
+    
+    #--
+    # Public Instance Methods
+    #++
+    
+    def [](index)
+      return @items[index]
+    end
+    
+    def each
+      @items.each {|item| yield item }
+    end
+    
+    # Returns +true+ if the current page is the first page of the list, +false+
+    # otherwise.
+    def first_page?
+      return @page == 1
+    end
+    
+    # Returns +true+ if the current page is the last page of the list, +false+
+    # otherwise.
+    def last_page?
+      return @page == @pages
+    end
+    
+    # Loads the next page in the list.
+    def next
+      if last_page?
+        raise ListError, 'Already on the last page of the list'
+      end
+      
+      @load_args['page'] = @page + 1      
+      update_list
+    end
+    
+    # Loads the specified page in the list.
+    def page=(page)
+      if page < 1 || page > @pages
+        raise ArgumentError, 'Page number out of bounds'
+      end
+      
+      @load_args['page'] = page
+      update_list
+    end
+    
+    # Sets the number of items loaded per page. Must be between 1 and 500
+    # inclusive.
+    def per_page=(per_page)
+      if per_page < 1 || per_page > 500
+        raise ArgumentError, 'per_page must be between 1 and 500 inclusive'
+      end
+      
+      @per_page = per_page
+      @load_args['per_page'] = @per_page
+    end
+    
+    # Loads the previous page in the list.
+    def previous
+      if first_page?
+        raise ListError, 'Already on the first page of the list'
+      end
+      
+      @load_args['page'] = @page - 1
+      update_list
+    end
+    
+    alias prev previous
+    
+    #--
+    # Private Instance Methods
+    #++
+    
+    private
+    
+    def update_list
+      @items = []
+      
+      @response = @flickr.request(@load_method, @load_args).
+          at('/*[@page]:first')
+      
+      @per_page = @response['perpage'].to_i
+      @page     = @response['page'].to_i
+      @pages    = @response['pages'].to_i
+      @total    = @response['total'].to_i
+    end
+    
+  end
+
+end; end