manipulator 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 The New York Times Company
+
+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/README.rdoc

@@ -0,0 +1,46 @@
+= manipulator
+
+S3 is great for storing image files, but manipulating images after they've been saved to S3 (rotating, resizing, cropping, etc.) is a bit of a chore.  Usually it goes something like this:
+
+* download file from S3, save to local tmp file
+* run imagemagick over local tmp file
+* push modified image back to S3
+* remember to clean up tmp file
+
+After re-implementing this pattern a few times over (and filling up /tmp by forgetting the last step), we decided to roll this into a gem that makes S3 image manipulation as easy as:
+
+ m = Manipulator.new
+
+ m.manipulate('my-bucket','some/file.jpg') do |img|
+   img.rotate(90).resize_to_fit(75,75)
+ end
+
+The idea is to instantiate a Manipulator and then pass it a bucket name and key to manipulate.  Manipulator will download your image to a local tmp file, then yield an RMagick Image wrapping that file.  Call methods on the yielded image to make modifications; as soon as the block returns, the modified image is pushed back to S3 and the tmp file is removed.
+
+== Install
+
+Manipulator is released on gemcutter. If you haven't already set yourself up with that, here's how:
+
+ $ gem install gemcutter
+ $ gem tumble
+
+Then, to install Manipulator:
+
+ $ gem install manipulator
+
+You can also just declare the source:
+
+ $ gem install manipulator -s http://gemcutter.org
+
+== Dependencies
+
+* AWSCredentials (http://github.com/bkoski/aws_credentials)
+* AWS/S3 (http://gemcutter.org/gems/aws-s3)
+
+== Future
+
+* Allow images to be manipulated from other sources (FTP, HTTP, etc.)
+
+== Copyright
+
+Copyright (c) 2009 The New York Times Company. See LICENSE for details.

data/lib/manipulator.rb

@@ -0,0 +1,4 @@
+require 'aws_credentials'
+require 'aws/s3'
+require 'tmpdir'
+require File.join(File.dirname(__FILE__), 'manipulator', 'manipulator')

data/lib/manipulator/manipulator.rb

@@ -0,0 +1,66 @@
+# Tries to avoid case-sensitivity issues when requiring RMagick.
+# Borrowed from jnicklas' carrierwave.
+unless defined? Magick
+  begin
+    require 'rmagick'
+  rescue LoadError
+    require 'RMagick'
+  rescue LoadError
+    puts "WARNING: Failed to require rmagick, image processing may fail!"
+  end 
+end
+
+
+# Using Manipulator is as simple as creating an instance and calling manipulate.
+#
+# The connection to S3 is opened using credentials read from AWSCredentials.
+class Manipulator
+  
+  # Path to the local temp file used during manipulation
+  attr_accessor :temp_file_path
+
+  # Downloads the specified bucket, key from S3 to a local temp file
+  # and sets temp_file_path
+  def download(bucket, key)
+    AWS::S3::Base.establish_connection!(:access_key_id => AWSCredentials.access_key, :secret_access_key => AWSCredentials.secret_access_key)
+    @temp_file_path = File.join(Dir.tmpdir, key.gsub('/', '-'))
+    File.open(temp_file_path, 'w+') do |f|
+      f.puts AWS::S3::S3Object.value(key,bucket)
+    end
+  end
+  
+  # Pushes contents of temp file back to specified bucket, key on S3
+  def upload(bucket, key)
+    AWS::S3::S3Object.store(key, File.open(temp_file_path, 'r'), bucket, :access => :public_read)
+  end
+
+  # Specify a S3 key to manipulate (and its bucket).
+  #
+  # Block yields a Magick::Image image instance with access to the usual RMagick methods.
+  # Note that RMagick methods should be chained so that block returns image with all manipulations.
+  # For example, use
+  #  m.manipulate('my-bucket', 'my-key') do |img|
+  #    img.rotate(90).sepia_tone
+  #  end
+  # rather than
+  #  img.rotate(90)
+  #  img.sepia_tone
+  # This last case will only <tt>sepia_tone</tt> the image.
+  def manipulate(bucket, key, &block)
+    download(bucket, key)
+    begin
+      image = ::Magick::Image.read(temp_file_path).first
+      new_image = yield(image)
+      new_image.write(temp_file_path)
+      upload(bucket, key)
+    ensure
+      cleanup
+    end
+  end
+
+  # Removes the temp file
+  def cleanup
+    File.delete(temp_file_path)
+  end
+  
+end

data/test/helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'manipulator'
+
+class Test::Unit::TestCase
+end

data/test/test_manipulator.rb

@@ -0,0 +1,114 @@
+require 'helper'
+class TestManipulator < Test::Unit::TestCase
+
+  def setup
+    @key = File.join('data', 'ham.jpg')
+    @access_key = '1234'
+    AWSCredentials.stubs(:access_key).returns(@access_key)
+    @secret_key = '5678'
+    AWSCredentials.stubs(:secret_access_key).returns(@secret_key)
+    @bucket = 'foobar'
+    AWS::S3::Base.stubs(:establish_connection!)
+    @temp_file_path = '/tmp/whatever.jpg'
+    @new_file = stub('new file', :read => '123')
+    File.stubs(:open).returns(@new_file)
+  end
+
+  context "#download" do
+    setup do
+      @manipulator = Manipulator.new
+      AWS::S3::S3Object.stubs(:value).returns('123')
+    end
+    should "establish connection with credentials from aws_credentials" do
+      AWS::S3::Base.expects(:establish_connection!).with(:access_key_id => @access_key, :secret_access_key => @secret_key)
+      @manipulator.download(@bucket, @key)
+    end
+    should "set temp_file_path, replacing any /s with -s" do
+      @manipulator.download(@bucket, @key)
+      assert_equal File.join(Dir.tmpdir, @key.gsub('/', '-')), @manipulator.temp_file_path
+    end
+    should "write a local file with the correct name" do
+      local_file = mock('local_file')
+      local_file.expects(:puts).with('123')
+      File.expects(:open).yields(local_file)
+      @manipulator.download(@bucket, @key)
+    end
+  end
+
+  context "#manipulate" do
+    setup do
+      @manipulator = Manipulator.new
+      @file = stub_everything('fake file')
+      @manipulator.stubs(:download).returns(@key)
+      @manipulator.stubs(:upload)
+      @manipulator.stubs(:cleanup)
+      @manipulator.stubs(:temp_file_path).returns(@temp_file_path)
+      @mocked = mock('fake rmagick instance')
+      Magick::Image.stubs(:read).returns([@mocked])
+      @mocked.stubs(:write)
+    end
+
+    should "download the file" do
+      @manipulator.expects(:download).with(@bucket, @key).returns(@key)
+      @manipulator.manipulate(@bucket, @key) { |img| img }
+    end
+    should "create an RMagick Image instance and yield it to the block" do
+      Magick::Image.expects(:read).with(@temp_file_path).returns([@mocked])
+      @manipulator.manipulate(@bucket, @key) do |img|
+        assert_equal @mocked, img
+        img
+      end
+    end
+    should "write the returned manipulated image to the temp file" do
+      @mocked.expects(:write).with(@temp_file_path)
+      Magick::Image.stubs(:read).with(@temp_file_path).returns([@mocked])
+      @manipulator.manipulate(@bucket, @key) { |img| img }
+    end
+    should "upload the file back to s3" do
+      @manipulator.expects(:upload).with(@bucket, @key)
+      @manipulator.manipulate(@bucket, @key) { |img| img }
+    end
+    should "not run cleanup if download raises an error" do
+      @manipulator.stubs(:download).raises('foo')
+      @manipulator.expects(:cleanup).never
+      begin
+        @manipulator.manipulate(@bucket, @key) { |img| img }
+      rescue
+      end
+    end
+    should "ensure that it calls cleanup if download success" do
+      @manipulator.expects(:cleanup)
+      begin
+        @manipulator.manipulate(@bucket, @key) do |img|
+          raise "an error"
+        end
+      rescue
+      end
+    end
+  end
+
+  context "#upload" do
+    setup do
+      @manipulator = Manipulator.new
+      @manipulator.stubs(:temp_file_path).returns(@temp_file_path)
+    end
+    should "call S3Object.store with contents of tempfile" do
+      AWS::S3::S3Object.expects(:store).with(@key,@new_file,@bucket, :access => :public_read)
+      @manipulator.upload(@bucket, @key)
+    end
+  end
+
+
+  context "#cleanup" do
+    setup do
+      @manipulator = Manipulator.new
+      @key = File.join(File.dirname(__FILE__), 'data', 'ham.jpg')
+      @manipulator.stubs(:temp_file_path).returns(@temp_file_path)
+      Manipulator.any_instance.stubs(:download)
+    end
+    should "call delete on temp_file" do
+      File.expects(:delete).with(@temp_file_path)
+      @manipulator.cleanup
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: manipulator
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jacqui Maher
+- Ben Koski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-22 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: aws_credentials
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: aws-s3
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A library to allow photo manipulation on S3 images using RMagick
+email: jacqui@brighter.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- lib/manipulator.rb
+- lib/manipulator/manipulator.rb
+- test/helper.rb
+- test/test_manipulator.rb
+has_rdoc: true
+homepage: http://github.com/newsdev/manipulator
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: manipulate your photos on s3
+test_files: 
+- test/helper.rb
+- test/test_manipulator.rb