quata 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7784275cd18e6a826b6a74a9099cfa0270557779
-  data.tar.gz: c4f4655ae4b3436aa4f0fd289673d9c748682201
+  metadata.gz: ee013d7102f41a7111beeb91d3e281e979e5a6e5
+  data.tar.gz: bebc7f30bdf578fea50410f71478e33ae2399bbd
 SHA512:
-  metadata.gz: ff5064da6fd39ba64ef4b57df65f694d537129febcfbfb458065c7bf6c7e86e66260b7c8b91d6b9c375d95b89b3e1c15a3db563ac161cade625fc3fe28c47798
-  data.tar.gz: fe0b245fcfdfb8204b99f76223008460229d2bb0446fc1a9810b5b7ad7884c3a3069ee2f578062c0e57f0884e695ac7749ecbc814fd7e30275d4c46afc23f07b
+  metadata.gz: 248bc0587c9c8ad2f51ecfe11add8893a65216e8c5711ba8029e1d34cd55ddf444bc20c394593ea08607d685e945106c821989fdf358590d1ae86f83b1af307b
+  data.tar.gz: a76b18055f12c4cb24cf4941911bc3c07ea7730869c5c11e0369f22cacdd4440c092283724a223e1102f4ea213f33afb604773da7bdf4e2f76c3a95ee1598cd6

data/README.md

@@ -28,6 +28,7 @@ Or with bundler:
 gem 'quata'
 ```
 
+
 Features
 --------------------------------------------------
 
@@ -38,6 +39,7 @@ Features
 * Save output to a file, including bulk downloads.
 * Includes a built in file cache (disabled by default).
 
+
 Usage
 --------------------------------------------------
 
@@ -45,7 +47,7 @@ First, require and initialize with your API key
 
 ```ruby
 require 'quata'
-quandl = Quandl.new 'Your API Key'
+quandl = Quata::API.new 'Your API Key'
 ```
 
 Now, you can access any Quandl endpoint with any optional parameter, like
@@ -62,33 +64,73 @@ a method name, like this:
 result = quandl.datasets "WIKI/AAPL", rows: 3
 ```
 
-By default, you will get a ruby hash in return. If you wish to get the raw
-output, you can use the `get!` method:
+In other words, these calls are the same:
 
 ```ruby
-result = quandl.get! "datasets/WIKI/AAPL", rows: 3 # => JSON string
-result = quandl.get! "datasets/WIKI/AAPL.json", rows: 3 # => JSON string
-result = quandl.get! "datasets/WIKI/AAPL.csv", rows: 3 # => CSV string
+quandl.get 'endpoint', param: value
+quandl.endpoint, param: value
 ```
 
-To save the output directly to a file, use the `save` method:
+as well as these two:
 
 ```ruby
-quandl.save "aapl.csv", "datasets/WIKI/AAPL.csv", rows: 3
+quandl.get 'endpoint/sub', param: value
+quandl.endpoint 'sub', param: value
 ```
 
-Debugging your request and adding "sticky" query parameters that stay with
-you for the following requests is also easy:
+By default, you will get a ruby hash in return. If you wish to have more 
+control over the response, use the `get!` method instead:
 
 ```ruby
-quandl.debug = true
-quandl.param rows: 10, order: 'asc'
-puts quandl.datasets 'WIKI/AAPL'
-# => https://www.quandl.com/api/v3/datasets/WIKI/AAPL.json?auth_token=key&rows=10&order=asc
+result = quandl.get! "datasets/WIKI/AAPL", rows: 3
+
+# Request Object
+p payload.request.class
+# => HTTParty::Request
+
+# Response Object
+p payload.response.class
+# => Net::HTTPOK
+
+p payload.response.body
+# => JSON string
 
-quandl.param order: nil # remove param
+p payload.response.code
+# => 200
+
+p payload.response.msg
+# => OK
+
+# Headers Object
+p payload.headers
+# => Hash with headers
+
+# Parsed Response Object
+p payload.parsed_response
+# => Hash with HTTParty parsed response 
+#    (this is the content returned with #get)
 ```
 
+You can get the response as CSV by calling `get_csv`:
+
+```ruby
+result = quandl.get_csv "datasets/WIKI/AAPL", rows: 3
+# => CSV string
+```
+
+To save the output directly to a file, use the `save` method:
+
+```ruby
+quandl.save "filename.json", "datasets/WIKI/AAPL", rows: 3
+```
+
+Or, to save CSV, use the `save_csv` method:
+
+```ruby
+quandl.save_csv "filename.csv", "datasets/WIKI/AAPL", rows: 3
+```
+
+
 Command Line
 --------------------------------------------------
 
@@ -142,7 +184,7 @@ $ quata url datasets/WIKI/AAPL rows:5
 Caching
 --------------------------------------------------
 
-Quata uses the [WebCache][3] gem for automatic HTTP caching.
+Quata uses the [Lightly][3] gem for automatic HTTP caching.
 To take the path of least surprises, caching is disabled by default.
 
 You can enable and customize it by either passing options on 
@@ -150,13 +192,13 @@ initialization, or by accessing the `WebCache` object directly at
 a later stage.
 
 ```ruby
-quandl = Quandl.new 'Your API Key', use_cache: true
-quandl = Quandl.new 'Your API Key', use_cache: true, cache_dir: 'tmp'
-quandl = Quandl.new 'Your API Key', use_cache: true, cache_life: 120
+quandl = Quata::API.new 'Your API Key', use_cache: true
+quandl = Quata::API.new 'Your API Key', use_cache: true, cache_dir: 'tmp'
+quandl = Quata::API.new 'Your API Key', use_cache: true, cache_life: 120
 
 # or 
 
-quandl = Quandl.new 'Your API Key'
+quandl = Quata::API.new 'Your API Key'
 quandl.cache.enable
 quandl.cache.dir = 'tmp/cache'   # Change cache folder
 quandl.cache.life = 120          # Change cache life to 2 minutes
@@ -180,4 +222,4 @@ Terminalcast
 
 [1]: https://www.quandl.com/blog/getting-started-with-the-quandl-api
 [2]: https://github.com/DannyBen/quata/blob/master/lib/quata/docopt.txt
-[3]: https://github.com/DannyBen/webcache
+[3]: https://github.com/DannyBen/lightly

data/bin/quata

@@ -1,4 +1,9 @@
 #!/usr/bin/env ruby
 
 require 'quata'
-Quata::CommandLine.instance.execute ARGV
+
+begin
+  Quata::CommandLine.instance.execute ARGV
+rescue Quata::BadResponse => e
+  STDERR.puts "#{e.class} - #{e.message}"
+end

data/lib/quata.rb

@@ -1,4 +1,4 @@
 require 'quata/version'
-require 'quata/web_api'
-require 'quata/quandl'
+require 'quata/api'
 require 'quata/command_line'
+require 'quata/exceptions'

data/lib/quata/api.rb

@@ -0,0 +1,42 @@
+require 'apicake'
+
+module Quata
+  # Provides access to all the Quandl API endpoints
+  class API < APICake::Base
+    base_uri 'https://www.quandl.com/api/v3'
+
+    attr_reader :api_key
+
+    # TODO:
+    # - handle format
+
+    # Initializes the API with an optional API Key, and cache settings.
+    def initialize(api_key=nil, opts={})
+      opts, api_key = api_key, nil if api_key.is_a?(Hash) && opts.empty?
+      @api_key = api_key
+      cache.disable unless opts[:use_cache]
+      cache.dir = opts[:cache_dir] if opts[:cache_dir]
+      cache.life = opts[:cache_life] if opts[:cache_life]
+    end
+
+    # Returns a hash that will be merged into all query strings before
+    # sending the request to Quandl. This method is used by API Cake.
+    def default_query
+      { api_key: api_key } 
+    end
+
+    # Forwards all arguments to #get! and converts the JSON response to CSV
+    # If the response contains one or more arrays, the first array will be
+    # the CSV output. Otherwise, the response itself will be used.
+    def get_csv(path, params={})
+      path = "#{path}.csv"
+      payload = get! path, params
+
+      if payload.response.code != '200'
+        raise Quata::BadResponse, "#{payload.response.code} #{payload.response.msg}"
+      end
+
+      payload.response.body
+    end
+  end
+end

data/lib/quata/command_line.rb

@@ -9,13 +9,6 @@ module Quata
   class CommandLine
     include Singleton
 
-    attr_reader :quandl
-
-    def initialize
-      @quandl = Quandl.new api_key, options
-      @quandl.format = :csv
-    end
-
     # Gets an array of arguments (e.g. ARGV), executes the command if valid
     # and shows usage patterns / help otherwise.
     def execute(argv=[])
@@ -28,73 +21,90 @@ module Quata
       end
     end
 
+    def quandl
+      @quandl ||= quandl!
+    end
+
     private
 
+    attr_reader :path, :params, :file, :csv
+
+    def quandl!
+      API.new api_key, options
+    end
+
     # Called when the arguments match one of the usage patterns. Will 
     # delegate action to other, more specialized methods.
     def handle(args)
-      path   = args['PATH']
-      params = args['PARAMS']
-      file   = args['FILE']
-      
-      return get(path, params)        if args['get']
-      return pretty(path, params)     if args['pretty']
-      return see(path, params)        if args['see']
-      return url(path, params)        if args['url']
-      return save(file, path, params) if args['save']
+      @path   = args['PATH']
+      @params = translate_params args['PARAMS']
+      @file   = args['FILE']
+      @csv    = args['--csv']
+
+      return get    if args['get']
+      return pretty if args['pretty']
+      return see    if args['see']
+      return url    if args['url']
+      return save   if args['save']
     end
 
-    def get(path, params)
-      puts quandl.get! path, translate_params(params)
+    def get
+      if csv
+        puts quandl.get_csv path, params
+      else
+        payload = quandl.get! path, params
+        puts payload.response.body
+      end
     end
 
-    def save(file, path, params)
-      success = quandl.save file, path, translate_params(params)
+    def save
+      if csv
+        success = quandl.save_csv file, path, params
+      else
+        success = quandl.save file, path, params
+      end
       puts success ? "Saved #{file}" : "Saving failed"
     end
 
-    def pretty(path, params)
-      quandl.format = :json
-      response = quandl.get path, translate_params(params)
-      puts JSON.pretty_generate response
+    def pretty
+      payload = quandl.get path, params
+      puts JSON.pretty_generate payload
     end
 
-    def see(path, params)
-      quandl.format = :json
-      ap quandl.get path, translate_params(params)
+    def see
+      ap quandl.get path, params
     end
 
-    def url(path, params)
-      quandl.debug = true
-      puts quandl.get path, translate_params(params)
-      quandl.debug = false
+    def url
+      puts quandl.url path, params
     end
 
     # Convert a params array like [key:value, key:value] to a hash like
     # {key: value, key: value}
-    def translate_params(params)
-      return nil if params.empty?
+    def translate_params(pairs)
       result = {}
-      params.each do |param|
-        key, value = param.split ':'
-        result[key] = value
+      return result if pairs.empty?
+      pairs.each do |pair|
+        key, value = pair.split ':'
+        result[key.to_sym] = value
       end
       result
     end
 
-    def api_key
-      @api_key ||= ENV['QUANDL_KEY']
-    end
-
     def options
-      return {} unless cache_dir || cache_life
       result = {}
+      return result unless cache_dir || cache_life
+
       result[:use_cache] = true
       result[:cache_dir] = cache_dir if cache_dir
       result[:cache_life] = cache_life.to_i if cache_life
       result
     end
 
+    def api_key
+      ENV['QUANDL_KEY']
+    end
+
     def cache_dir
       ENV['QUANDL_CACHE_DIR']
     end

data/lib/quata/docopt.txt

@@ -1,11 +1,11 @@
 Quata
 
 Usage:
-  quata get PATH [PARAMS...]
+  quata get [--csv] PATH [PARAMS...]
   quata pretty PATH [PARAMS...]
   quata see PATH [PARAMS...]
   quata url PATH [PARAMS...]
-  quata save FILE PATH [PARAMS...]
+  quata save [--csv] FILE PATH [PARAMS...]
   quata (-h|--help|--version)
 
 Commands:
@@ -26,10 +26,8 @@ Commands:
 
 Parameters:
   PATH:
-    This is the Quandl API path, for example: datasets/WIKI/AAPL.
-    Format is defaulted to CSV in most cases, but you can override it like
-    you normally would by appending it at the end, like 
-    datasets/WIKI/AAPL.json
+    This is the Quandl API path without the query string.
+    For example: datasets/WIKI/AAPL.
 
   PARAMS:
     An optional list of query string parameters, separated by a space, to 
@@ -39,14 +37,32 @@ Parameters:
   FILE:
     Path to the output file.
 
+Flags:
+  --csv
+    When this flag is provided, the data will be converted to CSV before
+    it is displayed or saved. Note that this works only with endpoints that
+    have a 'data' attribute.
+
+Environment Variables:
+  QUANDL_KEY=y0urAP1k3y
+    Set Your Quandl api key. This variable is optional.
+
+  QUANDL_CACHE_LIFE=360
+    Set the number of seconds to consider the cache fresh. This variable
+    it optional.
+
+  QUANDL_CACHE_DIR=./cache
+    Set the cache directory. This variable is optional.
+    If both QUANDL_CACHE_DIR and QUANDL_CACHE_LIFE are not set, requests
+    will not be cached.
+
 Examples:
   quata get databases per_page:2
   quata get datasets/WIKI/AAPL
-  quata get datasets/WIKI/AAPL rows:5
+  quata get --csv datasets/WIKI/AAPL rows:5
   quata get datasets source_code:WIKI query:* 
   quata get datasets query:oil
-  quata get datasets.json "query:qqq index"
-  quata see datasets/WIKI/AAPL rows:5
   quata url datasets/WIKI/AAPL rows:5
-  quata save output.csv datasets/WIKI/AAPL rows:5
-  quata pretty datasets.json query:qqq
+  quata save --csv output.csv datasets/WIKI/AAPL rows:5
+  quata save output.json datasets/WIKI/AAPL rows:5
+  quata pretty datasets "query:qqq index" per_page:2

data/lib/quata/exceptions.rb

@@ -0,0 +1,3 @@
+module Quata
+  class BadResponse < StandardError; end
+end

data/lib/quata/version.rb

@@ -1,3 +1,3 @@
 module Quata
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quata
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-22 00:00:00.000000000 Z
+date: 2017-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docopt
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.6'
 - !ruby/object:Gem::Dependency
-  name: webcache
+  name: apicake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -160,11 +160,11 @@ files:
 - README.md
 - bin/quata
 - lib/quata.rb
+- lib/quata/api.rb
 - lib/quata/command_line.rb
 - lib/quata/docopt.txt
-- lib/quata/quandl.rb
+- lib/quata/exceptions.rb
 - lib/quata/version.rb
-- lib/quata/web_api.rb
 homepage: https://github.com/DannyBen/quata
 licenses:
 - MIT

data/lib/quata/quandl.rb

@@ -1,41 +0,0 @@
-require 'json'
-
-# Provides access to all the Quandl API endpoints
-class Quandl < Quata::WebAPI
-  attr_reader :api_key
-
-  def initialize(api_key=nil, opts={})
-    if api_key.is_a? Hash
-      opts = api_key
-      api_key = nil
-    end
-
-    @api_key = api_key
-
-    defaults = {
-      use_cache: false,
-      cache_dir: nil,
-      cache_life: nil,
-      base_url: 'https://www.quandl.com/api/v3'
-    }
-
-    opts = defaults.merge! opts
-
-    self.cache.disable unless opts[:use_cache]
-    self.cache.dir = opts[:cache_dir] if opts[:cache_dir]
-    self.cache.life = opts[:cache_life] if opts[:cache_life]
-
-    param auth_token: api_key if api_key
-    self.format = :json
-
-    after_request do |response| 
-      begin
-        JSON.parse response, symbolize_names: true
-      rescue JSON::ParserError
-        response
-      end
-    end
-    
-    super opts[:base_url]
-  end
-end

data/lib/quata/web_api.rb

@@ -1,93 +0,0 @@
-require 'uri'
-require 'open-uri'
-require 'webcache'
-
-module Quata
-
-  # A general purpose HTTP wrapper. This is poor man's HTTParty with
-  # dynamic methods.
-  class WebAPI
-    attr_reader :base_url, :after_request_block, :last_error
-    attr_accessor :debug, :format
-
-    def initialize(base_url)
-      @base_url = base_url
-    end
-
-    # Allow using any method as the first segment of the path
-    # object.user 'details' becomes object.get 'user/details'
-    def method_missing(method_sym, *arguments, &block)
-      get "/#{method_sym}", *arguments
-    end
-
-    # Add one or more parameter to the default query string. Good for 
-    # adding keys that are always needed, like API keys.
-    def param(params)
-      params.each do |key, value|
-        default_params[key] = value
-        default_params.delete key if value.nil?
-      end
-    end
-
-    def cache
-      @cache ||= WebCache.new
-    end
-
-    # Set a block to be executed after the request. This is called only when
-    # using `get` and not when using `get!`. Good for JSON decoding, for 
-    # example.
-    def after_request(&block)
-      @after_request_block = block
-    end
-
-    # Return the response from the API. 
-    def get(path, extra=nil, params={})
-      response = get! path, extra, params
-      response = after_request_block.call(response) if after_request_block
-      response
-    end
-
-    # Return the response from the API, without executing the after_request
-    # block.
-    def get!(path, extra=nil, params={})
-      if extra.is_a?(Hash) and params.empty?
-        params = extra
-        extra = nil
-      end
-      
-      path = "#{path}/#{extra}" if extra
-      url = construct_url path, params
-
-      return url if debug 
-      
-      response = cache.get(url)
-      @last_error = response.error
-      response.content
-    end
-
-    # Save the response from the API to a file.
-    def save(filename, path, params={})
-      response = get! path, nil, params
-      return response if debug
-      File.write filename, response.to_s
-    end
-
-    # Build a URL from all its explicit and implicit pieces.
-    def construct_url(path, params={})
-      path = "/#{path}" unless path[0] == '/'
-      all_params = default_params.merge params
-      result = "#{base_url}#{path}"
-      result = "#{result}.#{format}" if format && File.extname(result) == ''
-      unless all_params.empty?
-        all_params = URI.encode_www_form all_params
-        result = "#{result}?#{all_params}"
-      end
-      result
-    end
-
-    def default_params
-      @default_params ||= {}
-    end
-
-  end
-end