flickrie 1.0.0 → 1.0.1

data/lib/flickrie/client.rb

@@ -1,68 +1,7 @@
-require 'faraday_middleware'
+require 'faraday'
 
 module Flickrie
-  OPEN_TIMEOUT = 4
-  TIMEOUT = 6
-
-  class << self
-    def self.attr_accessor_with_client_reset(*attributes) # :nodoc:
-      attr_reader *attributes
-
-      attributes.each do |attribute|
-        define_method "#{attribute}=" do |value|
-          instance_variable_set "@#{attribute}", value
-          @client = @upload_client = nil
-        end
-      end
-    end
-
-    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 = {}) # :nodoc:
-      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
-
-        b.use Middleware::StatusCheck
-        b.use FaradayMiddleware::ParseJson
-        b.use Middleware::OAuthCheck
-
-        b.adapter :net_http
-      end
-    end
-
-    private
-
-    def params
-      {
-        :url => 'http://api.flickr.com/services/rest',
-        :params => {
-          :format => 'json',
-          :nojsoncallback => '1',
-          :api_key => api_key
-        },
-        :request => {
-          :open_timeout => open_timeout || OPEN_TIMEOUT,
-          :timeout => timeout || TIMEOUT
-        }
-      }
-    end
-  end
-
-  class Client < Faraday::Connection # :nodoc:
+  class Client < Faraday::Connection
     def get(method, params = {})
       super() do |req|
         req.params[:method] = method
@@ -77,7 +16,6 @@ module Flickrie
       end
     end
 
-    #--
     # people
     def find_user_by_email(email, params = {})
       get 'flickr.people.findByEmail',
@@ -89,22 +27,21 @@ module Flickrie
         {:username => username}.merge(params)
     end
 
-    def get_user_info(user_nsid, params = {})
+    def get_user_info(nsid, params = {})
       get 'flickr.people.getInfo',
-        {:user_id => user_nsid}.merge(params)
+        {:user_id => nsid}.merge(params)
     end
 
-    def media_from_user(user_nsid, params = {})
+    def media_from_user(nsid, params = {})
       get 'flickr.people.getPhotos',
-        ensure_media({:user_id => user_nsid}.merge(params))
+        ensure_media({:user_id => nsid}.merge(params))
     end
 
-    def public_media_from_user(user_nsid, params = {})
+    def public_media_from_user(nsid, params = {})
       get 'flickr.people.getPublicPhotos',
-        ensure_media({:user_id => user_nsid}.merge(params))
+        ensure_media({:user_id => nsid}.merge(params))
     end
 
-    #--
     # photos
     def add_media_tags(media_id, tags, params = {})
       post 'flickr.photos.addTags',
@@ -120,9 +57,9 @@ module Flickrie
       get 'flickr.photos.getContactsPhotos', ensure_media(params)
     end
 
-    def public_media_from_user_contacts(user_nsid, params = {})
+    def public_media_from_user_contacts(nsid, params = {})
       get 'flickr.photos.getContactsPublicPhotos',
-        ensure_media({:user_id => user_nsid}.merge(params))
+        ensure_media({:user_id => nsid}.merge(params))
     end
 
     def get_media_context(media_id, params = {})
@@ -163,29 +100,26 @@ module Flickrie
       get 'flickr.photos.search', ensure_media(params)
     end
 
-    #--
     # photos.upload
     def check_upload_tickets(tickets, params = {})
       get 'flickr.photos.upload.checkTickets',
         {:tickets => tickets}.merge(params)
     end
 
-    #--
     # photos.licenses
     def get_licenses(params = {})
       get 'flickr.photos.licenses.getInfo', params
     end
 
-    #--
     # photosets
     def get_set_info(set_id, params = {})
       get 'flickr.photosets.getInfo',
         {:photoset_id => set_id}.merge(params)
     end
 
-    def sets_from_user(user_nsid, params = {})
+    def sets_from_user(nsid, params = {})
       get 'flickr.photosets.getList',
-        {:user_id => user_nsid}.merge(params)
+        {:user_id => nsid}.merge(params)
     end
 
     def media_from_set(set_id, params = {})
@@ -193,7 +127,6 @@ module Flickrie
         ensure_media({:photoset_id => set_id}.merge(params))
     end
 
-    #--
     # test
     def test_login(params = {})
       get 'flickr.test.login', params

data/lib/flickrie/instance.rb

@@ -2,28 +2,27 @@ module Flickrie
   class Instance
     attr_reader :access_token, :access_secret
 
+    # Initializes a new authenticated instance. Example:
+    #
+    #     flickrie = Flickrie::Instance.new("ACCESS_TOKEN", "ACCESS_SECRET")
+    #     flickrie.find_user_by_email("...")
     def initialize(access_token, access_secret)
       @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
+    # See {Flickrie.client} for more info.
     def client
       @client ||= Flickrie.new_client(access_token_hash)
     end
 
-    def upload_client
-      @upload_client ||= Flickrie.new_upload_client(access_token_hash)
-    end
-
     include ApiMethods
 
     private
 
+    def upload_client
+      @upload_client ||= Flickrie.new_upload_client(access_token_hash)
+    end
+
     def access_token_hash
       {:token => access_token, :secret => access_secret}
     end

data/lib/flickrie/location.rb

@@ -1,20 +1,32 @@
 module Flickrie
   class Location
+    # @!parse attr_reader :latitude
     def latitude()  @info['latitude']  end
+    # @!parse attr_reader :longitude
     def longitude() @info['longitude'] end
+    # @!parse attr_reader :accuracy
     def accuracy()  @info['accuracy']  end
+    # @!parse attr_reader :context
     def context()   Integer(@info['context']) rescue nil end
 
+    # @!parse attr_reader :neighbourhood
     def neighbourhood() new_area('neighbourhood') end
+    # @!parse attr_reader :locality
     def locality()      new_area('locality')      end
+    # @!parse attr_reader :county
     def county()        new_area('county')        end
+    # @!parse attr_reader :region
     def region()        new_area('region')        end
+    # @!parse attr_reader :country
     def country()       new_area('country')       end
 
+    # @!parse attr_reader :place_id
     def place_id() @info['place_id'] end
+    # @!parse attr_reader :woeid
     def woeid()    @info['woeid']    end
 
     def [](key) @info[key] end
+    # @!parse attr_reader :hash
     def hash() @info end
 
     private

data/lib/flickrie/media.rb

@@ -7,58 +7,94 @@ require 'date'
 
 module Flickrie
   module Media
+    # @!parse attr_reader :id
     def id()             @info['id']           end
+    # @!parse attr_reader :secret
     def secret()         @info['secret']       end
+    # @!parse attr_reader :server
     def server()         @info['server']       end
+    # @!parse attr_reader :farm
     def farm()           @info['farm']         end
+    # @!parse attr_reader :title
     def title()          @info['title']        end
+    # @!parse attr_reader :description
     def description()    @info['description']  end
+    # @!parse attr_reader :media_status
     def media_status()   @info['media_status'] end
+    # @!parse attr_reader :path_alias
     def path_alias()     @info['pathalias']    end
 
+    # @!parse attr_reader :camera
     def camera() @info['camera'] end
-    # ==== Example
+    # Returns exif of the photo/video. Example:
     #
-    #   photo.exif.get('Model') # => 'Canon PowerShot G12'
+    #     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'
+    #     photo.exif.get('X-Resolution', :data => 'raw')   # => '180'
+    #     photo.exif.get('X-Resolution', :data => 'clean') # => '180 dpi'
+    #     photo.exif.get('X-Resolution')                   # => '180 dpi'
+    #
+    # @return [Flickrie::Media::Exif]
+    #
+    # @!parse attr_reader :exif
     def exif() Exif.new(@info['exif']) rescue nil end
 
+    # @!parse attr_reader :views_count
     def views_count()    Integer(@info['views'])          rescue nil end
+    # @!parse attr_reader :comments_count
     def comments_count() Integer(@info['comments_count']) rescue nil end
 
-    # Returns an instance of Flickrie::Location
+    # @return [Flickrie::Location]
+    #
+    # @!parse attr_reader :location
     def location() Location.new(@info['location']) rescue nil end
-    # Returns an instance of Flickrie::Media::Visibility
+    # @return [Flickrie::Media::Visibility]
+    #
+    # @!parse attr_reader :geo_permissions
     def geo_permissions() Visibility.new(@info['geoperms']) rescue nil end
 
-    # Returns an array of Flickrie::Media::Tag
+    # @return [Array<Flickrie::Media::Tag>]
+    #
+    # @!parse attr_reader :tags
     def tags() @info['tags'].map { |info| Tag.new(info) }     rescue nil end
-    # Returns an array of Flickrie::Media::Tag
+    # @return [Array<Flickrie::Media::Tag>]
+    #
+    # @!parse attr_reader :machine_tags
     def machine_tags() tags.select { |tag| tag.machine_tag? } rescue nil end
 
-    # Returns an instance of Flickrie::License
+    # @return [Flickrie::License]
+    # @!parse attr_reader :license
     def license() License.new(@info['license']) rescue nil end
 
+    # @!parse attr_reader :posted_at
     def posted_at()   Time.at(Integer(@info['dates']['posted']))           rescue nil end
+    # @!parse attr_reader :uploaded_at
     def uploaded_at() Time.at(Integer(@info['dates']['uploaded']))         rescue nil end
+    # @!parse attr_reader :updated_at
     def updated_at()  Time.at(Integer(@info['dates']['lastupdate']))       rescue nil end
+    # @!parse attr_reader :taken_at
     def taken_at()    DateTime.parse(@info['dates']['taken']).to_time      rescue nil end
+    # @!parse attr_reader :taken_at_granularity
     def taken_at_granularity() Integer(@info['dates']['takengranularity']) rescue nil end
 
-    # Returns an instance of Flickrie::User
+    # @return [Flickrie::User]
+    #
+    # @!parse attr_reader :owner
     def owner() User.new(@info['owner']) rescue nil end
 
+    # @!parse attr_reader :safety_level
     def safety_level() Integer(@info['safety_level']) rescue nil end
 
+    # @!parse attr_reader :safe?
     def safe?()       safety_level <= 1 if safety_level end
+    # @!parse attr_reader :moderate?
     def moderate?()   safety_level == 2 if safety_level end
+    # @!parse attr_reader :restricted?
     def restricted?() safety_level == 3 if safety_level end
 
-    #--
-    # TODO: Take care about the url from #get_info
+    # @comment TODO: Take care about the url from #get_info
+    #
+    # @!parse attr_reader :url
     def url
       if owner and id
         "http://www.flickr.com/photos/#{owner.nsid}/#{id}"
@@ -67,37 +103,57 @@ module Flickrie
       end
     end
 
-    # Returns an instance of Flickrie::Media::Visibility
+    # @return [Flickrie::Media::Visibility]
+    #
+    # @!parse attr_reader :visibility
     def visibility() Visibility.new(@info['visibility']) rescue nil end
 
+    # @!parse attr_reader :primary?
     def primary?() Integer(@info['isprimary']) == 1 rescue nil end
 
+    # @!parse attr_reader :favorite?
     def favorite?() Integer(@info['isfavorite']) == 1 rescue nil end
 
+    # @!parse attr_reader :can_comment?
     def can_comment?()  Integer(@info['editability']['cancomment']) == 1 rescue nil end
+    # @!parse attr_reader :can_add_meta?
     def can_add_meta?() Integer(@info['editability']['canaddmeta']) == 1 rescue nil end
 
+    # @!parse attr_reader :can_everyone_comment?
     def can_everyone_comment?()  Integer(@info['publiceditability']['cancomment']) == 1 rescue nil end
+    # @!parse attr_reader :can_everyone_add_meta?
     def can_everyone_add_meta?() Integer(@info['publiceditability']['canaddmeta']) == 1 rescue nil end
 
+    # @!parse attr_reader :can_download?
     def can_download?() Integer(@info['usage']['candownload']) == 1 rescue nil end
+    # @!parse attr_reader :can_blog?
     def can_blog?()     Integer(@info['usage']['canblog']) == 1     rescue nil end
+    # @!parse attr_reader :can_print?
     def can_print?()    Integer(@info['usage']['canprint']) == 1    rescue nil end
+    # @!parse attr_reader :can_share?
     def can_share?()    Integer(@info['usage']['canshare']) == 1    rescue nil end
 
+    # @!parse attr_reader :has_people?
     def has_people?() Integer(@info['people']['haspeople']) == 1 rescue nil end
 
+    # @!parse attr_reader :faved?
     def faved?() Integer(@info['is_faved']) == 1 rescue nil end
 
-    # Returns an array of Flickrie::Media::Note
+    # @return [Array<Flickrie::Media::Note>]
+    #
+    # @!parse attr_reader :notes
     def notes() @info['notes']['note'].map { |hash| Note.new(hash) } rescue nil end
 
-    # Returns an array of Flickrie::User
+    # @return [Array<Flickrie::User>]
+    #
+    # @!parse attr_reader :favorites
     def favorites() @info['person'].map { |info| User.new(info) } rescue nil end
 
     def [](key) @info[key] end
+    # @!parse attr_reader :hash
     def hash() @info end
 
+    # Same as calling `Flickrie.get_(photo|video)_info(id)`.
     def get_info(params = {}, info = nil)
       info ||= Flickrie.client.get_media_info(id, params).body['photo']
       @info.update(info)
@@ -112,6 +168,7 @@ module Flickrie
       self
     end
 
+    # Same as calling `Flickrie.get_(photo|video)_info(id)`.
     def get_exif(params = {}, info = nil)
       info ||= Flickrie.client.get_media_exif(id, params).body['photo']
       @info.update(info)
@@ -119,6 +176,7 @@ module Flickrie
       self
     end
 
+    # Same as calling `Flickrie.get_(photo|video)_info(id)`.
     def get_favorites(params = {}, info = nil)
       info ||= Flickrie.client.get_media_favorites(id, params).body['photo']
       @info.update(info)
@@ -130,7 +188,8 @@ module Flickrie
       @info = info
     end
 
-    module ClassMethods # :nodoc:
+    # @private
+    module ClassMethods
       def from_set(hash)
         hash['photo'].map do |info|
           info['owner'] = {
@@ -224,10 +283,12 @@ module Flickrie
     end
     extend(ClassMethods)
 
+    # @private
     def self.included(klass)
       klass.extend(ClassMethods)
     end
 
+    # @private
     def self.new(info)
       eval(info['media'].capitalize).new(info)
     end

data/lib/flickrie/media/exif.rb

@@ -1,13 +1,14 @@
 module Flickrie
   module Media
     class Exif
-      # ==== Example
+      # Gets exif. Example:
       #
-      #   photo.exif.get('Model') # => 'Canon PowerShot G12'
+      #     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'
       #
-      #   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 }
@@ -19,6 +20,7 @@ module Flickrie
       end
 
       def [](key) @info[key] end
+      # @!parse attr_reader :hash
       def hash() @info end
 
       private