ideaoforder-fleakr 0.7.0

data/.gitignore

@@ -0,0 +1,3 @@
+/pkg/
+/coverage/
+/doc/

data/README.rdoc

@@ -0,0 +1,381 @@
+= 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"
+
+=== Contacts
+
+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" ...>]
+
+See the documentation for Fleakr.contacts for what options are available.
+
+=== 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.
+
+== 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:
+
+* {John Guenin}[http://github.com/johng]
+* {Thomas Olausson}[http://github.com/latompa]
+
+Thanks!
+
+== 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,73 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "fleakr"
+    gemspec.summary = "A small, yet powerful, gem to interface with Flickr photostreams"
+    gemspec.description = "A small, yet powerful, gem to interface with Flickr photostreams"
+    gemspec.email = 'reaganpr@gmail.com'
+    gemspec.homepage = 'http://sneaq.net'
+    gemspec.authors = ["Patrick Reagan", "Mark Dickson"]
+    gemspec.add_dependency('hpricot', '>= 0.6.164')
+    gemspec.add_dependency('activesupport', '>= 2.0')
+    gemspec.add_dependency('loggable', '>= 0.2.0')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+# require 'rubygems'
+# require 'rake/gempackagetask'
+# require 'rake/testtask'
+# 
+# require 'lib/fleakr/version'
+# 
+# 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.6.164')
+#   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
+# 
+# begin
+#   require 'rcov/rcovtask'
+# 
+#   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']
+#   end
+#   
+#   task :default => :coverage
+#   
+# rescue LoadError
+#   warn "\n**** Install rcov (sudo gem install relevance-rcov) to get coverage stats ****\n"
+#   task :default => :test
+# 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