flickrie 0.7.3 → 1.0.0

data/.gitignore

@@ -6,3 +6,4 @@ wiki/
 .DS_Store
 api_methods.md
 .bundle/
+.rspec

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3

data/CHANGELOG.md

@@ -1,82 +1,122 @@
 # Flickrie changelog
 
+## Version 1.0.0
+
+- Changes that are backwards compatible:
+
+-- Fixed content type not being passed to the file you're uploading
+   if you specified it directly.
+
+-- The request will now be retried once more if it timeouts
+
+-- In authentication:
+--- you can now call `request_token.authorize_url` instead of `request_token.get_authorization_url`.
+--- you can now call `request_token.get_access_token(code)` instead of `Flickrie::OAuth.get_access_token(code, request_token)`.
+--- you also get the infomation about the user who just authenticated,
+    which you can then access with `access_token.user_info`
+    (it's a Hash with keys `:fullname`, `:user_nsid` and `:username`)
+
+-- When calling `Flickrie.get_photos_counts`, the `Flickrie::MediaCount`
+   now also has attributes `#time_interval` (alias for `#date_range`),
+   `#from` and `#to`.
+
+- Changes that are **not** backwards compatible:
+
+-- If you're passing in the content type of the file you're uploading,
+   the parameter is now called `:content_type`, not `:mime_type`.
+
+-- If there is a problem in obtaining the access token, `Flickrie::Error`
+   is now raised, instead of `Flickrie::OAuth::Error`.
+
+-- When you're calling `request_token.get_authorization_url`, if you want to
+   specifiy permissions, you now have to pass the `:perms` option,
+   instead of `:permissions`. In this way you can pass any parameter,
+   and it will be appended to the URL (in case Flickr adds a new parameter).
+
+-- When you have a `Flickrie::User` instance, the
+   `Flickrie::User#time_zone` now returns a struct with `#label` and
+   `#offset` attributes (before it returned a `Hash` with those keys).
+
+-- When you call `Flickrie.get_media_context`, the result is now a
+   struct with attributes `#count`, `#previous`, `#next`.
+
 ## Version 0.7.3
 
-- covered "flickr.people.getPhotos" (I released it as a patch because
-  it's important)
+- Covered "flickr.people.getPhotos" (I released it as a patch because
+  it's important).
 
 ## Version 0.7.2
 
-- specified versions of dependencies and Ruby accurately
+- Specified versions of dependencies and Ruby accurately.
 
 ## Version 0.7.1
 
-- fixed an oauth bug
-- added `#hash` method to photos, sets etc. which you can call to get the
+- Fixed an oauth bug.
+- Added `#hash` method to photos, sets etc. which you can call to get the
   raw data (in Ruby hash). This is useful if I accidentally left something out,
   or if Flickr added something new that I didn't cover yet, that you can
   still get to the data. `#[]` reads from the same hash.
 
 ## Version 0.7.0
 
-- covered `flickr.photos.getFavorites` and `flickr.test.login`
-- bug fixes (especially regarding the `Flickr::Instance`)
+- Covered `flickr.photos.getFavorites` and `flickr.test.login`.
+- Bug fixes (especially regarding the `Flickr::Instance`).
 
 ## Version 0.6.1
 
-- `Flickrie::Media::Ticket` is now called just `Flickrie::Ticket`
+- `Flickrie::Media::Ticket` is now called just `Flickrie::Ticket`.
 
 ## Version 0.6.0
 
-- you can access the raw response hash with square brackets, if you notice I
+- You can access the raw response hash with square brackets, if you notice I
   didn't cover some part of it with methods. So, for example, after calling
-  `Flickrie.get_photo_info`, you can get the photo ID by calling `photo['id']`
+  `Flickrie.get_photo_info`, you can get the photo ID by calling `photo['id']`.
 
-- when `Flickrie::Error` is raised, you can now access its `#code`
+- When `Flickrie::Error` is raised, you can now access its `#code`
   attribute. This makes better error handling, because error code
-  is (supposed to be) unique, unlike the error message
+  is (supposed to be) unique, unlike the error message.
 
 ## Version 0.5.2
 
-- the gem now also works with Faraday 0.7 (I apologize for not
-  making Faraday >= 0.8 a dependency before)
+- The gem now also works with Faraday 0.7 (I apologize for not
+  making Faraday >= 0.8 a dependency before).
 
 ## Version 0.5.1
 
-- fixed a documentation error
+- Fixed a documentation error.
 
 ## Version 0.5.0
 
-- covered `flickr.photos.getCounts`
-- covered `flickr.photos.getExif`
+- Covered `flickr.photos.getCounts`.
+- Covered `flickr.photos.getExif`.
 
 ## Version 0.4.1
 
-- handle file uploads for Rails and Sinatra smarter (see [this wiki](https://github.com/janko-m/flickrie/wiki/Some-tips.md), tip #7)
+- Handle file uploads for Rails and Sinatra smarter (see [this wiki](https://github.com/janko-m/flickrie/wiki/Some-tips.md), tip #7)
 
 ## Version 0.4.0
 
-- covered `flickr.photos.getContactsPhotos`
-- covered `flickr.photos.getContactsPublicPhotos`
-- covered `flickr.photos.getContext`
-- implemented uploading photos
-- covered `flickr.photos.upload.checkTickets`
+- Covered `flickr.photos.getContactsPhotos`.
+- Covered `flickr.photos.getContactsPublicPhotos`.
+- Covered `flickr.photos.getContext`.
+- Implemented uploading photos.
+- Covered `flickr.photos.upload.checkTickets`.
 
 ## Version 0.3.2
 
-- enabled passing params to `Flickrie::Set#photos`
+- Enabled passing params to `Flickrie::Set#photos`.
 
 ## Version 0.3.1
 
-- fixed an error when accessing tags from photos fetched through
-  certain API calls
+- Fixed an error when accessing tags from photos fetched through
+  certain API calls.
 
 ## Version 0.3.0
 
-- the proper error is now raised on wrong access tokens
-- implemented a better way of using access tokens, using `Flickrie::Instance.new(access_token, access_secret)`
-  (see [this wiki](https://github.com/janko-m/flickrie/wiki/Authentication-in-web-applications) for an example)
+- The proper error is now raised on wrong access tokens.
+- Implemented a better way of using access tokens, using `Flickrie::Instance.new(access_token, access_secret)`
+  (see [this wiki](https://github.com/janko-m/flickrie/wiki/Authentication-in-web-applications) for an example).
 
 ## Version 0.2.2
 
-- removed `addressable` gem as a dependency
+- Removed `addressable` gem as a dependency.

data/Gemfile

@@ -6,7 +6,8 @@ group :test do
   gem "faraday", '0.7.6'
 end
 
-# You can run `bundle [install] --without debugger pry` if
-# you don't want to install them
-gem "debugger", :group => :debugger
-gem "pry",      :group => :pry
+# You can run `bundle [install] --without extras` if you don't want to install them
+group :extras do
+  gem "debugger"
+  gem "pry"
+end

data/README.md

@@ -1,31 +1,38 @@
-# Flickrie
+# Flickrie [![Build Status](https://secure.travis-ci.org/janko-m/flickrie.png)](http://travis-ci.org/janko-m/flickrie)
 
 ## About
 
-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 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. Take a look at the "Covered API
-methods" section of this readme.
-
-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 :)
-
-There are 2 things that are different from the Flickr's API documentation:
-- "photoset" is here just "set". This is because the word "photoset" is actually
-incorrect, since sets can also hold videos.
-- "person" is here refered to as "user".
+This gem is a nice wrapper for the Flickr API with an object-oriented interface.
+
+The reason why I did this gem is because the existing ones either weren't
+well maintained, or they weren't object oriented and provided a literal
+wrapper over the API. That didn't statisfy me, because Flickr API
+sometimes gives you the same information in different ways. And I want
+to normalize that. Also, JSON responses can return "time" attributes
+only in the string format. And I thought it would be nice that, if you're
+accessing the `updated_at` attribute for example, you actually **get**
+an instance of `Time`, instead of a string, or even integer. These are
+just some of the reason I decided to make this gem.
+
+The method names here aren't called the same as Flickr's API methods
+(and they can't be), but they follow a pattern which
+shouldn't be too difficult to predict. Take a look at the ["Currently covered API
+methods"](https://github.com/janko-m/flickrie#currently-covered-api-methods) section of this readme.
+
+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?`. Because this
+is a **ruby** wrapper, I wanted to write it in Ruby/Rails fashion. At
+first you might not approve of this, because then you might not know
+what the methods name are if you know the name of the key in the
+response hash. But, on the other hand, Flickr often gives you the same
+information in different formats, so this also acts as a normalizer. The
+downsize of this approach is that it may not be up to date when the
+Flickr API changes, but that's why I have **you** to open a new issue
+when you notice something isn't working :)
+
+The gem works on Ruby versions `1.9.2` and `1.9.3`. Also, it follows
+[Semantic versioning](http://semver.org/).
 
 ## Examples of usage
 
@@ -35,16 +42,25 @@ You first need to install the gem.
 [sudo] gem install flickrie
 ```
 
+Then, if you're using Bundler in your project, put it into your `Gemfile`:
+
+```ruby
+gem "flickrie"
+```
+
 Then in your app you set the API key and shared secret (if you don't have them
 already, you can apply for them [here](http://www.flickr.com/services/apps/create/apply)).
 
 ```ruby
 require 'flickrie'
+
 Flickrie.api_key = "API_KEY"
 Flickrie.shared_secret = "SHARED_SECRET"
 ```
 
-Then you can search for stuff.
+If your in Rails, it's a good idea to put this into an initializer.
+
+Now you can search for stuff.
 
 ```ruby
 set_id = 819234
@@ -64,7 +80,7 @@ You can also throw in some parameters to `Flickrie.photos_from_set` to get more
 photos = Flickrie.photos_from_set(819234, :extras => 'owner_name,last_update,tags,views')
 
 photo = photos.first
-photo.tags           # => "cave cold forrest"
+photo.tags.join(' ') # => "cave cold forrest"
 photo.owner.username # => "jsmith"
 photo.updated_at     # => 2012-04-20 23:29:17 +0200
 photo.views_count    # => 24
@@ -86,7 +102,7 @@ photo.owner.real_name       # => "John Smith"
 photo.location.country.name # => "United States"
 ```
 
-If you already have an existing photo, you can also get info like this:
+If you already have an existing photo (providing it holds its ID), you can also get info like this:
 
 ```ruby
 photo.description # => nil
@@ -133,15 +149,17 @@ Flickrie.api_key = "API_KEY"
 Flickrie.shared_secret = "SHARED_SECRET"
 
 request_token = Flickrie::OAuth.get_request_token
-url = request_token.get_authorization_url
+url = request_token.authorize_url
 puts "Visit this url to authenticate: #{url}"
 
 print "If you agreed, the code was displayed afterwards. Enter it: "
 code = gets.strip
-access_token = Flickrie::OAuth.get_access_token(code, request_token)
+access_token = request_token.get_access_token(code)
+puts "You successfully authenticated!"
+
 Flickrie.access_token = access_token.token
 Flickrie.access_secret = access_token.secret
-puts "You successfully authenticated!"
+access_token.user_params # => {:fullname => "John Smith", :user_nsid => "67131352@N03", :username => "jsmith"}
 ```
 
 When getting the authorization url, you can also call
@@ -151,8 +169,11 @@ request_token.get_authorization_url(:permissions => "read")
 to ask only for "read" permissions from the user. Available permissions
 are "read", "write" and "delete".
 
-If you want to make authentication in your web application, check out my [flickr_auth](https://github.com/janko-m/flickr_auth) gem.
-Or, if you want to do it manually, check out [this wiki](https://github.com/janko-m/flickrie/wiki/Authentication-in-web-applications) for instructions.
+If you want to make authentication in your web application, check out my
+[flickr_auth](https://github.com/janko-m/flickr_auth) gem.
+Or, if you want to do it manually, check out
+[this wiki](https://github.com/janko-m/flickrie/wiki/Authentication-in-web-applications)
+for instructions.
 
 ## Photo upload
 
@@ -165,9 +186,7 @@ photo.title # => "A cow"
 For the list of parameters you can pass in when uploading a photo, see
 [this page](http://www.flickr.com/services/api/upload.api.html).
 
-Few notes:
-- Photo uploads require authentication with "write" permissions.
-- Path to the photo has to be absolute.
+Note that photo uploads require authentication with "write" permissions.
 
 See [this wiki](https://github.com/janko-m/flickrie/wiki/Asynchronous-photo-upload) for an example
 of an asynchronous photo upload.
@@ -214,23 +233,6 @@ default.
 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.
 
-## How to contribute
-
-Nothing special, you just fork the project, and send me a pull request.
-Don't forget to cover the change with tests. If you don't know how to
-write tests, send the pull requests without them, it's ok.
-
-An important note: if you want to add a line in the tests which makes a **new** HTTP request,
-you'll have to get your own API key and access token. You can get the
-API key and secret [here](http://www.flickr.com/services/apps/create/apply)
-(assuming you already have a Flickr account), and you can then obtain an access token by using my
-authentication system (described above). You then have to assign these
-values to the environment variables `FLICKR_API_KEY`, `FLICKR_SHARED_SECRET`,
-`FLICKR_ACCESS_TOKEN` and `FLICKR_ACCESS_SECRET`. That's it, you should
-be able to run the tests normally now.
-
-Feel free to email me if you have any problems.
-
 ## Cedits
 
 Special thanks to @**mislav**, my brother, he helped me really a lot

data/Rakefile

@@ -1,15 +1,17 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
+task :default => :spec
+
 desc "Run the specs (use spec:name to run a single spec)"
 task :spec do |task, args|
-  system "bundle exec rspec --color"
+  system "rspec -Ispec"
 end
 
 Dir["spec/*_spec.rb"].each do |spec|
   task_name = File.basename(spec)[/.+(?=_spec\.rb)/]
   task :"spec:#{task_name}" do
-    system "bundle exec rspec #{spec} --color"
+    system "rspec -Ispec #{spec}"
   end
 end
 
@@ -25,18 +27,13 @@ task :console do
   end
   begin
     require 'pry'
-    system "bundle exec pry --require 'flickrie' --require './credentials'"
+    system "pry --require 'flickrie' --require './credentials'"
   rescue LoadError
-    system "bundle exec irb -r 'flickrie' -r './credentials'"
+    system "irb -r 'flickrie' -r './credentials'"
   end
   FileUtils.remove_file "credentials.rb"
 end
 
-task :rdoc do
-  FileUtils.rm_rf "doc"
-  system "rdoc lib/"
-end
-
 # copied from Rails
 begin
   require 'rails/source_annotation_extractor'

data/lib/flickrie/api_methods.rb

@@ -1,3 +1,4 @@
+require 'flickrie/middleware'
 require 'flickrie/client'
 require 'flickrie/upload_client'
 require 'flickrie/oauth'
@@ -20,7 +21,6 @@ module Flickrie
     #   photo.title # => "Me and Jessica"
     #
     # If the <tt>:async => 1</tt> option is passed, returns the ticket ID.
-    #
     def upload(media, params = {})
       response = upload_client.upload(media, params)
       if params[:async] == 1
@@ -39,7 +39,6 @@ module Flickrie
     #   photo.title # => "Me and Jessica"
     #
     # If the <tt>:async => 1</tt> option is passed, returns the ticket ID.
-    #
     def replace(media, media_id, params = {})
       response = upload_client.replace(media, media_id, params)
       if params[:async] == 1
@@ -131,6 +130,12 @@ module Flickrie
         select { |media| media.is_a?(Photo) }
     end
 
+    # ==== Example
+    #
+    #   context = Flickrie.get_photo_context(37124234)
+    #   context.count    # => 23
+    #   context.previous # => #<Photo: id=2433240, ...>
+    #   context.next     # => #<Video: id=1282404, ...>
     def get_media_context(media_id, params = {})
       response = client.get_media_context(media_id, params)
       Media.from_context(response.body)
@@ -138,6 +143,7 @@ module Flickrie
     alias get_photo_context get_media_context
     alias get_video_context get_media_context
 
+    # Returns instances of Flickrie::MediaCount
     def get_media_counts(params = {})
       response = client.get_media_counts \
         MediaCount.ensure_utc(params)
@@ -147,19 +153,23 @@ module Flickrie
     alias get_photos_counts get_media_counts
     alias get_videos_counts get_media_counts
 
+    # See Flickrie::Media#exif for details
     def get_photo_exif(photo_id, params = {})
       response = client.get_media_exif(photo_id, params)
       Photo.from_exif(response.body['photo'])
     end
+    # See Flickrie::Media#exif for details
     def get_video_exif(video_id, params = {})
       response = client.get_media_exif(video_id, params)
       Video.from_exif(response.body['photo'])
     end
 
+    # Returns instances of Flickrie::User
     def get_photo_favorites(photo_id, params = {})
       response = client.get_media_favorites(photo_id, params)
       Photo.new(response.body['photo'])
     end
+    # Returns instances of Flickrie::User
     def get_video_favorites(video_id, params = {})
       response = client.get_media_favorites(video_id, params)
       Video.new(response.body['photo'])
@@ -169,14 +179,15 @@ module Flickrie
       response = client.get_media_info(media_id, params)
       Media.from_info(response.body['photo'])
     end
-
     alias get_photo_info get_media_info
     alias get_video_info get_media_info
 
+    # Returns an instance of Flickrie::Photo
     def get_photo_sizes(photo_id, params = {})
       response = client.get_media_sizes(photo_id, params)
       Photo.from_sizes(response.body['sizes'])
     end
+    # Returns an instance of Flickrie::Video
     def get_video_sizes(video_id, params = {})
       response = client.get_media_sizes(video_id, params)
       Video.from_sizes(response.body['sizes'])
@@ -244,6 +255,8 @@ module Flickrie
 
     #--
     # test
+    #++
+    # Returns an instance of Flickrie::User
     def test_login(params = {})
       response = client.test_login(params)
       User.from_test(response.body['user'])

data/lib/flickrie/client.rb

@@ -1,10 +1,8 @@
 require 'faraday_middleware'
 
 module Flickrie
-  DEFAULTS = {
-    :open_timeout => 4,
-    :timeout => 6
-  }.freeze
+  OPEN_TIMEOUT = 4
+  TIMEOUT = 6
 
   class << self
     def self.attr_accessor_with_client_reset(*attributes) # :nodoc:
@@ -25,24 +23,24 @@ module Flickrie
     #
     #   Flickrie.client.get  "flickr.photos.licenses.getInfo"
     #   Flickrie.client.post "flickr.photos.licenses.setLicense", :photo_id => 1241497, :license_id => 2
-    #
     def client
       @client ||= new_client
     end
 
     def new_client(access_token_hash = {}) # :nodoc:
-      Client.new(params) do |conn|
-        conn.use FaradayMiddleware::OAuth,
+      Client.new(params) do |b|
+        b.use Middleware::Retry
+        b.use FaradayMiddleware::OAuth,
           :consumer_key => api_key,
           :consumer_secret => shared_secret,
           :token => access_token_hash[:token] || access_token,
           :token_secret => access_token_hash[:secret] || access_secret
 
-        conn.use StatusCheck
-        conn.use FaradayMiddleware::ParseJson, :content_type => /(text\/plain)|(json)$/
-        conn.use OAuthStatusCheck
+        b.use Middleware::StatusCheck
+        b.use FaradayMiddleware::ParseJson
+        b.use Middleware::OAuthCheck
 
-        conn.adapter :net_http
+        b.adapter :net_http
       end
     end
 
@@ -57,40 +55,13 @@ module Flickrie
           :api_key => api_key
         },
         :request => {
-          :open_timeout => open_timeout || DEFAULTS[:open_timeout],
-          :timeout => timeout || DEFAULTS[:timeout]
+          :open_timeout => open_timeout || OPEN_TIMEOUT,
+          :timeout => timeout || TIMEOUT
         }
       }
     end
   end
 
-  class Error < StandardError
-    attr_reader :code
-
-    def initialize(message, code = nil)
-      super(message)
-      @code = code.to_i
-    end
-  end
-
-  class StatusCheck < Faraday::Response::Middleware # :nodoc:
-    def on_complete(env)
-      if env[:body]['stat'] != 'ok'
-        raise Error.new(env[:body]['message'], env[:body]['code']),
-          env[:body]['message']
-      end
-    end
-  end
-
-  class OAuthStatusCheck < Faraday::Response::Middleware # :nodoc:
-    def on_complete(env)
-      if env[:status] != 200
-        message = env[:body][/(?<=oauth_problem=)[^&]+/]
-        raise Error, message.gsub('_', ' ').capitalize
-      end
-    end
-  end
-
   class Client < Faraday::Connection # :nodoc:
     def get(method, params = {})
       super() do |req|

data/lib/flickrie/instance.rb

@@ -12,7 +12,6 @@ module Flickrie
     #
     #   flickrie.client.get "flickr.photos.licenses.getInfo"
     #   flickrie.client.post "flickr.photos.licenses.setLicense", :photo_id => 1241497, :license_id => 2
-    #
     def client
       @client ||= Flickrie.new_client(access_token_hash)
     end

data/lib/flickrie/location.rb

@@ -1,12 +1,18 @@
 module Flickrie
   class Location
-    attr_reader :latitude, :longitude, :accuracy, :context, :place_id, :woeid
+    def latitude()  @info['latitude']  end
+    def longitude() @info['longitude'] end
+    def accuracy()  @info['accuracy']  end
+    def context()   Integer(@info['context']) rescue nil end
 
-    def neighbourhood() place('neighbourhood') end
-    def locality()      place('locality')      end
-    def county()        place('county')        end
-    def region()        place('region')        end
-    def country()       place('country')       end
+    def neighbourhood() new_area('neighbourhood') end
+    def locality()      new_area('locality')      end
+    def county()        new_area('county')        end
+    def region()        new_area('region')        end
+    def country()       new_area('country')       end
+
+    def place_id() @info['place_id'] end
+    def woeid()    @info['woeid']    end
 
     def [](key) @info[key] end
     def hash() @info end
@@ -15,21 +21,18 @@ module Flickrie
 
     def initialize(info = {})
       raise ArgumentError if info.nil?
-
       @info = info
-
-      %w[latitude longitude accuracy place_id woeid].each do |attribute|
-        instance_variable_set "@#{attribute}", @info[attribute]
-      end
-      @context = Integer(@info['context']) rescue nil
     end
 
-    def place(place_name)
-      if @info[place_name]
-        Struct.new(:name, :place_id, :woeid).new \
-          @info[place_name]['_content'],
-          @info[place_name]['place_id'],
-          @info[place_name]['woeid']
+    def new_area(area_name)
+      if @info[area_name]
+        area_class = Class.new(Struct.new(:name, :place_id, :woeid)) do
+          def to_s
+            name
+          end
+        end
+        info = @info[area_name]
+        area_class.new(info['_content'], info['place_id'], info['woeid'])
       end
     end
   end