flickrie 0.7.1 → 0.7.2

data/.gitignore

@@ -2,6 +2,7 @@ TODO.md
 Gemfile.lock
 pkg/
 doc/
+wiki/
 .DS_Store
-spec/vcr_cassettes
 api_methods.md
+.bundle/

data/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Flickrie changelog
 
+## Version 0.7.2
+
+- 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
+  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
 
-- cover `flickr.photos.getFavorites` and `flickr.test.login`
+- covered `flickr.photos.getFavorites` and `flickr.test.login`
 - bug fixes (especially regarding the `Flickr::Instance`)
 
 ## Version 0.6.1

data/Gemfile

@@ -2,10 +2,11 @@ source :rubygems
 
 gemspec
 
-gem "faraday", "~> 0.7.6"
-
-group :development, :test do
-  gem "flickrie", :path => "~/Projects/flickrie"
-  gem "pry"
-  gem "debugger"
+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

data/README.md

@@ -117,7 +117,7 @@ So, in your ERB template you could do something like this (in Rails):
 ```
 
 You can see the full list of available methods and attributes in the
-[documentation](http://janko-m.github.com/flickrie/doc/Flickrie.html).
+[documentation](http://janko-m.github.com/flickrie/Flickrie.html).
 For photos (and videos) have a look at the `Flickrie::Media` module,
 because it's included into `Flickrie::Photo` and `Flickrie::Video`, and most
 of the attributes are there.
@@ -214,6 +214,23 @@ 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,25 +1,63 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
-task :spec, :spec do |task, args|
-  command = "bundle exec rspec -I spec --require 'spec_helper'"
-  if args['spec'].nil?
-    system(command)
-  else
-    system(command + " spec/#{args['spec']}_spec.rb")
+desc "Run the specs (use spec:name to run a single spec)"
+task :spec do |task, args|
+  system "bundle exec rspec --color"
+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"
   end
 end
 
+desc "Open the console with credentials (API key, secret etc.) already filled in"
 task :console do
+  File.open("credentials.rb", "w") do |f|
+    f.write <<-CREDENTIALS
+      Flickrie.api_key = ENV['FLICKR_API_KEY']
+      Flickrie.shared_secret = ENV['FLICKR_SHARED_SECRET']
+      Flickrie.access_token = ENV['FLICKR_ACCESS_TOKEN']
+      Flickrie.access_secret = ENV['FLICKR_ACCESS_SECRET']
+    CREDENTIALS
+  end
   begin
     require 'pry'
-    system "bundle exec pry -I. --require 'flickrie' --require 'credentials'"
+    system "bundle exec pry --require 'flickrie' --require './credentials'"
   rescue LoadError
-    system "bundle exec irb -I. -r 'flickrie' -r 'credentials'"
+    system "bundle exec irb -r 'flickrie' -r './credentials'"
   end
+  FileUtils.remove_file "credentials.rb"
 end
 
 task :rdoc do
-  system "rm -rf doc/"
+  FileUtils.rm_rf "doc"
   system "rdoc lib/"
 end
+
+# copied from Rails
+begin
+  require 'rails/source_annotation_extractor'
+
+  desc "Enumerate all annotations (use notes:optimize, :fixme, :todo for focus)"
+  task :notes do
+    SourceAnnotationExtractor.enumerate "OPTIMIZE|FIXME|TODO", :tag => true
+  end
+
+  namespace :notes do
+    ["OPTIMIZE", "FIXME", "TODO"].each do |annotation|
+      # desc "Enumerate all #{annotation} annotations"
+      task annotation.downcase.intern do
+        SourceAnnotationExtractor.enumerate annotation
+      end
+    end
+
+    desc "Enumerate a custom annotation, specify with ANNOTATION=CUSTOM"
+    task :custom do
+      SourceAnnotationExtractor.enumerate ENV['ANNOTATION']
+    end
+  end
+rescue LoadError
+end

data/flickrie.gemspec

@@ -1,26 +1,30 @@
 # encoding: utf-8
-require File.expand_path('../lib/flickrie/version', __FILE__)
+require File.expand_path("../lib/flickrie/version", __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.author        = "Janko Marohnić"
-  gem.email         = "janko.marohnic@gmail.com"
-  gem.description   = %q{This gem is a nice wrapper for the Flickr API with an intuitive interface.}
-  gem.summary       = %q{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 :)}
-  gem.homepage      = "https://github.com/janko-m/flickrie"
-
-  gem.files         = `git ls-files`.split($\)
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
-  gem.name          = "flickrie"
-  gem.require_paths = ["lib"]
   gem.version       = Flickrie::VERSION
 
-  gem.license       = "MIT"
+  gem.author       = "Janko Marohnić"
+  gem.email        = "janko.marohnic@gmail.com"
+  gem.description  = %q{This gem is a nice wrapper for the Flickr API with an intuitive interface.}
+  gem.summary      = %q{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 :)}
+  gem.homepage     = "https://github.com/janko-m/flickrie"
+
+  gem.files        = `git ls-files`.split($\)
+  gem.test_files   = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name         = "flickrie"
+  gem.require_path = "lib"
+
+  gem.license      = "MIT"
+
+  gem.required_ruby_version = ">= 1.9.2"
 
-  gem.add_dependency "faraday_middleware"
+  gem.add_dependency "faraday_middleware", '>= 0.8.7', '< 0.9'
+  gem.add_dependency "faraday", '>= 0.7.6', '< 0.9'
   gem.add_dependency "simple_oauth", '~> 0.1'
   gem.add_dependency "multi_xml", '~> 0.4'
 
-  gem.add_development_dependency "activesupport", '>= 3'
+  gem.add_development_dependency "rake", '~> 0.9'
   gem.add_development_dependency "rspec", '>= 2'
-  gem.add_development_dependency "vcr"
+  gem.add_development_dependency "vcr", '>= 2', '< 3'
 end

data/lib/flickrie/api_methods.rb

@@ -12,6 +12,15 @@ require 'flickrie/ticket'
 
 module Flickrie
   module ApiMethods
+    # ==== Example
+    #
+    #   path = File.expand_path("photo.jpg")
+    #   id = Flickrie.upload(path, :title => "Me and Jessica", :description => "...")
+    #   photo = Flickrie.get_photo_info(id)
+    #   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
@@ -21,6 +30,16 @@ module Flickrie
       end
     end
 
+    # ==== Example
+    #
+    #   path = File.expand_path("photo.jpg")
+    #   photo_id = 42374 # ID of the photo to be replaced
+    #   id = Flickrie.replace(path, photo_id, :title => "Me and Jessica", :description => "...")
+    #   photo = Flickrie.get_photo_info(id)
+    #   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
@@ -169,6 +188,8 @@ module Flickrie
 
     #--
     # photos.upload
+    #++
+    # Returns an array of Flickrie::Ticket
     def check_upload_tickets(tickets, params = {})
       tickets = tickets.join(',') if tickets.respond_to?(:join)
       response = client.check_upload_tickets(tickets, params)
@@ -178,6 +199,8 @@ module Flickrie
 
     #--
     # licenses
+    #++
+    # Returns an array of Flickrie::License
     def get_licenses(params = {})
       response = client.get_licenses(params)
       License.from_hash(response.body['licenses']['license'])

data/lib/flickrie/client.rb

@@ -1,9 +1,13 @@
 require 'faraday_middleware'
 
 module Flickrie
+  DEFAULTS = {
+    :open_timeout => 4,
+    :timeout => 6
+  }.freeze
+
   class << self
-    # :nodoc:
-    def self.attr_accessor_with_client_reset(*attributes)
+    def self.attr_accessor_with_client_reset(*attributes) # :nodoc:
       attr_reader *attributes
 
       attributes.each do |attribute|
@@ -14,15 +18,19 @@ module Flickrie
       end
     end
 
-    # :doc:
     attr_accessor_with_client_reset :api_key, :shared_secret,
       :timeout, :open_timeout, :access_token, :access_secret
 
+    # ==== Example
+    #
+    #   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 = {})
+    def new_client(access_token_hash = {}) # :nodoc:
       Client.new(params) do |conn|
         conn.use FaradayMiddleware::OAuth,
           :consumer_key => api_key,
@@ -34,15 +42,12 @@ module Flickrie
         conn.use FaradayMiddleware::ParseJson, :content_type => /(text\/plain)|(json)$/
         conn.use OAuthStatusCheck
 
-        conn.adapter Faraday.default_adapter
+        conn.adapter :net_http
       end
     end
 
     private
 
-    OPEN_TIMEOUT = 4
-    TIMEOUT = 6
-
     def params
       {
         :url => 'http://api.flickr.com/services/rest',
@@ -52,8 +57,8 @@ module Flickrie
           :api_key => api_key
         },
         :request => {
-          :open_timeout => open_timeout || OPEN_TIMEOUT,
-          :timeout => timeout || TIMEOUT
+          :open_timeout => open_timeout || DEFAULTS[:open_timeout],
+          :timeout => timeout || DEFAULTS[:timeout]
         }
       }
     end
@@ -86,7 +91,7 @@ module Flickrie
     end
   end
 
-  class Client < Faraday::Connection
+  class Client < Faraday::Connection # :nodoc:
     def get(method, params = {})
       super() do |req|
         req.params[:method] = method

data/lib/flickrie/instance.rb

@@ -6,6 +6,13 @@ module Flickrie
       @access_token, @access_secret = access_token, access_secret
     end
 
+    # ==== Example
+    #
+    #   flickrie = Flickrie::Instance.new("ACCESS_TOKEN", "ACCESS_SECRET")
+    #
+    #   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/media/exif.rb

@@ -1,6 +1,14 @@
 module Flickrie
   module Media
     class Exif
+      # ==== Example
+      #
+      #   photo.exif.get('Model') # => 'Canon PowerShot G12'
+      #
+      #   photo.exif.get('X-Resolution', :data => 'raw')   # => '180'
+      #   photo.exif.get('X-Resolution', :data => 'clean') # => '180 dpi'
+      #   photo.exif.get('X-Resolution')                   # => '180 dpi'
+      #
       def get(key, options = {})
         hash = @info.find { |hash| hash['label'] == key }
         data = hash[options[:data]] || hash['clean'] || hash['raw']
@@ -10,9 +18,10 @@ module Flickrie
         nil
       end
 
-      def [](key)
-        @info[key]
-      end
+      def [](key) @info[key] end
+      def hash() @info end
+
+      private
 
       def initialize(info)
         raise ArgumentError if info.nil?

data/lib/flickrie/media/note.rb

@@ -8,6 +8,11 @@ module Flickrie
         @content
       end
 
+      def [](key) @info[key] end
+      def hash() @info end
+
+      private
+
       def initialize(hash)
         @id = hash['id']
         @author = User.new \

data/lib/flickrie/media/tag.rb

@@ -13,9 +13,10 @@ module Flickrie
         User.new('nsid' => @info['author']) if @info['author']
       end
 
-      def [](key)
-        @info[key]
-      end
+      def [](key) @info[key] end
+      def hash() @info end
+
+      private
 
       def initialize(info)
         @info = info

data/lib/flickrie/media/visibility.rb

@@ -6,9 +6,10 @@ module Flickrie
       def family?()   @info['isfamily'].to_i == 1 if @info['isfamily']   end
       def contacts?() @info['iscontact'].to_i == 1 if @info['iscontact'] end
 
-      def [](key)
-        @info[key]
-      end
+      def [](key) @info[key] end
+      def hash() @info end
+
+      private
 
       def initialize(info)
         raise ArgumentError if info.nil?

data/lib/flickrie/media.rb

@@ -30,12 +30,22 @@ module Flickrie
     def views_count()    Integer(@info['views'])          rescue nil end
     def comments_count() Integer(@info['comments_count']) rescue nil end
 
+    # Returns an instance of Flickrie::Location
+    #
     def location() Location.new(@info['location']) rescue nil end
+    # Returns an instance of Flickrie::Media::Visibility
+    #
     def geo_permissions() Visibility.new(@info['geoperms']) rescue nil end
 
+    # Returns an array of Flickrie::Media::Tag
+    #
     def tags() @info['tags'].map { |info| Tag.new(info) }     rescue nil end
+    # Returns an array of Flickrie::Media::Tag
+    #
     def machine_tags() tags.select { |tag| tag.machine_tag? } rescue nil end
 
+    # Returns an instance of Flickrie::License
+    #
     def license() License.new(@info['license']) rescue nil end
 
     def posted_at()   Time.at(Integer(@info['dates']['posted']))           rescue nil end
@@ -44,6 +54,8 @@ module Flickrie
     def taken_at()    DateTime.parse(@info['dates']['taken']).to_time      rescue nil end
     def taken_at_granularity() Integer(@info['dates']['takengranularity']) rescue nil end
 
+    # Returns an instance of Flickrie::User
+    #
     def owner() User.new(@info['owner']) rescue nil end
 
     def safety_level() Integer(@info['safety_level']) rescue nil end
@@ -52,6 +64,7 @@ module Flickrie
     def moderate?()   safety_level == 2 if safety_level end
     def restricted?() safety_level == 3 if safety_level end
 
+    #--
     # TODO: Take care about the url from #get_info
     def url
       if owner and id
@@ -61,6 +74,8 @@ module Flickrie
       end
     end
 
+    # Returns an instance of Flickrie::Media::Visibility
+    #
     def visibility() Visibility.new(@info['visibility']) rescue nil end
 
     def primary?() Integer(@info['isprimary']) == 1 rescue nil end
@@ -82,8 +97,12 @@ module Flickrie
 
     def faved?() Integer(@info['is_faved']) == 1 rescue nil end
 
+    # Returns an array of Flickrie::Media::Note
+    #
     def notes() @info['notes']['note'].map { |hash| Note.new(hash) } rescue nil end
 
+    # Returns an array of Flickrie::User
+    #
     def favorites() @info['person'].map { |info| User.new(info) } rescue nil end
 
     def [](key) @info[key] end

data/lib/flickrie/oauth.rb

@@ -8,18 +8,16 @@ module Flickrie
 
     # :nodoc:
     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 |conn|
-        conn.use FaradayMiddleware::OAuth, oauth_params
+        conn.use FaradayMiddleware::OAuth, {
+            :consumer_key => Flickrie.api_key,
+            :consumer_secret => Flickrie.shared_secret
+          }.merge(additional_oauth_params)
 
         conn.use StatusCheck
         conn.use ParseResponseParams
 
-        conn.adapter Faraday.default_adapter
+        conn.adapter :net_http
       end
     end
 

data/lib/flickrie/photo.rb

@@ -1,9 +1,9 @@
 module Flickrie
+  # See Flickrie::Media for the other methods.
+  #
   class Photo
     include Media
 
-    attr_reader :size
-
     SIZES = {
       'Square 75'  => 'sq',
       'Thumbnail'  => 't',
@@ -17,6 +17,8 @@ module Flickrie
       'Original'   => 'o'
     }
 
+    def size() @size end
+
     def square!(number) @size = "Square #{number}"; self end
     def thumbnail!()    @size = "Thumbnail";        self end
     def small!(number)  @size = "Small #{number}";  self end
@@ -63,6 +65,8 @@ module Flickrie
 
     def rotation() Integer(@info['rotation']) rescue nil end
 
+    # Same as calling <tt>Flickrie.get_photo_sizes(photo.id)</tt>
+    #
     def get_sizes(params = {}, info = nil)
       info ||= Flickrie.client.get_media_sizes(id, params).body['sizes']
       @info['usage'] ||= {}

data/lib/flickrie/set.rb

@@ -19,10 +19,18 @@ module Flickrie
       photos_count + videos_count rescue nil
     end
 
+    # Returns an instance of Flickrie::User
+    #
     def owner() User.new('nsid' => @info['owner']) if @info['owner'] end
 
+    # Same as calling <tt>Flickrie.photos_from_set(set.id)</tt>
+    #
     def photos(params = {}) Flickrie.photos_from_set(id, params) end
+    # Same as calling <tt>Flickrie.videos_from_set(set.id)</tt>
+    #
     def videos(params = {}) Flickrie.videos_from_set(id, params) end
+    # Same as calling <tt>Flickrie.media_from_set(set.id)</tt>
+    #
     def media(params = {})  Flickrie.media_from_set(id, params)  end
 
     def can_comment?() Integer(@info['can_comment']) == 1 rescue nil end
@@ -42,6 +50,8 @@ module Flickrie
     def [](key) @info[key] end
     def hash() @info end
 
+    # Same as calling <tt>Flickrie.get_set_info(set.id)</tt>
+    #
     def get_info(info = nil)
       info ||= Flickrie.client.get_set_info(id).body['photoset']
       @info.update(info)

data/lib/flickrie/upload_client.rb

@@ -1,5 +1,6 @@
 module Flickrie
   class << self
+    # :nodoc:
     def upload_client
       @upload_client ||= new_upload_client
     end
@@ -17,7 +18,7 @@ module Flickrie
         conn.use FaradayMiddleware::ParseXml
         conn.use OAuthStatusCheck
 
-        conn.adapter Faraday.default_adapter
+        conn.adapter :net_http
       end
     end
 
@@ -27,7 +28,7 @@ module Flickrie
       {
         :url => 'http://api.flickr.com/services',
         :request => {
-          :open_timeout => open_timeout || OPEN_TIMEOUT
+          :open_timeout => open_timeout || DEFAULTS[:open_timeout]
         }
       }
     end
@@ -43,7 +44,7 @@ module Flickrie
     end
   end
 
-  class UploadClient < Faraday::Connection
+  class UploadClient < Faraday::Connection # :nodoc:
     def upload(media, params = {})
       media_file = get_file(media, params[:mime_type])
       media_title = get_title(media)
@@ -80,16 +81,13 @@ module Flickrie
     }.freeze
 
     def get_file(object, mime_type = nil)
-      if object.class.name == "String"
-        # file path
+      if object.class.name == "String" # file path
         file_path = object
         mime_type ||= get_mime_type(file_path)
-      elsif object.class.name == "ActionDispatch::Http::UploadedFile"
-        # Rails
+      elsif object.class.name == "ActionDispatch::Http::UploadedFile" # Rails
         file_path = object.tempfile
         mime_type ||= object.content_type
-      elsif object.class.name == "Hash"
-        # Sinatra
+      elsif object.class.name == "Hash" # Sinatra
         file_path = object[:tempfile].path
         mime_type ||= object[:type]
       end
@@ -107,11 +105,11 @@ module Flickrie
 
     def get_title(object)
       filename =
-        if object.class.name == "String"
+        if object.class.name == "String" # file path
           File.basename(object)
-        elsif object.class.name == "ActionDispatch::Http::UploadedFile"
+        elsif object.class.name == "ActionDispatch::Http::UploadedFile" # Rails
           object.original_filename
-        elsif object.class.name == "Hash"
+        elsif object.class.name == "Hash" # Sinatra
           object[:filename]
         end
 

data/lib/flickrie/user.rb

@@ -39,6 +39,8 @@ module Flickrie
     alias photos_count media_count
     alias videos_count media_count
 
+    # The same as calling <tt>Flickrie.public_photos_from_user(user.nsid)</tt>
+    #
     def public_photos() Flickrie.public_photos_from_user(nsid) end
 
     def pro?() Integer(@info['ispro']) == 1 rescue nil end
@@ -46,6 +48,8 @@ module Flickrie
     def [](key) @info[key] end
     def hash() @info end
 
+    # The same as calling <tt>Flickrie.get_user_info(user.nsid)</tt>
+    #
     def get_info(params = {}, info = nil)
       info ||= Flickrie.client.get_user_info(nsid, params).body['person']
       @info.update(info)

data/lib/flickrie/version.rb

@@ -1,3 +1,3 @@
 module Flickrie
-  VERSION = '0.7.1'
+  VERSION = "0.7.2"
 end

data/lib/flickrie/video.rb

@@ -1,4 +1,6 @@
 module Flickrie
+  # See Flickrie::Media for the other methods.
+  #
   class Video
     include Media
 
@@ -15,6 +17,8 @@ module Flickrie
     def download_url()        @video['download_url']        end
     def mobile_download_url() @video['mobile_download_url'] end
 
+    # This fetches the #source_url, #download_url and the #mobile_download_url
+    #
     def get_sizes(params = {}, info = nil)
       info ||= Flickrie.client.get_media_sizes(id, params).body['sizes']
       @info['usage'] ||= {}

data/spec/api_methods_spec.rb

@@ -1,3 +1,5 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "spec_helper"))
+
 describe Flickrie::ApiMethods do
   it "should have certain methods working" do
     VCR.use_cassette "api_methods/upload_and_delete" do