datasift 1.5.0 → 2.0.0

data/.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 sftp-config.json
 .idea/
+rdoc/

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 MediaSift Ltd
+Copyright (c) 2011-2012 MediaSift Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,9 +2,9 @@ DataSift
 ========
 
 The official Ruby library for accessing the DataSift API. See
-http://datasift.net for full details and to sign up for an account.
+http://datasift.com/ for full details and to sign up for an account.
 
-The examples and tests use the username and API key in config.yml.
+The examples use the username and API key in config.yml unless otherwise noted.
 
 Install Instructions
 --------------------
@@ -19,7 +19,7 @@ If you're using the source you'll need to install the dependencies.
 sudo gem install yajl-ruby rest-client
 
 The library will use SSL connections by default. While we recommend using SSL
-you may disable it if required by passing false as the third parameter when
+you may disable it if r§equired by passing false as the third parameter when
 creating a user, or by calling user.enableSSL(false) on the user object.
 
 Simple example
@@ -56,7 +56,9 @@ more details.
 Changelog
 ---------
 
-* v.1.5.0 Added getBalance to the User class [joncooper] (2012-05-24)
+* v.2.0.0 Added support for Historics queries and Push delivery (2012-08-31)
+
+* v.1.5.0 Added getBalance to the User class [joncooper](https://github.com/joncooper) (2012-05-24)
 
 * v.1.4.1 Fixed a minor bug in the SSL support (2012-05-15)
 

data/VERSION

@@ -1 +1 @@
-1.5.0
+2.0.0

data/config.yml

@@ -1,2 +1,2 @@
-username: YOUR_USERNAME_HERE
-api_key: YOUR_API_KEY_HERE
+username: 3ft9
+api_key: 584b068700b016093686a8d3f95696ac

data/datasift.gemspec

@@ -2,17 +2,17 @@
 $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
-	s.name			= 'datasift'
-	s.version		= File.open('VERSION').first
+	s.name    = 'datasift'
+	s.version = File.open('VERSION').first
 
-	s.authors		= ['DataSift']
-	s.email			= ['support@datasift.net']
-	s.description	= %q{The official Ruby library for accessing the DataSift API. See http://datasift.com/ for full details and to sign up for an account.}
-	s.summary		= %q{DataSift is a simple wrapper for the DataSift API.}
-	s.homepage		= 'http://github.com/datasift/datasift-ruby'
+	s.authors     = ['DataSift']
+	s.email       = ['support@datasift.net']
+	s.description = %q{The official Ruby library for accessing the DataSift API. See http://datasift.com/ for full details and to sign up for an account.}
+	s.summary     = %q{DataSift is a simple wrapper for the DataSift API.}
+	s.homepage    = 'http://github.com/datasift/datasift-ruby'
 
-	s.platform					= Gem::Platform::RUBY
-	s.rubygems_version			= %q{1.3.6}
+	s.platform                  = Gem::Platform::RUBY
+	s.rubygems_version          = %q{1.3.6}
 	s.required_rubygems_version	= Gem::Requirement.new(">= 1.3.6") if s.respond_to? :required_rubygems_version=
 
 	s.add_runtime_dependency('rest-client', '~> 1.6.3')
@@ -21,7 +21,7 @@ Gem::Specification.new do |s|
 	s.add_development_dependency('shoulda', '~> 2.11.3')
 	s.add_development_dependency('rspec', '~> 2.6.0')
 
-	s.files			= `git ls-files`.split("\n")
-	s.test_files	= `git ls-files -- {test,spec,features}/*`.split("\n")
+	s.files         = `git ls-files`.split("\n")
+	s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
 	s.require_paths = ["lib"]
 end

data/examples/historics.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+ruby historics/$3.rb $1 $2 ${@:4}

data/examples/historics/create-from-csdl.rb

@@ -0,0 +1,71 @@
+# This script creates a new Historics query from a file containing CSDL.
+#
+# 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.
+#
+
+# Function to display usage instructions with an optional error message.
+def usage(message = '', end_of_story = true)
+	puts message + '\n' unless message.length() == 0
+	puts
+	puts 'Usage: create-from-csdl <username> <api_key> \\'
+	puts '            <csdl_filename> <start> <end> <sources> <name> <sample>'
+	puts
+	puts 'Where: csdl_filename = the stream hash the query should run'
+	puts '       start         = the start date for the query (YYYYMMDDHHMMSS)'
+	puts '       end           = the end date for the query (YYYYMMDDHHMMSS)'
+	puts '       sources       = comma separated list of data sources (e.g. twitter)'
+	puts '       name          = a friendly name for the query'
+	puts '       sample        = the sample rate'
+	puts
+	puts 'Example'
+	puts '       create-from-csdl csdl.txt 20120101000000 20120101235959 \\'
+	puts '                      twitter HistoricsQuery123 100'
+	puts
+	exit 1 unless not end_of_story
+end
+
+# 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()
+
+# Check that we have enough arguments
+usage() unless env.args.size() == 6
+
+# Read the arguments
+csdl_filename = env.args[0]
+start_date    = env.args[1]
+end_date      = env.args[2]
+sources       = env.args[3].split(',')
+name          = env.args[4]
+sample        = env.args[5]
+
+# Parse the dates
+start_date = DateTime.strptime(start_date, '%Y%m%d%H%M%S')
+end_date   = DateTime.strptime(end_date,   '%Y%m%d%H%M%S')
+
+# Read the CSDL
+csdl = File.open(csdl_filename, 'r').read
+
+begin
+	# Create the definition
+	definition = env.user.createDefinition(csdl)
+
+	# Create the Historics query
+	historic = definition.createHistoric(start_date, end_date, sources, name, sample)
+
+	# Prepare the query
+	historic.prepare()
+
+	# Display the details
+	env.displayHistoricDetails(historic)
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+ rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/historics/create-from-hash.rb

@@ -0,0 +1,65 @@
+# This script creates a new Historics query from a stream hash.
+#
+# 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.
+#
+
+# Function to display usage instructions with an optional error message.
+def usage(message = '', end_of_story = true)
+	puts message + '\n' unless message.length() == 0
+	puts
+	puts 'Usage: create-from-hash \\'
+	puts '            <username> <api_key> <hash> <start> <end> <sources> <name> <sample>'
+	puts
+	puts 'Where: hash    = the stream hash the query should run'
+	puts '       start   = the start date for the query (YYYYMMDDHHMMSS)'
+	puts '       end     = the end date for the query (YYYYMMDDHHMMSS)'
+	puts '       sources = comma separated list of data sources (e.g. twitter)'
+	puts '       name    = a friendly name for the query'
+	puts '       sample  = the sample rate'
+	puts
+	puts 'Example'
+	puts '       create-from-hash <hash> 20120101000000 20120101235959 \\'
+	puts '                      twitter HistoricsQuery123 100'
+	puts
+	exit 1 unless not end_of_story
+end
+
+# 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()
+
+# Check that we have enough arguments
+usage() unless env.args.size() == 6
+
+# Read the arguments
+stream_hash = env.args[0]
+start_date  = env.args[1]
+end_date    = env.args[2]
+sources     = env.args[3].split(',')
+name        = env.args[4]
+sample      = env.args[5]
+
+# Parse the dates
+start_date = DateTime.strptime(start_date, '%Y%m%d%H%M%S')
+end_date   = DateTime.strptime(end_date,   '%Y%m%d%H%M%S')
+
+begin
+	# Create the Historics query
+	historic = env.user.createHistoric(stream_hash, start_date, end_date, sources, name, sample)
+
+	# Prepare the query
+	historic.prepare()
+
+	# Display the details
+	env.displayHistoricDetails(historic)
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+ rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/historics/delete.rb

@@ -0,0 +1,30 @@
+# This script deletes Historics queries from 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 playback IDs') unless env.args.size() > 0
+
+begin
+	for playback_id in env.args
+		historic = env.user.getHistoric(playback_id)
+		print 'Deleting ' + playback_id + ', "' + historic.name + '"...'
+		historic.delete()
+		puts 'done'
+	end
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/historics/env.rb

@@ -0,0 +1,37 @@
+# This class is used by the Historics examples to remove the noise of
+# dealing with command line arguments.
+#
+
+# Include the DataSift library
+require File.dirname(__FILE__) + '/../../lib/datasift'
+
+class Env
+	attr_reader :user, :args
+
+	def initialize(args = false)
+		if args === false
+			args = ARGV
+		end
+
+		abort('Please specify your DataSift username and API key as the first two command line arguments!') unless args.size() >= 2
+
+		username = args.shift
+		api_key = args.shift
+		@user = DataSift::User.new(username, api_key)
+
+		@args = args
+	end
+
+	def displayHistoricDetails(historic)
+		puts 'Playback ID: ' + historic.hash
+		puts 'Stream hash: ' + historic.stream_hash
+		puts 'Name:        ' + historic.name
+		puts 'Start time:  ' + historic.start_date.strftime('%Y-%m-%d %H:%M:%S')
+		puts 'End time:    ' + historic.end_date.strftime('%Y-%m-%d %H:%M:%S')
+		puts 'Sources:     ' + historic.sources.join(', ')
+		puts 'Sample:      ' + String(historic.sample)
+		puts 'Created at:  ' + (historic.created_at.nil? ? 'None' : historic.created_at.strftime('%Y-%m-%d %H:%M:%S'))
+		puts 'Status:      ' + historic.status
+		puts '--'
+	end
+end

data/examples/historics/list.rb

@@ -0,0 +1,30 @@
+# This script lists Historics queries 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()
+
+begin
+	historics = env.user.listHistorics()
+
+	if historics['historics'].size() == 0
+		puts 'No Historics queries exist in your account.'
+	else
+		for historic in historics['historics']
+			env.displayHistoricDetails(historic)
+		end
+	end
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/historics/start.rb

@@ -0,0 +1,30 @@
+# This script starts Historics queries 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 playback IDs') unless env.args.size() > 0
+
+begin
+	for playback_id in env.args
+		historic = env.user.getHistoric(playback_id)
+		print 'Starting ' + playback_id + ', "' + historic.name + '"...'
+		historic.start()
+		puts 'done'
+	end
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/historics/stop.rb

@@ -0,0 +1,30 @@
+# This script stops Historics queries 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 playback IDs') unless env.args.size() > 0
+
+begin
+	for playback_id in env.args
+		historic = env.user.getHistoric(playback_id)
+		print 'Stopping ' + playback_id + ', "' + historic.name + '"...'
+		historic.stop()
+		puts 'done'
+	end
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/historics/view.rb

@@ -0,0 +1,28 @@
+# This script views Historics queries 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 playback IDs') unless env.args.size() > 0
+
+begin
+	for playback_id in env.args
+		historic = env.user.getHistoric(playback_id)
+		env.displayHistoricDetails(historic)
+	end
+
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+rescue DataSift::DataSiftError => err
+	puts 'ERR: [' + err.class.name + '] ' + err.message
+end

data/examples/push.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+ruby push/$3.rb $1 $2 ${@:4}

data/examples/push/delete.rb

@@ -0,0 +1,33 @@
+# This script deletes Push subscriptions from 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)
+		print 'Deleting ' + sub_id + ', "' + sub.name + '"...'
+		sub.delete()
+	rescue DataSift::DataSiftError => err
+		puts 'ERR: [' + err.class.name + '] ' + err.message
+	else
+		puts 'done'
+	end
+end
+
+if env.user.rate_limit_remaining != -1
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+end