easy_s3 0.0.1 → 1.0.0

data/.gitignore

@@ -1,3 +1,5 @@
 pkg/*
 *.gem
 .bundle
+.rvmrc
+notes.txt

data/Gemfile

@@ -2,3 +2,7 @@ source :gemcutter
 
 # Specify your gem's dependencies in easy_s3.gemspec
 gemspec
+
+group :development, :test do
+  gem "rspec"
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    easy_s3 (0.0.1)
+      aws-s3
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    aws-s3 (0.6.2)
+      builder
+      mime-types
+      xml-simple
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    mime-types (1.16)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    xml-simple (1.0.12)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  easy_s3!
+  rspec

data/README.md

@@ -0,0 +1,67 @@
+Easier Than S3?
+===============
+The [Ruby S3 Gem](https://github.com/marcel/aws-s3) is already easy, what's this all about? Its true, the standard gem is great, but I usually use it the same way every time and only do a few things with it. Like, I almost always use the same bucket for everything an app does. And I never use more than one S3 account in one app. So, I was always writing the same few bits of code to support my use case and I decided to cut a gem to make this easier.
+
+Install
+-------
+Just use the `gem` command:
+
+    gem install easy_s3
+
+If you don't have `aws-s3`, rubygems will install it for you.
+
+Setup
+-----
+`EasyS3` must be instantiated before you can use it and there are a couple ways you can do this. The most straightforward way is to simply pass it three string parameters:
+
+    easy_s3 = EasyS3.new('bucket', 'key', 'secret')
+
+This will create a new instance of `EasyS3` that you can then use later (see Methods and Usage below).
+
+Another approach is to set ENV variables for the gem to use. If you set `ENV['EASY_S3_KEY']` and `ENV['EASY_S3_SECRET']`, then you can leave those parameters off, like this:
+
+    easy_s3 = EasyS3.new('bucket')
+
+But make sure you name your ENV variables as above so the gem can find them.
+
+I like the second approach best because it keeps sensitive things out of your repo. In development, I'll have a handful of apps using this gem and they all use the same S3 account, so setting these variables once in my .profile file works great. But when I do have a project that uses a different S3 account, then I'll use the first approach, but still use EVN variables, just ones that are specific to the app I'm working with, like this:
+
+    easy_s3 = EasyS3.new('bucket', ENV['MYAPP_EASY_S3_KEY'], ENV['MYAPP_EASY_S3_SECRET'])
+
+Whichever way you go about setting up your instance, the main thing you're setting is the bucket and that's my main assumption here: that you'll do all your work in one bucket. If that's not how you use S3, this gem ain't for you. If that is how you use S3, then I think you'll like convenience of not having to specify this over and over again. 
+
+Methods
+-------
+Once you've got your `EasyS3` instance, you can call five main methods on it:
+
+    easy_s3.write(path, data) => writes the data its given to the file at path
+    easy_s3.file(path) => gets the AWS::S3::S3Object found at path
+    easy_s3.exists?(path) => check if a file exists at path and returns a boolean
+    easy_s3.append(path, data) => appends data to the end of the file found at path (uses write)
+    easy_s3.read(path) => returns a string of the value of the file found at path (uses file)
+
+Remember: these are all being called in the context of your `EasyS3` instance, so the S3 account and bucket are coming from your setup above.
+
+Usage
+-----
+I wrote this to support five use cases.
+
+--Create a file and write some data to it:
+
+    easy_s3.write('path/to/file.txt', 'blah, blah, blah')
+
+--Append a message to a log file:
+
+    easy_s3.append('path/to/log/file.txt', 'ack, the program asploded!')
+
+--See if a file exists
+
+    puts 'our file is there!' if easy_s3.exists?('path/to/file.txt')
+
+--Get the value of a file
+
+    data = easy_s3.read('path/to/file.txt')
+
+--Get the actual `S3Object` (and then do something with it)
+
+    file = easy_s3.file('path/to/file.txt')

data/easy_s3.gemspec

@@ -7,9 +7,9 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Jon Allured"]
   s.email       = ["jon.allured@me.com"]
-  s.homepage    = "http://rubygems.org/gems/easy_s3"
-  s.summary     = "easy wrapper for working with S3"
-  s.description = "easy wrapper for working with S3"
+  s.homepage    = "https://github.com/jonallured/easy_s3"
+  s.summary     = "simple wrapper for working with S3"
+  s.description = "wraps the S3 Ruby Gem with some simple methods for those common tasks that should be easier"
 
   s.required_rubygems_version = ">= 1.3.6"
 

data/lib/easy_s3.rb

@@ -1,29 +1,37 @@
 require 'aws/s3'
 
-s3_key = ENV['EASY_S3_KEY']
-s3_secret = ENV['EASY_S3_SECRET']
-S3_BUCKET = ENV['EASY_S3_BUCKET']
-AWS::S3::Base.establish_connection!(:access_key_id => s3_key, :secret_access_key => s3_secret)
-
-module EasyS3
-  def self.write(path, data)
-    # creates a new file or overwrites an existing file with data
-    AWS::S3::S3Object.store(path, data, S3_BUCKET, :access => :public_read)
+class EasyS3
+  
+  attr_accessor :bucket
+  
+  def initialize(bucket, key = ENV['EASY_S3_KEY'], secret = ENV['EASY_S3_SECRET'])
+    @bucket = bucket
+    EasyS3.connect_to_s3(key, secret)
+  end
+  
+  def write(path, data)
+    AWS::S3::S3Object.store(path, data, @bucket, :access => :public_read)
+  end
+  
+  def file(path)
+    AWS::S3::S3Object.find(path, @bucket)
   end
-  def self.append(path, data)
-    # appends data to the value of the file
-    self.write(path, self.read(path) + data)
+  
+  def exists?(path)
+    AWS::S3::S3Object.exists?(path, @bucket)
   end
-  def self.read(path)
-    # retuns the actual value of the file, use EasyS3.get_file if you want the object
-    self.file(path).value
+  
+  def read(path)
+    file(path).value
   end
-  def self.file(path)
-    # retuns the actual file object, use .value to get the contents
-    AWS::S3::S3Object.find(path, S3_BUCKET)
+  
+  def append(path, data)
+    write(path, read(path) + data)
   end
-  def self.exists?(path)
-    # returns true or false depending on whether the file exists
-    AWS::S3::S3Object.exists?(path, S3_BUCKET)
+    
+  def self.connect_to_s3(key, secret)
+    raise StandardError, "Bad key or secret" unless key and secret
+    AWS::S3::Base.establish_connection!(:access_key_id => key, :secret_access_key => secret)
   end
+  
 end

data/lib/easy_s3/version.rb

@@ -1,3 +1,3 @@
 module EasyS3
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/spec/easy_s3_spec.rb

@@ -0,0 +1,114 @@
+require 'rubygems'
+require 'rspec'
+require "#{File.dirname __FILE__}/../lib/easy_s3"
+
+describe EasyS3 do
+  
+  before(:each) do
+    AWS::S3::Base.stub!(:establish_connection!)
+  end
+  
+  describe '#new' do  
+    
+    it 'should return the first argument as the bucket attribute' do
+      easy_s3 = EasyS3.new('bucket')
+      easy_s3.bucket.should == 'bucket'
+    end
+    
+    context 'if passed S3 credentials' do
+      it 'should send connect_to_s3 the key and secret' do
+        EasyS3.should_receive(:connect_to_s3).with('key', 'secret')
+        EasyS3.new('bucket', 'key', 'secret')
+      end
+    end
+    
+    context 'if easy_s3 ENV variables exist' do
+      before(:each) do
+        ENV['EASY_S3_KEY'] = 'env_key'
+        ENV['EASY_S3_SECRET'] = 'env_secret'
+      end
+      
+      after(:each) do
+        ENV['EASY_S3_KEY'] = nil
+        ENV['EASY_S3_SECRET'] = nil
+      end
+      
+      it "should send connect_to_s3 ENV['EASY_S3_KEY'] and ENV['EASY_S3_SECRET']" do
+        EasyS3.should_receive(:connect_to_s3).with('env_key', 'env_secret')
+        EasyS3.new('bucket')
+      end
+    end
+    
+    context 'if config/easy_s3.yml exists' do
+      it 'should create an S3 connection using the credentials from the file'
+    end
+    
+  end
+  
+  describe '.connect_to_s3' do
+    
+    it 'should create a connection to s3 when passed a key and secret' do
+      AWS::S3::Base.should_receive(:establish_connection!).with(:access_key_id => 'key', :secret_access_key => 'secret')
+      EasyS3.connect_to_s3('key', 'secret')
+    end
+    
+    it 'should throw an error when either key or secret is nil' do
+      lambda do
+        EasyS3.connect_to_s3(nil, nil)
+      end.should raise_error(StandardError, "Bad key or secret")
+    end
+    
+  end
+  
+  describe 'instance methods' do
+    
+    before(:each) do
+      EasyS3.stub!(:connect_to_s3)
+      AWS::S3::S3Object.stub!(:exists?).and_return(true)
+      
+      @mock_s3_object = mock('S3Object')
+      @mock_s3_object.stub!(:value).and_return('some data')
+      AWS::S3::S3Object.stub!(:find).and_return(@mock_s3_object)
+    end
+    
+    describe '#write' do
+      it 'should send data to the path at S3' do
+        AWS::S3::S3Object.should_receive(:store).with('/path/to/file.txt', 'some message', 'bucket', :access => :public_read)
+        easy_s3 = EasyS3.new('bucket')
+        easy_s3.write('/path/to/file.txt', 'some message')
+      end
+    end
+    
+    describe '#file' do
+      it 'should return an S3Object when a file is found' do
+        easy_s3 = EasyS3.new('bucket')
+        file = easy_s3.file('/path/to/file.txt')
+        file.should == @mock_s3_object
+      end
+    end
+    
+    describe '#read' do
+      it 'should return the value of the file found' do
+        easy_s3 = EasyS3.new('bucket')
+        data = easy_s3.read('/path/to/file.txt')
+        data.should == 'some data'
+      end
+    end
+    
+    describe '#append' do
+      it 'should add its data to the data of the file at path' do
+        AWS::S3::S3Object.should_receive(:store).with('/path/to/file.txt', 'some data some message', 'bucket', :access => :public_read)
+        easy_s3 = EasyS3.new('bucket')
+        easy_s3.append('/path/to/file.txt', ' some message')
+      end
+    end
+    
+    describe '#exists?' do
+      it 'should return true when the file is found' do
+        easy_s3 = EasyS3.new('bucket')
+        easy_s3.exists?('/path/to/file.txt').should be_true
+      end
+    end
+    
+  end
+end

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: easy_s3
 version: !ruby/object:Gem::Version 
-  hash: 29
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 1
-  version: 0.0.1
+  prerelease: 
+  version: 1.0.0
 platform: ruby
 authors: 
 - Jon Allured
@@ -15,8 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-03 00:00:00 -06:00
-default_executable: 
+date: 2011-04-29 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: aws-s3
@@ -26,13 +20,10 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
   type: :runtime
   version_requirements: *id001
-description: easy wrapper for working with S3
+description: wraps the S3 Ruby Gem with some simple methods for those common tasks that should be easier
 email: 
 - jon.allured@me.com
 executables: []
@@ -44,12 +35,14 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- Gemfile.lock
+- README.md
 - Rakefile
 - easy_s3.gemspec
 - lib/easy_s3.rb
 - lib/easy_s3/version.rb
-has_rdoc: true
-homepage: http://rubygems.org/gems/easy_s3
+- spec/easy_s3_spec.rb
+homepage: https://github.com/jonallured/easy_s3
 licenses: []
 
 post_install_message: 
@@ -62,27 +55,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 23
-      segments: 
-      - 1
-      - 3
-      - 6
       version: 1.3.6
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
-summary: easy wrapper for working with S3
+summary: simple wrapper for working with S3
 test_files: []