datasift 3.1.5 → 3.2.0

data/lib/datasift.rb

@@ -16,8 +16,11 @@ require dir + '/managed_source'
 require dir + '/managed_source_auth'
 require dir + '/managed_source_resource'
 require dir + '/live_stream'
-require dir + '/dynamic_list'
-require dir + '/dynamic_list_replace'
+require dir + '/pylon'
+require dir + '/account'
+require dir + '/account_identity'
+require dir + '/account_identity_token'
+require dir + '/account_identity_limit'
 #
 require 'rbconfig'
 
@@ -39,13 +42,13 @@ module DataSift
     end
   end
 
+  # All API requests must be made by a Client object
   class Client < ApiResource
-    #+config+:: A hash containing configuration options for the client for e.g.
-    # {username => 'some_user', api_key => 'ds_api_key', 'enable_ssl' => true, open_timeout => 30, timeout => 30}
+    # @param config [Hash] A hash containing configuration options for the
+    #   client for e.g. { username: 'some_user', api_key: 'ds_api_key',
+    #   enable_ssl: true, open_timeout: 30, timeout: 30 }
     def initialize(config)
-      if config.nil?
-        raise InvalidConfigError.new('Config cannot be nil')
-      end
+      raise InvalidConfigError.new('Config cannot be nil') if config.nil?
       if !config.key?(:username) || !config.key?(:api_key)
         raise InvalidConfigError.new('A valid username and API key are required. ' +
           'You can check your API credentials at https://datasift.com/settings')
@@ -58,71 +61,97 @@ module DataSift
       @managed_source_resource  = DataSift::ManagedSourceResource.new(config)
       @managed_source_auth      = DataSift::ManagedSourceAuth.new(config)
       @historics_preview        = DataSift::HistoricsPreview.new(config)
-      @dynamic_list             = DataSift::DynamicList.new(config)
-      @dynamic_list_replace     = DataSift::DynamicListReplace.new(config)
+      @pylon                    = DataSift::Pylon.new(config)
+      @account                  = DataSift::Account.new(config)
+      @account_identity         = DataSift::AccountIdentity.new(config)
+      @account_identity_token   = DataSift::AccountIdentityToken.new(config)
+      @account_identity_limit   = DataSift::AccountIdentityLimit.new(config)
     end
 
     attr_reader :historics, :push, :managed_source, :managed_source_resource,
-      :managed_source_auth, :historics_preview, :dynamic_list,
-      :dynamic_list_replace
+      :managed_source_auth, :historics_preview, :pylon, :account,
+      :account_identity, :account_identity_token, :account_identity_limit
 
-    ##
     # Checks if the syntax of the given CSDL is valid
-    #+boolResponse+ If true then a boolean is returned indicating whether the
-    #   CSDL is valid, otherwise the response object itself is returned
+    #
+    # @param boolResponse [Boolean] If true a boolean is returned indicating
+    # whether the CSDL is valid, otherwise the full response object is returned
     def valid?(csdl, boolResponse = true)
       requires({ :csdl => csdl })
       res = DataSift.request(:POST, 'validate', @config, :csdl => csdl )
       boolResponse ? res[:http][:status] == 200 : res
     end
 
-    ##
     # Compile CSDL code.
-    #+csdl+:: The CSDL you wish to compile
+    #
+    # @param csdl [String] The CSDL you wish to compile
+    # @return [Object] API reponse object
     def compile(csdl)
       requires({ :csdl => csdl })
       DataSift.request(:POST, 'compile', @config, :csdl => csdl )
     end
 
-    ##
-    # Check the number of objects processed and delivered in a given period
-    #+period+:: Can be "day", "hour", or "current", defaults to hour
+    # Check the number of objects processed for a given time period
+    #
+    # @param period [String] Can be "day", "hour", or "current"
+    # @return [Object] API reponse object
     def usage(period = :hour)
       DataSift.request(:POST, 'usage', @config, :period => period )
     end
 
-    ##
-    # Calculate the DPU cost of consuming a stream.
-    def dpu(hash)
-      requires ({ :hash => hash })
-      DataSift.request(:POST, 'dpu', @config, :hash => hash )
+    # Calculate the DPU cost of running a filter, or Historics query
+    #
+    # @param hash [String] CSDL hash for which you wish to find the DPU cost
+    # @param historics_id [String] ID of Historics query for which you wish to
+    #   find the DPU cost
+    # @return [Object] API reponse object
+    def dpu(hash = '', historics_id = '')
+      fail ArgumentError, 'Must pass a filter hash or Historics ID' if
+        hash.empty? && historics_id.empty?
+      fail ArgumentError, 'Must only pass hash or Historics ID; not both' unless
+        hash.empty? || historics_id.empty?
+
+      params = {}
+      params.merge!(hash: hash) unless hash.empty?
+      params.merge!(historics_id: historics_id) unless historics_id.empty?
+
+      DataSift.request(:POST, 'dpu', @config, params)
     end
 
-    ##
     # Determine your credit balance or DPU balance.
+    #
+    # @return [Object] API reponse object
     def balance
       DataSift.request(:POST, 'balance', @config)
     end
 
-    ##
     # Collect a batch of interactions from a push queue
-    def pull(id, size = 20_971_520, cursor = '')
-      DataSift.request(:POST, 'pull', @config, { :id => id, :size => size, :cursor => cursor })
+    #
+    # @param id [String] ID of the Push subscription you wish to pull data from
+    # @param size [Integer] Max size (bytes) of the data you can receive from a
+    #   /pull API call
+    # @param cursor [String] A pointer into the Push queue associated with your
+    #   last delivery
+    # @return [Object] API reponse object
+    def pull(id, size = 20_971_520, cursor='')
+      DataSift.request(:POST, 'pull', @config, { :id => id, :size => size,
+        :cursor => cursor })
     end
   end
 
   # Generates and executes an HTTP request from the params provided
-  # Params:
-  # +method+:: the HTTP method to use e.g. GET,POST
-  # +path+:: the DataSift path relevant to the base URL of the API
-  # +username+:: API username
-  # +api_key+:: DS api key
-  # +params+:: A hash representing the params to use in the request, if its a
-  #   GET, HEAD or DELETE request these params are used as query string params,
-  #   if not they become form url encoded params
-  # +headers+:: any headers to pass to the API, Authorization header is
-  #   automatically included
-  def self.request(method, path, config, params = {}, headers = {}, timeout = 30, open_timeout = 30, new_line_separated = false)
+  #
+  # @param method [Symbol] The HTTP method to use
+  # @param path [String] The DataSift path relevant to the base URL of the API
+  # @param config [Object] The config object containing user details
+  # @param params [Hash] A hash representing the params to use in the request
+  # @param headers [Hash] Any headers to pass to the API
+  # @param timeout [Integer] Set the request timeout
+  # @param open_timeout [Integer] Set the request open timeout
+  # @param new_line_separated [Boolean] Will response be newline separated?
+  def self.request(method, path, config, params = {}, headers = {},
+    timeout = 30, open_timeout = 30, new_line_separated = false)
+
     validate config
     options = {}
     url = build_url(path, config)
@@ -206,6 +235,8 @@ module DataSift
     end
   end
 
+  private
+
   def self.build_url(path, config)
     'http' + (config[:enable_ssl] ? 's' : '') + '://' + config[:api_host] +
       '/' + config[:api_version] + '/' + path
@@ -228,14 +259,18 @@ module DataSift
 
   def self.handle_api_error(code, body)
     case code
-    when 400
-      raise BadRequestError.new(code, body)
-    when 401
-      raise AuthError.new(code, body)
-    when 404
-      raise ApiResourceNotFoundError.new(code, body)
-    else
-      raise DataSiftError.new(code, body)
+      when 400
+        raise BadRequestError.new(code, body)
+      when 401
+        raise AuthError.new(code, body)
+      when 404
+        raise ApiResourceNotFoundError.new(code, body)
+      when 409
+        raise ConflictError.new(code, body)
+      when 410
+        raise GoneError.new(code, body)
+      else
+        raise DataSiftError.new(code, body)
     end
   end
 

data/lib/errors.rb

@@ -1,3 +1,4 @@
+# Custom error class for rescuing DataSift errors
 class DataSiftError < StandardError
   attr_reader :status
   attr_reader :body
@@ -8,13 +9,14 @@ class DataSiftError < StandardError
   end
 
   def message
-    @body == nil ? @status : @body
+    @body.nil? ? @status : @body
   end
 
   def to_s
-    #if both body and status were provided then message is the body otherwise the status contains the message
-    msg           = !@body.nil? && !@status.nil? ? @body : @status
-    #if body is nil then status is the message body so no status is included
+    # If both body and status were provided then message is the body otherwise
+    #   the status contains the message
+    msg = !@body.nil? && !@status.nil? ? @body : @status
+    # If body is nil then status is the message body so no status is included
     status_string = @body.nil? ? '' : "(Status #{@status}) "
     "#{status_string} : #{msg}"
   end
@@ -23,18 +25,29 @@ end
 class NotSupportedError < DataSiftError
 end
 
+# Standard error returned when receiving a 400 response from the API
 class BadRequestError < DataSiftError
 end
 
+# Standard error returned when receiving a 401 response from the API
 class AuthError < DataSiftError
 end
 
 class ConnectionError < DataSiftError
 end
 
+# Standard error returned when receiving a 404 response from the API
 class ApiResourceNotFoundError < DataSiftError
 end
 
+# Standard error returned when receiving a 409 response from the API
+class ConflictError < DataSiftError
+end
+
+# Standard error returned when receiving a 410 response from the API
+class GoneError < DataSiftError
+end
+
 class InvalidConfigError < DataSiftError
 end
 
@@ -55,7 +68,10 @@ end
 
 class StreamingMessageError < DataSiftError
 end
+
 class WebSocketOnWindowsError < DataSiftError
 end
+
+# Standard error returned when trying to use a method while missing parameters
 class BadParametersError < DataSiftError
-end
+end

data/lib/historics.rb

@@ -1,94 +1,125 @@
 module DataSift
+  # Methods for using DataSift Historics
   class Historics < DataSift::ApiResource
-
-    ##
-    # Create a new historics query and return its id.
-    def prepare (hash, start, end_time, name, sources = 'twitter', sample = 100)
+    # Prepare a new Historics query
+    #
+    # @param hash [String] Hash of compiled CSDL filter
+    # @param start [Integer] Start timestamp for your Historics Query. Should be
+    #   provided as a Unix timestamp
+    # @param end_time [Integer] End timestamp for your Historics Query. Should
+    #   be provided as a Unix timestamp
+    # @param name [String] The name of your Historics query
+    # @param sources [String] Comma separated list of data sources you wish to
+    #   query
+    # @param sample [Integer] Sample size of your Historics query
+    # @return [Object] API reponse object
+    def prepare(hash, start, end_time, name, sources = 'twitter', sample = 100)
       params = {
-          :hash => hash,
-          :start => start,
-          :end => end_time,
-          :name => name,
-          :sources => sources,
-          :sample => sample
+        :hash => hash,
+        :start => start,
+        :end => end_time,
+        :name => name,
+        :sources => sources,
+        :sample => sample
       }
       requires params
       DataSift.request(:POST, 'historics/prepare', @config, params)
     end
 
-    # Pause historics query.
+    # Pause Historics query
+    #
+    # @param id [String] ID of the Historics query you need to pause
+    # @param reason [String] You can give a reason for pausing the query
     def pause(id, reason = '')
-      params = {:id => id}
+      params = { :id => id }
       requires params
       params[:reason] = reason
       DataSift.request(:PUT, 'historics/pause', @config, params)
     end
 
-    ##
-    # Resume historics query.
+    # Resume Historics query
+    #
+    # @param id [String] ID of the Historics query you need to resume
     def resume(id)
-      params = {:id => id}
+      params = { :id => id }
       requires params
       DataSift.request(:PUT, 'historics/resume', @config, params)
     end
 
-    ##
-    # Starts historics query.
+    # Start Historics query
+    #
+    # @param id [String] ID of the Historics query you need to start
     def start(id)
-      params = {:id => id}
+      params = { :id => id }
       requires params
       DataSift.request(:POST, 'historics/start', @config, params)
     end
 
-    ##
-    # Stop historics query.
+    # Stop Historics query
+    #
+    # @param id [String] ID of the Historics query you need to stop
+    # @param reason [String] You can give a reason for stopping the query
     def stop(id, reason = '')
-      params = {:id => id}
+      params = { :id => id }
       requires params
       params[:reason] = reason
       DataSift.request(:POST, 'historics/stop', @config, params)
     end
-    ##
 
-    ##
-    # Check the data coverage in the archive for a specified interval.
-    def status(start, end_time, sources='twitter')
-      params = {:start => start, :end => end_time, :sources => sources}
+    # Check the data coverage in the archive for a specified interval
+    #
+    # @param start [Integer] Start timestamp for the period you wish to query.
+    #   Should be provided as a Unix timestamp
+    # @param end_time [Integer] End timestamp for the period you wish to query.
+    #   Should be provided as a Unix timestamp
+    # @param sources [String] Comma separated list of data sources you wish to
+    #   query
+    def status(start, end_time, sources = 'twitter')
+      params = { :start => start, :end => end_time, :sources => sources }
       requires params
       DataSift.request(:GET, 'historics/status', @config, params)
     end
 
-    ##
-    # Update a historics query's name.
+    # Update the name of an Historics query
+    #
+    # @param id [String] ID of the Historics query you need to update
+    # @param name [String] New name for the Historics query
     def update(id, name)
-      params = {:id => id, :name => name}
+      params = { :id => id, :name => name }
       requires params
       DataSift.request(:POST, 'historics/update', @config, params)
     end
 
-    ##
-    # Delete a historics query.
+    # Delete an Historics query
+    #
+    # @param id [String] ID of the Historics query you need to delete
     def delete(id)
-      params = {:id => id}
+      params = { :id => id }
       requires params
       DataSift.request(:DELETE, 'historics/delete', @config, params)
     end
 
-    ##
-    # Get details for a given historics query.
+    # Get details for a given Historics query
+    #
+    # @param id [String] ID of the Historics query you need to get
+    # @param with_estimate [Boolean] 1 or 0 indicating whether you want to see
+    #   the estimated completion time of the Historics query
     def get_by_id(id, with_estimate = 1)
-      params = {:id => id, :with_estimate => with_estimate}
+      params = { :id => id, :with_estimate => with_estimate }
       requires params
       DataSift.request(:GET, 'historics/get', @config, params)
     end
 
-    ##
-    # Get details for a set of historics within the given page constraints.
-    def get(max=20, page=1, with_estimate = 1)
-      params = {:max => max, :page => page, :with_estimate => with_estimate}
+    # Get details for a list of Historics within the given page constraints
+    #
+    # @param max [Integer] Max number of Historics you wish to return per page
+    # @param page [Integer] Which page of results you need returned
+    # @param with_estimate [Boolean] 1 or 0 indicating whether you want to see
+    #   the estimated completion time of the Historics query
+    def get(max = 20, page = 1, with_estimate = 1)
+      params = { :max => max, :page => page, :with_estimate => with_estimate }
       requires params
       DataSift.request(:GET, 'historics/get', @config, params)
     end
-
   end
 end

data/lib/historics_preview.rb

@@ -1,21 +1,38 @@
 module DataSift
+  # Methods for using DataSift Historics Previews
   class HistoricsPreview < DataSift::ApiResource
-
+    # Create a new Historics Preview
+    #
+    # @param hash [String] Hash of compiled CSDL definition
+    # @param sources [String] Comma separated list of data sources you wish to
+    #   perform this Historics Preview against
+    # @param parameters [String] Historics Preview parameters. See our
+    #   {http://dev.datasift.com/docs/api/1/previewcreate /preview/create API
+    #   Docs} for full documentation
+    # @param start [String] Start timestamp for your Historics Preview. Should
+    #   be provided as Unix timestamp
+    # @param end_time [String] End timestamp for your Historics Preview. Should
+    #   be provided as Unix timestamp
     def create(hash, sources, parameters, start, end_time = nil)
       params = {
-          :hash       => hash,
-          :sources    => sources,
-          :parameters => parameters,
-          :start      => start
+        :hash       => hash,
+        :sources    => sources,
+        :parameters => parameters,
+        :start      => start
       }
-      params.merge!(:end => end_time) if end_time != nil
+      requires params
+      params.merge!(:end => end_time) unless end_time.nil?
 
       DataSift.request(:POST, 'preview/create', @config, params)
     end
 
+    # Retreive an Historics Preview
+    #
+    # @param id [String] ID of the Historics Preview
     def get(id)
-      DataSift.request(:POST, 'preview/get', @config, {:id => id})
+      params = { :id => id }
+      requires params
+      DataSift.request(:POST, 'preview/get', @config, params)
     end
-
   end
 end