quata 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 580ff598467d94e05a1ab31b7c6a07907fcb618a
-  data.tar.gz: 2acff7751ca88d39a4f57ea0b7aa1b31c09234be
+  metadata.gz: bea40dfd8ef5efedbf07a77c86c87c6bfed9ecea
+  data.tar.gz: f4cf1fada28faca37b9182d764600a46d38215ab
 SHA512:
-  metadata.gz: 8edcf7a6387ccb52603351c03685f68b5c2d4c35d806a1a7693cd019f2b8af2df7285832642a16a8decae6c2e726a875db0a3cd877d286fb63827c3d4b28ff54
-  data.tar.gz: 45aa82466c670de3b0935c510f00c4ba6ef4113a94fb14608fbc7a0e7ee30a4fe56b2c42ae752a21e9f959c69f56ab7dc58e8bb1e3ec9e839af3bb364b370184
+  metadata.gz: 2a75b9169a54d446a29262a56cc77e9c32033c1013db752bca777dd0a93666d4c6d818e58d9647bfe7c07ddf3a35f387e62dfbff8c8356ebfa57715db27c03ec
+  data.tar.gz: 376ba5b8b932047a37fbd35e7d57aa37768a04e926162c0d58977e3ca3dbad3408224b5d38ef16c4252ec18a9777591b81c3245417e389f829ca7d159e5d2c50

data/README.md

@@ -1,98 +1,128 @@
-Quata - Quandl API Library and Command Line
-==================================================
-
----
-
-Quata is a lightweight ruby library for accessing Quandl with a command 
-line interface.
-
----
-
-Features
---------------------------------------------------
-
-* Access any Quandl endpoint directly.
-* Display output in various formats.
-* Save output to a file, including bulk downloads.
-
-Example
---------------------------------------------------
-
-First, require and initialize Quata with your API key
-
-```ruby
-require 'quata'
-quandl = Quandl.new 'Your API Key'
-```
-
-Now, you can access any Quandl endpoint with any optional parameter, like
-this:
-
-```ruby
-result = quandl.get "datasets/WIKI/AAPL", rows: 3 # => Hash
-```
-
-In addition, for convenience, you can use the first part of the endpoint as
-a method name, like this:
-
-```ruby
-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:
-
-```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
-```
-
-To save the output directly to a file, use the `save` method:
-
-```ruby
-result = quandl.save "aapl.csv", "datasets/WIKI/AAPL.csv", rows: 3
-```
-
-Command Line
---------------------------------------------------
-
-The command line utility `quata` acts similarly. It provides these commands:
-
-`$ quata get PATH [PARAMS...]` - print the output.  
-`$ quata pretty PATH [PARAMS...]` - print a pretty JSON.  
-`$ quata see PATH [PARAMS...]` - print a colored output.  
-`$ quata url PATH [PARAMS...]` - show the constructed URL.  
-`$ quata save FILE PATH [PARAMS...]` - save the output to a file.  
-
-Run `quata --help` for more information.
-
-Examples:
-```bash
-# Shows the first two databases
-quata see databases per_page:2
-
-# Or more compactly, as CSV
-quata get databases per_page:2
-
-# Prints CSV to screen (CSV is the default in the command line)
-$ quata get datasets/WIKI/AAPL
-
-# Prints JSON instead
-$ quata get datasets/WIKI/AAPL.json
-
-# Pass arguments using the same syntax - key:value
-$ quata get datasets/WIKI/AAPL rows:5
-
-# Pass arguments that require spaces
-$ quata get datasets.json "query:qqq index"
-
-# Prints a colored output
-$ quata see datasets/WIKI/AAPL rows:5
-
-# Saves a file
-$ quata save output.csv datasets/WIKI/AAPL rows:5
-
-# Shows the URL that Quata has constructed, good for debugging
-$ quata url datasets/WIKI/AAPL rows:5
-```
+Quata - Quandl API Library and Command Line
+==================================================
+
+[![Gem](https://img.shields.io/gem/v/quata.svg?style=flat-square)](https://rubygems.org/gems/quata)
+[![Travis](https://img.shields.io/travis/DannyBen/quata.svg?style=flat-square)](https://travis-ci.org/DannyBen/quata)
+[![Code Climate](https://img.shields.io/codeclimate/github/DannyBen/quata.svg?style=flat-square)](https://codeclimate.com/github/DannyBen/quata)
+[![Gemnasium](https://img.shields.io/gemnasium/DannyBen/quata.svg?style=flat-square)](https://gemnasium.com/DannyBen/quata)
+
+---
+
+Quata is a lightweight ruby library for accessing Quandl, and includes 
+a command line interface.
+
+It provides direct access to all of the [Quandl API][1] endpoints.
+
+---
+
+Features
+--------------------------------------------------
+
+* Easy to use interface.
+* Use as a library or through the command line.
+* Access any Quandl endpoint directly.
+* Display output in various formats.
+* Save output to a file, including bulk downloads.
+
+Example
+--------------------------------------------------
+
+First, require and initialize with your API key
+
+```ruby
+require 'quata'
+quandl = Quandl.new 'Your API Key'
+```
+
+Now, you can access any Quandl endpoint with any optional parameter, like
+this:
+
+```ruby
+result = quandl.get "datasets/WIKI/AAPL", rows: 3 # => Hash
+```
+
+In addition, for convenience, you can use the first part of the endpoint as
+a method name, like this:
+
+```ruby
+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:
+
+```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
+```
+
+To save the output directly to a file, use the `save` method:
+
+```ruby
+result = quandl.save "aapl.csv", "datasets/WIKI/AAPL.csv", rows: 3
+```
+
+Debugging your request and adding "sticky" query parameters that stay with
+you for the following requests is also easy:
+
+```ruby
+quandl.debug true
+quandl.param :rows, 10
+quandl.param :order, 'asc'
+puts quandl.get 'WIKI/AAPL'
+=> https://www.quandl.com/api/v3/WIKI/AAPL.json?auth_token=key&rows=10&order=asc
+```
+
+Command Line
+--------------------------------------------------
+
+The command line utility `quata` acts in a similar way. To use your Quandl
+API key, simply set it in the environment variables `QUANDL_KEY`:
+
+`$ export QUANDL_KEY=your_key`
+
+These commands are available:
+
+`$ quata get PATH [PARAMS...]` - print the output.  
+`$ quata pretty PATH [PARAMS...]` - print a pretty JSON.  
+`$ quata see PATH [PARAMS...]` - print a colored output.  
+`$ quata url PATH [PARAMS...]` - show the constructed URL.  
+`$ quata save FILE PATH [PARAMS...]` - save the output to a file.  
+
+Run `quata --help` for more information, or view the [full usage help][2].
+
+Examples:
+
+```bash
+# Shows the first two databases 
+$ quata see databases per_page:2
+
+# Or more compactly, as CSV
+$ quata get databases per_page:2
+
+# Prints CSV to screen (CSV is the default in the command line)
+$ quata get datasets/WIKI/AAPL
+
+# Prints JSON instead
+$ quata get datasets/WIKI/AAPL.json
+
+# Pass arguments using the same syntax - key:value
+$ quata get datasets/WIKI/AAPL rows:5
+
+# Pass arguments that require spaces
+$ quata get datasets.json "query:qqq index"
+
+# Prints a colored output
+$ quata see datasets/WIKI/AAPL rows:5
+
+# Saves a file
+$ quata save output.csv datasets/WIKI/AAPL rows:5
+
+# Shows the URL that Quata has constructed, good for debugging
+$ quata url datasets/WIKI/AAPL rows:5
+# => https://www.quandl.com/api/v3/datasets/WIKI/AAPL.csv?auth_token=YOUR_KEY&rows=5
+```
+
+[1]: https://www.quandl.com/blog/getting-started-with-the-quandl-api
+[2]: https://github.com/DannyBen/quata/blob/master/lib/quata/docopt.txt

data/lib/quata/command_line.rb

@@ -5,6 +5,7 @@ require 'awesome_print'
 
 module Quata
 
+  # Handles the command line interface
   class CommandLine
     include Singleton
 
@@ -15,6 +16,8 @@ module Quata
       @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=[])
       doc = File.read File.dirname(__FILE__) + '/docopt.txt'
       begin
@@ -27,6 +30,8 @@ module Quata
 
     private
 
+    # 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']
@@ -65,6 +70,8 @@ module Quata
       quandl.debug false
     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?
       result = {}

data/lib/quata/docopt.txt

@@ -0,0 +1,52 @@
+Quata
+
+Usage:
+  quata get PATH [PARAMS...]
+  quata pretty PATH [PARAMS...]
+  quata see PATH [PARAMS...]
+  quata url PATH [PARAMS...]
+  quata save FILE PATH [PARAMS...]
+  quata (-h|--help|--version)
+
+Commands:
+  get
+    Downloads data and prints it to screen as it. 
+  
+  pretty
+    Downloads data and prints it as a prettified JSON output.
+
+  see
+    Downloads data and prints it with a colored output.
+
+  url
+    Shows the URL constructed from the request.
+
+  save
+    Downloads data and saves it to a file.
+
+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
+
+  PARAMS:
+    An optional list of query string parameters, separated by a space, to 
+    send with the request. Each parameter should be in the format of 
+    key:value, for example: page:2 per_page:10
+
+  FILE:
+    Path to the output file.
+
+Examples:
+  quata get databases per_page:2
+  quata get datasets/WIKI/AAPL
+  quata get 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

data/lib/quata/quandl.rb

@@ -1,6 +1,6 @@
-# Quandl
 require 'json'
 
+# Provides access to all the Quandl API endpoints
 class Quandl < Quata::WebAPI
   attr_reader :api_key
 
@@ -15,7 +15,7 @@ class Quandl < Quata::WebAPI
     after_request do |response| 
       begin
         JSON.parse response, symbolize_names: true
-      rescue JSON::ParserError => e  
+      rescue JSON::ParserError
         response
       end
     end

data/lib/quata/version.rb

@@ -1,3 +1,3 @@
 module Quata
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/quata/web_api.rb

@@ -3,6 +3,8 @@ require 'open-uri'
 
 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, :debug_mode
 
@@ -46,7 +48,7 @@ module Quata
       @after_request_block = block
     end
 
-    # Return the response from teh API. 
+    # 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
@@ -94,7 +96,11 @@ module Quata
     private
 
     def http_get(url)
-      open(url).read
+      begin
+        open(url).read
+      rescue OpenURI::HTTPError => e
+        e.message
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quata
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Danny Ben Shitrit
@@ -136,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: Easy to use API for Quandl data service with a command line interface
 email: db@dannyben.com
 executables:
@@ -147,6 +161,7 @@ files:
 - bin/quata
 - lib/quata.rb
 - lib/quata/command_line.rb
+- lib/quata/docopt.txt
 - lib/quata/quandl.rb
 - lib/quata/version.rb
 - lib/quata/web_api.rb
@@ -175,3 +190,4 @@ signing_key:
 specification_version: 4
 summary: Quandl API Library and Command Line
 test_files: []
+has_rdoc: