benschwarz-flickraw 0.5.1.1

data/README

@@ -0,0 +1,44 @@
+= Flickraw
+
+Flickraw is a library to access flickr[http://flickr.com] api in a simple way.
+It maps exactly the methods described in {the official api documentation}[http://www.flickr.com/services/api].
+It also try to present the data returned in a simple and intuitive way.
+The methods are fetched from flickr when loading the library by using introspection capabilities. So it is always up-to-date with regards to new methods added by flickr.
+
+You can read the class documentation here : FlickRaw.
+
+The rubyforge project : http://rubyforge.org/projects/flickraw
+
+= Installation
+Type this in a console (you might need to be superuser)
+ gem install flickraw
+
+You can recreate this documentation by typing this in the source directory:
+ rake rdoc
+
+= Usage
+
+ require 'flickraw'
+
+ list   = flickr.photos.getRecent
+
+ id     = list[0].id
+ secret = list[0].secret
+ info = flickr.photos.getInfo :photo_id => id, :secret => secret
+
+ info.title           # => "PICT986"
+ info.dates.taken     # => "2006-07-06 15:16:18"
+
+
+ sizes = flickr.photos.getSizes :photo_id => id
+
+ original = sizes.find {|s| s.label == 'Original' }
+ original.width       # => "800"
+
+See the _examples_ directory to find more examples.
+
+= Notes
+If you want to use the api authenticated with several user at the same time, you must pass the authentication token explicitely each time.
+This is because it is keeping the authentication token internally.
+As an alternative, you can create new Flickr objects besides Object.flickr which is created for you. Use Flickr.new to this effect.
+

data/copying.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Hank Lords <hanklords@gmail.com>
+
+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/flickraw_rdoc.rb

@@ -0,0 +1,147 @@
+require "rdoc/parsers/parserfactory"
+require "rdoc/parsers/parse_rb"
+
+FLICKR_API_URL='http://www.flickr.com/services/api'
+
+FakedToken = Struct.new :text
+
+module RDoc
+  class FlickrawParser < RubyParser
+    extend ParserFactory
+    parse_files_matching(/flickraw\.rb$/)
+
+    def scan
+      super
+
+      fr = @top_level.find_module_named 'FlickRaw'
+      k = fr.add_class NormalClass, 'Flickr', 'FlickRaw::Request'
+      k.record_location @top_level
+      @stats.num_classes += 1
+
+      add_flickr_methods(FlickRaw::Flickr, k)
+      @top_level
+    end
+
+    private
+    def add_flickr_methods(obj, doc)
+      obj.constants.each { |const_name|
+        const = obj.const_get const_name
+        if const.is_a?(Class) && const < FlickRaw::Request
+          name = const.name.sub(/.*::/, '')
+          k = doc.add_class NormalClass, name, 'FlickRaw::Request'
+          k.record_location @top_level
+          @stats.num_classes += 1
+
+          m = AnyMethod.new nil, name.downcase
+          m.comment = "Returns a #{name} object."
+          m.params = ''
+          m.singleton = false
+          doc.add_method m
+
+          progress("c")
+          @stats.num_methods += 1
+
+          add_flickr_methods(const, k)
+        end
+      }
+
+      obj.flickr_methods.each {|name|
+        flickr_method = obj.request_name + '.' + name
+        info = flickr.reflection.getMethodInfo :method_name => flickr_method
+
+        m = AnyMethod.new nil, name
+        m.comment = flickr_method_comment(info)
+        m.params = flickr_method_args(info)
+        m.singleton = false
+
+        m.start_collecting_tokens
+        m.add_token FakedToken.new( %{
+# Generated automatically from flickr api
+  def #{name}(*args)
+    @flickr.call '#{flickr_method}', *args
+  end
+} )
+        doc.add_method m
+        progress(".")
+        @stats.num_methods += 1
+      }
+    end
+
+    def flickr_method_comment(info)
+      description = unescapeHTML(info.method.description.to_s)
+#       description.gsub!( /<\/?(\w+)>/ ) {|b|
+#         return b if ['em', 'b', 'tt'].include? $1
+#         return ''
+#       }
+
+      if info.respond_to? :arguments
+        args = info.arguments.select { |arg| arg.name != 'api_key' }
+
+        arguments = "<b>Arguments</b>\n"
+        if args.size > 0
+          args.each {|arg|
+            arguments << "[#{arg.name} "
+            arguments << "<em>(required)</em> " if arg.optional == '0'
+            arguments << "] "
+            arguments << "#{unescapeHTML(arg.to_s)}\n"
+          }
+        end
+      end
+
+      if info.respond_to? :errors
+        errors = "<b>Error codes</b>\n"
+        info.errors.each {|e|
+          errors << "* #{e.code}: <em>#{e.message}</em>\n\n"
+          errors << "  #{unescapeHTML e.to_s}\n"
+        }
+      end
+
+      if info.method.respond_to? :response
+        response = "<b>Returns</b>\n"
+        raw = unescapeHTML(info.method.response.to_s)
+        response << raw.collect { |line| line.insert(0, ' ') }.join
+      else
+        response = ''
+      end
+
+      str = "{#{info.method.name}}[#{FLICKR_API_URL}/#{info.method.name}.html] request.\n\n"
+      str << description << "\n\n"
+      str << arguments << "\n\n"
+      str << errors << "\n\n"
+      str << response << "\n\n"
+    end
+
+    def flickr_method_args(info)
+      str = ''
+      if info.respond_to? :arguments
+        args = info.arguments.select { |arg| arg.name != 'api_key' }
+
+        if args.size > 0
+          str << '('
+          args.each {|arg|
+            str << ":#{arg.name} => '#{arg.name}'"
+            str << ','
+          }
+          str.chomp! ','
+          str << ')'
+        end
+      end
+      str
+    end
+
+    def unescapeHTML(string)
+      string.gsub!('\/', '/')
+      string.gsub(/&(.*?);/n) do
+        match = $1.dup
+        case match
+        when /\Aamp\z/ni   then '&'
+        when /\Aquot\z/ni  then '"'
+        when /\Agt\z/ni    then '>'
+        when /\Alt\z/ni    then '<'
+        when /\Anbsp\z/ni  then ' '
+        else                    "&#{match};"
+        end
+      end
+    end
+  end
+end

data/lib/flickraw.rb

@@ -0,0 +1,252 @@
+# Copyright (c) 2006 Mael Clerambault <maelclerambault@yahoo.fr>
+#
+# 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.
+
+begin
+  require 'minigems'
+rescue LoadError
+  require 'rubygems'
+end
+require 'net/http'
+require 'open-uri'
+require 'md5'
+require 'json'
+require 'cgi'
+
+module FlickRaw
+  VERSION='0.5.1.1'
+
+  FLICKR_HOST='http://api.flickr.com'.freeze
+
+  # Path of flickr REST API
+  REST_PATH='/services/rest/?'.freeze
+
+  # Path of flickr auth page
+  AUTH_PATH='/services/auth/?'.freeze
+
+  # Path of flickr upload
+  UPLOAD_PATH='/services/upload/'.freeze
+
+  @api_key = '7b124df89b638e545e3165293883ef62'
+
+  module SimpleOStruct # :nodoc:
+    def __attr_define(k,v)
+      instance_variable_set "@#{k}", v
+      meta = class << self; self; end
+      meta.class_eval { attr_reader k.to_s }
+    end
+  end
+
+  class Response # :nodoc:
+    include SimpleOStruct
+    def initialize(h)
+      h.each {|k, v| __attr_define k, Response.structify(v, k) }
+    end
+
+    def self.structify(obj, name = '')
+      if obj.is_a? Hash
+        if name =~ /s$/ and obj[$`].is_a? Array
+          list = structify obj.delete($`)
+          list.extend SimpleOStruct
+          list.instance_eval { obj.each {|kv, vv| __attr_define kv, vv } }
+          list
+        elsif obj.keys == ['_content']
+          obj['_content'].to_s
+        else
+          Response.new obj
+        end
+      elsif obj.is_a? Array
+        obj.collect {|e| structify e}
+      else
+        obj
+      end
+    end
+
+    def to_s; @_content || super end
+  end
+
+  class FailedResponse < StandardError
+    attr_reader :code
+    alias :msg :message
+    def initialize(msg, code, req)
+      @code = code
+      super("'#{req}' - #{msg}")
+    end
+  end
+
+  class Request
+    def initialize(flickr = nil) # :nodoc:
+      @flickr = flickr
+
+      self.class.flickr_objects.each {|name|
+        klass = self.class.const_get name.capitalize
+        instance_variable_set "@#{name}", klass.new(@flickr)
+      }
+    end
+
+    def self.build_request(req) # :nodoc:
+      method_nesting = req.split '.'
+      raise "'#{@name}' : Method name mismatch" if method_nesting.shift != request_name.split('.').last
+
+      if method_nesting.size > 1
+        name = method_nesting.first
+        class_name = name.capitalize
+        if const_defined? class_name
+          klass = const_get( class_name)
+        else
+          klass = Class.new Request
+          const_set(class_name, klass)
+          attr_reader name
+          flickr_objects << name
+        end
+
+        klass.build_request method_nesting.join('.')
+      else
+        req = method_nesting.first
+        define_method(req) { |*args|
+          class_req = self.class.request_name
+          @flickr.call class_req + '.' + req, *args
+        }
+        flickr_methods << req
+      end
+    end
+
+    # List of the flickr subobjects of this object
+    def self.flickr_objects; @flickr_objects ||= [] end
+
+    # List of the flickr methods of this object
+    def self.flickr_methods; @flickr_methods ||= [] end
+
+    # Returns the prefix of the request corresponding to this class.
+    def self.request_name; name.downcase.gsub(/::/, '.').sub(/[^\.]+\./, '') end
+  end
+
+  # Root class of the flickr api hierarchy.
+  class Flickr < Request
+    def initialize # :nodoc:
+      super self
+      @token = nil
+    end
+
+    # This is the central method. It does the actual request to the flickr server.
+    #
+    # Raises FailedResponse if the response status is _failed_.
+    def call(req, args={})
+      path = REST_PATH + build_args(args, req).collect { |a, v| "#{a}=#{v}" }.join('&')
+      http_response = open(FLICKR_HOST + path).read #Net::HTTP.start(FLICKR_HOST) { |http| http.get(path, 'User-Agent' => "Flickraw/#{VERSION}") }
+      parse_response(http_response, req)
+    end
+
+    # Use this to upload the photo in _file_.
+    #
+    #  flickr.upload_photo '/path/to/the/photo', :title => 'Title', :description => 'This is the description'
+    #
+    # See http://www.flickr.com/services/api/upload.api.html for more information on the arguments.
+    def upload_photo(file, args={})
+      photo = File.open(file, 'rb') { |f| f.read }
+      boundary = MD5.md5(photo).to_s
+
+      header = {'Content-type' => "multipart/form-data, boundary=#{boundary} ", 'User-Agent' => "Flickraw/#{VERSION}"}
+      query = ''
+      build_args(args).each { |a, v|
+        query <<
+          "--#{boundary}\r\n" <<
+          "Content-Disposition: form-data; name=\"#{a}\"\r\n\r\n" <<
+          "#{v}\r\n"
+      }
+      query <<
+        "--#{boundary}\r\n" <<
+        "Content-Disposition: form-data; name=\"photo\"; filename=\"#{file}\"\r\n" <<
+        "Content-Transfer-Encoding: binary\r\n" <<
+        "Content-Type: image/jpeg\r\n\r\n" <<
+        photo <<
+        "\r\n" <<
+        "--#{boundary}--"
+
+      http_response = Net::HTTP.start(FLICKR_HOST) { |http| http.post(UPLOAD_PATH, query, header) }
+      xml = http_response.body
+      if xml[/stat="(\w+)"/, 1] == 'fail'
+        msg = xml[/msg="([^"]+)"/, 1]
+        code = xml[/code="([^"]+)"/, 1]
+        raise FailedResponse.new(msg, code, 'flickr.upload')
+      end
+      Response.structify( {:stat => 'ok', :photoid => xml[/<photoid>(\w+)<\/photoid>/, 1], :ticketid => xml[/<ticketid>([^<]+)<\/ticketid>/, 1]})
+    end
+
+    private
+    def parse_response(response, req = nil)
+      json = JSON.load(response)
+      raise FailedResponse.new(json['message'], json['code'], req) if json.delete('stat') == 'fail'
+      name, json = json.to_a.first if json.size == 1
+
+      res = Response.structify json, name
+      lookup_token(req, res)
+      res
+    end
+
+    def build_args(args={}, req = nil)
+      full_args = {:api_key => FlickRaw.api_key, :format => 'json', :nojsoncallback => 1}
+      full_args[:method] = req if req
+      full_args[:auth_token] = @token if @token
+      args.each {|k, v| full_args[k.to_sym] = v.to_s }
+      full_args[:api_sig] = FlickRaw.api_sig(full_args) if FlickRaw.shared_secret
+      args.each {|k, v| full_args[k.to_sym] = CGI.escape(v.to_s) } if req
+      full_args
+    end
+
+    def lookup_token(req, res)
+      token_reqs = ['flickr.auth.getToken', 'flickr.auth.getFullToken', 'flickr.auth.checkToken']
+      @token = res.token if token_reqs.include?(req) and res.respond_to?(:token)
+    end
+  end
+
+  class << self
+    # Your flickr API key, see http://www.flickr.com/services/api/keys for more information
+    attr_accessor :api_key
+
+    # The shared secret of _api_key_, see http://www.flickr.com/services/api/keys for more information
+    attr_accessor :shared_secret
+
+    # Returns the flickr auth URL.
+    def auth_url(args={})
+      full_args = {:api_key => FlickRaw.api_key, :perms => 'read'}
+      args.each {|k, v| full_args[k.to_sym] = v }
+      full_args[:api_sig] = api_sig(full_args) if FlickRaw.shared_secret
+
+      FLICKR_HOST + AUTH_PATH + full_args.collect { |a, v| "#{a}=#{v}" }.join('&')
+    end
+
+    # Returns the signature of hsh. This is meant to be passed in the _api_sig_ parameter.
+    def api_sig(hsh)
+      MD5.md5(FlickRaw.shared_secret + hsh.sort{|a, b| a[0].to_s <=> b[0].to_s }.flatten.join).to_s
+    end
+  end
+
+  methods = Flickr.new.call 'flickr.reflection.getMethods'
+  methods.each { |method| Flickr.build_request method }
+end
+
+# Use this to access the flickr API easily. You can type directly the flickr requests as they are described on the flickr website.
+#  require 'flickraw'
+#
+#  recent_photos = flickr.photos.getRecent
+#  puts recent_photos[0].title
+def flickr; $flickraw ||= FlickRaw::Flickr.new end
+

data/test/test.rb

@@ -0,0 +1,67 @@
+require 'test/unit'
+require 'lib/flickraw'
+
+# utf8 hack
+def u(str)
+  str.gsub(/\\+u([0-9a-fA-F]{4,4})/u){["#$1".hex ].pack('U*')}
+end
+
+class Basic < Test::Unit::TestCase
+  def test_known
+    known_methods = ["flickr.activity.userComments", "flickr.activity.userPhotos", "flickr.auth.checkToken", "flickr.auth.getFrob", "flickr.auth.getFullToken", "flickr.auth.getToken", "flickr.blogs.getList", "flickr.blogs.postPhoto", "flickr.contacts.getList", "flickr.contacts.getPublicList", "flickr.favorites.add", "flickr.favorites.getList", "flickr.favorites.getPublicList", "flickr.favorites.remove", "flickr.groups.browse", "flickr.groups.getInfo", "flickr.groups.pools.add", "flickr.groups.pools.getContext", "flickr.groups.pools.getGroups", "flickr.groups.pools.getPhotos", "flickr.groups.pools.remove", "flickr.groups.search", "flickr.interestingness.getList", "flickr.people.findByEmail", "flickr.people.findByUsername", "flickr.people.getInfo", "flickr.people.getPublicGroups", "flickr.people.getPublicPhotos", "flickr.people.getUploadStatus", "flickr.photos.addTags", "flickr.photos.comments.addComment", "flickr.photos.comments.deleteComment", "flickr.photos.comments.editComment", "flickr.photos.comments.getList", "flickr.photos.delete", "flickr.photos.geo.getLocation", "flickr.photos.geo.getPerms", "flickr.photos.geo.removeLocation", "flickr.photos.geo.setLocation", "flickr.photos.geo.setPerms", "flickr.photos.getAllContexts", "flickr.photos.getContactsPhotos", "flickr.photos.getContactsPublicPhotos", "flickr.photos.getContext", "flickr.photos.getCounts", "flickr.photos.getExif", "flickr.photos.getFavorites", "flickr.photos.getInfo", "flickr.photos.getNotInSet", "flickr.photos.getPerms", "flickr.photos.getRecent", "flickr.photos.getSizes", "flickr.photos.getUntagged", "flickr.photos.getWithGeoData", "flickr.photos.getWithoutGeoData", "flickr.photos.licenses.getInfo", "flickr.photos.licenses.setLicense", "flickr.photos.notes.add", "flickr.photos.notes.delete", "flickr.photos.notes.edit", "flickr.photos.recentlyUpdated", "flickr.photos.removeTag", "flickr.photos.search", "flickr.photos.setDates", "flickr.photos.setMeta", "flickr.photos.setPerms", "flickr.photos.setTags", "flickr.photos.transform.rotate", "flickr.photos.upload.checkTickets", "flickr.photosets.addPhoto", "flickr.photosets.comments.addComment", "flickr.photosets.comments.deleteComment", "flickr.photosets.comments.editComment", "flickr.photosets.comments.getList", "flickr.photosets.create", "flickr.photosets.delete", "flickr.photosets.editMeta", "flickr.photosets.editPhotos", "flickr.photosets.getContext", "flickr.photosets.getInfo", "flickr.photosets.getList", "flickr.photosets.getPhotos", "flickr.photosets.orderSets", "flickr.photosets.removePhoto", "flickr.reflection.getMethodInfo", "flickr.reflection.getMethods", "flickr.tags.getHotList", "flickr.tags.getListPhoto", "flickr.tags.getListUser", "flickr.tags.getListUserPopular", "flickr.tags.getListUserRaw", "flickr.tags.getRelated", "flickr.test.echo", "flickr.test.login", "flickr.test.null", "flickr.urls.getGroup", "flickr.urls.getUserPhotos", "flickr.urls.getUserProfile", "flickr.urls.lookupGroup", "flickr.urls.lookupUser"]
+    found_methods = flickr.reflection.getMethods
+    assert_instance_of Array, found_methods
+    known_methods.each { |m| assert found_methods.include?(m), m}
+  end
+
+  def test_found
+    found_methods = flickr.reflection.getMethods
+    found_methods.each { |m|
+      assert_nothing_raised {
+        begin
+          eval m
+        rescue FlickRaw::FailedResponse
+        end
+      }
+    }
+  end
+
+  def test_photos
+    list = flickr.photos.getRecent :per_page => '10'
+    assert_instance_of Array, list
+    assert_equal(list.size, 10)
+
+    id = secret = info = nil
+    assert_nothing_raised(NoMethodError) {
+      id = list[0].id
+      secret = list[0].secret
+    }
+    assert_nothing_raised(FlickRaw::FailedResponse) {
+      info = flickr.photos.getInfo :photo_id => id, :secret => secret
+    }
+    assert_respond_to info, :id
+    assert_respond_to info, :secret
+    assert_respond_to info, :title
+    assert_respond_to info, :description
+    assert_respond_to info, :owner
+    assert_respond_to info, :dates
+    assert_respond_to info, :comments
+    assert_respond_to info, :tags
+  end
+
+  def test_url_escape
+    result_set = nil
+    assert_nothing_raised {
+      result_set = flickr.photos.search :text => "family vacation"
+    }
+    assert_operator result_set.total.to_i, :>=, 0
+
+    # Unicode tests
+    echo = nil
+    utf8_text = "Hélène François, €uro"
+    assert_nothing_raised {
+      echo = flickr.test.echo :utf8_text => utf8_text
+    }
+    assert_equal u(echo.utf8_text), utf8_text
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: benschwarz-flickraw
+version: !ruby/object:Gem::Version 
+  version: 0.5.1.1
+platform: ruby
+authors: 
+- Mael Clerambault
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-22 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: maelclerambault@yahoo.fr
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/flickraw.rb
+- flickraw_rdoc.rb
+- copying.txt
+- README
+- Rakefile
+- test/test.rb
+has_rdoc: false
+homepage: http://flickraw.rubyforge.org
+post_install_message: 
+rdoc_options: []
+
+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: flickraw
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Flickr library with a syntax close to the syntax described on http://www.flickr.com/services/api
+test_files: []
+