flickr-objects 0.2.0 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eebc705fe752afa94151b9a736292d266f37b15a
+  data.tar.gz: 70de81c78b4a5bdb9e575aa96b2aa5d069523ba8
+SHA512:
+  metadata.gz: 4003856d98c98ddf1b9336b51452c846134d991b9e9cf230f1e4b75830cec0b60d354c2408db07a207133cef37438e8b351d7a9bc27bba09f7a1c52236047580
+  data.tar.gz: 4e4698dbc564b5efb8b496c48bccc6216239ae711b22ee4268216c25af2998c3449b3150e783db4817e3c105612d21fbade3bcff4df434c2fa8cb31a727c0bf4

data/README.md

@@ -1,9 +1,10 @@
 # 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/)
+- Web page: [http://janko-m.github.com/flickr-objects/](http://janko-m.github.com/flickr-objects/)
+- Home page: [https://github.com/janko-m/flickr-objects](https://github.com/janko-m/flickr-objects)
+- API Documentation: [http://rubydoc.info/gems/flickr-objects/](http://rubydoc.info/gems/flickr-objects/)
 
 ## Installation and setup
 
@@ -17,34 +18,34 @@ Now create an initializer where you set your Flickr credentials.
 
 ```ruby
 Flickr.configure do |config|
-  config.api_key = "API_KEY"
+  config.api_key       = "API_KEY"
   config.shared_secret = "SHARED_SECRET"
 end
 ```
 
-If you don't have them yet, you can apply for them [here](http://www.flickr.com/services/apps/create/apply).
+If you don't have them yet, you can apply for them
+[here](http://www.flickr.com/services/apps/create/apply).
 
-For list of possible configuration options, take a look at [this
-wiki](https://github.com/janko-m/flickr-objects/wiki/Configuration).
+For list of possible configuration options, take a look at
+[`Flickr::Configuration`](http://rubydoc.info/gems/flickr-objects/Flickr/Configuration).
 
 ## Usage
 
-This gem maps [Flickr's API methods](http://flickr.com/api) to methods on objects.
-A handy reference for those mappings is in `Flickr.api_methods`:
+This gem maps [Flickr's API methods](http://flickr.com/api) to Ruby methods.
 
 ```ruby
-Flickr.api_methods["flickr.photos.search"]     #=> ["Flickr::Photo.search"]
-Flickr.api_methods["flickr.photosets.getList"] #=> ["Flickr::Person#get_sets"]
+Flickr.photos.search(...)   # flickr.photos.search
+Flickr.person.get_sets(...) # flickr.photosets.getList
 ```
 
-As you see, sometimes names can differ, but you can always find out this way.
-So, `Flickr::Photo.search` is a **class** API method, and
-`Flickr::Person#get_sets` is an **instance** API method.
+For the list of all API methods (and their related Flickr's methods), see the
+[`Flickr::Api`](http://rubydoc.info/gems/flickr-objects/Flickr/Api) module.
+These methods are included to the `Flickr` module.
 
-Here's an example:
+Example:
 
 ```ruby
-photos = Flickr.photos.search(user_id: "78733179@N04") #=> [#<Flickr::Photo: ...>, #<Flickr::Photo: ...>, ...]
+photos = Flickr.photos.search(user_id: "78733179@N04") #=> [#<Flickr::Object::Photo: ...>, #<Flickr::Object::Photo: ...>, ...]
 
 photo = photos.first
 photo.id                 #=> "231233252"
@@ -52,45 +53,45 @@ photo.title              #=> "My cat"
 photo.visibility.public? #=> true
 
 person = Flickr.people.find("78733179@N04")
-sets = person.get_sets #=> [#<Flickr::Set: ...>, #<Flickr::Set: ...>, ...]
-
-set = sets.first
+set = person.sets.first
 set.id           #=> "11243423"
 set.photos_count #=> 40
 ```
 
-We can learn few things here:
+Few notes here:
 
-- Interface to object's class methods is always the plural of object's name
-  (above we called `Flickr::Photo.search` with `Flickr.photos.search`).
-- You can always manually instantiate objects with `Flickr.<objects>.find(id)`
+- flickr-objects distinguishes **instance** from **class** API methods. So,
+  `Flickr.photos.search` is a class API method. And `Flickr.people.get_sets`
+  is by its nature an **instance** API method, because we're finding sets
+  *from a person*; in that case we can call `#get_sets` on an instance of
+  person (so that our code looks better).
+- Flickr objects can always be instantiated with `Flickr.<objects>.find(id)`
   (in the above example we did `Flickr.people.find(id)`).
 
-Parameters to API methods are not always passed as a hash. For example, instead
-of calling "flickr.people.findByEmail" like this:
+## Arguments to API methods
+
+By its nature, API methods always accept a hash of parameters. Using that approach,
+this would be the call for "flickr.people.findByEmail":
 
 ```ruby
 Flickr.people.find_by_email(find_email: "janko.marohnic@gmail.com")
 ```
 
-this gem has the convention of calling it like this:
+But that looks lame. Luckily, in these kind of methods flickr-objects improves
+the argument list:
 
 ```ruby
 Flickr.people.find_by_email("janko.marohnic@gmail.com")
 ```
 
-This is always the case with obvious (and required) parameters. You can still
-always pass a hash of other parameters as the last argument.
-
-For documentation on valid arguments, just look at the source code at
-[`lib/flickr/api`](https://github.com/janko-m/flickr-objects/tree/master/lib/flickr/api),
-under a specific object.
+Of course, all parameters are documented:
+[`Flickr::Api::Person#find_by_email`](http://rubydoc.info/gems/flickr-objects/Flickr/Api/Person#find_by_email-instance_method)
 
 ## Sizes
 
 ```ruby
-person = Flickr.person.find(person_id)
-photo = person.get_public_photos(sizes: :all).first
+person = Flickr.person.find("78733179@N04")
+photo = person.public_photos(sizes: true).first
 
 photo.small!(320)
 photo.source_url #=> "http://farm9.staticflickr.com/8191/8130464513_780e01decd_n.jpg"
@@ -101,14 +102,14 @@ photo.medium!(500)
 photo.width      #=> 500
 ```
 
-It is important here that you pass `sizes: :all` to `Flickr::Person#get_public_photos`.
+It is important here that you pass `sizes: true` to `Flickr::Person#public_photos`.
 So, in your (Rails) application, one could use it like this:
 
 ```ruby
 class PhotosController < ApplicationController
   def index
     person = Flickr.people.find("78733179@N04")
-    @photos = person.get_public_photos(sizes: :all).map { |photo| photo.medium!(500) }
+    @photos = person.public_photos(sizes: true).map(&:medium500!)
   end
 end
 ```
@@ -118,12 +119,11 @@ end
 <% end %>
 ```
 
-To find out more, take a look at [this wiki](https://github.com/janko-m/flickr-objects/wiki/Sizes).
+To find out more, see [`Flickr::Object::Photo`](http://rubydoc.info/gems/flickr-objects/Flickr/Object/Photo).
 
 ## Authentication
 
-If you need to make authenticated API requests (which you'll probably often want), you should create an
-instance, assigning it the user's access token.
+You may need to make authenticated API requests, using an access token.
 
 ```ruby
 flickr = Flickr.new("ACCESS_TOKEN_KEY", "ACCESS_TOKEN_SECRET")
@@ -133,10 +133,10 @@ flickr.test_login #=> {"id" => "78733179@N04", "username" => ...}
 flickr.people.find("78733179@N04").get_photos #=> [#<Flickr::Photo ...>, #<Flickr::Photo, ...>, ...]
 ```
 
-For details on how to authenticate (obtain the access token) take a look at
-[this wiki](http://github.com/janko-m/flickr-objects/wiki/Authentication).
+For details on how to authenticate, i.e. obtain the access token, see
+[`Flickr::OAuth`](http://rubydoc.info/gems/flickr-objects/Flickr/OAuth).
 
-You can also assign the access token globally in your configuration.
+If you want, you can also assign the access token globally in your configuration.
 
 ```ruby
 Flickr.configure do |config|
@@ -145,6 +145,8 @@ Flickr.configure do |config|
 end
 ```
 
+Naturally, this way you don't need to create an instance like above.
+
 ## Upload
 
 ```ruby
@@ -153,30 +155,14 @@ photo = Flickr.photos.find(photo_id).get_info!
 photo.title #=> "Dandelions"
 ```
 
-In the first argument you can pass in either a string (path to the file) or an open file.
-For the details on the additional options you can pass in, check out Flickr's [upload
-documentation](http://www.flickr.com/services/api/upload.api.html).
-
-For asynchronous upload take a look at [this wiki](https://github.com/janko-m/flickr-objects/wiki/Upload).
-
-## Attributes and methods
-
-For the list of attributes and methods that Flickr objects have, the best place to look at
-is the source code. The source code is written in such a simple way that it acts as its
-own documentation, so don't be discouraged if you haven't had experience in looking into other
-people's code yet :)
-
-For example, list of `Flickr::Photo`'s attributes can be found in
-[`lib/flickr/objects/photo.rb`](https://github.com/janko-m/flickr-objects/blob/master/lib/flickr/objects/photo.rb).
-Take a look just to see how it looks like :)
+See [`Flickr.upload`](http://rubydoc.info/gems/flickr-objects/Flickr/Api/General#upload-instance_method)
 
 ## Few words
 
-Most of the API methods are not covered yet (because they are so many). I will
-be covering new ones regularly.
-
-Feel free to speed up covering certain API methods by contacting me through
-[Twitter](https://twitter.com/m_janko). Pull requests are also very welcome :)
+Many of the API methods are not covered yet (because they are so many).
+I believe I covered all the important ones, but if you wish for me to
+cover certain new ones, feel free to contact me via [Twitter](https://twitter.com/m_janko).
+I also wouldn't mind getting a pull request ;)
 
 ## Social
 
@@ -184,4 +170,4 @@ 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).
+This project is released under the [MIT license](LICENSE).

data/lib/flickr/api/abstract/params_processor.rb

@@ -0,0 +1,68 @@
+module Flickr
+  module Api
+    class Abstract
+
+      ##
+      # Does processing of parameters passed to API requests, to enable nicer
+      # syntax.
+      #
+      class ParamsProcessor
+
+        attr_reader :params
+
+        def initialize(params)
+          @params = params
+        end
+
+        def process_for(flickr_method)
+          add_sizes! if add_sizes?(flickr_method)
+
+          @params
+        end
+
+        private
+
+        ##
+        # @example
+        #   processor = ParamsProcessor.new({sizes: true})
+        #   processor.add_sizes!
+        #   processor.params #=> {extras: "url_sq,url_t,url_q,url_s,url_n,url_m,url_z,url_c,url_l,url_h,url_k,url_o"}
+        #
+        #   processor = ParamsProcessor.new({sizes: ["Square 75", "Thumbnail"]})
+        #   processor.add_sizes!
+        #   processor.params #=> {extras: "url_sq,url_t"}
+        #
+        def add_sizes!
+          if [true, :all].include? @params[:sizes]
+            @params[:sizes] = Flickr::Object::Photo::SIZES
+          end
+
+          sizes = Array(@params[:sizes])
+            .map { |name| Flickr::Object::Photo::Size.new(name) }
+            .map { |size| "url_#{size.abbreviation}" }
+          existing_extras = String(@params[:extras]).split(",")
+
+          @params[:extras] = (existing_extras + sizes).join(",")
+        end
+
+        def add_sizes?(flickr_method)
+          [ "photos.getContactsPhotos",
+            "photos.search",
+            "photos.getNotInSet",
+            "photos.getRecent",
+            "photos.getUntagged",
+            "photos.getWithGeoData",
+            "photos.getWithoutGeoData",
+            "photos.RecentlyUpdated",
+            "photosets.getPhotos",
+            "people.getPhotos",
+            "people.getPhotosOf",
+            "people.getPublicPhotos",
+            "people.getContactsPublicPhotos" ].include?(flickr_method)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/flickr/api/abstract.rb

@@ -0,0 +1,113 @@
+module Flickr
+  module Api
+
+    ##
+    # This class abstracts the interface for communication with the Flickr API.
+    #
+    # @see Flickr::ApiError
+    #
+    class Abstract
+
+      extend Flickr::AutoloadHelper
+
+      autoload_names :ParamsProcessor
+
+      ##
+      # @private
+      #
+      def self.object_class
+        Flickr::Object.const_get(name.match(/^Flickr::Api::/).post_match)
+      end
+
+      ##
+      # @private
+      #
+      def initialize(access_token = nil)
+        @access_token = access_token
+      end
+
+      ##
+      # @param id [String] ID of the object to be instantiated
+      # @example
+      #   person = Flickr.photos.find("1")
+      #   person.photos.each do |photo|
+      #     # ...
+      #   end
+      #
+      def find(id)
+        object_class = self.class.object_class
+        object_class.new({"id" => id}, @access_token)
+      end
+
+      private
+
+      def get(flickr_method, params = {})
+        make_request(:get, flickr_method, params)
+      end
+
+      def post(flickr_method, params = {})
+        make_request(:post, flickr_method, params)
+      end
+
+      def make_request(http_method, flickr_method, params = {})
+        process_params(params, flickr_method)
+        client[:data].send(http_method, "flickr.#{flickr_method}", params)
+      end
+
+      def upload(params = {})
+        client[:upload].upload(params)
+      end
+
+      def replace(params = {})
+        client[:upload].replace(params)
+      end
+
+      def client
+        {
+          data:   Flickr::Client::Data.new(@access_token),
+          upload: Flickr::Client::Upload.new(@access_token),
+        }
+      end
+
+      ##
+      # Enhances params, allowing nicer syntax.
+      #
+      # @example
+      #   params = {sizes: ["Thumbnail", "Medium 500"]}
+      #   process_params(params, "flickr.photos.search")
+      #   params #=> {extras: "url_t,url_m"}
+      # @see Flickr::Api::Abstract::ParamsProcessor
+      #
+      def process_params(params, flickr_method)
+        ParamsProcessor.new(params).process_for(flickr_method)
+      end
+
+      ##
+      # @example
+      #   photo = new_object(:Photo, {"id" => "1"})
+      #   photo #=> #<Flickr::Object::Photo:0x007fcb9e08dee8 id="1">
+      #
+      def new_object(class_name, attributes)
+        object_class = self.class.object_class.const_get(class_name)
+        object_class.new(attributes, @access_token)
+      end
+
+      ##
+      # @example
+      #   photos = new_list(:Photo, [{"id" => "1"}], {"page" => 1})
+      #   photos #=> #<Flickr::Object::List:0x007ffe6b51d468
+      #          #   @attributes={"page"=>1},
+      #          #   @objects=
+      #          #    [#<Flickr::Object::Photo:0x007ffe6b4ff760 owner=#<Flickr::Object::Person:0x007ffe6b52d408 >>,
+      #          #     #<Flickr::Object::Photo:0x007ffe6b4fdcd0 owner=#<Flickr::Object::Person:0x007ffe6b556ab0 >>]>
+      #
+      def new_list(class_name, attributes_list, list_attributes)
+        objects = attributes_list.map { |attributes| new_object(class_name, attributes) }
+        list = Flickr::Object::List.new(list_attributes)
+        list.populate(objects)
+      end
+
+    end
+
+  end
+end

data/lib/flickr/api/general.rb

@@ -0,0 +1,75 @@
+require "flickr/sanitized_file"
+
+module Flickr
+  module Api
+
+    class General < Abstract
+
+      ##
+      # @example
+      #   photo = File.open("/path/to/dandelions.jpg")
+      #   Flickr.upload(photo, title: "Dandelions")
+      # @param photo [String, File, Rails, Sinatra] Photo to upload
+      # @param params [Hash] See documentation below
+      # @return [String] ID of the uploaded photo (if synchronous)
+      # @return [String] ID of the upload ticket (if asynchronous). See {Flickr::Api::UploadTicket#check}.
+      # @docs [Upload API](http://www.flickr.com/services/api/upload.api.html)
+      #
+      def upload(photo, params = {})
+        response = super params.merge(photo: SanitizedFile.new(photo))
+        params[:async] == 1 ? response["ticketid"] : response["photoid"]
+      end
+
+      ##
+      # @example
+      #   photo = File.open("/path/to/dandelions.jpg")
+      #   Flickr.replace(photo, photo_id, title: "Dandelions")
+      # @param photo [String, File, Rails, Sinatra] Photo to upload
+      # @param photo_id [String] ID of the photo which will be replaced
+      # @param params [Hash] See documentation below
+      # @return [String] ID of the uploaded photo (if synchronous)
+      # @return [String] ID of the upload ticket (if asynchronous)
+      # @docs [Replace API](http://www.flickr.com/services/api/replace.api.html)
+      #
+      def replace(photo, photo_id, params = {})
+        response = super params.merge(photo: SanitizedFile.new(photo), photo_id: photo_id)
+        params[:async] == 1 ? response["ticketid"] : response["photoid"]["__content__"]
+      end
+
+      ##
+      # @return [Array<String>]
+      # @docs [flickr.reflection.getMethods](http://www.flickr.com/services/api/flickr.reflection.getMethods.html)
+      #
+      def get_methods(params = {})
+        response = get "reflection.getMethods", params
+        response["methods"]["method"].map { |hash| hash["_content"] }
+      end
+
+      ##
+      # @return [Hash]
+      # @docs [flickr.test.login](http://www.flickr.com/services/api/flickr.test.login.html)
+      #
+      def test_login(params = {})
+        get "test.login", params
+      end
+
+      ##
+      # @return [Hash]
+      # @docs [flickr.test.echo](http://www.flickr.com/services/api/flickr.test.echo.html)
+      #
+      def test_echo(params = {})
+        get "test.echo", params
+      end
+
+      ##
+      # @return [Hash]
+      # @docs [flickr.test.null](http://www.flickr.com/services/api/flickr.test.null.html)
+      #
+      def test_null(params = {})
+        get "test.null", params
+      end
+
+    end
+
+  end
+end

data/lib/flickr/api/person.rb

@@ -1,51 +1,103 @@
-require_relative "api_methods/person"
+module Flickr
+  module Api
 
-class Flickr
-  class Person < Object
-    def self.find_by_email(email, params = {})
-      response = client.get f(__method__), params.merge(find_email: email)
-      new(response["user"], client)
-    end
+    class Person < Abstract
 
-    def self.find_by_username(username, params = {})
-      response = client.get f(__method__), params.merge(username: username)
-      new(response["user"], client)
-    end
+      ##
+      # @param email [String]
+      # @return [Flickr::Object::Person]
+      # @docs [flickr.people.findByEmail](http://www.flickr.com/services/api/flickr.people.findByEmail.html)
+      #
+      def find_by_email(email, params = {})
+        response = get "people.findByEmail", params.merge(find_email: email)
+        new_object(:Person, response["user"])
+      end
 
-    def self.get_upload_status(params = {})
-      response = client.get f(__method__), params
-      UploadStatus.new(response["user"], client)
-    end
+      ##
+      # @param username [String]
+      # @return [Flickr::Object::Person]
+      # @docs [flickr.people.findByUsername](http://www.flickr.com/services/api/flickr.people.findByUsername.html)
+      #
+      def find_by_username(username, params = {})
+        response = get "people.findByUsername", params.merge(username: username)
+        new_object(:Person, response["user"])
+      end
 
-    def get_info!(params = {})
-      response = client.get f(__method__), params.merge(user_id: id)
-      @hash.update(response["person"])
-      self
-    end
+      ##
+      # @return [Flickr::Object::Person::UploadStatus]
+      # @docs [flickr.people.getUploadStatus](http://www.flickr.com/services/api/flickr.people.getUploadStatus.html)
+      #
+      def get_upload_status(params = {})
+        response = get "people.getUploadStatus", params
+        new_object(:UploadStatus, response["user"])
+      end
 
-    def get_photos(params = {})
-      response = client.get f(__method__), handle_extras(params.merge(user_id: id))
-      Photo.new_list(response["photos"].delete("photo"), client, response["photos"])
-    end
+      ##
+      # @param person_id [String]
+      # @return [Flickr::Object::Person]
+      # @docs [flickr.people.getInfo](http://www.flickr.com/services/api/flickr.people.getInfo.html)
+      #
+      def get_info(person_id, params = {})
+        response = get "people.getInfo", params.merge(user_id: person_id)
+        new_object(:Person, response["person"])
+      end
 
-    def get_photos_of(params = {})
-      response = client.get f(__method__), handle_extras(params.merge(user_id: id))
-      Photo.new_list(response["photos"].delete("photo"), client, response["photos"])
-    end
+      ##
+      # @param person_id [String]
+      # @param params [Hash] See documentation below
+      # @return [Flickr::Object::List<Flickr::Object::Photo>]
+      # @docs [flickr.people.getPhotos](http://www.flickr.com/services/api/flickr.people.getPhotos.html)
+      #
+      def get_photos(person_id, params = {})
+        response = get "people.getPhotos", params.merge(user_id: person_id)
+        new_list(:Photo, response["photos"].delete("photo"), response["photos"])
+      end
 
-    def get_public_photos(params = {})
-      response = client.get f(__method__), handle_extras(params.merge(user_id: id))
-      Photo.new_list(response["photos"].delete("photo"), client, response["photos"])
-    end
+      ##
+      # @param person_id [String]
+      # @param params [Hash] See documentation below
+      # @return [Flickr::Object::List<Flickr::Object::Photo>]
+      # @docs [flickr.people.getPhotosOf](http://www.flickr.com/services/api/flickr.people.getPhotosOf.html)
+      #
+      def get_photos_of(person_id, params = {})
+        response = get "people.getPhotosOf", params.merge(user_id: person_id)
+        new_list(:Photo, response["photos"].delete("photo"), response["photos"])
+      end
 
-    def get_public_photos_from_contacts(params = {})
-      response = client.get f(__method__), handle_extras(params.merge(user_id: id))
-      Photo.new_list(response["photos"].delete("photo"), client, response["photos"])
-    end
+      ##
+      # @param person_id [String]
+      # @param params [Hash] See documentation below
+      # @return [Flickr::Object::List<Flickr::Object::Photo>]
+      # @docs [flickr.people.getPublicPhotos](http://www.flickr.com/services/api/flickr.people.getPublicPhotos.html)
+      #
+      def get_public_photos(person_id, params = {})
+        response = get "people.getPublicPhotos", params.merge(user_id: person_id)
+        new_list(:Photo, response["photos"].delete("photo"), response["photos"])
+      end
+
+      ##
+      # @param person_id [String]
+      # @param params [Hash] See documentation below
+      # @return [Flickr::Object::List<Flickr::Object::Photo>]
+      # @docs [flickr.photos.getContactsPublicPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPublicPhotos.html)
+      #
+      def get_public_photos_from_contacts(person_id, params = {})
+        response = get "photos.getContactsPublicPhotos", params.merge(user_id: person_id)
+        new_list(:Photo, response["photos"].delete("photo"), response["photos"])
+      end
+
+      ##
+      # @param person_id [String]
+      # @param params [Hash] See documentation below
+      # @return [Flickr::Object::List<Flickr::Object::Set>]
+      # @docs [flickr.photosets.getList](http://www.flickr.com/services/api/flickr.photosets.getList.html)
+      #
+      def get_sets(person_id, params = {})
+        response = get "photosets.getList", params.merge(user_id: person_id)
+        new_list(:Set, response["photosets"].delete("photoset"), response["photosets"])
+      end
 
-    def get_sets(params = {})
-      response = client.get f(__method__), params.merge(user_id: id)
-      Set.new_list(response["photosets"].delete("photoset"), client, response["photosets"])
     end
+
   end
 end