flickr-objects 0.0.1

data/README.md

@@ -0,0 +1,167 @@
+# Flickr Objects
+
+This gem is an object-oriented wrapper for the [Flickr API](http://flickr.com/api).
+To see its capability, take a look at this nice demonstration:
+
+[http://janko-m.github.com/flickr-objects/](http://janko-m.github.com/flickr-objects/)
+
+## Installation and setup
+
+Add it to your `Gemfile`, and run `bundle install`.
+
+```ruby
+gem "flickr-objects"
+```
+
+Now create an initializer where you set your Flickr credentials.
+
+```ruby
+Flickr.configure do |config|
+  config.api_key = "API_KEY"
+  config.shared_secret = "SHARED_SECRET"
+end
+```
+
+If you don't have your API key and shared secret yet, you can apply for them
+[here](http://www.flickr.com/services/apps/create/apply).
+
+## Usage
+
+Let's start with a general example.
+
+```ruby
+person_id = "78733179@N04"
+person = Flickr.people.find(preson_id)
+photos = person.get_public_photos #=> API request
+
+photo = photos.first
+photo.id                 #=> "231233252"
+photo.title              #=> "My cat"
+photo.visibility.public? #=> true
+photo.description        #=> nil
+photo.get_info!          # makes an API request
+photo.description        #=> "He's trying to catch a fly"
+```
+
+So, we've seen 2 API requests here:
+
+- `person.get_public_photos` (`Flickr::Person#get_public_photos`)
+- `photo.get_info!` (`Flickr::Photo#get_info!`)
+
+They correspond to the API methods listed on Flickr's official [API page](http://flickr.com/api).
+`Flickr::Person#get_public_photos` corresponds to `flickr.people.getPublicPhotos`, and
+`Flickr::Photo#get_info!` corresponds to `flickr.photos.getInfo`.
+
+Let's say you want to call Flickr's `flickr.photosets.getList`. To find out how to call it,
+you can use `Flickr.api_methods` in the console. This method acts like a
+documentation for API methods. So, for example:
+
+```ruby
+Flickr.api_methods["flickr.photosets.getList"] #=> ["Flickr::Person#get_sets"]
+```
+
+Now you found out that it corresponds to `Flickr::Person#get_sets`, which means
+you can call it like this:
+
+```ruby
+sets = Flickr.people.find(person_id).get_sets
+sets.first.id #=> "12312324"
+```
+
+## Sizes
+
+```ruby
+person = Flickr.person.find(person_id)
+photo = person.get_public_photos(sizes: :all).first
+
+photo.small!(320)
+photo.source_url #=> "http://farm9.staticflickr.com/8191/8130464513_780e01decd_n.jpg"
+photo.width      #=> 320
+photo.height     #=> 280
+
+photo.medium!(500)
+photo.width      #=> 500
+```
+
+## Authenticated requests
+
+If you need to make authenticated API requests (which you'll often want), you can create a kind
+of a instance, assigning to it user's access token. That instance then has the same interface as `Flickr`.
+
+```ruby
+flickr = Flickr.new("ACCESS_TOKEN_KEY", "ACCESS_TOKEN_SECRET")
+
+flickr.test_login #=> {"id" => "78733179@N04", "username" => ...}
+flickr.people.find(person_id).get_public_photos
+# ...
+```
+
+If you're in a Rails application, probably the best solution for authenticating
+users through Flickr (thus obtaining their access tokens) is the
+[omniauth-flickr](https://github.com/timbreitkreutz/omniauth-flickr) gem.
+Another (more lightweight) solution would be [flickr-login](https://github.com/janko-m/flickr-login).
+
+You can also assign the access token globally in your configuration.
+
+```ruby
+Flickr.configure do |config|
+  config.api_key = "API_KEY"
+  config.shared_secret = "SHARED_SECRET"
+  config.access_token_key = "ACCESS_TOKEN_KEY"
+  config.access_token_secret = "ACCESS_TOKEN_SECRET"
+end
+```
+
+This is useful if you're, for example, using Flickr as a photo storage in your
+application, and that access token is actually yours.
+
+
+## Upload
+
+```ruby
+photo_id = Flickr.upload("/path/to/photo.jpg", title: "Dandelions")
+photo = Flickr.photos.find(photo_id).get_info!
+photo.title #=> "Dandelions"
+```
+
+You can also upload asynchronously, which will return the upload ticket, which
+you can then use to check when the upload has finished.
+
+```ruby
+ticket_id = Flickr.upload("/path/to/photo.jpg", title: "Dandelions", ansync: true)
+ticket = Flickr.check_upload_tickets(ticket_id).first
+ticket.complete? #=> false
+
+sleep 1
+
+ticket = Flickr.check_upload_tickets(ticked_id).first
+ticket.complete? #=> true
+ticket.photo.id #=> "232594385"
+```
+
+## Attributes
+
+For the list of attributes that Flickr objects have, the best place to look at
+is the source code. For example, list of common attributes that `Flickr::Photo`
+and `Flickr::Video` have can be found in `lib/flickr/objects/media.rb`.
+
+![Flickr::Media](http://farm9.staticflickr.com/8195/8133340670_38c60aaca7.jpg)
+
+As you can see, it is very readable ;)
+
+## Few words
+
+Most of the API methods are not covered yet (because they are so many for one
+person). All the most important API methods should be implemented, so a person
+with normal demands should have everything he needs. If you feel like some API
+methods should have higher priority to be covered, feel free to post it in
+issues, and I will try to get it covered in the next version. Pull requests are
+also very welcome :)
+
+## Social
+
+You can follow me on Twitter, I'm [@m_janko](https://twitter.com/m_janko).
+
+## License
+
+This project is released under the [MIT license](https://github.com/janko-m/flickr-objects/blob/master/LICENSE).

data/lib/flickr/api/flickr.rb

@@ -0,0 +1,40 @@
+class Flickr
+  api_methods = proc do
+    def upload(media, params = {})
+      response = upload_client.upload(media, params)
+      params[:async] == 1 ? response["ticketid"] : response["photoid"]
+    end
+
+    def replace(media, id, params = {})
+      response = upload_client.replace(media, id, params)
+      params[:async] == 1 ? response["ticketid"] : response["photoid"]
+    end
+
+    def check_upload_tickets(tickets, params = {})
+      response = client.get flickr_method(__method__), params.merge(tickets: tickets.to_s)
+      Collection.new(response["uploader"].delete("ticket"), UploadTicket, response["uploader"], client)
+    end
+    api_method :check_upload_tickets, "flickr.photos.upload.checkTickets"
+
+    def test_login(params = {})
+      client.get flickr_method(__method__), params
+    end
+    api_method :test_login, "flickr.test.login"
+
+    def test_echo(params = {})
+      client.get flickr_method(__method__), params
+    end
+    api_method :test_echo, "flickr.test.echo"
+
+    def test_null(params = {})
+      client.get flickr_method(__method__), params
+    end
+    api_method :test_null, "flickr.test.null"
+  end
+
+  def self.api_method(*args) class_api_method(*args) end
+  instance_eval(&api_methods)
+
+  def self.api_method(*args) instance_api_method(*args) end
+  class_eval(&api_methods)
+end

data/lib/flickr/api/media.rb

@@ -0,0 +1,63 @@
+class Flickr
+  class Media < Object
+    def add_tags(tags, params = {})
+      client.post flickr_method(__method__), params.merge(photo_id: id, tags: tags)
+      tags
+    end
+    instance_api_method :add_tags, "flickr.photos.addTags"
+
+    def delete(params = {})
+      client.post flickr_method(__method__), params.merge(photo_id: id)
+      self
+    end
+    instance_api_method :delete, "flickr.photos.delete"
+
+    def self.get_from_contacts(params = {})
+      response = client.get flickr_method(__method__), handle_extras(params)
+      Collection.new(response["photos"].delete("photo"), Media, response["photos"], client)
+    end
+    class_api_method :get_from_contacts, "flickr.photos.getContactsPhotos"
+
+    def get_info!(params = {})
+      response = client.get flickr_method(__method__), params.merge(photo_id: id)
+      @hash.update(response["photo"])
+      self
+    end
+    instance_api_method :get_info!, "flickr.photos.getInfo"
+
+    def get_sizes!(params = {})
+      response = client.get flickr_method(__method__), params.merge(photo_id: id)
+      @hash.update(response["sizes"])
+      self
+    end
+    instance_api_method :get_sizes!, "flickr.photos.getSizes"
+
+    def remove_tag(tag_id, params = {})
+      client.post flickr_method(__method__), params.merge(photo_id: id, tag_id: tag_id)
+      tag_id
+    end
+    instance_api_method :remove_tag, "flickr.photos.removeTag"
+
+    def self.search(params = {})
+      response = client.get flickr_method(__method__), handle_extras(params)
+      Collection.new(response["photos"].delete("photo"), self, response["photos"], client)
+    end
+    class_api_method :search, "flickr.photos.search"
+
+    def set_content_type(content_type, params = {})
+      client.post flickr_method(__method__), params.merge(photo_id: id, content_type: content_type)
+      content_type
+    end
+    instance_api_method :set_content_type, "flickr.photos.setContentType"
+    alias content_type= set_content_type
+    instance_api_method :content_type=, "flickr.photos.setContentType"
+
+    def set_tags(tags, params = {})
+      client.post flickr_method(__method__), params.merge(photo_id: id, tags: tags)
+      tags
+    end
+    instance_api_method :set_tags, "flickr.photos.setTags"
+    alias tags= set_tags
+    instance_api_method :tags=, "flickr.photos.setTags"
+  end
+end

data/lib/flickr/api/person.rb

@@ -0,0 +1,70 @@
+class Flickr
+  class Person < Object
+    def self.find_by_email(email, params = {})
+      response = client.get flickr_method(__method__), params.merge(find_email: email)
+      new(response["user"], client)
+    end
+    class_api_method :find_by_email, "flickr.people.findByEmail"
+
+    def self.find_by_username(username, params = {})
+      response = client.get flickr_method(__method__), params.merge(username: username)
+      new(response["user"], client)
+    end
+    class_api_method :find_by_username, "flickr.people.findByUsername"
+
+    def get_info!(params = {})
+      response = client.get flickr_method(__method__), params.merge(user_id: id)
+      @hash.update(response["person"])
+      self
+    end
+    instance_api_method :get_info!, "flickr.people.getInfo"
+
+    def get_photos(params = {})
+      get_media(params).select { |object| object.is_a?(Flickr::Photo) }
+    end
+    instance_api_method :get_photos, "flickr.people.getPhotos"
+    def get_videos(params = {})
+      get_media(params).select { |object| object.is_a?(Flickr::Video) }
+    end
+    instance_api_method :get_videos, "flickr.people.getPhotos"
+    def get_media(params = {})
+      response = client.get flickr_method(__method__), handle_extras(params.merge(user_id: id))
+      Collection.new(response["photos"].delete("photo"), Media, response["photos"], client)
+    end
+    instance_api_method :get_media, "flickr.people.getPhotos"
+
+    def get_public_photos(params = {})
+      get_public_media(params).select { |object| object.is_a?(Flickr::Photo) }
+    end
+    instance_api_method :get_public_photos, "flickr.people.getPublicPhotos"
+    def get_public_videos(params = {})
+      get_public_media(params).select { |object| object.is_a?(Flickr::Video) }
+    end
+    instance_api_method :get_public_videos, "flickr.people.getPublicPhotos"
+    def get_public_media(params = {})
+      response = client.get flickr_method(__method__), handle_extras(params.merge(user_id: id))
+      Collection.new(response["photos"].delete("photo"), Media, response["photos"], client)
+    end
+    instance_api_method :get_public_media, "flickr.people.getPublicPhotos"
+
+    def get_public_photos_from_contacts(params = {})
+      get_public_media_from_contacts(params).select {|object| object.is_a?(Flickr::Photo) }
+    end
+    instance_api_method :get_public_photos_from_contacts, "flickr.photos.getContactsPublicPhotos"
+    def get_public_videos_from_contacts(params = {})
+      get_public_media_from_contacts(params).select {|object| object.is_a?(Flickr::Video) }
+    end
+    instance_api_method :get_public_videos_from_contacts, "flickr.photos.getContactsPublicPhotos"
+    def get_public_media_from_contacts(params = {})
+      response = client.get flickr_method(__method__), handle_extras(params.merge(user_id: id))
+      Collection.new(response["photos"].delete("photo"), Media, response["photos"], client)
+    end
+    instance_api_method :get_public_media_from_contacts, "flickr.photos.getContactsPublicPhotos"
+
+    def get_sets(params = {})
+      response = client.get flickr_method(__method__), params.merge(user_id: id)
+      Collection.new(response["photosets"].delete("photoset"), Set, response["photosets"], client)
+    end
+    instance_api_method :get_sets, "flickr.photosets.getList"
+  end
+end

data/lib/flickr/api/photo.rb

@@ -0,0 +1,11 @@
+class Flickr
+  class Photo < Media
+    def self.get_from_contacts(params = {})
+      super(params).select { |media| media.is_a?(self) }
+    end
+
+    def self.search(params = {})
+      super(params.merge(media: "photos"))
+    end
+  end
+end

data/lib/flickr/api/set.rb

@@ -0,0 +1,70 @@
+class Flickr
+  class Set < Object
+    def add_photo(media_id, params = {})
+      client.post flickr_method(__method__), params.merge(photoset_id: id, photo_id: media_id)
+    end
+    instance_api_method :add_photo, "flickr.photosets.addPhoto"
+    alias add_video add_photo
+    instance_api_method :add_video, "flickr.photosets.addPhoto"
+    alias add_media add_photo
+    instance_api_method :add_media, "flickr.photosets.addPhoto"
+
+    def self.create(params = {})
+      response = client.post flickr_method(__method__), params
+      new(response["photoset"], client)
+    end
+    class_api_method :create, "flickr.photosets.create"
+
+    def delete(params = {})
+      client.post flickr_method(__method__), params.merge(photoset_id: id)
+      self
+    end
+    instance_api_method :delete, "flickr.photosets.delete"
+
+    def edit_photos(params = {})
+      client.post flickr_method(__method__), params.merge(photoset_id: id)
+      self
+    end
+    instance_api_method :edit_photos, "flickr.photosets.editPhotos"
+    alias edit_videos edit_photos
+    instance_api_method :edit_videos, "flickr.photosets.editPhotos"
+    alias edit_media edit_photos
+    instance_api_method :edit_media, "flickr.photosets.editPhotos"
+
+    def get_info!(params = {})
+      response = client.get flickr_method(__method__), params.merge(photoset_id: id)
+      @hash.update(response["photoset"])
+      self
+    end
+    instance_api_method :get_info!, "flickr.photosets.getInfo"
+
+    def get_photos(params = {})
+      get_media(params.merge(media: "photos"))
+    end
+    instance_api_method :get_photos, "flickr.photosets.getPhotos"
+    def get_videos(params = {})
+      get_media(params.merge(media: "videos"))
+    end
+    instance_api_method :get_videos, "flickr.photosets.getPhotos"
+    def get_media(params = {})
+      response = client.get flickr_method(__method__), handle_extras(params.merge(photoset_id: id))
+      Collection.new(response["photoset"].delete("photo"), Media, response["photoset"], client)
+    end
+    instance_api_method :get_media, "flickr.photosets.getPhotos"
+
+    def remove_photos(media_id, params = {})
+      client.post flickr_method(__method__), params.merge(photoset_id: id, photo_ids: media_id)
+    end
+    instance_api_method :remove_photos, "flickr.photosets.removePhotos"
+    alias remove_videos remove_photos
+    instance_api_method :remove_videos, "flickr.photosets.removePhotos"
+    alias remove_media remove_photos
+    instance_api_method :remove_media, "flickr.photosets.removePhotos"
+
+    instance_api_method :remove_media, "flickr.photosets.removePhoto"
+    alias remove_photo remove_photos
+    instance_api_method :remove_photo, "flickr.photosets.removePhoto"
+    alias remove_video remove_photos
+    instance_api_method :remove_video, "flickr.photosets.removePhoto"
+  end
+end

data/lib/flickr/api/video.rb

@@ -0,0 +1,11 @@
+class Flickr
+  class Video < Media
+    def self.get_from_contacts(params = {})
+      super(params).select { |media| media.is_a?(self) }
+    end
+
+    def self.search(params = {})
+      super(params.merge(media: "videos"))
+    end
+  end
+end

data/lib/flickr/api.rb

@@ -0,0 +1,50 @@
+require "flickr/client"
+require "flickr/api_caller"
+
+class Flickr
+  include ApiCaller
+
+  def initialize(*access_token)
+    @access_token = access_token
+  end
+
+  def client
+    @client ||= MethodsClient.new(@access_token)
+  end
+
+  def upload_client
+    @upload_client ||= UploadClient.new(@access_token)
+  end
+
+  def self.client
+    @client ||= MethodsClient.new(configuration.access_token)
+  end
+
+  def self.upload_client
+    @upload_client ||= UploadClient.new(configuration.access_token)
+  end
+end
+
+require "flickr/api/flickr"
+
+class Flickr
+  def self.map_interface(method, klass)
+    define_method(method) do
+      klass.tap do |klass|
+        klass.instance_variable_set("@client", client)
+      end
+    end
+
+    define_singleton_method(method) do
+      klass.tap do |klass|
+        klass.instance_variable_set("@client", client)
+      end
+    end
+  end
+
+  map_interface :media,  Media
+  map_interface :photos, Photo
+  map_interface :videos, Video
+  map_interface :people, Person
+  map_interface :sets,   Set
+end

data/lib/flickr/api_caller.rb

@@ -0,0 +1,95 @@
+class Flickr
+  module ApiCaller
+
+    def self.included(base)
+      base.send(:include, ClientMethods) unless base == Flickr
+      base.send(:include, ApiMethods)
+      base.send(:include, ParamsFixingMethods)
+    end
+
+    module ClientMethods
+      def self.included(base)
+        base.send(:include, Methods)
+        base.send(:extend,  Methods)
+      end
+
+      module Methods
+        attr_reader :client
+      end
+    end
+
+    module ApiMethods
+      def self.included(base)
+        base.send(:include, InstanceMethods)
+        base.send(:extend, ClassMethods)
+      end
+
+      module ClassMethods
+        def instance_api_method(method, flickr_method)
+          Flickr.api_methods[flickr_method] << "#{self.name}##{method}"
+          children.each { |child| Flickr.api_methods[flickr_method] << "#{child.name}##{method}" } if respond_to?(:children)
+        end
+
+        def class_api_method(method, flickr_method)
+          Flickr.api_methods[flickr_method] << "#{self.name}.#{method}"
+          children.each { |child| Flickr.api_methods[flickr_method] << "#{child.name}.#{method}" } if respond_to?(:children)
+        end
+
+        def flickr_method(method_name)
+          resolve_flickr_method("#{self.name}.#{method_name}")
+        end
+
+        def resolve_flickr_method(full_method_name)
+          pair = Flickr.api_methods.find { |key, value| value.include?(full_method_name) }
+          pair.first
+
+        rescue NoMethodError
+          raise "method #{full_method_name} is not registered"
+        end
+      end
+
+      module InstanceMethods
+        def flickr_method(method_name)
+          self.class.resolve_flickr_method("#{self.class.name}##{method_name}")
+        end
+      end
+    end
+
+    module ParamsFixingMethods
+      def self.included(base)
+        base.send(:include, Methods)
+        base.send(:extend,  Methods)
+      end
+
+      module Methods
+        def handle_extras(params)
+          include_sizes(include_media(params))
+        end
+
+        def include_media(params)
+          include_in_extras(params, "media")
+        end
+
+        def include_sizes(params)
+          return params if params[:sizes].nil?
+
+          abbrs = case params[:sizes]
+                  when :all
+                    Media::SIZES.values
+                  else
+                    params[:sizes].map { |size| Media::SIZES[size] }
+                  end
+          urls = abbrs.map { |abbr| "url_#{abbr}" }.join(",")
+          include_in_extras(params, urls)
+        end
+
+        def include_in_extras(params, things)
+          params.dup.tap do |params|
+            params[:extras] = [params[:extras], things].compact.join(",")
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/flickr/client/methods_client.rb

@@ -0,0 +1,22 @@
+class Flickr
+  class MethodsClient < Client
+    def initialize(access_token)
+      super(access_token)
+    end
+
+    [:get, :post].each do |http_method|
+      define_method(http_method) do |flickr_method, params = {}|
+        response = super("rest") do |req|
+          req.params[:method] = flickr_method
+          req.params.update(params)
+        end
+
+        response.body
+      end
+    end
+
+    def parser
+      FaradayMiddleware::ParseJson
+    end
+  end
+end

data/lib/flickr/client/middleware/retry.rb

@@ -0,0 +1,38 @@
+class Flickr
+  class Client < Faraday::Connection
+    module Middleware
+      # A copy-paste from Faraday's master branch
+      class Retry < Faraday::Middleware
+        # Public: Initialize middleware
+        #
+        # Options:
+        # max        - Maximum number of retries (default: 2).
+        # interval   - Pause in seconds between retries (default: 0).
+        # exceptions - The list of exceptions to handle. Exceptions can be
+        #              given as Class, Module, or String. (default:
+        #              [Errno::ETIMEDOUT, Timeout::Error, Error::TimeoutError])
+        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
+            if retries > 0
+              retries -= 1
+              sleep @sleep if @sleep > 0
+              retry
+            end
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flickr/client/middleware.rb

@@ -0,0 +1,42 @@
+require "cgi"
+require "flickr/client/middleware/retry"
+
+class Flickr
+  class Client < Faraday::Connection
+    module Middleware
+      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
+          end
+        end
+      end
+
+      class CheckStatus < Faraday::Response::Middleware
+        def on_complete(env)
+          env[:body] = env[:body]["rsp"] || env[:body]
+
+          if env[:body]["stat"] != "ok"
+            message = env[:body]["message"] || env[:body]["err"]["msg"]
+            code = env[:body]["code"] || env[:body]["err"]["code"]
+            raise Error.new(message, code)
+          end
+        end
+      end
+    end
+
+    class OAuthError < ArgumentError
+    end
+
+    class Error < StandardError
+      attr_reader :code
+
+      def initialize(message, code = nil)
+        super(message)
+        @code = code.to_i
+      end
+    end
+  end
+end