tiny_png 0.1.1 → 0.2.0

data/README.md

@@ -18,8 +18,15 @@ this API was introduced, TinyPNG could only be used from their [web interface](h
 And while their homepage is cool and all, manually uploading and saving files is a less-than-enjoyable
 process.  The kind of process a computer was made to do for you.  Ergo this gem.
 
+**TinyPNG's API service is currently in private beta.  You will need to request an API key to use this gem.**
+[See here](https://twitter.com/tinypng/status/256049113852944384) for details.
+
 This gem interacts with TinyPNG's API to replace a given PNG with its shrunken counterpart.
 
+When you pass a full path into the `shrink` method, it will replace the source image with the image
+returned by TinyPNG.  If this process fails for whatever reason, the original image will be restored.
+On success, the original image is completely overwritten and is no longer available.
+
 ## Installation
 
 If you're using bundler, just add the following to your Gemfile:
@@ -30,28 +37,50 @@ gem 'tiny_png'
 
 ## Usage
 
-Create an instance of the `TinyPng::Shrink` class, passing in your API key:
+Create an instance of the `TinyPng::Client` class, passing in your API key:
 
 ```ruby
-@tiny = TinyPng::Shrink.new API_KEY
+@client = TinyPng::Client.new API_KEY
 ```
 
 If you want to work with a list of images, and want to silently suppress exceptions, just pass that in the options field:
 
 ```ruby
-@tiny = TinyPng::Shrink.new API_KEY, { :suppress_exceptions => true }
+@client = TinyPng::Client.new API_KEY, { :suppress_exceptions => true }
 ```
 
-Next, pass in the full path to the image you want to shrink
+Next, pass in the full paths to the images you want to shrink (you can also pass in whole directories)
+
+```ruby
+@client.shrink '/FULL/PATH/TO/IMAGE.png'
+```
 
 ```ruby
-@tiny.shrink '/FULL/PATH/TO/IMAGE.png'
+@client.shrink '/FULL/PATH/TO/image.png', '/FULL/PATH/TO/ANOTHER/image.png', '/DIRECTORY/WITH/LOTS/OF/IMAGES'
 ```
 
-The shrunken image will be saved in the same path, effectively overwriting the old file.
+The `shrink` method will return a hash of arrays letting you know which paths were successfully overwritten and which
+ones failed:
+
+```
+{
+	:success => [
+		'/THIS/ONE/WAS/overwritten.png',
+		'/THIS/ONE/WAS/ALSO/overwritten.png'
+	], 
+	:failure => [
+		'/THIS/FAILED/AND/WAS/reverted.png',
+		'/THIS/ISNT/A/png.gif'
+	]
+}
+```
+
+Each successfully shrunken image will overwrite the original file.
 
 **NOTE:**
 
+For each image path analyzed (whether sent in directly or picked out of a folder):
+
 - There must be a file already at the specified path
 - That file must be readable and writeable
 - The file name *must* end in `.png`

data/lib/tiny_png.rb

@@ -1,4 +1,4 @@
 module TinyPng
 end
 
-require File.join File.dirname(__FILE__), 'tiny_png', 'tiny_png'
+require File.join File.dirname(__FILE__), 'tiny_png', 'client'

data/lib/tiny_png/client.rb

@@ -0,0 +1,32 @@
+require 'base64'
+require 'httparty'
+require File.join File.dirname(__FILE__), 'exceptions'
+require File.join File.dirname(__FILE__), 'shrink'
+require File.join File.dirname(__FILE__), 'exception_handling'
+
+module TinyPng
+  class Client
+    include TinyPng::ExceptionHandling
+    include TinyPng::Shrink
+    
+    include HTTParty
+    base_uri 'api.tinypng.org'
+    
+    #
+    # Create a new instance of the TinyPng::Shrink class
+    #
+    # Arguments:
+    # - api_key (String)
+    # - options (Hash)
+    #   - :suppress_exceptions (Boolean)
+    #     Default: false
+    #     If false (the default), exceptions will be raised when the process fails.  If suppression is turned on, exceptions will not be raised, but a false value will be returned if shrinking fails for any reason.
+    #
+    # Returns: TinyPng::Client instance
+    #
+    def initialize api_key, options={}
+      @options = { :suppress_exceptions => false }.merge options
+      @auth = { :username => 'api', :password => api_key }
+    end
+  end
+end

data/lib/tiny_png/shrink.rb

@@ -0,0 +1,66 @@
+module TinyPng::Shrink
+  #
+  # Replace an image at a given path with its shrunken version
+  #
+  # The image at the given path will be submitted to TinyPNG and the new version will overwrite the original.  If this process fails for any reason, the original file will be rolled back.
+  #
+  # Arguments:
+  # - shrinkwrap (any number of objects to be shrunk)
+  #   You can pass in a directory, or individual files that should be shrunk.  All should be absolute paths.
+  #
+  #   If you send in a path to a specific file, it must end in `.png` or it will not be sent to TinyPNG for processing.
+  #
+  #   Likewise, when traversing through a directory, only files that end in `.png` will be processed.
+  #
+  #   All paths to specific files (whether sent in directly or picked out from the directory) need to be readable and writeable.
+  #
+  # Returns: Hash { :success => [Array, Of, Paths, Successfully, Overwrittern], :failure => [Array, Of, Paths, Left, Unchanged] }
+  #
+  
+  def shrink *shrinkwrap
+    results = { :success => [], :failure => [] }
+    [shrinkwrap].flatten.each do |shrinkable|
+      if File.directory? shrinkable
+        Dir.glob("#{shrinkable.gsub(/\/$/,'')}/**/*.png") do |image_path|
+          key = self.shrink_in_place(image_path) ? :success : :failure
+          results[key].push image_path
+        end
+      else
+        key = shrink_in_place(shrinkable) ? :success : :failure
+        results[key].push shrinkable
+      end
+    end
+    results
+  end
+  
+  protected
+  
+  def shrink_in_place image_path
+    # check to make sure everything looks kosher before sending data to TinyPNG
+    return raise_exception InvalidFileType, 'The file must be a PNG' unless image_path.downcase.match(/\.png$/)
+    return raise_exception FileDoesntExist, "Can't find a file at the specified path" unless File.exists? image_path
+    return raise_exception FileNotReadable, "Can't read the requested file" unless File.readable? image_path
+    return raise_exception FileNotWriteable, "Can't write to the specifed file" unless File.writable? image_path
+    
+    # store current content in case we need to rollback later
+    current_content = File.read image_path
+    
+    # passes our quick checks, so let's fire off the request
+    response = self.class.post('/api/shrink', :basic_auth => @auth, :body => current_content.force_encoding('BINARY'))
+    
+    # abort unless TinyPNG successfully did its thing
+    return raise_exception ShrinkingFailed, response.message unless response.code == 200
+    
+    # only overwrite if the new file is smaller than the old
+    if response['output']['ratio'] < 1
+      begin
+        open(image_path, 'wb') { |f| f.write HTTParty.get(response['output']['url']).parsed_response }
+      rescue # if the writing process fails for whatever reason, rollback and raise custom error
+        open(image_path, 'wb') { |f| f.write current_content }
+        return raise_exception ShrinkingFailed, "Couldn't write new content"
+      end
+    end
+    
+    true
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tiny_png
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-10 00:00:00.000000000 Z
+date: 2012-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &2152385040 !ruby/object:Gem::Requirement
+  requirement: &2152072180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,21 +21,23 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152385040
+  version_requirements: *2152072180
 description: Use the TinyPNG service to minimize the size of your image files.
 email: chris@thesturgills.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/tiny_png/client.rb
 - lib/tiny_png/exception_handling.rb
 - lib/tiny_png/exceptions.rb
-- lib/tiny_png/tiny_png.rb
+- lib/tiny_png/shrink.rb
 - lib/tiny_png.rb
 - LICENSE
 - README.md
-homepage: http://chris.thesturgills.com
-licenses: []
+homepage: https://github.com/sturgill/tiny_png
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:

data/lib/tiny_png/tiny_png.rb

@@ -1,74 +0,0 @@
-require 'base64'
-require 'httparty'
-require File.join File.dirname(__FILE__), 'exceptions'
-require File.join File.dirname(__FILE__), 'exception_handling'
-
-module TinyPng
-  class Shrink
-    include TinyPng::ExceptionHandling
-    
-    include HTTParty
-    base_uri 'api.tinypng.org'
-    
-    #
-    # Create a new instance of the TinyPng::Shrink class
-    #
-    # Arguments:
-    # - api_key (String)
-    # - options (Hash)
-    #   - :suppress_exceptions (Boolean)
-    #     Default: false
-    #     If false (the default), exceptions will be raised when the process fails.  If suppression is turned on, exceptions will not be raised, but a false value will be returned if shrinking fails for any reason.
-    #
-    # Returns: TinyPng::Shrink instance
-    #
-    def initialize api_key, options={}
-      @options = { :suppress_exceptions => false }.merge options
-      @auth = { :username => 'api', :password => api_key }
-    end
-    
-    #
-    # Replace an image at a given path with its shrunken version
-    #
-    # The image at the given path will be submitted to TinyPNG and the new version will overwrite the original.  If this process fails for any reason, the original file will be rolled back.
-    #
-    # Arguments:
-    # - image_path (String)
-    #   The full path to the image that should be shrunk. Requirements:
-    #   - Must be the full and absolute path (not a relative path)
-    #   - Path must end in `.png`
-    #   - Path must be readable
-    #   - Path must be writeable
-    #
-    # Returns: Boolean (whether or not the action was successful)
-    #
-    def shrink image_path
-      # check to make sure everything looks kosher before sending data to TinyPNG
-      return raise_exception InvalidFileType, 'The file must be a PNG' unless image_path.downcase.match(/\.png$/)
-      return raise_exception FileDoesntExist, "Can't find a file at the specified path" unless File.exists? image_path
-      return raise_exception FileNotReadable, "Can't read the requested file" unless File.readable? image_path
-      return raise_exception FileNotWriteable, "Can't write to the specifed file" unless File.writable? image_path
-      
-      # store current content in case we need to rollback later
-      current_content = File.read image_path
-      
-      # passes our quick checks, so let's fire off the request
-      response = self.class.post('/api/shrink', :basic_auth => @auth, :body => current_content.force_encoding('BINARY'))
-      
-      # abort unless TinyPNG successfully did its thing
-      return raise_exception ShrinkingFailed, response.message unless response.code == 200
-      
-      # only overwrite if the new file is smaller than the old
-      if response['output']['ratio'] < 1
-        begin
-          open(image_path, 'wb') { |f| f.write HTTParty.get(response['output']['url']).parsed_response }
-        rescue # if the writing process fails for whatever reason, rollback and raise custom error
-          open(image_path, 'wb') { |f| f.write current_content }
-          return raise_exception ShrinkingFailed, "Couldn't write new content"
-        end
-      end
-      
-      true
-    end
-  end
-end