fleakr 0.6.3 → 0.7.0

data/README.rdoc

@@ -26,15 +26,15 @@ Now that you have your key, you can get things rolling with irb and the fleakr g
 
     $ irb -r rubygems
     >> require 'fleakr'
-    
+
 Then, set your API key (only need to do this once per session):
 
     >> Fleakr.api_key = '<your api key here>'
 
 === A Brief Tour
 
-With just an API key, you have the ability to retrieve a substantial amount of data 
-about users, their photosets, photos, contacts, and groups.  Let's start by finding a 
+With just an API key, you have the ability to retrieve a substantial amount of data
+about users, their photosets, photos, contacts, and groups.  Let's start by finding a
 user by his username:
 
     >> user = Fleakr.user('the decapitator')
@@ -44,7 +44,7 @@ By email:
 
     >> user = Fleakr.user('user@host.com')
     => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">
-    
+
 Or even by URL:
 
     >> user = Fleakr.user('http://www.flickr.com/photos/the_decapitator/')
@@ -53,7 +53,7 @@ Or even by URL:
 Once you have a user, you can find his associated sets:
 
     >> user.sets
-    => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">, 
+    => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">,
         #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ...
 
 His individual photos:
@@ -68,9 +68,9 @@ Or contacts:
         @id="12289718@N00", @icon_farm="1", @icon_server="4">
 
 Or his groups if you would like:
-    
+
     >> user.groups
-    => [#<Fleakr::Objects::Group:0x11f2330 ..., 
+    => [#<Fleakr::Objects::Group:0x11f2330 ...,
         #<Fleakr::Objects::Group:0x11f2308 ...
     >> user.groups.first.name
     => "Rural Decay"
@@ -93,20 +93,20 @@ When accessing a set, you can also grab all the photos that are in that set:
 
 === Contacts
 
-Besides pulling back a given user's public contacts list, you can also retrieve the list of 
+Besides pulling back a given user's public contacts list, you can also retrieve the list of
 contacts for the currently authenticated user (see below about authentication).  For example,
 you can retrieve all contacts:
 
     >> Fleakr.contacts
     => [#<Fleakr::Objects::Contact:0x111ff84 @username="bryan.ray" ...>]
-    
+
 Or just the contacts marked as 'family':
-    
+
     >> Fleakr.contacts(:family)
     => [#<Fleakr::Objects::Contact:0x12db42c @username="Grandbob" ...>]
-    
+
 Or a specific page of contacts marked as 'friends':
-    
+
     >> Fleakr.contacts(:friends, :page => 3, :per_page => 5)
     => [#<Fleakr::Objects::Contact:0x12a6c54 @username="Louise and BCG" ...>]
 
@@ -116,40 +116,40 @@ See the documentation for Fleakr.contacts for what options are available.
 
 Each photo object contains metadata about a collection of images, each representing different
 sizes.  Once we have a single photo:
-    
+
     >> photo = user.photos.first
     => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
-    
+
 We can get information about one of the sizes:
 
     >> photo.small
     => #<Fleakr::Objects::Image:0x1768f1c @height="172", @size="Small", @width="240",
-        @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg",  
+        @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg",
         @page="http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/">
 
 Grab the URL for the image itself:
 
     >> photo.small.url
     => "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg"
-    
+
 Or grab the URL for its page on the Flickr site:
-    
+
     >> photo.small.page
     => "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"
-    
+
 Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and
 are accessed in the same way:
-    
+
     >> photo.original.url
     => "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg"
-    
+
 === Tags
 
 Tags are available for users and photos.  Retrieving them is easy:
 
     >> user = Fleakr.user('the decapitator')
     >> user.tags
-    => [#<Fleakr::Objects::Tag:0x190d5fc @value="ad">, 
+    => [#<Fleakr::Objects::Tag:0x190d5fc @value="ad">,
         #<Fleakr::Objects::Tag:0x1908a20 @value="ads">, ...
     >> user.photos.first.tags
     => [#<Fleakr::Objects::Tag:0x17b1b18 @machine_flag="0", @author_id="21775151@N06", ...
@@ -169,12 +169,12 @@ All tags have values, but for tags associated with photos there is some addition
     => false
     >> tag.author
     => #<Fleakr::Objects::User:0x1a149f0 @username="the decapitator", ... >
-    
+
 Each tag can also have related tags:
 
     >> user.photos.first.tags[1].related.first.related.first.to_s
     => "face"
-    
+
 You get the idea - see Fleakr::Objects::Tag for more information.
 
 === Comments
@@ -219,28 +219,41 @@ in turn, can have either collections or sets associated with them. For example:
     >> user.collections.first.collections.first.sets.first.title
     => "A Trip to Yosemite"
 
-Note that collections are limited to Flickr pro members. See Fleakr::Objects::Collection for more 
+Note that collections are limited to Flickr pro members. See Fleakr::Objects::Collection for more
 information.
 
+=== Accessing Resources by URL
+
+Sometimes you want to retrieve a person, set, or photo but you only have the public Flickr URL for
+that entity.  Retrieval is easy:
+
+    >> Fleakr.resource_from_url('http://www.flickr.com/people/reagent/')
+    => #<Fleakr::Objects::User @id="25073988@N05", @username="reagent", @authentication_options={}>
+
+This method also supports the retrieval of photos from a shortened Flickr URL:
+
+    >> Fleakr.resource_from_url('http://flic.kr/p/95Nr83')
+    => #<Fleakr::Objects::Photo @id="5305179788", @title="Comic Sans Sign", ... >
+
 === Saving Images
 
 If a photo interests you, save it down to a directory of your choosing:
 
     >> photo.original.save_to('/tmp')
     => #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)>
-    
-Similarly, you can save down entire sets.  Just specify the target directory and the size 
+
+Similarly, you can save down entire sets.  Just specify the target directory and the size
 of the images you're interested in:
 
     >> user.sets.first.save_to('/tmp', :square)
     => [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ...
-    
+
 This creates a subdirectory within the target directory based on the set's name and preserves
 the original order of the photos:
-    
+
     >> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map
-    => ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg", 
-        "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg", 
+    => ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg",
+        "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg",
         "/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ]
 
 === Searching
@@ -248,7 +261,7 @@ the original order of the photos:
 If you would prefer to just search photos, you can do that with search text:
 
     >> photos = Fleakr.search('ponies!!')
-    => [#<Fleakr::Objects::Photo:0x11f4e64 @title="hiroshima atomic garden", @id="3078234390">, 
+    => [#<Fleakr::Objects::Photo:0x11f4e64 @title="hiroshima atomic garden", @id="3078234390">,
         #<Fleakr::Objects::Photo:0x11f4928 @title="PONYLOV", @id="3077360853">, ...
     >> photos.first.title
     => "hiroshima atomic garden"
@@ -265,21 +278,38 @@ Searches can also be scoped to other entities in the system (namely Users and Gr
 
     >> user.groups.first.search('awesome')
     => [#<Fleakr::Objects::Photo:0x18cb4cc @server_id="2012", @id="2181921273",
-         @farm_id="3", @title="", @secret="634eda7521">, ... 
+         @farm_id="3", @title="", @secret="634eda7521">, ...
     >> user.search('serpent')
     => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
         @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
 
+=== Exif Data
+
+Exif metadata can be retrieved for a photo:
+
+    >> photo = Fleakr::Objects::Photo.find_by_id('4507120023')
+    >> photo.metadata.keys
+    => ["ImageSize", "Optical Zoom Mode", "RedBalance", "Y-Resolution", ... ]
+    >> photo.metadata['ImageSize']
+    => "3264x2448"
+
+You can iterate over the available elements and grab additional information:
+
+    >> photo.metadata.map {|k, e| "#{k} => '#{e.clean}'" }
+    => ["Exposure => '0.003 sec (1/400)'", "Y-Resolution => '180 dpi'", ... ]
+
+See the documentation for Fleakr::Objects::Metadata for information on what's available.
+
 === Uploading Files
 
-Before you can upload files, you need to be able to make authenticated calls to the Flickr 
+Before you can upload files, you need to be able to make authenticated calls to the Flickr
 API.  Skip to the next section (Authenticated Calls) for details on how to make this work.
 
 Uploading single files is simple:
 
     >> Fleakr.upload('/path/to/image.jpg')
     => [#<Fleakr::Objects::Photo:0x217fb54 @updated="1236133594", @server_id="3266", ...>]
-    
+
 Notice that the newly-uploaded image is returned.  You can further inspect / modify this as
 necessary.  The real magic is in uploading multiple files - the upload method takes a file
 glob:
@@ -291,7 +321,7 @@ glob:
 
 You can also set options on the file(s) that you're uploading:
 
-    >> Fleakr.upload('/path/to/party/images/*.jpg', :viewable_by => :everyone, 
+    >> Fleakr.upload('/path/to/party/images/*.jpg', :viewable_by => :everyone,
                                                     :title => 'Party Pics')
 
 The full list of options can be found in the Fleakr::Objects::Photo documentation.
@@ -299,8 +329,8 @@ The full list of options can be found in the Fleakr::Objects::Photo documentatio
 === Authenticated Calls
 
 While read-only access to the API gets you quite a bit of data, you'll need to generate an
-authentication token if you want access to the more powerful features (like uploading your 
-own photos).  
+authentication token if you want access to the more powerful features (like uploading your
+own photos).
 
 Depending on how you intend to use the Flickr API, there are 2 methods for performing
 authenticated calls.
@@ -315,22 +345,22 @@ list of keys on the Flickr site, click on the 'Edit key details' link and ensure
 1. The value for 'Mobile Permissions' is set to either 'write' or 'delete'
 
 Once this is set, you'll see your Authentication URL on the key details page (it will look
-something like http://www.flickr.com/auth-534525246245).  Paste this URL into your browser and 
+something like http://www.flickr.com/auth-534525246245).  Paste this URL into your browser and
 confirm access to get your mini-token. Now you're ready to configure your authentication token:
 
     Fleakr.api_key       = 'ABC123'
     Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
-    
+
     token = Fleakr.token_from_mini_token('294-585-410')
     Fleakr.auth_token = token.value
-    
+
     Fleakr.upload('/path/to/my/photo.jpg')
 
 Once you use the mini-token once it is no longer available.  To use the generated auth_token
 for future requests, you'll need to make sure that you set the value permanently:
 
     Fleakr.auth_token = '72157622657341094-41241e527f325abb'
-    
+
 === Multiple Users
 
 If you need to have your application access other users photos on their behalf, you'll want to
@@ -340,31 +370,31 @@ use the Web authentication method.  Edit your key details and make sure that:
 1. The value for 'Authentication Type' is set to 'Web Application'
 1. You configure your callback URL to point to something valid and accessible
 
-Make sure that your key and secret are set as above. You can then begin the process by requesting 
-that the user authorize access to his Flickr account by redirecting to an authorization URL.  I'm 
+Make sure that your key and secret are set as above. You can then begin the process by requesting
+that the user authorize access to his Flickr account by redirecting to an authorization URL.  I'm
 assuming Rails conventions here, but this should work with any Ruby web framework:
 
     redirect_to Fleakr.authorization_url
-    
+
 By default, we request read permission for access.  This doesn't really do much more than what the
 public API allows, so you can request different permissions when asking for authorization:
 
     # The values :read, :write, and :delete are supported
     redirect_to Fleakr.authorization_url(:delete)
 
-One the user authorizes your application, he will be redirected back to your callback URL with a 
+One the user authorizes your application, he will be redirected back to your callback URL with a
 <tt>frob</tt> parameter as part of the query string.  You'll need to exchange this for a token:
 
     token = Fleakr.token_from_frob(params[:frob])
-    
-The actual authentication token is available by calling <tt>token.value</tt> in the above 
+
+The actual authentication token is available by calling <tt>token.value</tt> in the above
 example.  You'll want to store this value somewhere to make future API calls on behalf of this
-user. To make that process easier, there is a method that you can use that will allow you to 
+user. To make that process easier, there is a method that you can use that will allow you to
 automatically scope your requests to the authenticated user:
 
     user = Fleakr.user_for_token('72157622657341094-41241e527f325abb')
-    
-From there, you can make any of the usual calls available with the API. See 
+
+From there, you can make any of the usual calls available with the API. See
 Fleakr::Objects::User for more information.
 
 === What Went Wrong?
@@ -374,27 +404,27 @@ what's really going on when you run into unexpected behavior.  To make things ea
 have Fleakr log all of the API traffic.  Here's how:
 
     Fleakr.logger = Logger.new('/tmp/fleakr.log')
-    
-Now any calls to the API will log both their request and response data to that file.  But be 
+
+Now any calls to the API will log both their request and response data to that file.  But be
 warned, this can be pretty verbose by default (especially if you're doing file uploads).  To see
 just the requests you need to tune the log level:
 
     logger = Logger.new('/tmp/fleakr.log')
     logger.level = Logger::INFO
-    
+
     Fleakr.logger = logger
-    
+
 Even if something doesn't go wrong, this is a good way to get a sense for when you're making
 API requests.
 
 == Contributing
 
-If there is a feature that you would like to contribute, I gladly accept pull requests.  There 
+If there is a feature that you would like to contribute, I gladly accept pull requests.  There
 are a few things that make my life easier when integrating your changes:
 
 * Verify that all tests are passing (run `rake` from the project root)
 * Keep your commits small, focused, and tested - this allows me to apply changes cleanly
-* Leave the Rakefile and version information intact - if you really want to make changes, 
+* Leave the Rakefile and version information intact - if you really want to make changes,
   please do so in a separate commit.
 
 Once your changes are applied, I will add you to the list of contributors.
@@ -404,6 +434,7 @@ Once your changes are applied, I will add you to the list of contributors.
 While Fleakr started as a labor of love for me, I'm glad that others have been interested
 in this project enough to contribute their ideas and code:
 
+* {Gordon Anderson}[http://github.com/gordonbanderson]
 * {Mark Dickson}[http://github.com/ideaoforder]
 * {John Guenin}[http://github.com/johng]
 * {Thomas Olausson}[http://github.com/latompa]
@@ -426,7 +457,7 @@ Thanks!
 * Implement save-able search results (e.g. Fleakr.search('ponies').save_to('/path', :medium))
 * Implement deeper associations for core elements (e.g. tags / etc..)
 * Implement write methods for photos & photosets
-* Implement flickr.places.* portion of API 
+* Implement flickr.places.* portion of API
 
 == License
 

data/Rakefile

@@ -1,8 +1,9 @@
 require 'rubygems'
 require 'rake/gempackagetask'
 require 'rake/testtask'
+require 'hanna/rdoctask'
 
-require 'lib/fleakr/version'
+require File.expand_path('../lib/fleakr/version', __FILE__)
 
 spec = Gem::Specification.new do |s|
   s.name             = 'fleakr'
@@ -13,11 +14,10 @@ spec = Gem::Specification.new do |s|
   s.summary          = "A small, yet powerful, gem to interface with Flickr photostreams"
   s.author           = 'Patrick Reagan'
   s.email            = 'reaganpr@gmail.com'
-  s.homepage         = 'http://sneaq.net'
+  s.homepage         = 'http://fleakr.org'
   s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
-  
+
   s.add_dependency('hpricot', '>= 0.6.164')
-  s.add_dependency('activesupport', '>= 2.0')
   s.add_dependency('loggable', '>= 0.2.0')
 end
 
@@ -25,6 +25,23 @@ Rake::GemPackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end
 
+Rake::RDocTask.new(:doc) do |doc|
+  doc.rdoc_files.include('README.rdoc').
+    include('lib/**/*.rb').
+    exclude('lib/fleakr/version.rb')
+
+  doc.main = "README.rdoc" # page to start on
+  doc.title = "Fleakr #{Fleakr::Version} Documentation"
+
+  doc.rdoc_dir = "doc/#{Fleakr::Version}"
+  doc.options << '--quiet'
+end
+
+desc 'Install this Gem'
+task :install => :gem do
+  sh "gem install pkg/#{spec.full_name}.gem"
+end
+
 Rake::TestTask.new do |t|
   t.libs << 'test'
   t.test_files = FileList["test/**/*_test.rb"]
@@ -34,21 +51,23 @@ end
 begin
   require 'rcov/rcovtask'
 
+  desc 'Run tests with code coverage statistics'
   Rcov::RcovTask.new(:coverage) do |t|
     t.libs       = ['test']
     t.test_files = FileList["test/**/*_test.rb"]
     t.verbose    = true
-    t.rcov_opts  = ['--text-report', "-x #{Gem.path}", '-x /Library/Ruby', '-x /usr/lib/ruby']
+    t.rcov_opts  = ['--text-report', "-x #{Gem.path}", '-x /Library/Ruby', '-x /usr/lib/ruby', "-x #{ENV['HOME']}/.rvm"]
   end
-  
+
   task :default => :coverage
-  
+
 rescue LoadError
-  warn "\n**** Install rcov (sudo gem install relevance-rcov) to get coverage stats ****\n"
+  desc 'Run tests with code coverage statistics'
+  task(:coverage) { $stderr.puts 'Run `gem install rcov` to get coverage stats' }
   task :default => :test
 end
 
-desc 'Generate the gemspec to serve this Gem from Github'
+desc 'Generate the gemspec for this Gem'
 task :gemspec do
   file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
   File.open(file, 'w') {|f| f << spec.to_ruby }

data/lib/fleakr.rb

@@ -3,25 +3,10 @@ $:.unshift(File.dirname(__FILE__))
 require 'uri'
 require 'cgi'
 require 'net/http'
+require 'time'
 require 'hpricot'
 require 'forwardable'
 
-# Require only what we need from ActiveSupport
-require 'active_support/core_ext/array'
-require 'active_support/core_ext/module'
-
-begin
-  # ActiveSupport < 2.3.5
-  require 'active_support/core_ext/blank'
-rescue NameError
-  # ActiveSupport >= 2.3.5 will raise a NameError exception
-  require 'active_support/core_ext/object/blank'
-end
-
-require 'active_support/core_ext/time'
-require 'active_support/inflector'
-require 'active_support/core_ext/string'
-
 require 'digest/md5'
 require 'fileutils'
 require 'loggable'
@@ -36,7 +21,7 @@ require 'fleakr/objects'
 # == Quick Start
 #
 # Getting started is easy, just make sure you have a valid API key from Flickr and you can
-# then start making any non-authenticated request to pull back data for yours and others' 
+# then start making any non-authenticated request to pull back data for yours and others'
 # photostreams, sets, contacts, groups, etc...
 #
 # For now, all activity originates from a single user which you can find by username or
@@ -57,10 +42,10 @@ require 'fleakr/objects'
 #  user.groups
 #
 # To see what other associations and attributes are available, see the Fleakr::Objects::User class
-# 
+#
 # == Authentication
 #
-# If you want to do something more than just retrieve public photos (like upload your own), 
+# If you want to do something more than just retrieve public photos (like upload your own),
 # you'll need to generate an authentication token to use across requests and sessions.
 #
 # Assuming you've already applied for a key, go back and make sure you have the right settings
@@ -71,7 +56,7 @@ require 'fleakr/objects'
 # 1. The value for 'Mobile Permissions' is set to either 'write' or 'delete'
 #
 # Once this is set, you'll see your Authentication URL on the key details page (it will look
-# something like http://www.flickr.com/auth-534525246245).  Paste this URL into your browser and 
+# something like http://www.flickr.com/auth-534525246245).  Paste this URL into your browser and
 # confirm access to get your mini-token. Now you're ready to make authenticated requests:
 #
 #   require 'rubygems'
@@ -83,7 +68,7 @@ require 'fleakr/objects'
 #
 #   Fleakr.upload('/path/to/my/photo.jpg')
 #   Fleakr.token.value # => "34132412341235-12341234ef34"
-# 
+#
 # Once you use the mini-token once, it is no longer available.  To use the generated auth_token
 # for future requests, just set Fleakr.auth_token to the generated value.
 #
@@ -92,7 +77,9 @@ module Fleakr
   # Generic catch-all exception for any API errors
   class ApiError < StandardError; end
 
-  mattr_accessor :api_key, :shared_secret, :auth_token
+  class << self
+    attr_accessor :api_key, :shared_secret, :auth_token
+  end
 
   # Find a user based on some unique user data.  This method will try to find
   # the user based on several methods, starting with username and falling back to email and URL
@@ -103,6 +90,8 @@ module Fleakr
   #  Fleakr.user('user@host.com')
   #  Fleakr.user('http://www.flickr.com/photos/the_decapitator/')
   #
+
+  # TODO: Use User.find_by_identifier for some of this
   def self.user(user_data, options = {})
     user = nil
     [:username, :email, :url].each do |attribute|
@@ -112,7 +101,7 @@ module Fleakr
     end
     user
   end
-  
+
   # Search all photos on the Flickr site.  By default, this searches based on text, but you can pass
   # different search parameters (passed as hash keys):
   #
@@ -127,7 +116,7 @@ module Fleakr
     params = {:text => params} unless params.is_a?(Hash)
     Objects::Search.new(params).results
   end
-  
+
   # Upload one or more files to your Flickr account (requires authentication).  Simply provide
   # a filename or a pattern to upload one or more files:
   #
@@ -135,13 +124,13 @@ module Fleakr
   #  Fleakr.upload('/User/Pictures/Party/*.jpg')
   #
   # Additionally, options can be supplied as part of the upload that will apply to all files
-  # that are matched by the pattern passed to <tt>glob</tt>.  For a full list, see 
+  # that are matched by the pattern passed to <tt>glob</tt>.  For a full list, see
   # Fleakr::Objects::Photo.
   #
   def self.upload(glob, options = {})
     Dir[glob].map {|file| Fleakr::Objects::Photo.upload(file, options) }
   end
-  
+
   # Get all contacts for the currently authenticated user.  The provided contact type can be
   # one of the following:
   #
@@ -159,11 +148,11 @@ module Fleakr
     options = {}
     options.merge!(:filter => contact_type) unless contact_type.nil?
     options.merge!(additional_options)
-    
+
     Fleakr::Objects::Contact.find_all(options)
   end
 
-  # Generate an authorization URL to redirect users to.  This defaults to 
+  # Generate an authorization URL to redirect users to.  This defaults to
   # 'read' permission, but others are available when passed to this method:
   #
   #  * :read - permission to read private information (default)
@@ -181,7 +170,7 @@ module Fleakr
   def self.token_from_frob(frob)
     Fleakr::Objects::AuthenticationToken.from_frob(frob)
   end
-  
+
   # Exchange a mini token for an authentication token.
   #
   def self.token_from_mini_token(mini_token)
@@ -196,10 +185,15 @@ module Fleakr
     token.user
   end
 
+  # Retrieve a photo, person, or set from a flickr.com URL:
+  #
+  def self.resource_from_url(url)
+    Fleakr::Objects::Url.new(url).resource
+  end
+
 end
 
 # Alias Fleakr methods as Flickr if possible
 if defined?(Flickr).nil?
   Flickr = Fleakr
-end
-
+end