datasift 2.1.1 → 3.0.0.beta

data/examples/push/view.rb

@@ -1,31 +0,0 @@
-# This script views the details of Push subscriptions in your account.
-#
-# NB: Most of the error handling (exception catching) has been removed for
-# the sake of simplicity. Nearly everything in this library may throw
-# exceptions, and production code should catch them. See the documentation
-# for full details.
-#
-
-# Include the shared Env class
-require File.dirname(__FILE__) + '/env'
-
-# Create the env object. This reads the command line arguments, creates the
-# user object, and provides access to both along with helper functions.
-env = Env.new()
-
-# Make sure we have something to do
-abort('Please specify one or more subscription IDs') unless env.args.size() > 0
-
-for sub_id in env.args
-	begin
-		sub = env.user.getPushSubscription(sub_id)
-		env.displaySubscriptionDetails(sub)
-	rescue DataSift::DataSiftError => err
-		puts 'ERR: [' + err.class.name + '] ' + err.message
-		puts '--'
-	end
-end
-
-if env.user.rate_limit_remaining != -1
-	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
-end

data/examples/twitter-track.rb

@@ -1,61 +0,0 @@
-# This example constructs a DataSift_Definition object with CSDL that looks
-# for anything containing the word "football". It then gets an HTTP
-# consumer for that definition and displays matching interactions to the
-# screen as they come in. It will display 10 interactions and then stop.
-#
-# NB: Most of the error handling (exception catching) has been removed for
-# the sake of simplicity. Nearly everything in this library may throw
-# exceptions, and production code should catch them. See the documentation
-# for full details.
-#
-
-# Make sure we have some arguments
-if ARGV.size == 0
-	puts 'ERR: Please specify the words and/or phrases to track!'
-	puts
-	puts
-	exit!
-end
-
-# Include the DataSift library
-require './' + File.dirname(__FILE__) + '/../lib/datasift'
-
-# Include the configuration - put your username and API key in this file
-require 'yaml'
-config = YAML::load(File.open(File.join(File.dirname(__FILE__), '..', 'config.yml')))
-
-# Authenticate
-puts 'Creating user...'
-user = DataSift::User.new(config['username'], config['api_key'])
-
-# Create the definition
-csdl = 'interaction.type == "twitter" and (interaction.content contains "' + ARGV.join('" or interaction.content contains "') + '")'
-puts 'Creating definition...'
-puts '  ' + csdl
-definition = user.createDefinition(csdl)
-
-# Create the consumer
-puts 'Getting the consumer...'
-consumer = definition.getConsumer(DataSift::StreamConsumer::TYPE_HTTP)
-
-# Setting up the onStopped handler
-consumer.onStopped do |reason|
-	puts
-	puts 'Stopped: ' + reason
-	puts
-end
-
-# And start consuming
-puts 'Consuming...'
-puts '--'
-consumer.consume(true) do |interaction|
-	if interaction
-		puts 'Type: ' + interaction['interaction']['type']
-		puts 'Content: ' + interaction['interaction']['content']
-		puts '--'
-	end
-end
-
-puts
-puts 'Finished consuming'
-puts

data/lib/DataSift/apiclient.rb

@@ -1,73 +0,0 @@
-require 'rest_client'
-require 'yajl'
-
-module DataSift
-	#The ApiClient class wraps the functionality that makes calls to the
-	#DataSift API.
-	class ApiClient
-		#Make a call to a DataSift API endpoint.
-		#=== Parameters
-		#* +user+ - The DataSift User object.
-		#* +endpoint+ - The endpoint of the API call.
-		#* +params+ - The parameters to be passed along with the request.
-		#=== Returns
-		#A Hash contatining...
-		#* +response_code+ - The HTTP response code.
-		#* +data+ - A Hash containing the response data.
-		#* +rate_limit+ - The total API credits you get per hour.
-		#* +rate_limit_remaining+ - The number of API credits you have remaining for this hour.
-		def call(user, endpoint, params = {}, user_agent = User::USER_AGENT)
-			# Build the full endpoint URL
-			url = 'http' + (user.use_ssl ? 's' : '') + '://' + User::API_BASE_URL + endpoint
-
-			retval = {
-				'response_code' => 500,
-				'data' => { 'error' => 'Unknown error' },
-				'rate_limit' => -1,
-				'rate_limit_remaining' => -1,
-			}
-
-			begin
-				# Make the call
-				res = RestClient.post(url, params, { 'Auth' => user.username + ':' + user.api_key, 'User-Agent' => user_agent })
-
-				# Success
-				retval['response_code'] = res.code
-
-				# Parse the JSON response
-				retval['data'] = Yajl::Parser.parse(res)
-
-				# Rate limit headers
-				if (res.headers[:x_ratelimit_limit])
-					retval['rate_limit'] = res.headers[:x_ratelimit_limit]
-				end
-
-				if (res.headers[:x_ratelimit_remaining])
-					retval['rate_limit_remaining'] = res.headers[:x_ratelimit_remaining]
-				end
-			rescue RestClient::ExceptionWithResponse => err
-				# Set the response code
-				retval['response_code'] = err.http_code
-
-				# And set the data
-				retval['data'] = Yajl::Parser.parse(err.response)
-			end
-
-			return retval
-		end
-
-	private
-
-		#Convert a Hash to an HTTP query string.
-		#=== Parameters
-		#* +hash+ - The Hash to convert.
-		#=== Returns
-		#A string containing the equivalent query string.
-		def hashToQuerystring(hash)
-			hash.keys.inject('') do |query_string, key|
-				query_string << '&' unless key == hash.keys.first
-				query_string << "#{URI.encode(key.to_s)}=#{URI.encode(hash[key].to_s)}"
-			end
-		end
-	end
-end

data/lib/DataSift/definition.rb

@@ -1,202 +0,0 @@
-require 'date'
-
-module DataSift
-	#The Definition class represents a stream definition.
-	class Definition
-		#The CSDL for this Definition.
-		attr_reader :csdl
-
-		#Constructor. A User object is required, and you can optionally supply a
-		#default CSDL string.
-		#=== Parameters
-		#* +user+ - The DataSift::User object.
-		#* +csdl+ - Optional default CSDL string.
-		#* +hash+ - Optional default hash string.
-		def initialize(user, csdl = '', hash = false)
-			raise InvalidDataError, 'Please supply a valid User object when creating a Definition object.' unless user.is_a? DataSift::User
-			@user = user
-			clearHash()
-			@hash = hash
-			self.csdl = csdl
-			@total_dpu = false
-			@created_at = false
-		end
-
-		#CSDL getter
-		def csdl
-			raise InvalidDataError, 'The CSDL is not available' unless !@csdl.nil?
-			return @csdl
-		end
-
-		#CSDL setter. Strips the incoming string and resets the hash if it's changed.
-		def csdl=(csdl)
-			if csdl.nil?
-				@csdl = nil
-			else
-				raise InvalidDataError, 'The CSDL must be a string.' unless csdl.is_a? String
-				csdl = csdl.strip
-				clearHash() unless csdl == @csdl
-				@csdl = csdl
-			end
-		end
-
-		#Total DPU getter.
-		def total_dpu
-			compile() unless @total_dpu
-			return @total_dpu
-		end
-
-		#Created at getter.
-		def created_at
-			compile() unless @created_at
-			return @created_at
-		end
-
-		#Hash getter. If the hash has not yet been obtained the CSDL will be
-		#compiled first.
-		def hash
-			if @hash == false
-				compile()
-			end
-
-			return @hash
-		end
-
-		#Reset the hash to false. The effect of this is to mark the definition as
-		#requiring compilation.
-		def clearHash()
-			@csdl = '' unless !@csdl.nil?
-			@hash = false
-			@total_dpu = false
-			@created_at = false
-		end
-
-		#Call the DataSift API to compile this definition. On success it will
-		#store the returned hash.
-		def compile()
-			raise InvalidDataError, 'Cannot compile an empty definition.' unless @csdl.length > 0
-
-			begin
-				res = @user.callAPI('compile', { 'csdl' => @csdl })
-
-				if res.has_key?('hash')
-					@hash = res['hash']
-				else
-					raise CompileFailedError, 'Compiled successfully but no hash in the response'
-				end
-
-				if res.has_key?('dpu')
-					@total_dpu = Float(res['dpu'])
-				else
-					raise CompileFailedError, 'Compiled successfully but no DPU in the response'
-				end
-
-				if res.has_key?('created_at')
-					@created_at = Date.parse(res['created_at'])
-				else
-					raise CompileFailedError, 'Compiled successfully but no created_at in the response'
-				end
-			rescue APIError => err
-				clearHash()
-
-				case err.http_code
-				when 400
-					raise CompileFailedError, err
-				else
-					raise APIError('Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.inspect + ']', err.http_code)
-				end
-			end
-		end
-
-		#Call the DataSift API to validate this definition. On success it will
-		#store the details in the response.
-		def validate()
-			raise InvalidDataError, 'Cannot validate an empty definition.' unless @csdl.length > 0
-
-			begin
-				res = @user.callAPI('validate', { 'csdl' => @csdl })
-
-				if res.has_key?('dpu')
-					@total_dpu = Float(res['dpu'])
-				else
-					raise CompileFailedError, 'Validated successfully but no DPU in the response'
-				end
-
-				if res.has_key?('created_at')
-					@created_at = Date.parse(res['created_at'])
-				else
-					raise CompileFailedError, 'Validated successfully but no created_at in the response'
-				end
-			rescue APIError => err
-				clearHash()
-
-				case err.http_code
-				when 400
-					raise CompileFailedError, err
-				else
-					raise APIError('Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.inspect + ']', err.http_code)
-				end
-			end
-		end
-
-		#Call the DataSift API to get the DPU for this definition. Returns
-		#=== Returns
-		#A Hash containing...
-		#* +detail+ - The breakdown of running the rule
-		#* +dpu+ - The total DPU of the rule
-		def getDPUBreakdown()
-			raise InvalidDataError, "Cannot get the DPU for an empty definition." unless @csdl.length > 0
-
-			@user.callAPI('dpu', { 'hash' => self.hash })
-		end
-
-		#Call the DataSift API to get buffered interactions.
-		#=== Parameters
-		#* +count+ - Optional number of interactions to return (max 200).
-		#* +from_id+ - Optional start ID.
-		#=== Returns
-		#An array of Hashes where each Hash is an interaction.
-		def getBuffered(count = false, from_id = false)
-			raise InvalidDataError, "Cannot get buffered interactions for an empty definition." unless @csdl.length > 0
-
-			params = { 'hash' => self.hash }
-
-			if count
-				params['count'] = count
-			end
-
-			if from_id
-				params['interaction_id'] = from_id
-			end
-
-			retval = @user.callAPI('stream', params)
-
-			raise APIError, 'No data in the response' unless retval.has_key?('stream')
-
-			return retval['stream']
-		end
-
-		#Create a Historics query based on this Definition.
-		#=== Parameters
-		#* +start_date+ - The start date for a new Historics query.
-		#* +end_date+ - The end date for a new Historics query.
-		#* +sources+ - An array of sources for a new Historics query.
-		#* +name+ - The name for a new Historics query.
-		#* +sample+ - The sample rate for the new Historics query.
-		#=== Returns
-		#A Historic object.
-		def createHistoric(start_date, end_date, sources, sample, name)
-			return Historic.new(@user, hash, start_date, end_date, sources, sample, name)
-		end
-
-		#Returns a StreamConsumer-derived object for this definition, for the
-		#given type.
-		#=== Parameters
-		#* +type+ - The consumer type for which to construct a consumer.
-		#=== Returns
-		#A StreamConsumer-derived object.
-		def getConsumer(type = nil, on_interaction = nil, on_stopped = nil)
-			StreamConsumer.factory(@user, type, self)
-		end
-	end
-end

data/lib/DataSift/exceptions.rb

@@ -1,33 +0,0 @@
-module DataSift
-	# All exceptions inherit from DataSiftError.
-	class DataSiftError < StandardError; end
-
-	# Thrown when access to the API is denied.
-	class AccessDeniedError < DataSiftError; end
-
-	# Thrown when CSDL validation or compilation fails.
-	class CompileFailedError < DataSiftError; end
-
-	# Thrown whenever invalid data is encountered in the library.
-	class InvalidDataError < DataSiftError; end
-
-	# Thrown when you exceed your API rate limit.
-	class RateLimitExceededError < DataSiftError; end
-
-	# Thrown when error occur while reading streaming data.
-	class StreamError < DataSiftError; end
-
-	#Thrown when an error is found in API responses.
-	#These errors optionally carry the HTTP error code.
-	class APIError < DataSiftError
-		#The HTTP status code.
-		attr_reader :http_code
-
-		#Constructor.
-		#=== Parameters
-		#* +http_code+ - Optional HTTP status code.
-		def initialize(http_code = -1)
-			@http_code = http_code
-		end
-	end
-end

data/lib/DataSift/historic.rb

@@ -1,316 +0,0 @@
-require 'date'
-
-module DataSift
-	#The Historic class represents a Historics query.
-	class Historic
-		#Get a list of Historics queries in your account.
-		#=== Parameters
-		#* +user+ - The user object making the request.
-		#* +page+ - The page number to get.
-		#* +per_page+ - The number of items per page.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of Historics queries in your account.
-		#* +historics+ - An array of Hashes where each Hash is a Historics query.
-		def self.list(user, page = 1, per_page = 20)
-			begin
-				res = user.callAPI(
-					'historics/get', {
-						'page' => page,
-						'max' => per_page
-					})
-
-				retval = { 'count' => res['count'], 'historics' => [] }
-				for historic in res['data']
-					retval['historics'].push(new(user, historic))
-				end
-				retval
-			rescue APIError => err
-				case err.http_code
-				when 400
-					# Missing or invalid parameters
-					raise InvalidDataError, err
-				else
-					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
-				end
-			end
-		end
-
-		#The ID of this Historics query.
-		attr_reader :playback_id
-		#The stream hash which this Historics query is executing.
-		attr_reader :stream_hash
-		#The friendly name for this Historics query.
-		attr_reader :name
-		#The start date for this Historics query.
-		attr_reader :start_date
-		#The end date for this Historics query.
-		attr_reader :end_date
-		#The date/time when this Historics query was created.
-		attr_reader :created_at
-		#The current status of this Historics query.
-		attr_reader :status
-		#The current progress in percent of this Historics query.
-		attr_reader :progress
-		#The data sources for which this Historics query is looking.
-		attr_reader :sources
-		#The sample percentage that this Historics query will match.
-		attr_reader :sample
-		#The DPU cost of running this Historics query.
-		attr_reader :dpus
-		#True if this Historics query has been deleted.
-		attr_reader :is_deleted
-
-		#Constructor. Pass all parameters to create a new Historics query, or provide a User object and a playback_id as the hash parameter to load an existing query from the API.
-		#=== Parameters
-		#* +user+ - The DataSift::User object.
-		#* +hash+ - Either a stream_hash, an array containing the Historics query data or a playback ID.
-		#* +start_date+ - The start date for a new Historics query.
-		#* +end_date+ - The end date for a new Historics query.
-		#* +sources+ - An array of sources for a new Historics query.
-		#* +name+ - The name for a new Historics query.
-		#* +sample+ - The sample rate for the new Historics query.
-		def initialize(user, hash, start_date = false, end_date = false, sources = false, sample = false, name = false)
-			raise InvalidDataError, 'Please supply a valid User object when creating a Historic object.' unless user.is_a? DataSift::User
-			@user = user
-
-			if not start_date
-				if hash.kind_of?(Hash)
-					# Initialising from an array
-					@playback_id = hash['id']
-					initFromArray(hash)
-				else
-					# Fetching from the API
-					@playback_id = hash
-					reloadData()
-				end
-			else
-				# Creating a new Historic query, make sure we have all the parameters
-				raise InvalidDataError,
-					'Please supply all parameters when creating a new Historics query' unless
-						start_date != false and end_date != false and sources != false and
-						name != false and sample != false
-
-				# Convert and validate the parameters as required
-				hash = hash.hash if hash.is_a? DataSift::Definition
-				start_date = DateTime.strptime(start_date, '%s') unless start_date.is_a? Date
-				end_date = DateTime.strptime(end_date, '%s') unless end_date.is_a? Date
-				raise InvalidDataError, 'Please supply an array of sources' unless sources.kind_of?(Array)
-
-				@playback_id  = false
-				@stream_hash  = hash
-				@start_date   = start_date
-				@end_date     = end_date
-				@sources      = sources
-				@name         = name
-				@sample       = sample
-				@progress     = 0
-				@dpus         = false
-				@availability = {}
-				@is_deleted   = false
-			end
-		end
-
-		#Reload the data for this object from the API.
-		def reloadData()
-			#Can't do this if we've been deleted
-			raise InvalidDataError, 'Cannot reload the data for a deleted Historics query' unless not @is_deleted
-
-			#Can't do this without a playback ID
-			raise InvalidDataError, 'Cannot reload the data with a Historics query with no playback ID' unless @playback_id
-
-			begin
-				initFromArray(@user.callAPI('historics/get', { 'id' => @playback_id }))
-			rescue APIError => err
-				case err.http_code
-				when 400
-					raise InvalidDataError, err
-				else
-					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
-				end
-			end
-		end
-
-		#Initialise this obejct from the data in a Hash.
-		#=== Parameters
-		#* +data+ - The Hash containing the data.
-		def initFromArray(data)
-			raise APIError, 'No playback ID in the response' unless data.has_key?('id')
-			raise APIError, 'Incorrect playback ID in the response' unless not @playback_id or data['id'] == @playback_id
-			@playback_id = data['id']
-
-			raise APIError, 'No definition hash in the response' unless data.has_key?('definition_id')
-			@stream_hash = data['definition_id']
-
-			raise APIError, 'No name in the response' unless data.has_key?('name')
-			@name = data['name']
-
-			raise APIError, 'No start timestamp in the response' unless data.has_key?('start')
-			@start_date = DateTime.strptime(String(data['start']), '%s')
-
-			raise APIError, 'No end timestamp in the response' unless data.has_key?('end')
-			@end_date = DateTime.strptime(String(data['end']), '%s')
-
-			raise APIError, 'No created at timstamp in the response' unless data.has_key?('created_at')
-			@created_at = DateTime.strptime(String(data['created_at']), '%s')
-
-			raise APIError, 'No status in the response' unless data.has_key?('status')
-			@status = data['status']
-
-			raise APIError, 'No progress in the response' unless data.has_key?('progress')
-			@progress = data['progress']
-
-			raise APIError, 'No sources in the response' unless data.has_key?('sources')
-			@sources = data['sources']
-
-			raise APIError, 'No sample in the response' unless data.has_key?('sample')
-			@sample = data['sample']
-
-			@is_deleted = (@status == 'deleted')
-
-			return true
-		end
-
-		#Getter for the playback ID. If the Historics query has not yet been
-		#prepared that will be done automagically to obtain the playback ID.
-		def hash
-			if @playback_id == false
-				prepare()
-			end
-
-			@playback_id
-		end
-
-		#Name setter. Updates via the API if this Historics query has already
-		#been prepared.
-		def name=(new_name)
-			raise InvalidDataError, 'Cannot set the name of a deleted Historics query' unless not @is_deleted
-
-			if not @playback_id
-				@name = new_name
-			else
-				@user.callAPI('historics/update', { 'id' => @playback_id, 'name' => new_name })
-				reloadData()
-			end
-		end
-
-		#Call the DataSift API to prepare this Historics query
-		def prepare()
-			raise InvalidDataError, 'Cannot prepare a deleted Historics query' unless not @is_deleted
-			raise InvalidDataError, 'This Historics query has already been prepared' unless not @playback_id
-
-			begin
-				res = @user.callAPI(
-					'historics/prepare', {
-						'hash' => @stream_hash,
-						'start' => Integer(@start_date.strftime('%s')),
-						'end' => Integer(@end_date.strftime('%s')),
-						'name' => @name,
-						'sources' => @sources.join(','),
-						'sample' => @sample
-					})
-
-				raise InvalidDataError, 'Prepared successfully but no playback ID in the response' unless res.has_key?('id')
-				@playback_id = res['id']
-
-				raise InvalidDataError, 'Prepared successfully but no DPU cost in the response' unless res.has_key?('dpus')
-				@dpus = res['dpus']
-
-				raise InvalidDataError, 'Prepared successfully but no availability in the response' unless res.has_key?('availability')
-				@availability = res['availability']
-			rescue APIError => err
-				case err.http_code
-				when 400
-					raise InvalidDataError, err
-				else
-					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
-				end
-			end
-
-			# Reload the data so we get the created_at date, initial status and the rest.
-			reloadData()
-		end
-
-		#Start this Historics query.
-		def start()
-			raise InvalidDataError, 'Cannot start a deleted Historics query' unless not @is_deleted
-			raise InvalidDataError, 'Cannot start a Historics query that hasn\'t been prepared' unless @playback_id
-
-			begin
-				res = @user.callAPI('historics/start', { 'id' => @playback_id })
-			rescue APIError => err
-				case err.http_code
-				when 400
-					# Missing or invalid parameters
-					raise InvalidDataError, err
-				when 404
-					# Historics query not found
-					raise InvalidDataError, err
-				else
-					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
-				end
-			end
-		end
-
-		#Stop this Historics query.
-		def stop()
-			raise InvalidDataError, 'Cannot stop a deleted Historics query' unless not @is_deleted
-			raise InvalidDataError, 'Cannot stop a Historics query that hasn\'t been prepared' unless @playback_id
-
-			begin
-				res = @user.callAPI('historics/stop', { 'id' => @playback_id })
-			rescue APIError => err
-				case err.http_code
-				when 400
-					# Missing or invalid parameters
-					raise InvalidDataError, err
-				when 404
-					# Historics query not found
-					raise InvalidDataError, err
-				else
-					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
-				end
-			end
-		end
-
-		#Delete this Historics query.
-		def delete()
-			raise InvalidDataError, 'Cannot delete a deleted Historics query' unless not @is_deleted
-			raise InvalidDataError, 'Cannot delete a Historics query that hasn\'t been prepared' unless @playback_id
-
-			begin
-				@user.callAPI('historics/delete', { 'id' => @playback_id })
-				@is_deleted = true
-			rescue APIError => err
-				case err.http_code
-				when 400
-					# Missing or invalid parameters
-					raise InvalidDataError, err
-				when 404
-					# Historics query not found
-					raise InvalidDataError, err
-				else
-					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
-				end
-			end
-		end
-
-		#Get a page of Push subscriptions for this Historics query, where each
-		#page contains up to per_page items. Results will be returned in the
-		#order requested.
-		#=== Parameters
-		#* +page+ - The page number to get.
-		#* +per_page+ - The number of items per page.
-		#* +order_by+ - The field by which to order the results.
-		#* +order_dir+ - Ascending or descending.
-		#* +include_finished+ - True to include subscriptions against finished Historics queries.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of Push subscriptions in your account.
-		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
-		def getPushSubscriptions(page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC)
-			return PushSubscription.list(@user, page, per_page, order_by, order_dir, true, 'playback_id', @playback_id)
-		end
-	end
-
-end