flickr-objects 0.2.0 → 0.3.0

data/lib/flickr/middleware.rb

@@ -1,10 +1,46 @@
 require "cgi"
 require "faraday"
-require "flickr/errors"
 require "faraday_middleware/response_middleware"
+require "flickr/error"
 
-class Flickr
+module Flickr
+
+  ##
+  # A place for some custom middlewares for the API requests, mostly for translating
+  # Flickr errors into Ruby errors.
+  #
+  # @private
+  #
   module Middleware
+
+    ##
+    # Translates `Faraday::Error::TimeoutError` into `Flickr::TimeoutError`.
+    #
+    # @raise Flickr::TimeoutError
+    #
+    class CatchTimeout
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        begin
+          @app.call(env)
+        rescue Faraday::Error::TimeoutError
+          raise Flickr::TimeoutError
+        end
+      end
+    end
+
+    ##
+    # Checks for errors in responses from Flickr, in which case it raises a
+    # `Flickr::ApiError` which contains the code and the message found in the response.
+    #
+    # It's a bit ugly because Flickr returns different error formats when uploading
+    # than when querying, so we need to take care of all cases.
+    #
+    # @raise Flickr::ApiError
+    #
     class CheckStatus < Faraday::Response::Middleware
       def on_complete(env)
         env[:body] = env[:body]["rsp"] || env[:body]
@@ -12,21 +48,32 @@ class Flickr
         if env[:body]["stat"] != "ok"
           message = env[:body]["message"] || env[:body]["err"]["msg"]
           code = env[:body]["code"] || env[:body]["err"]["code"]
-          raise ApiError.new(message, code)
+
+          raise Flickr::ApiError.new(message, code)
         end
       end
     end
 
+    ##
+    # Checks for OAuth errors. They are in a different form than standard Flickr errors,
+    # so a special middleware is required.
+    #
+    # @raise Flickr::OAuthError
+    #
     class CheckOAuth < Faraday::Response::Middleware
       def on_complete(env)
         if env[:status] != 200
           message = CGI.parse(env[:body])["oauth_problem"].first
           pretty_message = message.gsub('_', ' ').capitalize
-          raise OAuthError, pretty_message
+          raise Flickr::OAuthError, pretty_message
         end
       end
     end
 
+    ##
+    # Parses OAuth respones (which are in form of URL parameters). It subclasses
+    # FaradayMiddleware's internal `ResponseMiddleware` class for convenient parsing.
+    #
     class ParseOAuth < FaradayMiddleware::ResponseMiddleware
       define_parser do |body|
         CGI.parse(body).inject({}) do |hash, (key, value)|
@@ -35,29 +82,6 @@ class Flickr
       end
     end
 
-    # A copy from Faraday (credits to @mislav)
-    class Retry < Faraday::Middleware
-      def initialize(app, options = {})
-        super(app)
-        @retries, options = options, {} if options.is_a? Integer
-        @retries ||= options.fetch(:max, 2).to_i
-        @sleep     = options.fetch(:interval, 0).to_f
-        @errmatch  = options.fetch(:exceptions) { [Errno::ETIMEDOUT, 'Timeout::Error', Faraday::Error::TimeoutError] }
-      end
-
-      def call(env)
-        retries = @retries
-        begin
-          @app.call(env)
-        rescue *@errmatch => error
-          if retries > 0
-            retries -= 1
-            sleep @sleep if @sleep > 0
-            retry
-          end
-          raise Flickr::TimeoutError, error.message
-        end
-      end
-    end
   end
+
 end

data/lib/flickr/oauth.rb

@@ -1,109 +1,124 @@
-require "faraday"
-require "faraday_middleware"
-require "flickr/middleware"
-
-class Flickr
+require "uri"
+
+module Flickr
+
+  ##
+  # Interface for authenticating through OAuth.
+  #
+  # Example:
+  #
+  #     request_token = Flickr::OAuth.get_request_token
+  #     request_token.authorize_url
+  #
+  #     # ... user visits the authorize URL, and gets the verifier ...
+  #
+  #     access_token = request_token.get_access_token(verifier)
+  #
+  #     access_token.key       # "..."
+  #     access_token.secret    # "..."
+  #     access_token.user_info # {username: "...", nsid: "...", ...}
+  #
   module OAuth
-    URL = "http://www.flickr.com/services/oauth".freeze
-    NO_CALLBACK = 'oob'.freeze
-    DEFAULTS = Client::DEFAULTS
 
     extend self
 
-    def get_request_token(options = {})
-      response = connection.get "request_token" do |req|
-        req.params[:oauth_callback] = options[:callback_url] || NO_CALLBACK
-      end
-
-      RequestToken.new(response.body)
+    ##
+    # @param params [Hash]
+    # @option params [String] :callback_url If the user is being authorized
+    #   through another web application, this parameter can be used to redirect
+    #   the user back to that application.
+    #
+    # @return [Flickr::OAuth::RequestToken]
+    #
+    def get_request_token(params = {})
+      params[:oauth_callback] = params.delete(:callback_url)
+      response = client.get_request_token(params)
+      RequestToken.new(response[:oauth_token], response[:oauth_token_secret])
     end
 
-    def get_access_token(verifier, request_token)
-      response = connection(request_token.to_a).get "access_token" do |req|
-        req.params[:oauth_verifier] = verifier
-      end
-
-      AccessToken.new(response.body)
+    ##
+    # @param oauth_verifier [String] The code provided by Flickr after visiting
+    #   the authorize URL.
+    # @param request_token [RequestToken, Array(String, String)]
+    #
+    # @return [Flickr::OAuth::AccessToken]
+    #
+    def get_access_token(oauth_verifier, request_token)
+      params = {oauth_verifier: oauth_verifier}
+      response = client(request_token.to_a).get_access_token(params)
+      AccessToken.new(response[:oauth_token], response[:oauth_token_secret],
+        response.reject { |key, value| [:oauth_token, :oauth_token_secret].include?(key) })
     end
 
     class Token
-      attr_reader :token, :secret
-
-      def initialize(*args)
-        if args.first.is_a?(Hash)
-          @token = args.first[:oauth_token]
-          @secret = args.first[:oauth_token_secret]
-        else
-          @token = args.first
-          @secret = args.last
-        end
+      attr_reader :key, :secret
+      alias token key
+
+      ##
+      # @param key [String]
+      # @param secret [String]
+      #
+      def initialize(key, secret)
+        @key, @secret = key, secret
       end
 
       def to_a
-        [token, secret]
+        [key, secret]
       end
     end
 
     class RequestToken < Token
+      ##
+      # @param params [Hash]
+      # @option params [String] :perms Optional. Can be `read`, `write`, or `delete`,
+      #   depending on which permissions you want (for example, "flickr.photos.delete"
+      #   requires `delete` permissions). If not specified, defaults to `write`.
+      #
       def authorize_url(params = {})
-        require 'uri'
-        url = URI.parse(URL)
-        url.path += '/authorize'
+        url = URI.parse("http://www.flickr.com/services/oauth")
+        url.path += "/authorize"
         query_params = {oauth_token: token}.merge(params)
-        url.query = query_params.map { |k,v| "#{k}=#{v}" }.join('&')
+        url.query = query_params.map { |k, v| "#{k}=#{v}" }.join("&")
         url.to_s
       end
 
-      def get_access_token(verifier)
-        OAuth.get_access_token(verifier, self)
+      ##
+      # @param oauth_verifier [String]
+      # @see Flickr::OAuth.get_access_token.
+      #
+      def get_access_token(oauth_verifier)
+        Flickr::OAuth.get_access_token(oauth_verifier, self)
       end
     end
 
     class AccessToken < Token
+      ##
+      # Holds user's information after authentication.
+      #
+      # @example
+      #   {
+      #     fullname:  "Janko Marohnić",
+      #     user_nsid: "78733179@N04",
+      #     username:  "@janko-m"
+      #   }
+      #
       attr_reader :user_info
 
-      def initialize(info)
-        super
-        @user_info = info.tap do |info|
-          info.delete(:oauth_token)
-          info.delete(:oauth_token_secret)
-        end
+      ##
+      # @private
+      #
+      def initialize(key, secret, user_info)
+        super(key, secret)
+        @user_info = user_info
       end
     end
 
     private
 
-    def connection(request_token = nil)
-      api_key, shared_secret = Flickr.configuration.fetch(:api_key, :shared_secret)
-
-      open_timeout = Flickr.configuration.open_timeout || DEFAULTS[:open_timeout]
-      timeout      = Flickr.configuration.timeout      || DEFAULTS[:timeout]
-
-      url = URL
-      proxy = Flickr.configuration.proxy
-
-      params = {
-        url: url,
-        request: {
-          open_timeout: open_timeout,
-          timeout: timeout
-        },
-        proxy: proxy
-      }
-
-      Faraday.new(params) do |builder|
-        builder.use Middleware::Retry
-        builder.use FaradayMiddleware::OAuth,
-         consumer_key: api_key,
-         consumer_secret: shared_secret,
-         token: Array(request_token).first,
-         token_secret: Array(request_token).last
-
-        builder.use Middleware::ParseOAuth
-        builder.use Middleware::CheckOAuth
-
-        builder.adapter :net_http
-      end
+    def client(request_token = nil)
+      Flickr::Client::OAuth.new(request_token)
     end
+
   end
+
 end

data/lib/flickr/object/attribute_locations/list.rb

@@ -0,0 +1,25 @@
+module Flickr
+  class Object
+
+    class List
+
+      attributes.add_locations(
+        current_page: [
+          -> { @attributes["page"] },
+        ],
+        per_page: [
+          -> { @attributes["per_page"] },
+          -> { @attributes["perpage"] },
+        ],
+        total_entries: [
+          -> { @attributes["total"] },
+        ],
+        total_pages: [
+          -> { @attributes["pages"] },
+        ],
+      )
+
+    end
+
+  end
+end

data/lib/flickr/object/attribute_locations/location.rb

@@ -0,0 +1,29 @@
+module Flickr
+  class Object
+
+    class Location
+
+      Area.attributes.add_locations(
+        name: [
+          -> { @attributes["_content"] },
+        ],
+        woe_id: [
+          -> { @attributes["woeid"] },
+        ],
+      )
+
+      attributes.add_locations(
+        woe_id: [
+          -> { @attributes["woeid"] },
+        ],
+        indoors: [
+          -> { context == 1 },
+        ],
+        outdoors: [
+          -> { context == 2 },
+        ],
+      )
+    end
+
+  end
+end

data/lib/flickr/object/attribute_locations/permissions.rb

@@ -0,0 +1,31 @@
+module Flickr
+  class Object
+
+    class Permissions
+
+      attributes.add_locations(
+        can_comment: [
+          -> { @attributes["cancomment"] },
+          -> { @attributes["can_comment"] }
+        ],
+        can_add_meta: [
+          -> { @attributes["canaddmeta"] },
+        ],
+        can_download: [
+          -> { @attributes["candownload"] },
+        ],
+        can_blog: [
+          -> { @attributes["canblog"] },
+        ],
+        can_print: [
+          -> { @attributes["canprint"] },
+        ],
+        can_share: [
+          -> { @attributes["canshare"] },
+        ],
+      )
+
+    end
+
+  end
+end

data/lib/flickr/object/attribute_locations/person/upload_status.rb

@@ -0,0 +1,32 @@
+module Flickr
+  class Object
+    class Person
+
+      class UploadStatus
+
+        Month.attributes.add_locations(
+          maximum: [
+            -> { @attributes["maxkb"] / 1024 },
+          ],
+          used: [
+            -> { @attributes["usedkb"] / 1024 },
+          ],
+          remaining: [
+            -> { @attributes["remainingkb"] / 1024 },
+          ],
+        )
+
+        attributes.add_locations(
+          current_month: [
+            -> { @attributes["bandwidth"] },
+          ],
+          maximum_photo_size: [
+            -> { @attributes["filesize"]["maxmb"] },
+          ],
+        )
+
+      end
+
+    end
+  end
+end

data/lib/flickr/object/attribute_locations/person.rb

@@ -0,0 +1,78 @@
+module Flickr
+  class Object
+
+    class Person
+
+      attributes.add_locations(
+        id: [
+          -> { @attributes["nsid"] },
+        ],
+        nsid: [
+          -> { id },
+        ],
+        username: [
+          -> { @attributes["username"]["_content"] },
+        ],
+        real_name: [
+          -> { @attributes["realname"].fetch("_content") },
+          -> { @attributes["realname"] },
+        ],
+        icon_server: [
+          -> { @attributes["iconserver"] },
+        ],
+        icon_farm: [
+          -> { @attributes["iconfarm"] },
+        ],
+        buddy_icon_url: [
+          -> {
+            if icon_farm && icon_server && id
+              if icon_server > 0
+                "http://farm#{icon_farm}.staticflickr.com/#{icon_server}/buddyicons/#{id}.jpg"
+              else
+                "http://www.flickr.com/images/buddyicon.jpg"
+              end
+            end
+          },
+        ],
+        has_pro_account: [
+          -> { @attributes["ispro"] },
+        ],
+        location: [
+          -> { @attributes["location"]["_content"] },
+        ],
+        time_zone: [
+          -> { @attributes["timezone"] },
+        ],
+        description: [
+          -> { @attributes["description"]["_content"] },
+        ],
+        photos_url: [
+          -> { @attributes["photosurl"]["_content"] },
+        ],
+        profile_url: [
+          -> { @attributes["profileurl"]["_content"] },
+        ],
+        mobile_url: [
+          -> { @attributes["mobileurl"]["_content"] },
+        ],
+        first_photo_taken: [
+          -> { @attributes["photos"]["firstdatetaken"]["_content"] },
+        ],
+        first_photo_uploaded: [
+          -> { @attributes["photos"]["firstdate"]["_content"] },
+        ],
+        favorited_at: [
+          -> { @attributes["favedate"] },
+        ],
+        photos_count: [
+          -> { @attributes["photos"]["count"]["_content"] },
+        ],
+        photo_views_count: [
+          -> { @attributes["photos"]["views"]["_content"] },
+        ],
+      )
+
+    end
+
+  end
+end

data/lib/flickr/object/attribute_locations/photo/exif.rb

@@ -0,0 +1,29 @@
+module Flickr
+  class Object
+    class Photo
+
+      class Exif
+
+        attributes.add_locations(
+          items: [
+            -> { @attributes },
+          ],
+        )
+
+        Item.attributes.add_locations(
+          tagspace_id: [
+            -> { @attributes["tagspaceid"] },
+          ],
+          raw: [
+            -> { @attributes["raw"]["_content"] },
+          ],
+          clean: [
+            -> { @attributes["clean"]["_content"] },
+          ],
+        )
+
+      end
+
+    end
+  end
+end

data/lib/flickr/object/attribute_locations/photo/note.rb

@@ -0,0 +1,36 @@
+module Flickr
+  class Object
+    class Photo
+
+      class Note
+
+        attributes.add_locations(
+          author: [
+            -> {
+              if @attributes["author"]
+                {
+                  "id"       => @attributes["author"],
+                  "username" => @attributes["authorname"],
+                }
+              end
+            },
+          ],
+          coordinates: [
+            -> { [@attributes["x"], @attributes["y"]] if @attributes["x"] },
+          ],
+          width: [
+            -> { @attributes["w"] },
+          ],
+          height: [
+            -> { @attributes["h"] },
+          ],
+          content: [
+            -> { @attributes["_content"] },
+          ],
+        )
+
+      end
+
+    end
+  end
+end

data/lib/flickr/object/attribute_locations/photo/tag.rb

@@ -0,0 +1,23 @@
+module Flickr
+  class Object
+    class Photo
+
+      class Tag
+
+        attributes.add_locations(
+          author: [
+            -> { {"id" => @attributes.fetch("author")} },
+          ],
+          content: [
+            -> { @attributes["_content"] },
+          ],
+          machine_tag: [
+            -> { @attributes["machine_tag"] },
+          ],
+        )
+
+      end
+
+    end
+  end
+end