slaskis-fleakr 0.5.0

data/README.rdoc

@@ -0,0 +1,350 @@
+= Fleakr
+
+== Description
+
+A small, yet powerful, gem to interface with Flickr photostreams
+
+== Installation
+
+=== Stable
+
+    sudo gem install fleakr
+
+=== Bleeding Edge
+
+    sudo gem install reagent-fleakr --source=http://gems.github.com
+    
+Or ...
+
+    $ git clone git://github.com/reagent/fleakr.git
+    $ cd fleakr
+    $ rake gem && sudo gem install pkg/fleakr-<version>.gem
+
+== Usage
+
+To get started, you'll need to grab an API key from Flickr to at least perform any of
+the non-authenticated, read-only calls.  Head on over to the Flickr site to grab one, I'll
+be here when you get back: http://www.flickr.com/services/api/misc.api_keys.html
+
+Now that you have your key, you can get things rolling with irb and the fleakr gem:
+
+    $ 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 
+user by his username:
+
+    >> user = Fleakr.user('the decapitator')
+    => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
+
+Or by email:
+
+    >> user = Fleakr.user('user@host.com')
+    => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">
+
+Once you have a user, you can find his associated sets:
+
+    >> user.sets
+    => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">, 
+        #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ...
+
+His individual photos:
+
+    >> user.photos.first
+    => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
+
+Or contacts:
+
+    >> user.contacts.first
+    => #<Fleakr::Objects::User:0x19039bc @username=".schill",
+        @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:0x11f2308 ...
+    >> user.groups.first.name
+    => "Rural Decay"
+    >> user.groups.first.id
+    => "14581414@N00"
+
+Groups also contain photos:
+
+    >> user.groups.last.photos.first.title
+    => "Welcome To The Machine"
+
+When accessing a set, you can also grab all the photos that are in that set:
+
+    >> user.sets.first
+    => #<Fleakr::Objects::Set:0x1195bbc @title="The Decapitator", @id="72157603480986566", @description="">
+    >> user.sets.first.photos.first
+    => #<Fleakr::Objects::Photo:0x1140108 ... >
+    >> user.sets.first.photos.first.title
+    => "Untitled1"
+    
+=== Photos
+
+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",  
+        @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:0x1908a20 @value="ads">, ...
+    >> user.photos.first.tags
+    => [#<Fleakr::Objects::Tag:0x17b1b18 @machine_flag="0", @author_id="21775151@N06", ...
+
+All tags have values, but for tags associated with photos there is some additional information:
+
+    >> tag = user.photos.first.tags.first
+    >> tag.id
+    => "21729829-3263659141-427098"
+    >> tag.raw
+    => "decapitator"
+    >> tag.value
+    => "decapitator"
+    >> tag.to_s
+    => "decapitator"
+    >> tag.machine?
+    => 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
+
+Similar to tags, photosets and photos can each have comments:
+
+    >> user.sets.first.comments
+    => [#<Fleakr::Objects::Comment:0x19795cc ...
+    >> user.photos.first.comments
+    => [#<Fleakr::Objects::Comment:0x17bf0b0 @body="Dayum, that's some wishful thinking!" ...
+
+All comments have additional information:
+
+    >> comment = user.photos.first.comments.first
+    >> comment.id
+    => "21729829-3263659141-72157613553885978"
+    >> comment.body
+    => "Dayum, that's some wishful thinking!"
+    >> comment.to_s
+    => "Dayum, that's some wishful thinking!"
+    >> comment.url
+    => "http://www.flickr.com/photos/the_decapitator/3263659141/#comment72157613553885978"
+    >> comment.author
+    => #<Fleakr::Objects::User:0x178e3d4 @username="jaspertandy", ... >
+
+See Fleakr::Objects::Comment for more information.
+
+=== 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 
+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/03_2118696542_8af5763bde_s.jpg", ... ]
+
+=== Searching
+
+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:0x11f4928 @title="PONYLOV", @id="3077360853">, ...
+    >> photos.first.title
+    => "hiroshima atomic garden"
+
+You can also search based on tags:
+
+    >> photos = Fleakr.search(:tags => 'macro')
+    >> photos.first.title
+    => "Demure"
+    >> photos.first.id
+    => "3076049945"
+
+Searches can also be scoped to other entities in the system (namely Users and Groups):
+
+    >> user.groups.first.search('awesome')
+    => [#<Fleakr::Objects::Photo:0x18cb4cc @server_id="2012", @id="2181921273",
+         @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">]
+
+=== Uploading Files
+
+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:
+
+    >> Fleakr.upload('/path/to/images/*.jpg')
+    => [#<Fleakr::Objects::Photo:0x217faa0 ...>,
+        #<Fleakr::Objects::Photo:0x212fb18 ...>,
+        #<Fleakr::Objects::Photo:0x20e09c8 ...>]
+
+You can also set options on the file(s) that you're uploading:
+
+    >> 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.
+
+=== 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).  
+
+Assuming you've already applied for a key, go back and make sure you have the right settings
+to get your auth token.  Click on the 'Edit key details' link and ensure that:
+
+1. Your application description and notes are up-to-date
+1. The value for 'Authentication Type' is set to 'Mobile Application'
+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 
+confirm access to get your mini-token. Now you're ready to make authenticated requests:
+
+    require 'rubygems'
+    require 'fleakr'
+
+    Fleakr.api_key       = 'ABC123'
+    Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
+    Fleakr.mini_token    = '362-133-214'
+
+    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.  Similarly, if you have
+an authenticated frob from Flickr (using authentication for desktop applications, for example)
+you can also set <tt>Fleakr.frob</tt> to the frob value returned from the API.
+
+=== What Went Wrong?
+
+Because so much of the underlying API is hidden under the covers, it's often tough to know
+what's really going on when you run into unexpected behavior.  To make things easier, you can
+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 
+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.
+
+== Roadmap / TODO
+
+=== 0.4.x
+
+* Implement remaining bits of person and photo-related API calls (read-only)
+
+=== 0.5.x
+
+* Implement asynchronous file upload / replacement w/ ticket checking
+* Provide a better searching interface with ruby-like option syntax
+
+=== Future
+
+* 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 
+
+== License
+
+Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/fleakr/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'fleakr'
+  s.version          = Fleakr::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  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.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
+  
+  s.add_dependency('hpricot', '~> 0.8.1')
+  s.add_dependency('activesupport', '~> 2.0')
+  s.add_dependency('loggable', '~> 0.2.0')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end

data/lib/fleakr.rb

@@ -0,0 +1,164 @@
+$:.unshift(File.dirname(__FILE__))
+require 'rubygems'
+
+require 'uri'
+require 'cgi'
+require 'net/http'
+require 'hpricot'
+require 'forwardable'
+
+# Require only what we need from ActiveSupport
+require 'active_support/core_ext/array'
+require 'active_support/core_ext/module'
+require 'active_support/core_ext/blank'
+require 'active_support/core_ext/time'
+require 'active_support/inflector'
+require 'active_support/core_ext/string'
+
+require 'digest/md5'
+require 'fileutils'
+require 'loggable'
+
+require 'fleakr/api'
+require 'fleakr/core_ext'
+require 'fleakr/support'
+require 'fleakr/objects'
+
+# = Fleakr: A small, yet powerful, gem to interface with Flickr photostreams
+#
+# == 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' 
+# photostreams, sets, contacts, groups, etc...
+#
+# For now, all activity originates from a single user which you can find by username or
+# email address.
+#
+# Example:
+#
+#  require 'rubygems'
+#  require 'fleakr'
+#
+#  # Our API key is ABC123 (http://www.flickr.com/services/api/keys/apply/)
+#  Fleakr.api_key = 'ABC123'
+#  user = Fleakr.user('bees')
+#  user = Fleakr.user('user@host.com')
+#  # Grab a list of sets
+#  user.sets
+#  # Grab a list of the user's public groups
+#  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), 
+# 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
+# to get your auth token.  Click on the 'Edit key details' link and ensure that:
+#
+# 1. Your application description and notes are up-to-date
+# 1. The value for 'Authentication Type' is set to 'Mobile Application'
+# 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 
+# confirm access to get your mini-token. Now you're ready to make authenticated requests:
+#
+#   require 'rubygems'
+#   require 'fleakr'
+#
+#   Fleakr.api_key       = 'ABC123'
+#   Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
+#   Fleakr.mini_token    = '362-133-214'
+#
+#   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.
+#
+module Fleakr
+
+  # Generic catch-all exception for any API errors
+  class ApiError < StandardError; end
+
+  mattr_accessor :api_key, :shared_secret, :mini_token, :auth_token, :frob
+
+  # Find a user based on some unique user data.  This method will try to find
+  # the user based on username and will fall back to email if that fails.  Example:
+  #
+  #  Fleakr.api_key = 'ABC123'
+  #  Fleakr.user('the decapitator') # => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
+  #  Fleakr.user('user@host.com')   # => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">
+  #
+  def self.user(user_data)
+    begin
+      Objects::User.find_by_username(user_data)
+    rescue ApiError
+      Objects::User.find_by_email(user_data)
+    end
+  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):
+  #
+  # [tags] The list of tags to search on (either as an array or comma-separated)
+  # [user_id] Scope the search to this user
+  # [group_id] Scope the search to this group
+  #
+  # If you're interested in User- and Group-scoped searches, you may want to use User#search and Group#search
+  # instead.
+  #
+  def self.search(params)
+    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:
+  #
+  #  Fleakr.upload('/path/to/my/mug.jpg')
+  #  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 
+  # Fleakr::Objects::Photo.
+  #
+  def self.upload(glob, options = {})
+    Dir[glob].map {|file| Fleakr::Objects::Photo.upload(file, options) }
+  end
+
+  # Get the authentication token needed for authenticated requests.  Will either use
+  # a valid auth_token (if available) or a mini-token to generate the auth_token.
+  #
+  def self.token
+    @token ||= begin
+      if Fleakr.auth_token
+        Fleakr::Objects::AuthenticationToken.from_auth_token(Fleakr.auth_token)
+      elsif Fleakr.frob
+        Fleakr::Objects::AuthenticationToken.from_frob(Fleakr.frob)
+      elsif Fleakr.mini_token
+        Fleakr::Objects::AuthenticationToken.from_mini_token(Fleakr.mini_token)
+      end
+    end
+  end
+  
+  # Reset the cached token whenever setting a new value for the mini_token, auth_token, or frob
+  #
+  [:mini_token, :auth_token, :frob].each do |attribute|
+    class_eval <<-ACCESSOR
+      def self.#{attribute}=(#{attribute})
+        reset_token
+        @@#{attribute} = #{attribute}
+      end
+    ACCESSOR
+  end
+
+  def self.reset_token # :nodoc: #
+    @token = nil
+  end
+  
+end