cannikin-encosion 0.2.2 → 0.3.0

data/.gitignore

@@ -1,3 +1,3 @@
-tokens.txt
 .DS_Store
 test/random.rb
+pkg

data/README.rdoc

@@ -8,6 +8,17 @@ To get the gem:
   
 = Usage
 
+First thing is first. Tell Encosion what your read and write API tokens are:
+
+  require 'rubygems'
+  require 'encosion'
+  
+  Encosion.options[:read_token] = '123abc'
+  Encosion.options[:write_token] = 'abc123'
+  
+You don't have to set these ahead of time, you can pass in the token with each request
+if you want, but do it here and you won't have to worry about it any more.
+
 Encosion has several class methods that are similar to those found in ActiveRecord
 for finding records. You'll pass a hash of options which correspond to those expected
 by Brightcove (see http://docs.brightcove.com/en/media/). All calls will require you
@@ -16,25 +27,27 @@ read or write methods.
 
 == Read Methods
 
-  require 'rubygems'
-  require 'encosion'
-  
   # find all videos, 25 at a time, and return the first page
-  videos = Encosion::Video.find(:all, :token => '123abc', :page_size => 25, :page_number => 1)
+  videos = Encosion::Video.find(:all, :page_size => 25, :page_number => 1)
   
   # find a single video by Brightcove video id
-  video = Encosion::Video.find(12345, :token => '123abc')
+  video = Encosion::Video.find(12345)
   
   # find several videos by their Brightcove video ids
-  videos = Encosion::Video.find(12345, 67890, 24680, :token => '123abc')
+  videos = Encosion::Video.find(12345, 67890, 24680)
   
   # find videos by your own reference id
-  video = Encosion::Video.find_by_reference_id('our_internal_id', :token => '123abc')
+  video = Encosion::Video.find_by_reference_id('our_internal_id')
   
-  # check the status of a video (technically this uses the write API so you need to provide your write token)
-  status = Encosion::Video.status(12345, :token => '123abc') # finds by Brightcove video_id
-  status = Encosion::Video.status('our_internal_id', :token => '123abc') # finds by reference_id (string instead of integer)
+  # check the status of a video (technically this uses the write API so it requires your write token)
+  status = Encosion::Video.status(12345) # finds by Brightcove video_id
+  status = Encosion::Video.status('our_internal_id') # finds by reference_id (string instead of integer)
   
+These examples all assume that you've set your :read_token (and :write_token, in the case of
+Video.status) ahead of time. If not you can simply include the token in your call:
+
+  videos = Encosion::Video.find(:all, :page_size => 25, :page_number => 1, :token => '123abc')
+
 See Encosion::Video for all the available find methods and their variants.
 
 == Write Methods
@@ -42,13 +55,15 @@ See Encosion::Video for all the available find methods and their variants.
 To write a video to Brightcove you will instantiate Encosion::Video, set a few required fields
 and then save it:
 
-  require 'rubygems'
-  require 'encosion'
-  
   new_video = Encosion::Video.new(:file => File.new('/path/to/file'), :name => "My Awesome Video", :short_description => "A video of some awesome happenings", :tags => ['awesome','sweet'])
-  brightcove_id = new_video.save(:token => '123abc')
+  brightcove_id = new_video.save
   
 The save() method returns Brightcove's ID for the video (assuming the save was successful).
+
+Again, the above examples assume that you've pre-set your :write_token. If not, just include it
+in the save() call:
+
+  brightcove_id = new_video.save(:token => 'abc123')
   
 Brightcove requires a name and short description before it will let you save a video. The fields 
 that you can set are those that Brightcove considers writable:
@@ -62,10 +77,9 @@ that you can set are those that Brightcove considers writable:
 * reference_id (string)
 * economics (enumerable, either :free or :ad_supported)
 
-And of course the video file itself.
+And of course the video file itself. Just give :file a File object.
 
 = To Do
 
 * Implement the remaining Video write methods: update_video, delete_video, share_video, add_image
 * Implement the Playlist API read/write methods
-* Create a persistent config store so you can set the tokens once instead of on each method call

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.3.0

data/encosion.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{encosion}
-  s.version = "0.2.2"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Rob Cameron"]
-  s.date = %q{2009-08-03}
+  s.date = %q{2009-08-04}
   s.email = %q{cannikinn@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",

data/lib/encosion.rb

@@ -17,38 +17,26 @@ require 'encosion/exceptions'
 
 module Encosion
   
-  VERSION = '0.1.3'
+  VERSION = '0.3.0'
   LOGGER = Logger.new(STDOUT)
   
-  def self.new(*args)
-    Engine.new(*args)
-  end
+  SERVER = 'api.brightcove.com'
+  PORT = 80
+  SECURE = false
+  READ_PATH = '/services/library'
+  WRITE_PATH = '/services/post'
+  DEFAULT_OPTIONS = { :debug => false }
   
-  class Engine
-    
-    SERVER = 'api.brightcove.com'
-    PORT = 80
-    PATH = '/services/library'
-    SECURE = false
-    DEFAULT_ARGS = { :read_token => nil, :write_token => nil }
-    DEFAULT_OPTIONS = { :debug => false }
-    
-    attr_reader :read_token, :write_token
-    
-    def initialize(options={})
-      @options = DEFAULT_OPTIONS.merge(options)
-      @options[:read_token] = @options[:token] if @options[:token]  # if there's only one token, assume it's a read
-      @read_token = @options[:read_token]
-      @write_token = @options[:write_token]
-      if @read_token.nil? && @write_token.nil?
-        raise EncosionError::TokenMissing, 'You must provide either a read or write token to use the Brightcove API'
-      end
-      
-      #@http = Net::HTTP.new(SERVER, PORT)
-      #@http.use_ssl = SECURE
-      #@http.set_debug_output $stdout if @options[:debug]
-    end
-    
-  end
+  @options = {  :read_token => nil, 
+                :write_token => nil, 
+                :server => SERVER, 
+                :port => PORT, 
+                :secure => SECURE, 
+                :read_path => READ_PATH, 
+                :write_path => WRITE_PATH }
+  attr_accessor :options
+  
+  # make @options available so it can be set externally when using the library
+  extend self
   
 end

data/lib/encosion/base.rb

@@ -44,14 +44,16 @@ module Encosion
         else        find_from_ids(args,options)
         end
       end
+      
         
       # This is an alias for find(:all)
       def all(*args)
         find(:all, *args)
       end
+      
 
       # Performs an HTTP GET
-      def get(server,port,path,secure,command,options)
+      def get(server,port,secure,path,command,options)
         http = HTTPClient.new
         url = secure ? 'https://' : 'http://'
         url += "#{server}:#{port}#{path}"
@@ -71,14 +73,15 @@ module Encosion
         return body
       end
       
+      
       # Performs an HTTP POST
-      def post(server,port,path,secure,command,options,instance)
+      def post(server,port,secure,path,command,options,instance)
         http = HTTPClient.new
         url = secure ? 'https://' : 'http://'
         url += "#{server}:#{port}#{path}"
-
+        
         content = { 'json' => { 'method' => command, 'params' => options }.to_json }    # package up the variables as a JSON-RPC string
-        content.merge!({ 'file' => instance.file }) if instance.respond_to?('file')                    # and add a file if there is one
+        content.merge!({ 'file' => instance.file }) if instance.respond_to?('file')             # and add a file if there is one
 
         response = http.post(url, content)
         # get the header and body for error checking
@@ -90,6 +93,7 @@ module Encosion
         return body
       end
       
+      
       # Checks the HTTP response and handles any errors
       def error_check(header,body)
         if header.status_code == 200

data/lib/encosion/video.rb

@@ -1,12 +1,10 @@
 module Encosion
   
+  # Raised if you try to set an invalid economics value
+  class InvalidEconomicsValue < StandardError; end;
+  
   class Video < Base
     
-    SERVER = 'api.brightcove.com'
-    PORT = 80
-    SECURE = false
-    READ_PATH = '/services/library'
-    WRITE_PATH = '/services/post'
     ENUMS = { :economics => { :free => 'FREE', :ad_supported => 'AD_SUPPORTED'}}
     
     attr_accessor(:name, 
@@ -37,8 +35,8 @@ module Encosion
       
       # Find a video by reference_id. Invokes Brightcove Media API command 'find_video_by_reference_id' or
       # 'find_videos_by_reference_ids' depending on whether you call one or multiple ids
-      #   Encosion::Video.find_by_reference_id('mycompany_1',:token => 'asdf')
-      #   Encosion::Video.find_by_reference_id('mycompany_1','mycompany_2','mycompany_3',:token => 'asdf')
+      #   Encosion::Video.find_by_reference_id('mycompany_1')
+      #   Encosion::Video.find_by_reference_id('mycompany_1','mycompany_2','mycompany_3')
       
       def find_by_reference_id(*args)
         options = extract_options(args)
@@ -49,24 +47,24 @@ module Encosion
             raise AssetNotFound, "Couldn't find #{self.class} without a reference ID"
           when 1
             options.merge!({:reference_id => ids.first})
-            response = get(SERVER,PORT,READ_PATH,SECURE,'find_video_by_reference_id',options)
+            response = read('find_video_by_reference_id',options)
             return self.parse(response)
           else
             options.merge!({:reference_ids => ids.join(',')})
-            response = get(SERVER,PORT,READ_PATH,SECURE,'find_videos_by_reference_ids',options)
+            response = read('find_videos_by_reference_ids',options)
             return response['items'].collect { |item| self.parse(item) }
           end
       end
       
       # Find a video by text search. Invokes Brightcove Media API command 'find_videos_by_text'
-      #   Encosion::Video.find_by_text('funny videos',:token => 'asdf')
+      #   Encosion::Video.find_by_text('funny videos')
       
       def find_by_text(*args)
         options = extract_options(args)
         text = args.flatten.compact.uniq
         raise AssetNotFound, "Couldn't find #{self.class} without text" if text == ''
         options.merge!({:text => text.first})
-        if response = get(SERVER,PORT,READ_PATH,SECURE,'find_videos_by_text',options)
+        if response = read('find_videos_by_text',options)
           return response['items'].collect { |item| self.parse(item) }
         else
           nil
@@ -75,12 +73,12 @@ module Encosion
       
 
       # Find videos related to the given video_id. Invokes Brightcove Media API command 'find_related_videos'
-      #   Encosion::Video.find_related(123456,:token => 'asdf')
+      #   Encosion::Video.find_related(123456)
       
       def find_related(*args)
         options = extract_options(args)
         raise AssetNotFound, "Cannot find related #{self.class}s without a video_id or reference_id" if options[:video_id].nil? && options[:reference_id].nil?
-        if response = get(SERVER,PORT,READ_PATH,SECURE,'find_related_videos',options)
+        if response = read('find_related_videos',options)
           return response['items'].collect { |item| self.parse(item) }
         else
           return nil
@@ -89,7 +87,7 @@ module Encosion
       
       
       # Find a video by tag search. Invokes Brightcove Media API command 'find_videos_by_tags'
-      #   Encosion::Video.find_by_tags('bloopers','gagreel','funny',:token => 'asdf')
+      #   Encosion::Video.find_by_tags('bloopers','gagreel','funny')
       
       def find_by_tags(*args)
         options = extract_options(args)
@@ -100,7 +98,7 @@ module Encosion
             raise AssetNotFound, "Couldn't find #{self.class} without tags"
           else
             options.merge!({:and_tags => tags.join(',')})
-            if response = get(SERVER,PORT,READ_PATH,SECURE,'find_videos_by_tags',options)
+            if response = read('find_videos_by_tags',options)
               return response['items'].collect { |item| self.parse(item) }
             else
               return nil
@@ -124,18 +122,45 @@ module Encosion
           options.merge!({:video_id => id})
         end
         
-        if response = Video.post(SERVER,PORT,WRITE_PATH,SECURE,'get_upload_status',options,self)
+        if response = write('get_upload_status',options)
           return response['result'].downcase.to_sym
         else
           return nil
         end
       end
+      
+      
+      # the actual method that calls a get (user can use this directly if they want to call a method that's not included here)
+      def read(method,options)
+        # options.merge!(Encosion.options)
+        options.merge!({:token => Encosion.options[:read_token]}) unless options[:token]
+        get(  Encosion.options[:server],
+              Encosion.options[:port],
+              Encosion.options[:secure],
+              Encosion.options[:read_path],
+              method,
+              options)
+      end
+      
+      
+      # the actual method that calls a post (user can use this directly if they want to call a method that's not included here)
+      def write(method,options)
+        # options.merge!(Encosion.options)
+        options.merge!({:token => Encosion.options[:write_token]}) unless options[:token]
+        Video.post( Encosion.options[:server],
+                    Encosion.options[:port],
+                    Encosion.options[:secure],
+                    Encosion.options[:write_path],
+                    method,
+                    options,
+                    self)
+      end
 
       protected
         # Find some videos by ids
         def find_one(id, options)
           options.merge!({:video_id => id})
-          response = get(SERVER,PORT,READ_PATH,SECURE,'find_video_by_id',options)
+          response = read('find_video_by_id',options)
           return self.parse(response)
         end
       
@@ -143,17 +168,17 @@ module Encosion
         # Find mutliple videos by id
         def find_some(ids, options)
           options.merge!({:video_ids => ids.join(',')})
-          response = get(SERVER,PORT,READ_PATH,SECURE,'find_videos_by_ids',options)
+          response = read('find_videos_by_ids',options)
           return response['items'].collect { |item| self.parse(item) }
         end
       
       
         # Find all videos
         def find_all(options)
-          response = get(SERVER,PORT,READ_PATH,SECURE,'find_all_videos',options)
+          response = read('find_all_videos', options)
           return response['items'].collect { |item| self.parse(item) }
         end
-
+        
       
         # Creates a new Video object from a Ruby hash (used to create a video from a parsed API call)
         def parse(obj)
@@ -201,7 +226,7 @@ module Encosion
       @thumbnail_url = args[:thumbnail_url]
       @reference_id = args[:reference_id]
       @length = args[:length]
-      @economics = args[:economics]
+      @economics = self.economics = args[:economics]
       @plays_total = args[:plays_total]
       @plays_trailing_week = args[:plays_trailing_week]
       @file = args[:file]
@@ -216,7 +241,14 @@ module Encosion
       # check to make sure we have everything needed for a create_video call
       raise NoFile, "You need to attach a file to this video before you can upload it: Video.file = File.new('/path/to/file')" if @file.nil?
       options = args.merge({ 'video' => self.to_brightcove })   # take the parameters of this video and make them a valid video object for upload
-      response = Video.post(SERVER,PORT,WRITE_PATH,SECURE,'create_video',options,self)
+      options.merge!({:token => Encosion.options[:write_token]}) unless options[:token]
+      response = Video.post(Encosion.options[:server],
+                            Encosion.options[:port],
+                            Encosion.options[:secure],
+                            Encosion.options[:write_path],
+                            'create_video',
+                            options,
+                            self)
       return response['result']    # returns the Brightcove ID of the video that was just uploaded
     end
     
@@ -242,6 +274,7 @@ module Encosion
         :plays_trailing_week => @plays_trailing_week }.to_json
     end
     
+    
     # Outputs the video object into Brightcove's expected format
     def to_brightcove
       { 'name' => @name,
@@ -256,11 +289,13 @@ module Encosion
     
     
     # Makes sure that the economics set on this video is one of a predetermined list
-    def encosion=(sym)
-      if ENUMS[:economics].has_key?(sym)
-        raise EncosionError::InvalidEconomicsValue, "A video's economics value must be one of #{ENUMS[:economics].collect { |key,value| e.key }.join(',')}"
-      else
-        @economics = sym
+    def economics=(sym)
+      unless sym.nil?
+        unless ENUMS[:economics].has_key?(sym)
+          raise InvalidEconomicsValue, "A video's economics value must be one of #{ENUMS[:economics].collect { |key,value| key.inspect }.join(', ')}"
+        else
+          @economics = sym
+        end
       end
     end
     

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cannikin-encosion
 version: !ruby/object:Gem::Version 
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors: 
 - Rob Cameron
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-03 00:00:00 -07:00
+date: 2009-08-04 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency