flickr-objects 0.2.0 → 0.3.0

data/lib/flickr/attributes.rb

@@ -0,0 +1,200 @@
+require "date"
+
+module Flickr
+
+  ##
+  # A helper class for true/false type.
+  #
+  # @private
+  #
+  class Boolean
+  end
+
+  ##
+  # A module that provides functionality of defining attributes of which locations
+  # can be found in the JSON response from Flickr.
+  #
+  # @private
+  #
+  module Attributes
+
+    ##
+    # Registers an attribute (name + type), defining the getter method (and in the
+    # boolean case an additional predicated alias).
+    #
+    def attribute(name, type)
+      new_attribute = Attribute.new(name, type)
+
+      attributes << new_attribute
+
+      define_method(name) do
+        self.class.attributes.find(name).value(self)
+      end
+      alias_method "#{name}?", name if type == Boolean
+
+      new_attribute
+    end
+
+    ##
+    # List of all registered attributes.
+    #
+    def attributes
+      @attributes ||= AttributeSet.new
+    end
+
+  end
+
+  ##
+  # This class stores the information about attributes. It stores the name, locations
+  # and type, and it is responsible for retrieving the attribute values from Flickr's
+  # JSON response, and optionally coercing them to the right type (for example, time
+  # can be represented in JSON only as a string, and here we convert it to actual
+  # instance of Ruby's `Time` class).
+  #
+  # @private
+  #
+  class Attribute
+
+    attr_reader :name, :type, :locations
+
+    def initialize(name, type)
+      @name, @type = name, type
+      @locations = []
+    end
+
+    def add_locations(locations)
+      @locations = locations + @locations
+    end
+
+    def value(object)
+      value = find_value(object)
+      coerce(value, object, @type)
+    end
+
+    private
+
+    ##
+    # Finds attribute value in the JSON response by looking at the given locations.
+    #
+    def find_value(context)
+      locations.each do |location|
+        begin
+          value = context.instance_exec(&location)
+          next if value.nil?
+          return value
+        rescue
+        end
+      end
+
+      nil
+    end
+
+    ##
+    # It coerces the found attribute value into a given type. For example, "boolean"
+    # type is represented in JSON as an integer (1/0), so values of this type need to
+    # be coerced the appropriate true/false values.
+    #
+    def coerce(value, object, type)
+      return value if value.nil?
+
+      if type.is_a?(Enumerable)
+        objects = value.map { |e| coerce(e, object, type.first) }
+        if type.respond_to?(:find_by)
+          return type.class.new({}).populate(objects)
+        else
+          return type.class.new(objects)
+        end
+      elsif type.ancestors.include? Flickr::Object
+        return type.new(value, object.access_token)
+      else
+        COERCIONS.fetch(type).each do |coercion|
+          begin
+            return coercion.call(value)
+          rescue
+          end
+        end
+      end
+
+      value
+    end
+
+    COERCIONS = {
+
+      String => [
+        ->(value) { String(value) },
+      ],
+
+      Time => [
+        ->(value) { Time.at(Integer(value)) },
+        ->(value) { DateTime.parse(value).to_time },
+      ],
+
+      Boolean => [
+        ->(value) { Integer(value) == 1 },
+      ],
+
+      Integer => [
+        ->(value) { Integer(value) },
+      ],
+
+      Float => [
+        ->(value) { Float(value) },
+      ],
+
+      Hash => [
+        ->(value) { value },
+      ],
+
+      Array => [
+        ->(value) { Array(value) },
+      ]
+
+    }
+
+  end
+
+  ##
+  # Container for the attributes.
+  #
+  # @private
+  #
+  class AttributeSet
+
+    include Enumerable
+
+    def initialize(*attributes)
+      @attributes = Array.new(attributes)
+    end
+
+    def each(*args, &block)
+      @attributes.each(*args, &block)
+    end
+
+    ##
+    # Shorthand for finding attributes by name.
+    #
+    def find(name = nil)
+      if name
+        super() { |attribute| attribute.name == name }
+      else
+        super()
+      end
+    end
+
+    ##
+    # Shorthand for adding locations to multiple attributes at once.
+    #
+    def add_locations(hash)
+      hash.each do |attribute_name, locations|
+        find(attribute_name).add_locations(locations)
+      end
+    end
+
+    def <<(attribute)
+      @attributes << attribute
+      self
+    end
+
+  end
+
+end

data/lib/flickr/base_converter.rb

@@ -0,0 +1,29 @@
+module Flickr
+
+  ##
+  # Converts numbers to different bases, used for generating URLs in Flickr. For example,
+  # base 58 is used for generating short URLs.
+  #
+  # @private
+  #
+  module BaseConverter
+
+    extend self
+
+    BASE58_ALPHABET = "123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ".chars.to_a.freeze
+
+    def to_base58(number)
+      number = Integer(number)
+      result = ""
+
+      begin
+        number, remainder = number.divmod(58)
+        result = BASE58_ALPHABET[remainder] + result
+      end while number > 0
+
+      result
+    end
+
+  end
+
+end

data/lib/flickr/client/data.rb

@@ -0,0 +1,47 @@
+module Flickr
+  class Client
+
+    ##
+    # Client for query and maniuplation of Flickr's photo data.
+    #
+    class Data < Flickr::Client
+
+      def initialize(access_token = nil)
+        access_token ||= Array.new(2, nil)
+
+        super() do |builder|
+          # Request
+          builder.use FaradayMiddleware::OAuth,
+            consumer_key:    api_key,
+            consumer_secret: shared_secret,
+            token:           access_token[0],
+            token_secret:    access_token[1]
+
+          # Response
+          builder.use Flickr::Middleware::CheckStatus
+          builder.use FaradayMiddleware::ParseJson
+          builder.use Flickr::Middleware::CheckOAuth
+        end
+      end
+
+      private
+
+      def do_request(http_method, flickr_method, params = {})
+        super(http_method, "rest") do |req|
+          req.params[:method] = flickr_method
+          req.params.update(params)
+        end
+      end
+
+      def url
+        if use_ssl?
+          "https://secure.flickr.com/services"
+        else
+          "http://api.flickr.com/services"
+        end
+      end
+
+    end
+
+  end
+end

data/lib/flickr/client/oauth.rb

@@ -0,0 +1,44 @@
+module Flickr
+  class Client
+
+    ##
+    # Client for OAuth authentication.
+    #
+    class OAuth < Flickr::Client
+
+      NO_CALLBACK = "oob".freeze
+
+      def initialize(request_token = nil)
+        request_token ||= Array.new(2, nil)
+
+        super() do |builder|
+          builder.use FaradayMiddleware::OAuth,
+            consumer_key:    api_key,
+            consumer_secret: shared_secret,
+            token:           request_token[0],
+            token_secret:    request_token[1]
+
+          builder.use Flickr::Middleware::ParseOAuth
+          builder.use Flickr::Middleware::CheckOAuth
+        end
+      end
+
+      def get_request_token(params = {})
+        params[:oauth_callback] ||= NO_CALLBACK
+        get "request_token", params
+      end
+
+      def get_access_token(params = {})
+        get "access_token", params
+      end
+
+      private
+
+      def url
+        "http://www.flickr.com/services/oauth"
+      end
+
+    end
+
+  end
+end

data/lib/flickr/client/upload.rb

@@ -0,0 +1,55 @@
+module Flickr
+  class Client
+
+    ##
+    # Client for uploading photos.
+    #
+    class Upload < Flickr::Client
+
+      def initialize(access_token = nil)
+        access_token ||= Array.new(2, nil)
+
+        super() do |builder|
+          # Request
+          builder.use FaradayMiddleware::OAuth,
+            consumer_key:    api_key,
+            consumer_secret: shared_secret,
+            token:           access_token[0],
+            token_secret:    access_token[1]
+          builder.use Faraday::Request::Multipart
+
+          # Response
+          builder.use Flickr::Middleware::CheckStatus
+          builder.use FaradayMiddleware::ParseXml
+          builder.use Flickr::Middleware::CheckOAuth
+        end
+      end
+
+      def upload(params = {})
+        params[:photo] = UploadIO(params[:photo])
+        post "upload", params
+      end
+
+      def replace(params = {})
+        params[:photo] = UploadIO(params[:photo])
+        post "replace", params
+      end
+
+      private
+
+      def UploadIO(file)
+        Faraday::UploadIO.new(file, file.content_type, file.path)
+      end
+
+      def url
+        if use_ssl?
+          "https://secure.flickr.com/services"
+        else
+          "http://api.flickr.com/services"
+        end
+      end
+
+    end
+
+  end
+end

data/lib/flickr/client.rb

@@ -2,56 +2,100 @@ require "faraday"
 require "faraday_middleware"
 require "flickr/middleware"
 
-class Flickr
-  class Client < Faraday::Connection
+module Flickr
+
+  ##
+  # This abstract class is the base for the client classes which communicate with
+  # the Flickr API. For example, the part of Flickr API for uploading photos need
+  # requests to be marked as multipart, while the part for querying data of photos
+  # doesn't need it. So it's obvious that we need separate classes.
+  #
+  # This class just extracts the common behaviour, like including the API key
+  # in requests.
+  #
+  # @private
+  #
+  class Client
+
+    extend Flickr::AutoloadHelper
+
+    autoload_dir "flickr/client",
+      :Data   => "data",
+      :Upload => "upload",
+      :OAuth  => "oauth"
+
     DEFAULTS = {
-      open_timeout: 4,
-      timeout: 6
+      open_timeout: 8,
+      timeout:      10,
     }
 
-    def initialize(access_token)
-      api_key, shared_secret = Flickr.configuration.fetch(:api_key, :shared_secret)
+    def initialize
+      @connection = Faraday.new(url, connection_options) do |builder|
+        builder.use Flickr::Middleware::CatchTimeout
+        yield builder if block_given?
+
+        builder.adapter :net_http
+      end
+    end
+
+    def get(*args, &block)
+      do_request(:get, *args, &block)
+    end
 
-      open_timeout = Flickr.configuration.open_timeout || DEFAULTS[:open_timeout]
-      timeout      = Flickr.configuration.timeout      || DEFAULTS[:timeout]
+    def post(*args, &block)
+      do_request(:post, *args, &block)
+    end
 
-      url = Flickr.configuration.secure ? "https://secure.flickr.com/services" : "http://api.flickr.com/services"
-      proxy = Flickr.configuration.proxy
+    private
 
-      params = {
-        url: url,
+    def connection_options
+      {
         params: {
           format: "json",
           nojsoncallback: 1,
-          api_key: api_key
+          api_key: api_key,
         },
         request: {
           open_timeout: open_timeout,
-          timeout: timeout
+          timeout: timeout,
         },
-        proxy: proxy
+        proxy: proxy,
       }
+    end
 
-      super(params) do |builder|
-        # Request
-        builder.use Middleware::Retry
-        builder.use FaradayMiddleware::OAuth,
-          consumer_key: api_key,
-          consumer_secret: shared_secret,
-          token: access_token.first,
-          token_secret: access_token.last
-        yield builder if block_given?
+    def url
+      # Should be implemented in subclasses
+    end
 
-        # Response
-        builder.use Middleware::CheckStatus
-        builder.use self.parser
-        builder.use Middleware::CheckOAuth
+    def do_request(http_method, *args, &block)
+      response = @connection.send(http_method, *args, &block)
+      response.body
+    end
 
-        builder.adapter :net_http
-      end
+    def api_key
+      Flickr.api_key
+    end
+
+    def shared_secret
+      Flickr.shared_secret
+    end
+
+    def open_timeout
+      Flickr.open_timeout || DEFAULTS[:open_timeout]
+    end
+
+    def timeout
+      Flickr.timeout || DEFAULTS[:timeout]
     end
+
+    def use_ssl?
+      !!Flickr.use_ssl
+    end
+
+    def proxy
+      Flickr.proxy
+    end
+
   end
-end
 
-require "flickr/client/methods_client"
-require "flickr/client/upload_client"
+end

data/lib/flickr/configuration.rb

@@ -1,25 +1,96 @@
-class Flickr
-  class Configuration
-    attr_accessor :api_key
-    attr_accessor :shared_secret
+module Flickr
 
-    attr_accessor :access_token_key
-    attr_accessor :access_token_secret
+  ##
+  # Provides general configuration options for the library.
+  #
+  module Configuration
 
+    ##
+    # @example
+    #     Flickr.configure do |config|
+    #       config.api_key = "..."
+    #       config.shared_secret = "..."
+    #       # ...
+    #     end
+    #
+    def configure
+      yield self
+      self
+    end
+
+    ##
+    # API key and shared secret are necessary for making API requests. You can apply
+    # for them [here][api_key].
+    #
+    # [api_key]: http://www.flickr.com/services/apps/create/apply
+    #
+    attr_accessor :api_key, :shared_secret
+
+    ##
+    # Required for authenticated requests.
+    #
+    #     config.access_token_key    = "KEY"
+    #     config.access_token_secret = "SECRET"
+    #
+    # For details on how to obtain it, take a look at the {Flickr::OAuth} module.
+    #
+    attr_accessor :access_token_key, :access_token_secret
+
+    ##
+    # @return [Array(string, string)]
+    # @private
+    #
+    def access_token
+      if access_token_key and access_token_secret
+        [access_token_key, access_token_secret]
+      end
+    end
+
+    ##
+    # Time to wait for the connection to Flickr to open. After that
+    # {Flickr::TimeoutError} is thrown.
+    #
+    # Default is `5` seconds.
+    #
     attr_accessor :open_timeout
+    ##
+    # Time to wait for the first block of response from Flickr. After that
+    # {Flickr::TimeoutError} is thrown.
+    #
+    # Default is `10` seconds.
+    #
     attr_accessor :timeout
 
-    attr_accessor :secure
+    ##
+    # You can choose to make requests over a secure connection (SSL).
+    #
+    #     config.use_ssl = true
+    #
+    # Default is `false`.
+    #
+    attr_accessor :use_ssl
+    alias secure= use_ssl=
+
+    ##
+    # You can choose to go over a proxy.
+    #
+    #     config.proxy = "http://proxy.com"
+    #
     attr_accessor :proxy
 
+    ##
+    # When retrieving photos from Flickr, you can enable automatic compatibility
+    # with a pagination library.
+    #
+    #     config.pagination = :will_paginate
+    #
+    # Supports [WillPaginate][will_paginate] and [Kaminari][kaminari].
+    #
+    # [will_paginate]: https://github.com/mislav/will_paginate
+    # [kaminari]: https://github.com/amatsuda/kaminari
+    #
     attr_accessor :pagination
 
-    def fetch(*attributes)
-      attributes.map { |attribute| send(attribute) }
-    end
-
-    def access_token
-      [access_token_key, access_token_secret]
-    end
   end
+
 end

data/lib/flickr/error.rb

@@ -0,0 +1,58 @@
+module Flickr
+
+  class Error < StandardError
+  end
+
+  ##
+  # This error is raised when there is an OAuth error (for example when the
+  # access token is missing on requests which require authentication).
+  #
+  class OAuthError < Error
+  end
+
+  ##
+  # This error is raised when there is an error in the request.
+  #
+  # @see #code
+  #
+  class ApiError < Error
+    ##
+    # Flickr's code of the error. The list possible errors and their codes is
+    # shown below every API method on {http://flickr.com/services/api}.
+    # For example:
+    #
+    #   - 100: There is no API key
+    #   - 105: Service currently unavailable
+    #   - ...
+    #
+    # @example
+    #   begin
+    #     Flickr.photos.get_recent
+    #   rescue Flickr::ApiError => error
+    #     puts "There is no API key" if error.code == 100
+    #   end
+    # @return [Integer]
+    #
+    attr_reader :code
+
+    ##
+    # @private
+    #
+    def initialize(message, code = nil)
+      super(message)
+      @code = code.to_i
+    end
+
+    def message
+      "#{code}: #{super}"
+    end
+  end
+
+  ##
+  # @see Flickr::Configuration#open_timeout
+  # @see Flickr::Configuration#timeout
+  #
+  class TimeoutError < Error
+  end
+
+end