imagery 0.0.1 → 0.0.2

data/.gitignore

@@ -20,3 +20,5 @@ pkg
 
 ## PROJECT::SPECIFIC
 /.rvmrc
+/.yardoc
+/doc

data/README.markdown

@@ -0,0 +1,231 @@
+Imagery
+=======
+
+(See documentation at [http://labs.sinefunc.com/imagery/doc](http://labs.sinefunc.com/imagery/doc))
+
+## Image manipulation should be simple. It should be customizable. It should allow for flexibility. Imagery attempts to solve these.
+
+### Imagery favors:
+
+1. Simplicity and explicitness over magic DSLs.
+2. OOP principles such as inheritance and composition.
+3. Flexibility and extensibility.
+4. Not being tied to any form of ORM.
+
+1. Simplicity and Explicitness
+------------------------------
+To get started using Imagery you only need ImageMagick, ruby and Imagery of 
+course.
+    
+    # on debian based systems
+    sudo apt-get install imagemagick
+    # or maybe using macports
+    sudo port install ImageMagick
+    [sudo] gem install imagery
+
+Then you may proceed using it.
+  
+    require 'rubygems'
+    require 'imagery'
+
+    Photo = Class.new(Struct.new(:id))
+    
+    i = Imagery.new(Photo.new(1001))
+    i.root = '/some/path/here'
+    i.sizes = { :thumb => ["48x48^", "48x48"], :large => ["480x320"] }
+    i.save(File.open('/some/path/to/image.jpg'))
+
+    File.exist?('/some/path/here/public/system/photo/1001/thumb.png')
+    # => true
+
+    File.exist?('/some/path/here/public/system/photo/1001/large.png')
+    # => true
+
+    File.exist?('/some/path/here/public/system/photo/1001/original.png')
+    # => true
+
+    # the defaut is to use the .id and the name of the class passed,
+    # but you can specify a different scheme.
+
+    i = Imagery.new(Photo.new(1001), `uuidgen`.strip, "photos")
+    i.root = '/some/path/here'
+    i.file == '/some/path/here/public/system/photos/1c2030a6-6bfa-11df-8997-67a71f1f84c7/original.png'
+    # => true
+
+2. OOP Principles (that we already know)
+----------------------------------------
+
+### Ohm example (See [http://ohm.keyvalue.org](http://ohm.keyvalue.org))
+    
+    # Imagery will use ROOT_DIR if its available
+    ROOT_DIR = "/u/apps/site/current"
+
+    class User < Ohm::Model
+      include Ohm::Callbacks
+      
+      after :save, :write_avatar
+
+      def avatar=(fp)
+        @avatar_fp = fp
+      end
+
+      def avatar
+        @avatar ||= 
+          Imagery.new(self).tap do |i|
+            i.sizes = { :thumb => ["48x48^", "48x48"], :medium => ["120x120"] }
+          end
+      end
+
+    protected
+      def write_avatar
+        avatar.save(@avatar_fp[:tempfile])  if @avatar_fp
+      end
+    end
+
+    # Since we're using composition, we can customize the dimensions on an 
+    # instance level.
+    class Collage < Ohm::Model
+      attribute :width
+      attribute :height
+
+      def photo
+        @photo ||= 
+          Imagery.new(self).tap do |i|
+            i.sizes = { :thumb => ["%sx%s" % [width, height]] }
+          end
+      end
+    end
+    
+    # For cases where we want to use S3 for some and normal filesystem for others
+    class S3Photo < Imagery::Model
+      include Imagery::S3
+      self.s3_bucket = 'my-bucket'
+    end
+
+    # then maybe some other files are using cloudfront
+    class CloudfrontPhoto < Imagery::Model
+      include Imagery::S3
+      self.s3_bucket = 'my-bucket'
+      self.s3_distribution_domain = 'assets.site.com'
+    end
+
+3. Flexibility and Extensibility
+--------------------------------
+### Existing plugins: Faking and S3
+
+#### Imagery::S3
+
+As was shown in some examples above you can easily do S3 integration.
+The access credentials are assumed to be stored in
+
+    ENV["AMAZON_ACCESS_KEY_ID"]
+    ENV["AMAZON_SECRET_ACCESS_KEY"]
+
+you can do this by setting it on your .bash_profile / .bashrc or just
+manually setting them somewhere in your appication
+
+    ENV["AMAZON_ACCESS_KEY_ID"] = '_access_key_id_'
+    ENV["AMAZON_SECRET_ACCESS_KEY"] = '_secret_access_key_'
+
+Now you can just start using it:
+  
+    Photo = Class.new(Struct.new(:id))
+
+    class Imagery::Model
+      include Imagery::S3
+      self.s3_bucket = 'my-bucket'
+    end
+
+    i = Imagery.new(Photo.new(1001))
+    i.root = '/tmp'
+    i.save(File.open('/some/path/to/image.jpg'))
+
+#### Imagery::Faking
+
+When doing testing, you definitely don't want to run image
+resizing everytime. Enter Faking.
+
+    # in your test_helper / spec_helper
+    Imagery::Model.send :include, Imagery::Faking
+    Imagery::Model.mode = :fake
+  
+    # but what if we want to run it for real on a case to case basis?
+    # sure we can!
+    Imagery::Model.real {
+      # do some imagery testing here
+    }
+
+#### Imagery::Test
+
+There is a module you can include in your test context to automate the pattern
+of testing / faking on an opt-in basis.
+
+    # in your test_helper / spec_helper
+    class Test::Unit::TestCase
+      include Imagery::Test
+    end
+    
+    # now when you do some testing... (User assumes the user example above)
+    imagery do |is_real|
+      user = User.new(:avatar => { tempfile: File.open('avatar.jpg') })
+      user.save
+
+      if is_real
+        assert File.exist?(user.avatar.file)
+      end
+    end
+
+Running your test suite:
+
+    REAL_IMAGERY=true rake test
+
+It's off by default though, so you don't have to do anything to make sure 
+Imagery doesn't run.
+
+### Extending Imagery
+By making use of standard Ruby idioms, we can easily do lots with it. 
+Exensibility is addressed via Ruby modules for example:
+
+    module Imagery
+      module MogileStore
+        def self.included(base)
+          class << base
+            attr_accessor :mogile_config
+          end
+        end
+
+        def save(io)
+          if super
+            # do some mogie FS stuff here
+          end
+        end
+
+        def delete
+          super
+          # remove the mogile stuff here
+        end
+      end
+    end
+
+    # Now just include the module however, whenever you want
+    module Imagery
+      class Model
+        include Imagery::MogileStore
+        self.mogile_config = { :foo => :bar }
+      end
+    end
+
+
+### Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+### Copyright
+
+Copyright (c) 2010 Cyril David. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/imagery.gemspec

@@ -0,0 +1,70 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{imagery}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Cyril David"]
+  s.date = %q{2010-05-31}
+  s.description = %q{Uses ImageMagick directly underneath. Nuff said.}
+  s.email = %q{cyx.ucron@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "imagery.gemspec",
+     "lib/imagery.rb",
+     "lib/imagery/faking.rb",
+     "lib/imagery/model.rb",
+     "lib/imagery/s3.rb",
+     "lib/imagery/test.rb",
+     "test/fixtures/lake.jpg",
+     "test/helper.rb",
+     "test/test_imagery.rb",
+     "test/test_with_s3.rb"
+  ]
+  s.homepage = %q{http://github.com/sinefunc/imagery}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Image resizing without all the bloat}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_imagery.rb",
+     "test/test_with_s3.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<escape>, [">= 0"])
+      s.add_development_dependency(%q<contest>, [">= 0"])
+      s.add_development_dependency(%q<aws-s3>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+    else
+      s.add_dependency(%q<escape>, [">= 0"])
+      s.add_dependency(%q<contest>, [">= 0"])
+      s.add_dependency(%q<aws-s3>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<escape>, [">= 0"])
+    s.add_dependency(%q<contest>, [">= 0"])
+    s.add_dependency(%q<aws-s3>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
+  end
+end
+

data/lib/imagery.rb

@@ -2,19 +2,17 @@ require 'escape'
 require 'fileutils'
 
 module Imagery
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
   
   autoload :Model,  "imagery/model"
   autoload :Faking, "imagery/faking"
   autoload :S3,     "imagery/s3"
-
+  autoload :Test,   "imagery/test"
+  
+  # Syntactic sugar for Imagery::Model::new
+  # @see Imagery::Model#initialize for details
   def new(*args, &blk)
     Model.new(*args, &blk)
   end
   module_function :new
-  
-  def faked(&blk)
-    Model.faked(&blk)
-  end
-  module_function :faked
 end

data/lib/imagery/faking.rb

@@ -19,6 +19,13 @@ module Imagery
       ensure
         @mode = @omode
       end
+
+      def real
+        @omode, @mode = @mode, nil
+        yield
+      ensure
+        @mode = @omode
+      end
     end
 
     def save(io)

data/lib/imagery/model.rb

@@ -1,41 +1,146 @@
 module Imagery
   class Model 
     UnknownSize = Class.new(StandardError)
+  
+    @@directory = 'public/system'
+    @@default   = { :original => ["1920x1200>"] }
 
+    # This is typically the database ID, you may also use something 
+    # like a GUID for it, the sky's the limit.
     attr :key
+  
+    # Used as a grouping scheme, if you name this as `photos` for example,
+    # you will have public/system/photos as the path.
     attr :namespace
+  
+    # Returns a single key => value pair hash, defaulting to @@default.
     attr :default
+
+    # Returns the directory used which defaults to public/system.
     attr :directory
+    
+    # Defaulting to :original, the value used here will be the default 
+    # size used when calling Imagery::Model#url and Imagery::Model#file.
+    attr_accessor :default_size
 
-    attr_writer   :root, :sizes
+    # Allows you to define the root of your application, all other paths
+    # are determined relative to this.
+    attr_writer :root
+
+    # Allows you to define the different sizes you want as a hash of 
+    # :style => [geometry] pairs.
+    attr_writer :sizes
     
-    def initialize(model, key = model.id, namespace = model.class.name.split('::').last.downcase)
-      @key       = key.to_s
-      @namespace = namespace
-      @default   = { :original => ["1920x1200>"] }
-      @directory = 'public/system'
-      @sizes     = {}
+    # @param [#id] model any ruby object
+    # @param [#to_s] key typically the database ID of a model. But you may also 
+    #                use anything here just as long as its unique across the
+    #                namespace.
+    # @param [String] namespace used as a grouping mechanism for your images.
+    def initialize(model, key = model.id, namespace = namespace_for(model.class))
+      @key          = key.to_s
+      @namespace    = namespace
+      @default      = @@default
+      @directory    = @@directory
+      @sizes        = {}
+      @default_size = :original
     end
     
+    # Returns all the sizes defined including the default size.
+    #
+    # @example
+    #   Photo = Class.new(Struct.new(:id))
+    #   i = Imagery::Model.new(Photo.new(1001))
+    #   i.sizes == { :original => ["1920x1280"] }
+    #   # => true
+    #
+    #   i.sizes = { :thumb => ["48x48"] }
+    #   i.sizes == { :thumb => ["48x48"], :original => ["1920x1280"] }
+    #   # => true
+    #
+    # @return [Hash] size => [dimension] pairs.
     def sizes
-      @sizes.merge(@default)
+      @sizes.merge(default)
     end
     
-    def file(size = :original)
+    # Gives the absolute file for a specified size.
+    #
+    # @example
+    #
+    #   Photo = Class.new(Struct.new(:id))
+    #   i = Imagery.new(Photo.new(1001))
+    #   i.root = '/tmp'
+    #   i.file(:original) == '/tmp/public/system/photo/1001/original.png
+    #   # => true
+    #
+    #   i.file(:thumb)
+    #   # raise Imagery::Model::UnknownSize
+    #
+    #   i.sizes = { :thumb => ["100x100"] }
+    #   i.file(:thumb) == '/tmp/public/system/photo/1001/thumb.png
+    #   # => true
+    #
+    # @param [Symbol] size the size specific filename.
+    # @raise [UnknownSize] if the size is not found in 
+    #                      Imagery::Model#sizes.
+    # @return [String] the absolute path of the size specific filename e.g.
+    #                  /u/apps/reddit/current/public/system/photo/1/thumb.png
+    #                  where photo is the namespace and 1 is the key.
+    def file(size = self.default_size)
       raise UnknownSize, "#{ size } is not defined" unless sizes.has_key?(size)
 
       root_path(directory, namespace, key, filename(size))
     end
 
-    def tmp
-      root_path(directory, namespace, key, 'tmp')
-    end
-
-    def url(size = :original)
+    # Gives the absolute URI path for use in a web context.
+    #
+    #   Photo = Class.new(Struct.new(:id))
+    #   i = Imagery.new(Photo.new(1001))
+    #   i.url(:original) == '/system/photo/1001/original.png
+    #   # => true
+    #
+    #   i.file(:thumb)
+    #   # raise Imagery::Model::UnknownSize
+    #
+    #   i.sizes = { :thumb => ["100x100"] }
+    #   i.file(:thumb) == '/system/photo/1001/thumb.png
+    #   # => true
+    #
+    # @param [Symbol] size the size specific url.
+    # @raise [UnknownSize] if the size is not found in 
+    #                      Imagery::Model#sizes.
+    # @return [String] the absolute URI path of the size specific url e.g.
+    #                  /system/photo/1/thumb.png
+    #                  where photo is the namespace and 1 is the key.
+    def url(size = self.default_size)
       file(size).split('public').last
     end
     
+    # This module is basically here so that plugins like Imagery::S3
+    # can override #save and #delete and call super.
     module Persistence
+      # Writes the data in `io` and resizes them according to the different
+      # geometry strings.
+      #
+      # @example
+      #
+      #   Photo = Class.new(Struct.new(:id))
+      #   i = Imagery.new(Photo.new(1001))
+      #   i.root = '/tmp'
+      #   i.size = { :thumb => ["48x48"] }
+      #   i.save(File.open('/path/to/file.jpg'))
+      #
+      #   File.exist?("/tmp/public/system/photo/1001/thumb.png")
+      #   # => true
+      #
+      #   File.exist?("/tmp/public/system/photo/1001/original.png")
+      #   # => true
+      #
+      # @param [#read] io any object responding to read. Typically
+      #                a Rack filehandle is passed here from a 
+      #                controller in rails or a Sinatra handler.
+      #                You may also use File.open to provide a proper
+      #                IO handle.
+      # @return [true] returns when all other file operations are done.
       def save(io)
         FileUtils.mkdir_p(File.dirname(tmp))
         File.open(tmp, "wb") { |target| target.write(io.read) }
@@ -44,7 +149,9 @@ module Imagery
         
         return true
       end
-
+      
+      # Deletes all of the files related to this Imagery::Model instance.
+      # @return [true] when successfully deleted.
       def delete
         FileUtils.rm_rf File.dirname(file)
         return true
@@ -53,6 +160,14 @@ module Imagery
     include Persistence
 
   private
+    def tmp
+      root_path(directory, namespace, key, 'tmp')
+    end
+
+    def namespace_for(klass)
+      klass.name.split('::').last.downcase
+    end
+
     def filename(size)
       "%s.png" % size
     end

data/lib/imagery/s3.rb

@@ -9,8 +9,45 @@ module Imagery
     end
     
     S3_HOST = "http://s3.amazonaws.com"
-
-    def url(size = :original)
+  
+    # Returns a url publicly accessible. If a distribution domain is set,
+    # then the url will be based on that.
+    #
+    # @example
+    #   
+    #   class Imagery::Model
+    #     include Imagery::S3
+    #
+    #     self.s3_bucket = 'bucket-name'
+    #   end
+    #   
+    #   Photo = Class.new(Struct.new(:id))
+    #   i = Imagery.new(Photo.new(1001))
+    #
+    #   i.url == 'http://s3.amazonaws.com/bucket-name/photo/1001/original.png'
+    #   # => true
+    #
+    #   Imagery::Model.s3_distribution_domain = 'assets.site.com'
+    #   i.url == 'http://assets.site.com/photo/1001/original.png'
+    #   # => true
+    #
+    #   # You may also subclass this of course since it's just a ruby object
+    #   # and configure them differently as needed.
+    #
+    #   class CloudFront < Imagery::Model
+    #     include Imagery::S3
+    #     self.s3_bucket = 'cloudfront'
+    #     self.s3_distribution_domain = 'assets.site.com'
+    #   end
+    #
+    #   class RegularS3 < Imagery::Model
+    #     include Imagery::S3
+    #     self.s3_bucket = 'cloudfront'
+    #   end
+    #
+    # @param [Symbol] size the preferred size you want for the url.
+    # @return [String] the size specific url.
+    def url(size = self.default_size)
       if domain = self.class.s3_distribution_domain
         [domain, namespace, key, filename(size)].join('/')
       else
@@ -18,6 +55,8 @@ module Imagery
       end
     end
 
+    # In addition to saving the files and resizing them locally, uploads all
+    # the different sizes to amazon S3.
     def save(io)
       if super
         s3_object_keys.each do |key, size|
@@ -31,6 +70,8 @@ module Imagery
       end
     end
 
+    # Deletes all the files related to this Imagery instance and also
+    # all the S3 keys.
     def delete
       super
       s3_object_keys.each do |key, size|
@@ -46,11 +87,36 @@ module Imagery
     end
 
     module Gateway
+      # A wrapper for AWS::S3::S3Object.store. Basically auto-connects
+      # using the environment vars.
+      #
+      # @example
+      #   
+      #   AWS::S3::Base.connected?
+      #   # => false
+      #
+      #   Imagery::S3::Gateway.store(
+      #     'avatar', File.open('avatar.jpg'), 'bucket'
+      #   )
+      #   AWS::S3::Base.connected?
+      #   # => true
+      #       
       def store(*args)
         execute(:store, *args)
       end
       module_function :store
       
+      # A wrapper for AWS::S3::S3Object.delete. Basically auto-connects
+      # using the environment vars.
+      #
+      # @example
+      #   
+      #   AWS::S3::Base.connected?
+      #   # => false
+      #
+      #   Imagery::S3::Gateway.delete('avatar', 'bucket')
+      #   AWS::S3::Base.connected?
+      #   # => true
       def delete(*args)
         execute(:delete, *args)
       end

data/lib/imagery/test.rb

@@ -0,0 +1,17 @@
+module Imagery
+  module Test
+    def self.included(base)
+      Imagery::Model.send :include, Imagery::Faking
+      Imagery::Model.mode = :fake
+    end
+
+  protected
+    def imagery
+      if ENV["REAL_IMAGERY"]
+        Imagery::Model.real { yield true }
+      else
+        Imagery::Model.faked { yield false }
+      end
+    end
+  end
+end

data/test/test_imagery.rb

@@ -19,14 +19,14 @@ class TestImagery < Test::Unit::TestCase
   test "root_path when no ROOT_DIR" do
     imagery = Imagery.new(Photo.new(1001))
     imagery.root = '/'
-    assert_equal "/public/system/photo/1001/tmp", imagery.tmp
+    assert_equal "/public/system/photo/1001/tmp", imagery.send(:tmp)
   end
 
   test "root_path when ROOT_DIR defined on imagery" do
     Imagery::ROOT_DIR = '/root/dir'
 
     imagery = Imagery.new(Photo.new(1001))
-    assert_equal "/root/dir/public/system/photo/1001/tmp", imagery.tmp
+    assert_equal "/root/dir/public/system/photo/1001/tmp", imagery.send(:tmp)
 
     Imagery.send :remove_const, :ROOT_DIR
   end
@@ -35,7 +35,7 @@ class TestImagery < Test::Unit::TestCase
     Object::ROOT_DIR = '/root/dir'
 
     imagery = Imagery.new(Photo.new(1001))
-    assert_equal "/root/dir/public/system/photo/1001/tmp", imagery.tmp
+    assert_equal "/root/dir/public/system/photo/1001/tmp", imagery.send(:tmp)
 
     Object.send :remove_const, :ROOT_DIR
   end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Cyril David
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-28 00:00:00 +08:00
+date: 2010-05-31 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -73,18 +73,20 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.markdown
 files: 
 - .document
 - .gitignore
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - VERSION
+- imagery.gemspec
 - lib/imagery.rb
 - lib/imagery/faking.rb
 - lib/imagery/model.rb
 - lib/imagery/s3.rb
+- lib/imagery/test.rb
 - test/fixtures/lake.jpg
 - test/helper.rb
 - test/test_imagery.rb

data/README.rdoc

@@ -1,17 +0,0 @@
-= imagery
-
-Description goes here.
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2010 Cyril David. See LICENSE for details.