algorithmia 0.9.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 221b1eceac956d96b62ff29d39f7d3f922f17607
-  data.tar.gz: 9a95bdc4128ca4bfbbc72e2be46e6279cb807eed
+  metadata.gz: 58520146bbbd4bf21f0d0c7c7accc707d70c4026
+  data.tar.gz: 3833bedd5cc9467ab53359501e0604da85df5b9f
 SHA512:
-  metadata.gz: 7ce500a43c125a943e498913dba6a5f99d2652c73d7a7db8f198759cf380475db0afd590f3a05b37369dd3f858c6df68e77e498bd51989c4a8e14e0830bdcea4
-  data.tar.gz: 2dc4531f7708d00e13806eb6102b91e81eff0404eace4e42824e0ae91ed877ad7d8669a4fb335be563eb8095ed651d4e611824ef40605929bc8da65b156852c9
+  metadata.gz: 18d2c1fe796f70c1c61ca7d59b0cb7545c8f3ff4ab0ef96ea525826485654f7bc2974821e6995cacc3c5fa63d7cb8872e8a15187c0e1301483babbee8b35e541
+  data.tar.gz: 967c7bdea28778abb6777dc15f9318e145919be74621a12c07931659662739a25b10a54afd1c1965c4a74687271d41a4cd64dddd0f1032cc9ac5a388d1a51a8d

data/README.md

@@ -4,172 +4,192 @@ The Algorithmia Ruby client is a wrapper for making calls to the Algorithmia API
 
 With Algorithmia, you can leverage algorithms written in any language by including them in your Ruby project with a simple API call! Browse the collection of algorithms available on [Algorithmia.com](http://algorithmia.com).
 
-## Installation
-Add this line to your application's Gemfile:
+## Getting started
+
+The Algorithmia ruby client is [available on rubygems](https://rubygems.org/gems/algorithmia).
+Simply add `gem 'algorithmia'` to your application's Gemfile and run `bundle install`.
+
+Then create an Algorithmia client and authenticate with your API key:
 
 ```ruby
-gem 'algorithmia'
+require 'algorithmia'
+
+client = Algorithmia.client('YOUR_API_KEY')
 ```
 
-And then execute:
+You are now ready to call algorithms.
 
-```bash
-$ bundle
-```
+## Calling algorithms
+
+The following examples of calling algorithms are organized by type of input/output which vary between algorithms.
+
+Note: a single algorithm may have different input and output types, or accept multiple types of input,
+so consult the algorithm's description for usage examples specific to that algorithm.
+
+### Text input/output
+
+Call an algorithm with text input by simply passing a string into its `pipe` method.
+If the algorithm output is text, then the result field of the response will be a string.
 
-Or install it yourself as:
-```bash
-$ gem install algorithmia
+```ruby
+algo = client.algo('demo/Hello/0.1.1')
+puts algo.pipe('HAL 9000').result
+# -> Hello HAL 900
 ```
 
-## Basic Usage
+### JSON input/output
 
-To call to the API, the gem uses a client model. Create and configure a client object with your API key to start making requests.
+Call an algorithm with JSON input by simply passing in a type that can be serialized to JSON, like an `Array` or `Hash`.
+For algorithms that return JSON, the result field of the response will be the appropriate deserialized type.
 
 ```ruby
-require algorithmia
+algo = client.algo('WebPredict/ListAnagrams/0.1.0')
+result = algo.pipe(["transformer", "terraforms", "retransform"]).result
+# -> ["transformer","retransform"]
+```
 
-# Create a new client instance & set your API key
-client = Algorithmia.client('YOUR_API_KEY')
+Alternatively, if your input is already serialized to JSON, you may call `pipe_json`:
 
-algorithm        = 'demo/Hello/0.1.1'
-algorithm_result = client.algo(algorithm).pipe("HAL 9000").result
-puts algorithm_result
-# => Hello HAL 9000
+```ruby
+algo = client.algo('WebPredict/ListAnagrams/0.1.0')
+result = algo.pipe_json('["transformer", "terraforms", "retransform"]').result
+# -> ["transformer","retransform"]
 ```
 
-### Algorithm Objects
+### Binary input/output
 
-When you call `.algo` on your client, it will return a new instance of `Algorithmia::Algorithm`. On this object, you have the the following methods:
-- `pipe`: the default method to calling an algorithm (recommended)
-- `pipeJson`
-- `set_options`: set query parameters on your request
+Call an algorithm with Binary input by passing an `ASCII-8BIT`-encoded string into the `pipe` method.
+Similarly, if the algorithm response is binary data, then the result field of the response will be an `ASCII-8BIT` string.
+In practice, this involves working with methods like `IO.binread` and `IO.binwrite`.
 
 ```ruby
-algorithm = client.algo('demo/Hello/0.1.1')
-# => #<Algorithmia::Algorithm:0x007f80ea092fc8 @client=Algorithmia::Client, @endpoint="demo/Hello/0.1.1", @query_options={:timeout=>300, :stdout=>false, :output=>"default"}>
-
-# Pass in a hash of options to override the default query parameters
-algorithm.set_options({'timeout': 500})
-# => {:timeout=>500, :stdout=>false, :output=>"default"}
-
-# Use these helper methods to enable stdout or change the timeout value
-algorithm.set_timeout(500)
-# => 500
-algorithm.enable_stdout
-# => true
-algorithm
-# => #<Algorithmia::Algorithm:0x007fa008b02de0 @client=Algorithmia::Client, @endpoint="demo/hello", @query_options={:timeout=>500, :stdout=>true, :output=>"default"}>
-
-# Pass the input to the algorithm
-result = algorithm.pipe('HAL 9000')
-# => Hello HAL 9000
+input = File.binread("/path/to/bender.png")
+result = client.algo("opencv/SmartThumbnail/0.1").pipe(input).result
+# -> [ASCII-8BIT string of binary data]
 ```
 
-### Algorithm Responses
-
-When a successful response from the algorithm is returned, a new Algorithmia::Response object is created.
-
-``` ruby
-# Call an algorithm
-algorithm_response = client.algo(algorithm).pipe("HAL 9000").result
-puts algorithm_response
-# => #<Algorithmia::Response:0x007f9fc2845850 @json={:result=>0.14970585904042558, :metadata=>{:content_type=>"json", :duration=>0.0006857780000000001}}>
-
-# Get the raw json returned from the API
-puts algorithm_response.json
-# => {:result=>0.14970585904042558, :metadata=>{:content_type=>"json", :duration=>0.0006857780000000001}}
-
-# Use any one of the following helper methods to understand the response
-puts algorithm_response.result
-# => 0.14970585904042558
-puts algorithm_response.metadata
-# => {:content_type=>"json", :duration=>0.0006857780000000001}
-puts algorithm_response.duration
-# => 0.0006857780000000001
-puts algorithm_response.content_type
-# => "json"
-puts algorithm_response.stdout
-# => nil
-puts algorithm_response.alerts
-# => nil
+### Error handling
+
+API errors and Algorithm exceptions will be raised when calling `pipe`:
+
+```ruby
+client.algo('util/whoopsWrongAlgo').pipe('Hello, world!')
+# -> Algorithmia::Errors::NotFoundError: algorithm algo://util/whoopsWrongAlgo not found
 ```
 
-### The Data API
+And you can rescue Algorithm errors separate from other errors:
 
-The client also allows you to work with the Algorithmia Data API. You can manage your files and directories using DataObjects. There are two types of DataObjects: `DataFile` and `DataDirectory`.
+```ruby
+begin
+  client.algo('demo/Hello').pipe('world!')
+rescue Algorithmia::Errors::AlgorithmError => e
+  puts "Algorithm Error: #{e.message}"
+  puts e.stacktrace
+rescue => e
+  puts "Error: #{e.message}"
+end
 
-#### DataFiles
+```
+
+### Request options
+
+The client exposes options that can configure algorithm requests.
+This includes support for changing the timeout or indicating that the API should include stdout in the response.
 
 ```ruby
-file = client.file('data://test_user/test/sample_file.txt')
- => #<Algorithmia::DataFile:0x007ffbaa8747d8 @client=#<Algorithmia::Client:0x007ffbab0fc798 @api_key="YOUR_API_KEY">, @data_uri="data://test_user/test/sample_file.txt", @url="/data/test_user/test/sample_file.txt">
+algo = client.algo('demo/Hello/0.1.1').set(timeout: 10, stdout: true)
+response = algo.pipe('HAL 9000')
+stdout = response.stdout
+```
 
-file.put_file('/path/to/local/file/sample_file.txt')
-# => true
+Note: `stdout: true` is ignored if you do not have access to the algorithm source.
 
-file.exists?
-# => true
 
-# Write a string to the file. This will overwrite any existing content!
-file.put("This is the contents of the file.")
-# => true
+## Working with data
 
-# Get the file and write to a local file
-file.get_file
-# => #<File:/var/folders/yl/vv6ws5196cvb61xzwrg8l3vm0000gp/T/test.txt20160328-94761-i8cqxg>
+The Algorithmia Java client also provides a way to manage both Algorithmia hosted data
+and data from Dropbox or S3 accounts that you've connected to you Algorithmia account.
 
-file.get
-# => "This is the contents of the file."
+This client provides a `DataFile` type (generally created by `client.file(uri)`)
+and a `DataDir` type (generally created by `client.dir(uri)`) that provide methods for managing your data.
 
-file.delete
-# => true
+### Create directories
+
+Create directories by instantiating a `DataDirectory` object and calling `create`:
+
+```ruby
+client.dir("data://.my/robots").create
+client.dir("dropbox://robots").create
 ```
 
-#### DataDirectories
+### Upload files to a directory
+
+Upload files by calling `put` on a `DataFile` object, or by calling `putFile` on a `DataDirectory` object.
 
 ```ruby
-# Create a DataDirectory object
-dir = client.dir('data://test_user/test')
-# => #<Algorithmia::DataDirectory:0x007ffbab0fc748 @client=#<Algorithmia::Client:0x007ffbab0fc798 @api_key="YOUR_API_KEY">, @data_uri="data://test_user/test", @url="/data/test_user/test">
+robots = client.dir("data://.my/robots")
+
+# Upload local file
+robots.put_file("/path/to/Optimus_Prime.png")
+# Write a text file
+robots.file("Optimus_Prime.txt").put("Leader of the Autobots")
+# Write a binary file
+robots.file("Optimus_Prime.key").put([71, 101, 101, 107].pack('C*'))
+```
+
+### Download contents of file
 
-# Create a new directory
-dir.create
-# => true
+Download files by calling `get` or `get_file` on a `DataFile` object:
+
+```ruby
+# Download file and get the file handle
+t800File = client.file("data://.my/robots/T-800.png").get_file
 
-dir.exists?
-# => true
+# Get file's contents as a string
+t800Text = client.file("data://.my/robots/T-800.txt").get
 
-# Get a new DataDirectory object for the parent directory
-dir.parent
-# => #<Algorithmia::DataDirectory:0x007ffba924e148 @client=#<Algorithmia::Client:0x007ffbab0fc798 @api_key="YOUR_API_KEY">, @data_uri="data://test_user", @url="/data/test_user">
+# Get file's contents as JSON
+t800JsonString = client.file("data://.my/robots/T-800.txt").get
+t800Json =  JSON.parse(t800JsonString)
 
-# Delete the directory
-dir.delete
-# => true
+# Get file's contents as a byte array
+t800Bytes = client.file("data://.my/robots/T-800.png").get
 ```
 
-##### Working with directories:
+### Delete files and directories
 
-You can iterate over all contents in a directory, only the sub-directories, or the files within the directory by using of the the `each` methods provided. If no block is given to the method, an enumerator will be returned:
+Delete files and directories by calling delete on their respective `DataFile` or `DataDirectory` object.
+DataDirectories take an optional `force` parameter that indicates whether the directory should be deleted
+if it contains files or other directories.
 
 ```ruby
-# Return an enumerator for all directory contents, each sub-directory, or each file in the directory
-dir.each
-dir.each_directory
-dir.each_file
-#  => #<Enumerator: #<Algorithmia::DataDirectory:0x007ffba89bbcd8 @client=#<Algorithmia::Client:0x007ffbab0fc798 @api_key="YOUR_API_KEY">, @data_uri="data://test_user/test_two", @url="/data/test_user/test_two">:each>
-
-# Iterate all directory contents, each sub-directory, or each file in the directory
-dir.each { |item| block }
-dir.each_directory { |dir| block }
-dir.each_file { |file| block }
+client.file("data://.my/robots/C-3PO.txt").delete
+
+client.dir("data://.my/robots").delete(false)
 ```
 
+### List directory contents
 
-## Stuck? Need help?
+Iterate over the contents of a directory using the iterated returned
+by calling `each`, `each_directory`, or `each_file` on a `DataDirectory` object.
+If no block is given to the method, an enumerator will be returned.
 
-Check out our guides, tutorials, and how-tos in the [Algorithmia Developer Center](http://developers.algorithmia.com) as well as finding more specifics in our [API documentation](http://docs.algorithmia.com).
+```ruby
+# List top level directories
+client.dir("data://.my").each_dir do |dir|
+    puts "Directory " + dir.data_uri
+end
+
+# List files in the 'robots' directory
+client.dir("data://.my/robots").each_file do |file|
+    puts "File " + file.data_uri
+end
+
+# Iterate all directory contents
+client.dir("dropbox://").each do |item|
+    puts file.data_uri
+end
+```
 
 ## Development
 
@@ -181,6 +201,3 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/algorithmiaio/algorithmia-ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-## Not Yet Implemented:
-- Tests! :scream:
-

data/lib/algorithmia.rb

@@ -24,8 +24,8 @@ module Algorithmia
       Algorithmia::UnauthenticatedClient.new.dir(data_uri)
     end
 
-    def client(api_key=nil)
-      Algorithmia::Client.new(api_key)
+    def client(api_key=nil, base_url=nil)
+      Algorithmia::Client.new(api_key, base_url)
     end
   end
 end

data/lib/algorithmia/algorithm.rb

@@ -4,46 +4,27 @@ module Algorithmia
     def initialize(client, endpoint)
       @client = client
       @endpoint = '/v1/algo/' + endpoint
-      @query = {
-        timeout: 300,
-        stdout: false,
-        output: 'default'
-      }
+      @query = {}
     end
 
-    def set_options(options_hash)
+    def set(options_hash)
       @query.update(options_hash)
-    end
-
-    def set_timeout(timeout)
-      @query[:timeout] = timeout.to_i
-    end
-
-    def enable_stdout
-      @query[:stdout] = true
+      self
     end
 
     def pipe(input)
-      content_type = case
-        when input.kind_of?(String) && input.encoding == Encoding::ASCII_8BIT
-          'application/octet-stream'
-        when input.kind_of?(String)
-          'text/plain'
-        else
-          'application/json'
-        end
-
-      headers = {
-        'Content-Type' => content_type
-      }
-
-      response = Algorithmia::Requester.new(@client).post(@endpoint, input, query: @query, headers: headers)
+      client_timeout = (@query[:timeout] || 300) + 10
+      response = Algorithmia::Requester.new(@client).post(@endpoint, input, query: @query, headers: {}, timeout: client_timeout)
       Algorithmia::Response.new(response.parsed_response, @query[:output])
     end
 
     def pipe_json(input)
-      response = Algorithmia::Requester.new(@client).post(@endpoint, input, query: @query, headers: {})
-      Algorithmia::Response.new(response.parsed_response)
+      client_timeout = (@query[:timeout] || 300) + 10
+      headers = {
+        'Content-Type' => 'application/json'
+      }
+      response = Algorithmia::Requester.new(@client).post(@endpoint, input, query: @query, headers: headers, timeout: client_timeout)
+      Algorithmia::Response.new(response.parsed_response, @query[:output])
     end
   end
 end

data/lib/algorithmia/data_file.rb

@@ -26,18 +26,7 @@ module Algorithmia
     end
 
     def put(data)
-      content_type = case
-        when data.kind_of?(String) && data.encoding == Encoding::ASCII_8BIT
-          'application/octet-stream'
-        when data.kind_of?(String)
-          'text/plain'
-        else
-          'application/json'
-      end
-
-      headers = {'Content-Type' => content_type }
-      Algorithmia::Requester.new(@client).put(@url, data, headers: headers)
-      true
+      Algorithmia::Requester.new(@client).put(@url, data, headers: {})
     end
 
     alias_method :put_json, :put

data/lib/algorithmia/errors.rb

@@ -9,12 +9,20 @@ module Algorithmia
       end
     end
 
+    class AlgorithmError < Error;
+      attr_reader :stacktrace
+      def initialize(message, response, stacktrace)
+        super(message, response)
+        @stacktrace = stacktrace
+      end
+    end
+
     class ApiKeyEmptyError < Error; end
     class ApiKeyInvalidError < Error; end
     class InternalServerError < Error; end
     class JsonParseError < Error; end
     class NotFoundError < Error; end
     class UnauthorizedError < Error; end
-    class UnknownError < Error; end
+    class ApiError < Error; end
   end
 end

data/lib/algorithmia/requester.rb

@@ -8,7 +8,6 @@ module Algorithmia
       self.class.base_uri client.api_address
       @client = client
       @default_headers = {
-        'Content-Type' => 'application/json',
         'User-Agent' => 'Algorithmia Ruby Client'
       }
       unless @client.api_key.nil?
@@ -24,14 +23,20 @@ module Algorithmia
       response
     end
 
-    def post(endpoint, body, query: {}, headers: {})
+    def post(endpoint, body, query: {}, headers: {}, timeout: 60)
       headers = merge_headers(headers)
 
-      if headers['Content-Type'] == 'application/json'
-        body = body.to_json
+      headers['Content-Type'] ||= case
+        when body.kind_of?(String) && body.encoding == Encoding::ASCII_8BIT
+          'application/octet-stream'
+        when body.kind_of?(String)
+          'text/plain'
+        else
+          body = body.to_json
+          'application/json'
       end
 
-      response = self.class.post(endpoint, body: body, query: query, headers: headers)
+      response = self.class.post(endpoint, body: body, query: query, headers: headers, timeout: timeout)
       check_for_errors(response)
       response
     end
@@ -39,8 +44,14 @@ module Algorithmia
     def put(endpoint, body, query: {}, headers: {})
       headers = merge_headers(headers)
 
-      if headers['Content-Type'] == 'application/json'
-        body = body.to_json
+      headers['Content-Type'] ||= case
+        when body.kind_of?(String) && body.encoding == Encoding::ASCII_8BIT
+          'application/octet-stream'
+        when body.kind_of?(String)
+          'text/plain'
+        else
+          body = body.to_json
+          'application/json'
       end
 
       response = self.class.put(endpoint, body: body, query: query, headers: headers)
@@ -67,55 +78,27 @@ module Algorithmia
     def check_for_errors(response)
       if response.code >= 200 && response.code < 300
         if response.is_a?(Hash) and response['error']
-          parse_error_message(response) if response['error']
+          error = response['error']
+          raise Errors::AlgorithmError.new(error["message"], response, error["stacktrace"])
         end
         return
       end
 
+      message = response.dig("error", "message") if response.is_a?(Hash)
 
       case response.code
       when 401
-        if response.nil?
-          raise Errors::UnauthorizedError.new("The request you are making requires authorization. Please check that you have permissions & that you've set your API key.", nil)
-        end
-        raise Errors::UnauthorizedError.new(response["error"]["message"], response)
-      when 400
-        if response.nil?
-          raise Errors::NotFoundError.new("The request was invalid", nil)
-        end
-        parse_error_message(response)
+        message ||= "The request you are making requires authorization. Please check that you have permissions & that you've set your API key."
+        raise Errors::UnauthorizedError.new(message, response)
       when 404
-        if response.nil?
-          raise Errors::NotFoundError.new("The URI requested is invalid or the resource requested does not exist.", nil)
-        end
-        raise Errors::NotFoundError.new(response["error"]["message"], response)
-      when 500
-        if response.nil?
-          raise Errors::InternalServerError.new("Whoops! Something is broken.", nil)
-        end
-        raise Errors::InternalServerError.new(response["error"]["message"], response)
-      else
-        if response.nil?
-          raise Errors::UnknownError.new("An unknown error occurred", nil)
-        end
-        raise Errors::UnknownError.new("message: #{response["error"]["message"]} stacktrace: #{error["stacktrace"]}", response)
-      end
-    end
-
-    def parse_error_message(response)
-      error = response['error']
-
-      case error["message"]
-      when 'authorization required'
-        raise Errors::ApiKeyInvalidError.new("The API key you sent is invalid! Please set `Algorithmia::Client.api_key` with the key provided with your account.", response)
-      when 'Failed to parse input, input did not parse as valid json'
-        raise Errors::JsonParseError.new("Unable to parse the input. Please make sure it matches the expected input of the algorithm and can be parsed into JSON.", response)
+        message ||= "The URI requested is invalid or the resource requested does not exist."
+        raise Errors::NotFoundError.new(message, response)
+      when 500..599
+        message ||= "Whoops! Something is broken."
+        raise Errors::InternalServerError.new(message, response)
       else
-        if error["stacktrace"].nil?
-          raise Errors::UnknownError.new(error["message"], response)
-        else
-          raise Errors::UnknownError.new("message: #{error["message"]} stacktrace: #{error["stacktrace"]}", response)
-        end
+        message ||= "#{response.code} - an unknown error occurred"
+        raise Errors::ApiError.new(message, response)
       end
     end
 

data/lib/algorithmia/version.rb

@@ -1,3 +1,3 @@
 module Algorithmia
-  VERSION = "0.9.4"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: algorithmia
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Algorithmia
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-06 00:00:00.000000000 Z
+date: 2016-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -130,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A Ruby client for making API calls to Algorithmia