smugmug 0.0.1

data/doc/API

@@ -0,0 +1,310 @@
+# -*- text -*-
+# $Hg$
+
+= Introduction
+
+The majority of the SmugMug's function are auto-generated.  This means rdoc
+documentation is useless because none of the functions are visible.  It is
+probably still preferable to document the function within class files, but for
+now I am going to document them here.  This way everything is in one location.
+
+== Conventions
+
+* SmugMug refers to the company, or web site.
+* smugmug refers to this library.
+
+=== Method
+==== Naming
+
+SmugMug and ruby do not share the same naming convetions.  For example, a
+function to return an album's ID is called AlbumID by Smugmug, but ruby would
+name it album_id.  To keep both factions happy smugmug provides both naming
+conventions.  When data are boolean types the ruby method names have a trailing
+question mark.  This convention is used throughout ruby.
+
+==== Return Types
+
+There are four data types that are returned by SmugMug.  They are boolean, int,
+string, and float.  The smugmug library ensures that all data returned is cast
+to the appropriate type.  For example, the data returned from smugmug.com for
+AlbumID is a string, but smugmug returns a Fixnum (integer).  This convention
+is broken with dealing with EXIF data.  Camera manufacturers may encode unit
+information in their data, thereby preventing the casting of data.  For
+example, the method focal length for my Canon SD500 return 7mm.
+
+The type information for the methods can be found on SmugMug's wiki at
+http://smugmug.jot.com/WikiHome/API/Versions/1.1.1.
+
+= SmugMug::SmugMug
+
+The first time you use the library you need to login in SmugMug.  This requires
+a username and password, all subsequent login attempts do not require a
+username, and password.  The first time you login SmugMug returns your UserID,
+and a password hash.  These data are stored in ~/.smugmugrc by default, and
+used by smugmug for subsequent login attempts.
+
+== Login
+
+=== Security
+
+Logins are carried out over https, but all other operations are carried out
+over http.  This is currently not user configurable, but may be in future
+versions.
+
+=== First Login
+
+The first login attempt requires and username, and password.
+
+  sm = SmugMug::SmugMug.new('user@example.net', 'secret')
+
+=== Subsequent Login
+
+Subsequent logins do not require a username/password if ~/.smugmugrc has good
+data.
+
+  sm = SmugMug::SmugMug.new
+
+=== Logging
+
+All session data can be logged by for debugging purposes.  By default, all
+logging information is sent to /dev/null, or a StringIO if /dev/null does not
+exist.  (Note: Need a better solution that StringIO)
+
+To create a logging instance do the following before logging into SmugMug.
+  
+  $log = Logger.new('smugmug.log')
+  sm = SmugMug::SmugMug.new
+
+NOTE: If logging is enabled personal information is captured, most notable the
+username and password, or UserID and password hash depending how login was
+handled.
+
+= Albums
+
+Use the each method to iterate over your albums.  You can also use any?, and
+size to determine if there are albums, and the number of albums.  Because the
+each method is provided, you can use any enumerable method.
+
+  sm = SmugMug::SmugMug.new
+
+  if sm.any?
+    puts "You have albums."
+  else
+    puts "You have no albums."
+  end
+
+  puts "There are #{sm.size} albums"
+
+  sm.each do |album|
+    puts albums.title
+  end
+
+== Methods
+
+Each albums has the following methods.  The alias for each method is also shown
+for completeness.
+
+(Some of these functions are self explanatory, but others are not.  I need to
+clarify these.)
+
+=== Standard 
+
+The following methods are available for Standard, Power, and Pro, and act on
+the current album.
+
+  * AlbumID (album_id): returns the Album ID.
+  * HighlightID (hightlight_id): returns the hightlight ID.
+  * CategoryID (category_id): returns the category ID.
+  * SubCategoryID (sub_category_id): returns the sub category ID.
+  * Position (position): returns the position.
+  * SortMethod (sort_method): return sort method: Position, Caption, Filenames, Date Uploaded, Date Modified, Date Taken.
+  * SortDirection (sort_direction?): sort ascending (true), or descending (false).
+  * ImageCount (image_count): returns the number of images.
+  * Keywords (keywords): returns the keywords.
+  * Description (description): returns the description.
+  * LastUpdate (last_updated): returns the date and time when the album was last updated.
+  * CommunityID (community_id): returns the community id.
+  * Public (public?): show this gallery on your homepage?
+  * Password (password): returns the password.
+  * PasswordHint (password_hint): return password hint.
+  * CanRank (can_rank?): allow visitors to vote your photos most popular?
+  * Printable (printable?): can people buy prints of these photos?
+  * Filenames (filenames?): for photos without captions, show the filename instead of nothing?
+  * Comments (comments?): can visitors read and post comments?
+  * External (external?): allow external links?
+  * Originals (originals?): can people view your original full-size photos?
+  * FamilyEdit (family_edit?): can your family edit captions and keywords?
+  * FriendEdit (friend_edit?): can your friends edit captions and keywords?
+  * HideOwnder (hide_owner?): hide your name, navigation, and look and feel?
+  * EXIF (exif?): show extra camera info?
+  * Share (share?): do you want the 'share photo: links formus, blogs' link? 
+  * Header (header?): (???)
+  * SmugSearchable (smug_searchable?): do you want your photos in SmugMug's search?
+  * WorldSearchable (world_searchable?): can Google find your smug mug?
+
+  puts album.image_count
+  puts album.SortMethod
+
+=== Power
+
+The following methods are available for Power, and Pro. (Need help with these.)
+
+  * Header (header?): (???)
+  * TemplateID (template_id): (???)
+
+  puts album.header
+
+=== Pro
+
+The following methods are available for Pro.  (Need help with these.)
+ 
+  * Larges (larges?): (???)
+  * DefaultColor (default_color?): (???) 
+  * Clean (clean?): (???)
+  * Protected (protected?): (???)
+  * Watermark (watermark?): (???)
+
+  puts album.Watermark
+  puts album.watermark?
+
+== Stats
+
+Every album has statistics associted with it for the current month.  SmugMug
+supports the retreival of statistics from up to two months previous, but
+smugmug only supports the current month.
+
+    stats = album.stats
+    puts stats.bytes
+    puts album.stats.small
+
+=== Methods
+
+The following methods are supported for the an Album's statistics.  (I need to
+verify if these definitions are correct.)
+
+  * Bytes (bytes): return bytes downloaded for this album.
+  * Tiny (tiny): retuns the number of tiny images fetched.
+  * Thumb (thumb): retuns the number of thumb images fetched.
+  * Small (small): retuns the number of small images fetched.
+  * Medium (medium): retuns the number of medium images fetched.
+  * Large (large): retuns the number of large images fetched.
+  * Original (original): retuns the number of original images fetched.
+
+Note: album statistics also have a status, but that information is not returned
+by smugmug.  (I am not really sure what status means.)
+
+= Images
+
+Just like the Album class the methods any?, size, and each are available.
+These methods are attached to an album instance.  Likewise, album instances
+include Enumerable and can be used with any of the enumerable methods, such as
+inject.
+
+    if album.any?
+        puts "This album contains images."
+    else
+        puts "This album contains no images."
+    end
+
+    puts "This album contains #{album.size} images."
+    puts "This album contains #{album.image_count} images."
+
+    album.each do |image|
+        puts "#{image.file_name} has MD5 Sum #{image.md5_sum}"
+    end
+
+=== Methods
+
+Just like with Album there are two functions to access the same values.  One
+based on SmugMug's name, and based on ruby's convention.
+
+  * AlbumID (album_id): returns this image's album ID.
+  * ImageID (image_id): returns this image's ID.
+  * Position (position): returns this image's position.
+  * Serial (serial): returns this image's serial.
+  * Size (size): returns this image's size in bytes.
+  * Width (width): return this image's width in pixels.
+  * Height (height): return this image's height in pixels.
+  * LastUpdated (last_updated): returns the date and time the last time this image was updated.
+  * Caption (caption): returns the caption of this image.
+  * FileName (file_name): returns this image's file name.
+  * MD5Sum (md5_sum): returns this image's MD5 sum.
+  * Watermark (watermark): returns this image's watermark.
+  * Format (format): returns this image's format, such as JPG.
+  * Keywords (keywords): returns this image's keywords.
+  * Date (date): returns the date and time this image was taken (???)
+  * OriginalURL (original_url): return a URL pointing this image's original.
+  * LargeURL (Large_url): return a URL pointing a large version of this image's.
+  * MediumURL (medium_url): return a URL pointing a medium version of this image's.
+  * SmallURL (small_url): return a URL pointing a small version of this image's.
+  * ThumbURL (thumb_url): return a URL pointing a thumb version of this image's.
+  * TinyURL (tiny_url): return a URL pointing a tiny version of this image's.
+  * AlbumURL (album_url): return a URL pointing to this image's album.
+
+  puts "This image is #{image.size} bytes."
+
+== EXIF
+
+The method exif is attached to every image instance, and returns the EXIF class
+attached to this image.
+
+    exif = image.exif
+    puts "The camera that took this image was #{exif.model}."
+
+=== Methods
+
+EXIF methods are unique in that SmugMug does not guarantee that all methods are
+available.  This make sense because not all camera manfucaturers report the
+same data.  If you attempt to access data that does not exist the value nil is
+returned.
+
+    if image.exif.iso.nil?
+        puts "Sorry, no EXIF data is available for 'ISO'"
+    end
+
+All functions are in the context of this image.
+
+  * ImageId (image_id): returns the image ID.
+  * DateTime (date_time): returns the date and time.
+  * DateTimeOriginal (date_time_original): (???)
+  * DateTimeDigitized (date_time_digitized): returns the date and time when this image was digitized.
+  * Make (make): returns the make of the camera that took.
+  * Model (model): returns the model of the camera that took.
+  * ExposureTime (exposure_time): returns the exposure time.
+  * Aperture (aperture): returns the aperture. 
+  * ISO (iso): returns the ISO.
+  * FocalLength (focal_lenght): returns the focal length.
+  * FocalLength35mmFilm (focal_length35mm_film): (???)
+  * CCDWidth (ccdwidth): return the CCD width
+  * CompressedBitsPerPixel (compressed_bits_per_pixel): returns the compressed bits per pixel.
+  * Flash (flash): (???)
+  * Metering (metering): (???)
+  * ExposureProgram (exposure_program): (???)
+  * SubjectDistance (subject_distance): return the distance to the subject.
+  * SubjectDistanceRange (subject_distance_range): return an range of the distance to the subject.
+  * SensingMethod (sensing_method): returns the sensing method.
+  * ColorSpace (color_space): returns the color space.
+  * Brightness (brightness): returns the brigtness.
+
+  exif = image.exif
+  puts "This image was taked on #{exif.date_time}."
+ 
+== Stats
+
+Image stats are identical to album stats except that they apply to a specific
+image.
+
+=== Methods
+
+The following methods are supported for the an image's statistics.  (I need to
+verify if these definitions are correct.)
+
+  * Bytes (bytes): return bytes downloaded.
+  * Tiny (tiny): downloads of the tiny representation.
+  * Thumb (thumb): downloads of the thumb representation.
+  * Small (small): downloads of the small representation.
+  * Medium (medium): downloads of the medium representation. 
+  * Large (large): downloads of the large representation.
+  * Original (original): downloads of the original.
+
+  puts "The original of this image was downloaded #{image.stats.original} times for #{Time.now.month}/#{Time.now.year}"

data/doc/TODO

@@ -0,0 +1,32 @@
+# -*- text -*-
+# $Hg$
+
+== Documentation
+
+* You'll never have enough!
+
+== Library
+
+* More testing
+  a. extend the SmugMug servlet
+  a. make login more realistic
+  a. automatically generate fake test data
+  a. use SQLite has the backend for the servlet
+* Add write support
+  a. adding new albums
+  a. uploading new images
+  a. modifying album, and image attributes
+* Add support for categories, and sub categories
+* Add support for password protected galleries
+* Add support for a date type to MethodTable.
+* Add support for explicitly specifying an alias for a MethodTable.
+* Add support for scrubbing the data generated by canned.
+* Factor StatsBase out into base/stats.rb
+
+== Scripts
+
+* Add a script to query *all* of the SmugMug data and stick it in a
+  SQLite database.
+* Add a script to verify the integrity of one's photos.
+* Add a poor man's rsync script to upload missing photos to SmugMug.
+* Add a script to move photos between SmugMug and Picasa.

data/lib/net/httpz.rb

@@ -0,0 +1,31 @@
+# -*- ruby -*-
+# $Hg$
+
+require 'net/https'
+require 'stringio'
+require 'zlib'
+
+module Net
+    class HTTP
+        alias original_get get
+        def get(path, initheader = nil, dest = nil, &block)
+            headers = { 'Accept-Encoding' => 'gzip' }
+            headers.merge!(initheader) unless initheader.nil?
+
+            return original_get(path, headers, dest, &block)
+        end
+    end
+
+    class HTTPResponse
+	    def gzip?
+	        return false unless @header.has_key?('content-encoding')
+	        return @header['content-encoding'].to_s == 'gzip'
+	    end
+	
+	    alias original_body body
+	    def body
+	        data = original_body
+	        return (gzip?) ? Zlib::GzipReader.new(StringIO.new(data)).read : data
+	    end
+    end
+end

data/lib/smugmug.rb

@@ -0,0 +1,179 @@
+#!/usr/bin/env ruby
+# $Hg: smugmug.rb,v c21b2f4bec8c 2007/08/11 08:00:21 boumenot $
+
+require 'forwardable'
+require 'logger'
+require 'net/httpz'
+require 'rexml/document'
+require 'stringio'
+require 'time'
+require 'uri'
+require 'zlib'
+
+require 'smugmug/albums'
+require 'smugmug/cache'
+require 'smugmug/config'
+require 'smugmug/util'
+
+module SmugMug
+  
+    API_VERSION='1.1.1'
+    API_KEY='dydlCYDzmykqoLkVGgECEIP5WEuwWFzc'
+    URL="https://api.smugmug.com/hack/rest/#{API_VERSION}/"
+
+    VERSION = '0.0.1'
+    USERAGENT = "SmugMug Ruby Library - #{VERSION} " + '($HgRev: c21b2f4bec8ce187d5bcb5cd75a6076c40c0cf5f $)'
+
+    class SmugMugError < RuntimeError
+    end
+
+    class NotModified < SmugMugError
+    end
+
+    class SmugMug
+        include Enumerable
+
+        extend Forwardable
+        def_delegator :@config, :AccountType, :account_type
+        def_delegator :albums, :each, :each
+        def_delegator :albums, :any?, :any?
+        def_delegator :albums, :size, :size
+
+        attr_reader :base, :session_id
+
+        def initialize(*args)
+            if $log.nil?
+                $log = if File.exists?('/dev/null')
+                    Logger.new('/dev/null')
+                else
+                    Logger.new(StringIO.new)
+                end
+            end
+
+            @base = ENV.has_key?('SMUGMUG_URL') ? ENV['SMUGMUG_URL'] : URL
+            @config = Config.new()
+            login(*args)
+        end
+
+        def fetch(params={})
+            query = build_url(params)
+            data = get(query)
+            doc = REXML::Document.new(data)
+
+            if doc.root.attributes['stat'] == 'fail'
+                raise SmugMugError, 
+                    "#{doc.root.elements['err'].attributes['code']}" +
+                    "- #{doc.root.elements['err'].attributes['msg']}"
+            end
+
+            return doc
+        end
+
+        private
+
+        def albums
+            @albums = Albums.new(self) if @albums.nil?
+            return @albums
+        end
+
+        def build_url(params)
+            query = base + '?'
+
+            $log.debug('SmugMug#build_url') { "Params:" }
+            params.each do |k,v| 
+                $log.debug('SmugMug#build_url') { "  #{k}=#{v}" }
+                query += "#{k}=" + URI.encode(v.to_s) + '&'
+            end
+
+            return query
+        end
+
+        public
+
+        def get(url, headers={})
+            # XXX: this is a hack, think of a better solution
+            url.sub!(/^https:/, 'http:') unless url =~ /method=smugmug\.login/
+            $log.info('SmugMug#get') { url }
+
+            headers['User-Agent'] = USERAGENT 
+            uri = URI.parse(url)
+
+            http = Net::HTTP.new(uri.host, uri.port)
+
+            if uri.scheme == 'https'
+                http.use_ssl     = true
+                http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+            end
+            
+            http.start {
+                response = http.get(uri.path + '?' + uri.query, headers)
+
+                $log.info('SmugMug#get')  { "HTTP #{response.code} (#{response.message})" }
+                $log.debug('SmugMug#get') { "Headers (response):" }
+                response.each_header { |k,v| $log.debug('SmugMug#get') { "  #{k}: #{v}" } }
+                
+                case response.code.to_i
+                when 200
+                    body = response.body
+                    $log.debug('SmugMug#get') { body }
+                    return body
+                when 304
+                    $log.debug('SmugMug#get') { 'If-Modified-Since is false' }
+                    raise NotModified, "#{url} has not changed"
+                else
+                    raise SmugMugError, "GET of #{url} failed"
+                end
+            }
+        end
+
+        def post(url, body, headers={})
+        end
+
+        def login(*args)
+            params = {}
+            if @config.PasswordHash.nil?
+                raise SmugMugError, "Login by password requires a email address, and password" if args.size != 2
+
+                params[:method]       = 'smugmug.login.withPassword'
+                params[:EmailAddress] = args.shift
+                params[:Password]     = args.shift
+
+                @config.EmailAddress = params[:EmailAddress]
+            else
+                params[:method] = 'smugmug.login.withHash'
+                %w{UserID PasswordHash}.each do |var|
+                    params[var.to_sym] = @config.send(var.to_sym)
+                end
+            end
+
+            params[:APIKey] = API_KEY 
+            @login_doc = fetch(params).root.elements['Login']
+
+            @session_id = @login_doc.elements['SessionID'].text
+
+            Config::VARIABLES.each do |var|
+                @config.send("#{var}=".to_sym, @login_doc.elements[var].text) unless @login_doc.elements[var].nil?
+            end
+            @config.save
+        end
+    end
+end
+
+
+def main
+    unless ARGV.length == 2
+        puts "#{$0} Usage: <email> <password>"
+        Kernel.exit(1)
+    end
+
+    File.unlink('smugmug.log') if File.exists?('smugmug.log')
+    $log = Logger.new('smugmug.log')
+    sm = SmugMug::SmugMug.new(ARGV.shift, ARGV.shift)
+    sm.each do |album|
+        puts "#{album.id} -> #{album.title} (#{album.ImageCount})"
+    end
+end
+
+if __FILE__ == $0
+    main()
+end