flickraw 0.1

data/flickraw_rdoc.rb

@@ -0,0 +1,136 @@
+require "rdoc/parsers/parserfactory"
+require "rdoc/parsers/parse_rb"
+#require "flickraw"
+require "cgi"
+
+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( <<END
+# Generated automatically from the flickr api
+  def #{name}(*args)
+    Request.call '#{flickr_method}', *args
+  end
+END
+)
+
+        doc.add_method m
+        progress(".")
+        @stats.num_methods += 1
+      }
+    end
+
+    def flickr_method_comment(info)
+      description = CGI.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 << "#{CGI.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 << "  #{e.to_s}\n"
+        }
+      end
+
+      if info.method.respond_to? :response
+        response = "<b>Output</b>\n"
+        raw = CGI.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
+  end
+end

data/lib/flickraw.rb

@@ -0,0 +1,225 @@
+# 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.
+
+
+require 'rexml/document'
+require 'open-uri'
+require 'md5'
+
+module FlickRaw
+  VERSION='0.1'
+
+  # URL of the flickr REST api
+  REST_URL='http://www.flickr.com/services/rest/?'.freeze
+
+  # URL of the flickr auth page
+  AUTH_URL='http://flickr.com/services/auth/?'
+
+  @api_key = '7b124df89b638e545e3165293883ef62'
+
+  # This is a wrapper around the xml response which provides an easy interface.
+  class Xml 
+    # Returns the text content of the response
+    attr_reader :to_s
+
+    # Returns the raw xml of the response
+    attr_reader :to_xml
+
+    def initialize(xml) # :nodoc:
+      @to_s   = xml.texts.join(' ')
+      @to_xml = xml.to_s
+      @list = nil
+
+      xml.attributes.each {|a, v| attribute a, v }
+
+      if xml.name =~ /s\z/
+        elements = REXML::XPath.match( xml, xml.name.sub(/s\z/, ''))
+        unless elements.empty?
+          @list = elements.collect { |e| Xml.new e }
+        end
+      else
+        xml.elements.each {|e| attribute e.name, Xml.new(e) }
+      end
+    end
+
+    def respond_to?(m) # :nodoc:
+      super || @list.respond_to?(m)
+    end
+
+    private
+    def method_missing(sym, *args, &block)
+      if @list.respond_to?( sym)
+        @list.send sym, *args, &block
+      else
+        super
+      end
+    end
+
+    def attribute(sym, value)
+      meta = class << self; self; end
+      meta.class_eval { define_method(sym) { value } }
+    end
+  end
+
+  # This is what you get in response to an API call.
+  class Response < Xml
+    # This is called internally. It builds the response object according to xml response from the server.
+    def initialize(raw_xml)
+      doc = REXML::Document.new raw_xml
+      super doc.root
+      super doc.root.elements[1] if doc.root.elements.size == 1
+    end
+  end
+
+  class FailedResponse < StandardError
+    attr_reader :code
+    alias :msg :message
+    def initialize(msg, code)
+      @code = code
+      super( 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
+      class_req = name.downcase.gsub( /::/, '.')
+      class_req.sub( /[^\.]+\./, '')              # Removes RawFlickr at the beginning
+    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={})
+      url = build_call_url(req, args)
+      res = Response.new open(url, 'User-Agent' => "Flickraw/#{VERSION}")
+      raise FailedResponse.new( res.msg, res.code) if res.stat == 'fail'
+      lookup_token( req, res)
+      res
+    end
+
+    private
+    def build_call_url(req, args={})
+      full_args = {:api_key => FlickRaw.api_key, :method => req}
+      full_args[:auth_token] = @token if @token
+      args.each {|k, v| full_args[k.to_sym] = v }
+      full_args[:api_sig] = FlickRaw.api_sig(full_args)  if FlickRaw.shared_secret
+
+      url = REST_URL + full_args.collect { |a, v| "#{a}=#{v}" }.join('&')
+    end
+
+    def lookup_token(req, res)
+      token_reqs = ['flickr.auth.getToken', 'flickr.auth.getFullToken']
+      @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
+
+      url = AUTH_URL + 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.to_s }
+end
+
+class Object
+  # 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
+    @flickr ||= FlickRaw::Flickr.new
+  end
+end

data/rakefile

@@ -0,0 +1,30 @@
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+
+require 'lib/flickraw'
+require 'flickraw_rdoc'
+
+PKG_FILES = FileList["lib/flickraw.rb", "flickraw_rdoc.rb", "rakefile"].to_a
+
+spec = Gem::Specification.new do |s|
+  s.summary = "Flickr library with a syntax close to the syntax described on http://www.flickr.com/services/api"
+  s.name = "flickraw"
+  s.author = "Hank Lords"
+  s.email =  "hanklords@gmail.com"
+  s.version = FlickRaw::VERSION
+  s.has_rdoc = true
+  s.require_path = 'lib'
+  s.autorequire = 'rake'
+  s.files = PKG_FILES
+  s.description = "Flickr library with a syntax close to the syntax described on http://www.flickr.com/services/api"
+end
+
+Rake::RDocTask.new do |rd|
+  rd.rdoc_files.include "README", "lib/flickraw.rb", "TODO"
+  rd.options << "--inline-source"
+end
+
+Rake::GemPackageTask.new spec do |p|
+  p.need_tar_gz = true
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: flickraw
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+date: 2006-07-11 00:00:00 +02:00
+summary: Flickr library with a syntax close to the syntax described on http://www.flickr.com/services/api
+require_paths: 
+- lib
+email: hanklords@gmail.com
+homepage: 
+rubyforge_project: 
+description: Flickr library with a syntax close to the syntax described on http://www.flickr.com/services/api
+autorequire: rake
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Hank Lords
+files: 
+- lib/flickraw.rb
+- flickraw_rdoc.rb
+- rakefile
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+