flickrie 0.1.2 → 0.2.0

data/README.md

@@ -5,10 +5,19 @@
 This gem is a nice wrapper for the Flickr API with an intuitive interface.
 
 The reason why I did this gem is because the other ones either weren't
-well maintained, or they were too literal in the sense that the response from
-the API call wasn't processed almost at all. It doesn't seem too bad
-at first, but after a while you realize it's not pretty. So I wanted to
-make it pretty :)
+well maintained, or they were too literal in the sense that the responses from
+the API calls weren't processed almost at all. It doesn't seem too bad
+at first, but it would be great that, for example, if you're reading a time attribute,
+such as `last_update`, you actually **get** the instance of `Time`, and
+not a string representing that time (often in a timestamp (integer) format).
+That's what wrappers should be for.
+
+The method names here aren't called the same as Flickr's API methods, but they follow a pattern which
+shouldn't be too difficult to learn. Also, some attribute names that you
+get from the response are changed. So, for example, the `last_update`
+attribute is called `updated_at`, and the `candownload` attribute is
+called `can_download?`. After all, this is a **ruby** wrapper, so it
+should be written in Ruby/Rails fashion :)
 
 ## Examples of usage
 
@@ -18,18 +27,20 @@ You first need to install the gem.
 [sudo] gem install flickrie
 ```
 
-Then in your app you require it and set the API key.
+Then in your app you set the API key and secret (which you can apply
+for [here](http://www.flickr.com/services/apps/create/apply)).
 
 ```ruby
 require 'flickrie'
-Flickrie.api_key = "<your_api_key>"
-Flickrie.shared_secret = "<your_shared_secret>"
+Flickrie.api_key = "your api key"
+Flickrie.shared_secret = "your shared secret"
 ```
 
-Then you can search for photos.
+Then you can search for stuff.
 
 ```ruby
-photos = Flickrie.photos_from_set(819234) # => [#<Photo: id="8232348", ...>, #<Photo: id="8194318", ...>, ...]
+set_id = 819234
+photos = Flickrie.photos_from_set(set_id) # => [#<Photo: id="8232348", ...>, #<Photo: id="8194318", ...>, ...]
 
 photo = photos.first
 photo.id          # => "8232348"
@@ -39,11 +50,11 @@ photo.owner       # => #<User: nsid="67313352@N04", ...>
 photo.owner.nsid  # => "67313352@N04"
 ```
 
-Note that what Flickr refers to as "photoset" in its documentation, I
-refer to as "set". This is because the word "photoset" would be wrong,
-since sets can also hold videos.
+Note that, what Flickr refers to as "photoset" in its documentation, I
+refer to as "set". This is because the word "photoset" is actually
+incorrect, since sets can also hold videos.
 
-You can also throw in some parameters to get more information about photos.  For example,
+You can also throw in some parameters to `.photos_from_set` to get more information about photos. For example,
 
 ```ruby
 photos = Flickrie.photos_from_set(819234, :extras => 'owner_name,last_update,tags,views')
@@ -55,7 +66,8 @@ photo.updated_at     # => 2012-04-20 23:29:17 +0200
 photo.views_count    # => 24
 ```
 
-On the list of available parameters you can read in the [Flickr API documentation](http://www.flickr.com/services/api/), under the corresponding API method name (in the above case it's `flickr.photosets.getPhotos`).
+On the list of available parameters you can read in the [Flickr API documentation](http://www.flickr.com/services/api/),
+under the corresponding API method name (in the above case the method name would be `flickr.photosets.getPhotos`).
 
 You can also get additional info on a single photo:
 
@@ -70,7 +82,7 @@ photo.owner.real_name       # => "John Smith"
 photo.location.country.name # => "United States"
 ```
 
-You can also get this info on an existing photo:
+If you already have an existing photo, you can also get info like this:
 
 ```ruby
 photo.description # => nil
@@ -78,10 +90,11 @@ photo.get_info
 photo.description # => "In this photo Peter said something really funny..."
 ```
 
-If you want to display photos from flickr in your app, this is probably the most useful part:
+You'll also probably want to display these photos in your app.
 
 ```ruby
 photo = Flickrie.get_photo_sizes(8232348)
+# or "photo.get_sizes" on an existing photo
 
 photo.medium!(800)
 photo.size       # => "Medium 800"
@@ -96,41 +109,42 @@ photo.width      # => 240
 photo.width      # => 320
 ```
 
-If you want sizes to be available to photos you're fetching from a set, it's not a good idea to call `#get_sizes` on each photo, because that will make an HTTP request on each photo, which can be very slow. Instead, you should pass in these options:
-
-```ruby
-photos = Flickrie.photos_from_set(1242379, :extras => 'url_sq,url_q,url_t,url_s,url_n,url_m,url_z,url_c,url_l,url_o')
-photo = photos.first
-photo.medium!(640)
-photo.source_url # => "http://farm8.staticflickr.com/7049/6946979188_25bb44852b_z.jpg"
-```
-
-To see a full list of available methods, I see the [wiki](https://github.com/janko-m/flickrie/wiki). I promise, I will document the methods properly in near future :)
+You can see the full list of available methods and attributes in the
+[documentation](http://rubydoc.info/gems/flickrie/0.1.2/frames).
 
 ## Authentication
 
 ```ruby
 require 'flickrie'
 
-Flickrie.api_key = "<your api key>"
-Flickrie.shared_secret = "<your shared secret>"
+Flickrie.api_key = "your api key"
+Flickrie.shared_secret = "your shared secret"
+
+request_token = Flickrie::OAuth.get_request_token
+url = request_token.get_authorization_url
+puts "Visit this url to authenticate: #{url}"
 
-url = Flickrie.get_authorization_url
-puts "Visit this url to authorize: #{url}"
-puts "If you agreed, the code was displayed afterwards. Enter it: "
+print "If you agreed, the code was displayed afterwards. Enter it: "
 code = gets.strip
-Flickrie.authorize!(code)
-puts "You're all done! Now go make some authenticated requests. Make me proud, son."
+access_token = Flickrie::OAuth.get_access_token(code)
+Flickrie.access_token = access_token.token
+Flickrie.access_secret = access_token.secret
+puts "You successfully authenticated!"
 ```
 
-When calling `Flickrie.get_authorization_url`, you can also pass in the option `:permissions => "<perms>"`, where instead of `<perms>` you write either `read`, `write` or `delete`.
+When getting the authorization url, you can also call
+```ruby
+request_token.get_authorization_url(:permissions => "read")
+```
+to ask only for "read" permissions from the user. Available permissions
+are "read", "write" and "delete".
 
 ## A few words
 
 Now, I covered only a few out of many Flickr's API methods using this approach, but I'll constantly update this gem with new API methods. For all of the methods I didn't cover, you can call them using `Flickrie.client`, like this:
 
 ```ruby
-response = Flickrie.client.get("flickr.photos.getContext", :photo_id => 2842732)
+response = Flickrie.client.get "flickr.photos.getContext", :photo_id => 2842732
 reponse.body # =>
 # {
 #   "count" => {"_content" => 99},
@@ -151,8 +165,8 @@ It's not nearly as pretty, but at least you can get to the data.
 
 ## Issues
 
-Please, feel free to post any issues that you're having, I will try to
-help you in any way I can.
+Please, feel free to post any issues that you're having, I will be happy
+to help. I will also be happy if you let me know about any bugs.
 
 ## Cedits
 
@@ -169,8 +183,11 @@ basis of this gem.
 - `flickr.people.getPublicPhotos`
 
 ### photos
+- `flickr.photos.addTags`
+- `flickr.photos.delete`
 - `flickr.photos.getInfo`
 - `flickr.photos.getSizes`
+- `flickr.photos.removeTag`
 - `flickr.photos.search`
 
 ### photos.licenses

data/flickrie.gemspec

@@ -17,4 +17,5 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency 'faraday_middleware'
   gem.add_dependency 'simple_oauth'
+  gem.add_dependency 'addressable'
 end

data/lib/flickrie/client.rb

@@ -4,7 +4,7 @@ require 'simple_oauth'
 module Flickrie
   class << self
     attr_accessor :api_key, :shared_secret, :timeout, :open_timeout,
-      :token, :token_secret
+      :access_token, :access_secret
 
     def client
       @client ||= begin
@@ -12,8 +12,8 @@ module Flickrie
           conn.request :oauth,
             :consumer_key => api_key,
             :consumer_secret => shared_secret,
-            :token => token,
-            :token_secret => token_secret
+            :token => access_token,
+            :token_secret => access_secret
           conn.response :json, :content_type => /(text\/plain)|(json)$/
           conn.adapter Faraday.default_adapter
         end
@@ -82,8 +82,7 @@ module Flickrie
 
     def public_media_from_user(user_nsid, params = {})
       params = {:user_id => user_nsid}.merge(params)
-      params[:extras] = [params[:extras], 'media'].compact.join(',')
-      get 'flickr.people.getPublicPhotos', params
+      get 'flickr.people.getPublicPhotos', ensure_media(params)
     end
 
     # photos
@@ -91,6 +90,10 @@ module Flickrie
       post 'flickr.photos.addTags', :photo_id => media_id, :tags => tags
     end
 
+    def delete_media(media_id)
+      post 'flickr.photos.delete', :photo_id => media_id
+    end
+
     def get_media_info(media_id)
       get 'flickr.photos.getInfo', :photo_id => media_id
     end
@@ -104,8 +107,7 @@ module Flickrie
     end
 
     def search_media(params = {})
-      params[:extras] = [params[:extras], 'media'].compact.join(',')
-      get 'flickr.photos.search', params
+      get 'flickr.photos.search', ensure_media(params)
     end
 
     # licenses
@@ -124,8 +126,14 @@ module Flickrie
 
     def media_from_set(set_id, params = {})
       params = {:photoset_id => set_id}.merge(params)
+      get 'flickr.photosets.getPhotos', ensure_media(params)
+    end
+
+    private
+
+    def ensure_media(params)
       params[:extras] = [params[:extras], 'media'].compact.join(',')
-      get 'flickr.photosets.getPhotos', params
+      params
     end
   end
 end

data/lib/flickrie/oauth.rb

@@ -1,79 +1,95 @@
+require 'faraday_middleware'
+require 'faraday_middleware/response_middleware'
+require 'simple_oauth'
+
 module Flickrie
   module OAuth
-    class RequestToken
-      attr_reader :token, :secret
+    URL = 'http://www.flickr.com/services/oauth'.freeze
+    NO_CALLBACK = 'oob'.freeze
 
-      def initialize(response_body)
-        @token = response_body[/(?<=oauth_token=)[^&]+/]
-        @secret = response_body[/(?<=oauth_token_secret=)[^&]+/]
-      end
+    def self.new_connection(additional_oauth_params = {})
+      oauth_params = {
+        :consumer_key => Flickrie.api_key,
+        :consumer_secret => Flickrie.shared_secret
+      }.merge(additional_oauth_params)
+
+      Faraday.new(URL) do |connection|
+        connection.request :oauth, oauth_params
+        connection.use ParseFlickrResponse
+        connection.adapter Faraday.default_adapter
+      end.
+        tap do |connection|
+          connection.builder.insert_before ParseFlickrResponse, StatusCheck
+        end
+    end
 
-      def authorization_url(options = {})
-        url = "http://www.flickr.com/services/oauth/authorize?oauth_token=#{token}"
-        permissions = options[:permissions] || options[:perms]
-        url.concat("&perms=#{permissions}") if permissions
-        url
+    class StatusCheck < Faraday::Response::Middleware
+      def on_complete(env)
+        if env[:status] != 200
+          raise Error, env[:body]['oauth_problem'].gsub('_', ' ').capitalize
+        end
       end
     end
 
-    class Consumer
-      def initialize(api_key, shared_secret)
-        @api_key, @shared_secret = api_key, shared_secret
+    class Error < StandardError
+    end
+
+    class ParseFlickrResponse < FaradayMiddleware::ResponseMiddleware
+      dependency do
+        require 'addressable/uri' unless defined?(Addressable)
       end
 
-      def get_request_token
-        connection = Faraday.new "http://www.flickr.com/services/oauth" do |conn|
-          conn.request :oauth,
-            :consumer_key => @api_key,
-            :consumer_secret => @shared_secret
-          conn.adapter :net_http
-        end
+      define_parser do |body|
+        parser = Addressable::URI.new
+        parser.query = body
+        parser.query_values
+      end
+    end
 
-        response = connection.get("request_token") do |req|
-          req.params[:oauth_callback] = 'oob'
-        end
+    def self.get_request_token(callback = nil)
+      connection = new_connection
 
-        RequestToken.new(response.body)
+      response = connection.get "request_token" do |req|
+        req.params[:oauth_callback] = callback || NO_CALLBACK
       end
 
-      def get_access_token(oauth_verifier, request_token)
-        connection = Faraday.new "http://www.flickr.com/services/oauth" do |conn|
-          conn.request :oauth,
-            :consumer_key => @api_key,
-            :consumer_secret => @shared_secret,
-            :token => request_token.token,
-            :token_secret => request_token.secret
-          conn.adapter :net_http
-        end
+      RequestToken.from_response(response.body)
+    end
 
-        response = connection.get "access_token" do |req|
-          req.params[:oauth_verifier] = oauth_verifier
-        end
+    def self.get_access_token(verifier, request_token)
+      connection = new_connection \
+        :token => request_token.token,
+        :token_secret => request_token.secret
 
-        [
-          response.body[/(?<=oauth_token=)[^&]+/],
-          response.body[/(?<=oauth_token_secret=)[^&]+/]
-        ]
+      response = connection.get "access_token" do |req|
+        req.params[:oauth_verifier] = verifier
       end
-    end
-  end
-end
 
-module Flickrie
-  class << self
-    def get_authorization_url(options = {})
-      @request_token = consumer.get_request_token
-      @request_token.authorization_url(options)
+      AccessToken.from_response(response.body)
     end
 
-    def authorize!(code)
-      token, token_secret = consumer.get_access_token(code, @request_token)
+    module Token
+      def from_response(body)
+        new(body['oauth_token'], body['oauth_token_secret'])
+      end
     end
 
-    private
+    class RequestToken < Struct.new(:token, :secret)
+      extend Token
+
+      def get_authorization_url(options = {})
+        url = Addressable::URI.parse(URL)
+        url.path += "/authorize"
+        url.query_values = {
+          :oauth_token => token,
+          :perms => options[:permissions] || options[:perms]
+        }
+        url.to_s
+      end
+    end
 
-    def consumer
-      @consumer ||= OAuth::Consumer.new(api_key, shared_secret)
+    class AccessToken < Struct.new(:token, :secret)
+      extend Token
     end
   end
 end

data/lib/flickrie/version.rb

@@ -1,3 +1,3 @@
 module Flickrie
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/flickrie.rb

@@ -47,6 +47,12 @@ module Flickrie
     alias add_photo_tags add_media_tags
     alias add_video_tags add_media_tags
 
+    def delete_media(media_id)
+      client.delete_media(media_id)
+    end
+    alias delete_photo delete_media
+    alias delete_video delete_media
+
     def get_media_info(media_id)
       response = client.get_media_info(media_id)
       Media.from_info(response.body['photo'])

data/test/media_test.rb

@@ -12,8 +12,8 @@ class MediaTest < Test::Unit::TestCase
   def setup
     Flickrie.api_key = ENV['FLICKR_API_KEY']
     Flickrie.shared_secret = ENV['FLICKR_SHARED_SECRET']
-    Flickrie.token = ENV['FLICKR_TOKEN']
-    Flickrie.token_secret = ENV['FLICKR_TOKEN_SECRET']
+    Flickrie.access_token = ENV['FLICKR_ACCESS_TOKEN']
+    Flickrie.access_secret = ENV['FLICKR_ACCESS_SECRET']
     @media_id = 6946979188
     @set_id = 72157629851991663
     @user_nsid = '67131352@N04'

data/test/oauth_test.rb

@@ -0,0 +1,27 @@
+require 'test/unit'
+require 'flickrie/client'
+require 'flickrie/oauth'
+
+class OAuthTest < Test::Unit::TestCase
+  def test_raising_errors
+    Flickrie.api_key = "foo"
+    Flickrie.shared_secret = "foo"
+
+    assert_raises(Flickrie::OAuth::Error) do
+      Flickrie::OAuth.get_request_token
+    end
+
+    Flickrie.api_key = ENV['FLICKR_API_KEY']
+    assert_raises(Flickrie::OAuth::Error) do
+      Flickrie::OAuth.get_request_token
+    end
+
+    Flickrie.shared_secret = ENV['FLICKR_SHARED_SECRET']
+    assert_nothing_raised { Flickrie::OAuth.get_request_token }
+
+    request_token = Flickrie::OAuth.get_request_token
+    assert_raises(Flickrie::OAuth::Error) do
+      Flickrie::OAuth.get_access_token("foo", request_token)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flickrie
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday_middleware
-  requirement: &70309320225020 !ruby/object:Gem::Requirement
+  requirement: &70240604302180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70309320225020
+  version_requirements: *70240604302180
 - !ruby/object:Gem::Dependency
   name: simple_oauth
-  requirement: &70309320251620 !ruby/object:Gem::Requirement
+  requirement: &70240604300760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,18 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70309320251620
+  version_requirements: *70240604300760
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: &70240604298180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70240604298180
 description: This gem is a nice wrapper for the Flickr API with an intuitive interface.
 email:
 - janko.marohnic@gmail.com
@@ -65,6 +76,7 @@ files:
 - test/license_test.rb
 - test/location_test.rb
 - test/media_test.rb
+- test/oauth_test.rb
 - test/photo_test.rb
 - test/set_test.rb
 - test/user_test.rb
@@ -101,6 +113,7 @@ test_files:
 - test/license_test.rb
 - test/location_test.rb
 - test/media_test.rb
+- test/oauth_test.rb
 - test/photo_test.rb
 - test/set_test.rb
 - test/user_test.rb