flickrie 1.0.2 → 1.1.0

data/.gitignore

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

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Flickrie changelog
 
+## Version 1.0.3
+
+- Before `Flickrie::User` had only the `#public_photos` method, now, I
+  just added the missing `#public_videos`, `#public_media`, `#photos`,
+  `#videos` and `#media`.
+
+- Fixed Flickr's bug with mixing up the width and the height of a photo
+  (not only in the API, but also on their website).
+
+## Version 1.0.2
+
+- Fix some mistakes in the documentation
+
 ## Version 1.0.1
 
 - Transfered the documentation to YARD. [Documentation](http://rubydoc.info/gems/flickrie/)

data/Gemfile

@@ -2,10 +2,6 @@ source :rubygems
 
 gemspec
 
-group :test do
-  gem "faraday", '0.7.6'
-end
-
 # You can run `bundle [install] --without extras` if you don't want to install them
 group :extras do
   gem "debugger"

data/flickrie.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |gem|
   gem.author       = "Janko Marohnić"
   gem.email        = "janko.marohnic@gmail.com"
   gem.description  = %q{This gem wraps the Flickr API with a nice object-oriented interface.}
-  gem.summary      = %q{This gem wraps the Flickr API with a nice object-oriented interface.}
+  gem.summary      = gem.description
   gem.homepage     = "https://github.com/janko-m/flickrie"
 
   gem.files        = `git ls-files`.split($\)
@@ -25,6 +25,6 @@ Gem::Specification.new do |gem|
   gem.add_dependency "multi_xml", '~> 0.4'
 
   gem.add_development_dependency "rake", '~> 0.9'
-  gem.add_development_dependency "rspec", '>= 2'
+  gem.add_development_dependency "rspec", '>= 2.10', '< 3'
   gem.add_development_dependency "vcr", '~> 2.1'
 end

data/lib/flickrie/api_methods.rb

@@ -156,6 +156,7 @@ module Flickrie
     #
     # @param media_id [String, Fixnum]
     # @param tags [String] A space delimited string with tags
+    # @return [nil]
     # @api_method [flickr.photos.addTags](http://www.flickr.com/services/api/flickr.photos.addTags.html)
     #
     # @note This method requires authentication with "write" permissions.
@@ -169,6 +170,7 @@ module Flickrie
     # Deletes the photo/video with the given ID.
     #
     # @param media_id [String, Fixnum]
+    # @return [nil]
     # @api_method [flickr.photos.delete](http://www.flickr.com/services/api/flickr.photos.delete.html)
     #
     # @note This method requires authentication with "delete" permissions.
@@ -385,6 +387,7 @@ module Flickrie
     # Remove the tag with the given ID
     #
     # @param tag_id [String]
+    # @return [nil]
     # @api_method [flickr.photos.removeTag](http://www.flickr.com/services/api/flickr.photos.removeTag.html)
     #
     # @note This method requires authentication with "write" permissions.
@@ -436,7 +439,7 @@ module Flickrie
     #     ticket_id = Flickrie.upload(photo)
     #     sleep(10)
     #
-    #     ticket = Flickrie.check_upload_tickects(ticket_id)
+    #     ticket = Flickrie.check_upload_tickets(ticket_id)
     #     if ticket.complete?
     #       puts "Photo was uploaded, and its ID is #{ticket.photo_id}"
     #     end

data/lib/flickrie/license.rb

@@ -1,6 +1,11 @@
 module Flickrie
   class License
-    attr_reader :id, :name, :url
+    # @return [String]
+    attr_reader :id
+    # @return [String]
+    attr_reader :name
+    # @return [String]
+    attr_reader :url
 
     private
 

data/lib/flickrie/location.rb

@@ -1,32 +1,49 @@
 module Flickrie
   class Location
-    # @!parse attr_reader :latitude
+    # @!parse attr_reader \
+    #   :latitude, :longitude, :accuracy, :context,
+    #   :neighbourhood, :locality, :county, :region,
+    #   :country, :place_id, :woeid, :hash
+
+    # @return [Fixnum]
     def latitude()  @info['latitude']  end
-    # @!parse attr_reader :longitude
+    # @return [Fixnum]
     def longitude() @info['longitude'] end
-    # @!parse attr_reader :accuracy
+    # @return [String]
     def accuracy()  @info['accuracy']  end
-    # @!parse attr_reader :context
+    # @return [Fixnum]
     def context()   Integer(@info['context']) rescue nil end
 
-    # @!parse attr_reader :neighbourhood
+    # Returns a struct with attributes `#name`, `#place_id` and `#woeid`
+    #
+    # @return [Struct]
     def neighbourhood() new_area('neighbourhood') end
-    # @!parse attr_reader :locality
+    # Returns a struct with attributes `#name`, `#place_id` and `#woeid`
+    #
+    # @return [Struct]
     def locality()      new_area('locality')      end
-    # @!parse attr_reader :county
+    # Returns a struct with attributes `#name`, `#place_id` and `#woeid`
+    #
+    # @return [Struct]
     def county()        new_area('county')        end
-    # @!parse attr_reader :region
+    # Returns a struct with attributes `#name`, `#place_id` and `#woeid`
+    #
+    # @return [Struct]
     def region()        new_area('region')        end
-    # @!parse attr_reader :country
+    # Returns a struct with attributes `#name`, `#place_id` and `#woeid`
+    #
+    # @return [Struct]
     def country()       new_area('country')       end
 
-    # @!parse attr_reader :place_id
+    # @return [String]
     def place_id() @info['place_id'] end
-    # @!parse attr_reader :woeid
+    # @return [String]
     def woeid()    @info['woeid']    end
 
     def [](key) @info[key] end
-    # @!parse attr_reader :hash
+    # Returns the raw hash from the response. Useful if something isn't available by methods.
+    #
+    # @return [Hash]
     def hash() @info end
 
     private

data/lib/flickrie/media/exif.rb

@@ -1,6 +1,8 @@
 module Flickrie
   module Media
     class Exif
+      # @!parse attr_reader :hash
+
       # Gets exif. Example:
       #
       #     photo.exif.get('Model') # => 'Canon PowerShot G12'
@@ -20,7 +22,7 @@ module Flickrie
       end
 
       def [](key) @info[key] end
-      # @!parse attr_reader :hash
+      # @return [Hash]
       def hash() @info end
 
       private

data/lib/flickrie/media/note.rb

@@ -1,28 +1,39 @@
 module Flickrie
   module Media
     class Note
-      attr_reader :id, :author, :coordinates, :content,
-        :width, :height
+      # @!parse attr_reader \
+      #   :id, :author, :content, :coordinates, :width,
+      #   :height, :hash
+
+      # @return [String]
+      def id() @info['id'] end
+      # @return [Flickrie::User]
+      def author() User.new('nsid' => @info['author'], 'username' => @info['authorname']) end
+      # @return [String]
+      def content() @info['_content'] end
+      # Returns a 2-element array, representing a point.
+      #
+      # @return [Array<Fixnum>]
+      def coordinates() [@info['x'].to_i, @info['y'].to_i] end
+      # @return [Fixnum]
+      def width() @info['w'].to_i end
+      # @return [Fixnum]
+      def height() @info['h'].to_i end
 
       def to_s
-        @content
+        content
       end
 
       def [](key) @info[key] end
-      # @!parse attr_reader :hash
+      # @return [Fixnum]
       def hash() @info end
 
       private
 
-      def initialize(hash)
-        @id = hash['id']
-        @author = User.new \
-          'nsid' => hash['author'],
-          'username' => hash['authorname']
-        @content = hash['_content']
-        @coordinates = [hash['x'].to_i, hash['y'].to_i]
-        @width = hash['w'].to_i
-        @height = hash['h'].to_i
+      def initialize(info)
+        raise ArgumentError if info.nil?
+
+        @info = info
       end
     end
   end

data/lib/flickrie/media/tag.rb

@@ -1,25 +1,28 @@
 module Flickrie
   module Media
     class Tag
-      # @!parse attr_reader :id
+      # @!parse attr_reader \
+      #   :id, :raw, :content, :machine_tag?, :author, :hash
+
+      # @return [String]
       def id()      @info['id']       end
-      # @!parse attr_reader :raw
+      # @return [String]
       def raw()     @info['raw']      end
-      # @!parse attr_reader :content
+      # @return [String]
       def content() @info['_content'] end
 
-      # @!parse attr_reader :machine_tag?
+      # @return [Boolean]
       def machine_tag?
         @info['machine_tag'].to_i == 1 if @info['machine_tag']
       end
 
-      # @!parse attr_reader :author
+      # @return [Flickrie::User]
       def author
         User.new('nsid' => @info['author']) if @info['author']
       end
 
       def [](key) @info[key] end
-      # @!parse attr_reader :hash
+      # @return [Hash]
       def hash() @info end
 
       private

data/lib/flickrie/media/visibility.rb

@@ -1,17 +1,20 @@
 module Flickrie
   module Media
     class Visibility
-      # @!parse attr_reader :public?
+      # @!parse attr_reader \
+      #   :public?, :friends?, :family?, :contacts?, :hash
+
+      # @return [Boolean]
       def public?()   @info['ispublic'].to_i == 1 if @info['ispublic']   end
-      # @!parse attr_reader :friends?
+      # @return [Boolean]
       def friends?()  @info['isfriend'].to_i == 1 if @info['isfriend']   end
-      # @!parse attr_reader :family?
+      # @return [Boolean]
       def family?()   @info['isfamily'].to_i == 1 if @info['isfamily']   end
-      # @!parse attr_reader :contacts?
+      # @return [Boolean]
       def contacts?() @info['iscontact'].to_i == 1 if @info['iscontact'] end
 
       def [](key) @info[key] end
-      # @!parse attr_reader :hash
+      # @return [Hash]
       def hash() @info end
 
       private

data/lib/flickrie/media.rb

@@ -7,24 +7,36 @@ require 'date'
 
 module Flickrie
   module Media
-    # @!parse attr_reader :id
+    # @!parse attr_reader \
+    #   :id, :secret, :server, :farm, :title, :description,
+    #   :media_status, :path_alias, :camera, :exif, :views_count,
+    #   :comments_count, :location, :geo_permissions, :tags,
+    #   :machine_tags, :license, :posted_at, :uploaded_at,
+    #   :updated_at, :taken_at, :taken_at_granularity, :owner,
+    #   :safety_level, :safe?, :moderate?, :restricted?,
+    #   :url, :visibility, :primary?, :favorite?, :can_comment?,
+    #   :can_add_meta?, :can_everyone_comment?, :can_everyone_add_meta?,
+    #   :can_download?, :can_blog?, :can_print?, :can_share?,
+    #   :has_people?, :faved?, :notes, :favorites, :hash
+
+    # @return [String]
     def id()             @info['id']           end
-    # @!parse attr_reader :secret
+    # @return [String]
     def secret()         @info['secret']       end
-    # @!parse attr_reader :server
+    # @return [String]
     def server()         @info['server']       end
-    # @!parse attr_reader :farm
+    # @return [Fixnum]
     def farm()           @info['farm']         end
-    # @!parse attr_reader :title
+    # @return [String]
     def title()          @info['title']        end
-    # @!parse attr_reader :description
+    # @return [String]
     def description()    @info['description']  end
-    # @!parse attr_reader :media_status
+    # @return [String]
     def media_status()   @info['media_status'] end
-    # @!parse attr_reader :path_alias
+    # @return [String]
     def path_alias()     @info['pathalias']    end
 
-    # @!parse attr_reader :camera
+    # @return [String]
     def camera() @info['camera'] end
     # Returns exif of the photo/video. Example:
     #
@@ -35,66 +47,51 @@ module Flickrie
     #     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
+    # @return [Fixnum]
     def views_count()    Integer(@info['views'])          rescue nil end
-    # @!parse attr_reader :comments_count
+    # @return [Fixnum]
     def comments_count() Integer(@info['comments_count']) rescue nil end
 
     # @return [Flickrie::Location]
-    #
-    # @!parse attr_reader :location
     def location() Location.new(@info['location']) rescue nil end
     # @return [Flickrie::Media::Visibility]
-    #
-    # @!parse attr_reader :geo_permissions
     def geo_permissions() Visibility.new(@info['geoperms']) rescue nil end
 
     # @return [Array<Flickrie::Media::Tag>]
-    #
-    # @!parse attr_reader :tags
     def tags() @info['tags'].map { |info| Tag.new(info) }     rescue nil end
     # @return [Array<Flickrie::Media::Tag>]
-    #
-    # @!parse attr_reader :machine_tags
     def machine_tags() tags.select { |tag| tag.machine_tag? } rescue nil end
 
     # @return [Flickrie::License]
-    # @!parse attr_reader :license
     def license() License.new(@info['license']) rescue nil end
 
-    # @!parse attr_reader :posted_at
+    # @return [Time]
     def posted_at()   Time.at(Integer(@info['dates']['posted']))           rescue nil end
-    # @!parse attr_reader :uploaded_at
+    # @return [Time]
     def uploaded_at() Time.at(Integer(@info['dates']['uploaded']))         rescue nil end
-    # @!parse attr_reader :updated_at
+    # @return [Time]
     def updated_at()  Time.at(Integer(@info['dates']['lastupdate']))       rescue nil end
-    # @!parse attr_reader :taken_at
+    # @return [Time]
     def taken_at()    DateTime.parse(@info['dates']['taken']).to_time      rescue nil end
-    # @!parse attr_reader :taken_at_granularity
+    # @return [Fixnum]
     def taken_at_granularity() Integer(@info['dates']['takengranularity']) rescue nil end
 
     # @return [Flickrie::User]
-    #
-    # @!parse attr_reader :owner
     def owner() User.new(@info['owner']) rescue nil end
 
-    # @!parse attr_reader :safety_level
+    # @return [Fixnum]
     def safety_level() Integer(@info['safety_level']) rescue nil end
 
-    # @!parse attr_reader :safe?
+    # @return [Boolean]
     def safe?()       safety_level <= 1 if safety_level end
-    # @!parse attr_reader :moderate?
+    # @return [Boolean]
     def moderate?()   safety_level == 2 if safety_level end
-    # @!parse attr_reader :restricted?
+    # @return [Boolean]
     def restricted?() safety_level == 3 if safety_level end
 
-    # @comment TODO: Take care about the url from #get_info
-    #
-    # @!parse attr_reader :url
+    # @return [String]
     def url
       if owner and id
         "http://www.flickr.com/photos/#{owner.nsid}/#{id}"
@@ -104,56 +101,54 @@ module Flickrie
     end
 
     # @return [Flickrie::Media::Visibility]
-    #
-    # @!parse attr_reader :visibility
     def visibility() Visibility.new(@info['visibility']) rescue nil end
 
-    # @!parse attr_reader :primary?
+    # @return [Boolean]
     def primary?() Integer(@info['isprimary']) == 1 rescue nil end
 
-    # @!parse attr_reader :favorite?
+    # @return [Boolean]
     def favorite?() Integer(@info['isfavorite']) == 1 rescue nil end
 
-    # @!parse attr_reader :can_comment?
+    # @return [Boolean]
     def can_comment?()  Integer(@info['editability']['cancomment']) == 1 rescue nil end
-    # @!parse attr_reader :can_add_meta?
+    # @return [Boolean]
     def can_add_meta?() Integer(@info['editability']['canaddmeta']) == 1 rescue nil end
 
-    # @!parse attr_reader :can_everyone_comment?
+    # @return [Boolean]
     def can_everyone_comment?()  Integer(@info['publiceditability']['cancomment']) == 1 rescue nil end
-    # @!parse attr_reader :can_everyone_add_meta?
+    # @return [Boolean]
     def can_everyone_add_meta?() Integer(@info['publiceditability']['canaddmeta']) == 1 rescue nil end
 
-    # @!parse attr_reader :can_download?
+    # @return [Boolean]
     def can_download?() Integer(@info['usage']['candownload']) == 1 rescue nil end
-    # @!parse attr_reader :can_blog?
+    # @return [Boolean]
     def can_blog?()     Integer(@info['usage']['canblog']) == 1     rescue nil end
-    # @!parse attr_reader :can_print?
+    # @return [Boolean]
     def can_print?()    Integer(@info['usage']['canprint']) == 1    rescue nil end
-    # @!parse attr_reader :can_share?
+    # @return [Boolean]
     def can_share?()    Integer(@info['usage']['canshare']) == 1    rescue nil end
 
-    # @!parse attr_reader :has_people?
+    # @return [Boolean]
     def has_people?() Integer(@info['people']['haspeople']) == 1 rescue nil end
 
-    # @!parse attr_reader :faved?
+    # @return [Boolean]
     def faved?() Integer(@info['is_faved']) == 1 rescue nil end
 
     # @return [Array<Flickrie::Media::Note>]
-    #
-    # @!parse attr_reader :notes
     def notes() @info['notes']['note'].map { |hash| Note.new(hash) } rescue nil end
 
     # @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
+    # Returns the raw hash from the response. Useful if something isn't available by methods.
+    #
+    # @return [Hash]
     def hash() @info end
 
     # Same as calling `Flickrie.get_(photo|video)_info(id)`.
+    #
+    # @return [self]
     def get_info(params = {}, info = nil)
       info ||= Flickrie.client.get_media_info(id, params).body['photo']
       @info.update(info)
@@ -169,6 +164,8 @@ module Flickrie
     end
 
     # Same as calling `Flickrie.get_(photo|video)_info(id)`.
+    #
+    # @return [self]
     def get_exif(params = {}, info = nil)
       info ||= Flickrie.client.get_media_exif(id, params).body['photo']
       @info.update(info)
@@ -177,6 +174,8 @@ module Flickrie
     end
 
     # Same as calling `Flickrie.get_(photo|video)_info(id)`.
+    #
+    # @return [self]
     def get_favorites(params = {}, info = nil)
       info ||= Flickrie.client.get_media_favorites(id, params).body['photo']
       @info.update(info)

data/lib/flickrie/media_count.rb

@@ -2,12 +2,12 @@ require 'date'
 
 module Flickrie
   class MediaCount
-    # @!parse attr_reader :value
+    # @!parse attr_reader \
+    #   :value, :date_range, :from, :to, :hash
+
     def value() Integer(@info['count']) rescue nil end
 
     # @return [Range]
-    #
-    # @!parse attr_reader :date_range
     def date_range
       dates =
         case @dates_kind
@@ -23,13 +23,15 @@ module Flickrie
     end
     alias time_interval date_range
 
-    # @!parse attr_reader :from
+    # @return [Time]
     def from() date_range.begin end
-    # @!parse attr_reader :to
+    # @return [Time]
     def to()   date_range.end   end
 
     def [](key) @info[key] end
-    # @!parse attr_reader :hash
+    # Returns the raw hash from the response. Useful if something isn't available by methods.
+    #
+    # @return [Hash]
     def hash() @info end
 
     private

data/lib/flickrie/photo.rb

@@ -1,6 +1,8 @@
 module Flickrie
   class Photo
     include Media
+    # @!parse attr_reader \
+    #   :size, :width, :height, :source_url, :rotation
 
     SIZES = {
       'Square 75'  => 'sq',
@@ -15,59 +17,94 @@ module Flickrie
       'Original'   => 'o'
     }
 
-    # @!parse attr_reader :size
+    # Returns the current Flickr size of the photo ("Medium 500", for example).
+    #
+    # @return [String]
     def size() @size end
 
+    # @return [self]
     def square!(number) @size = "Square #{number}"; self end
+    # @return [self]
     def thumbnail!()    @size = "Thumbnail";        self end
+    # @return [self]
     def small!(number)  @size = "Small #{number}";  self end
+    # @return [self]
     def medium!(number) @size = "Medium #{number}"; self end
+    # @return [self]
     def large!(number)  @size = "Large #{number}";  self end
+    # @return [self]
     def original!()     @size = "Original";         self end
 
+    # @return [self]
     def square(number) dup.square!(number) end
+    # @return [self]
     def thumbnail()    dup.thumbnail!      end
+    # @return [self]
     def small(number)  dup.small!(number)  end
+    # @return [self]
     def medium(number) dup.medium!(number) end
+    # @return [self]
     def large(number)  dup.large!(number)  end
+    # @return [self]
     def original()     dup.original!       end
 
     # @comment Alternate size methods
+    # @return [self]
     def square75()   square(75)   end
+    # @return [self]
     def square75!()  square!(75)  end
+    # @return [self]
     def square150()  square(150)  end
+    # @return [self]
     def square150!() square!(150) end
+    # @return [self]
     def small240()   small(240)   end
+    # @return [self]
     def small240!()  small!(240)  end
+    # @return [self]
     def small320()   small(320)   end
+    # @return [self]
     def small320!()  small!(320)  end
+    # @return [self]
     def medium500()  medium(500)  end
+    # @return [self]
     def medium500!() medium!(500) end
+    # @return [self]
     def medium640()  medium(640)  end
+    # @return [self]
     def medium640!() medium!(640) end
+    # @return [self]
     def medium800()  medium(800)  end
+    # @return [self]
     def medium800!() medium!(800) end
+    # @return [self]
     def large1024()  large(1024)  end
+    # @return [self]
     def large1024!() large!(1024) end
 
+    # @return [self]
     def largest!() @size = largest_size; self end
+    # @return [self]
     def largest()  dup.largest! end
 
+    # @return [Array<String>]
     def available_sizes
       SIZES.select { |_,v| @info["url_#{v}"] }.keys
     end
 
-    # @!parse attr_reader :width
-    def width()  Integer(@info["width_#{size_abbr}"])  rescue nil end
-    # @!parse attr_reader :height
-    def height() Integer(@info["height_#{size_abbr}"]) rescue nil end
-    # @!parse attr_reader :source_url
+    # @return [Fixnum]
+    def width() flickr_size.min rescue nil end
+    # @return [Fixnum]
+    def height() flickr_size.max rescue nil end
+    # @return [String]
     def source_url() @info["url_#{size_abbr}"] end
 
-    # @!parse attr_reader :rotation
+    # @return [Fixnum]
     def rotation() Integer(@info['rotation']) rescue nil end
 
     # Same as calling `Flickrie.get_photo_sizes(photo.id)`.
+    #
+    # @return [self]
     def get_sizes(params = {}, info = nil)
       info ||= Flickrie.client.get_media_sizes(id, params).body['sizes']
       @info['usage'] ||= {}
@@ -111,5 +148,9 @@ module Flickrie
     def size_abbr
       SIZES[size]
     end
+
+    def flickr_size
+      [Integer(@info["width_#{size_abbr}"]), Integer(@info["height_#{size_abbr}"])]
+    end
   end
 end