nasdaq 0.3.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aed342089c070709ba3e3ae42d467da76f67428d3323d70c04c5a2c26131be7d
+  data.tar.gz: c33341051dc44b7351afbe394361c94a8b8d7fa193c1353e77ffff7e5a076de2
+SHA512:
+  metadata.gz: 4f281cf8f6c899edff90e6ed4f78ff0dda02f0c6b00c41204ffd7db1c2e1388dfc600a30628b69f2c8cabe08e0b885e38d5cebc61cbaa48a649cdbea8de0dac9
+  data.tar.gz: d4d1d7912ef5f5eeca413b26f37eaac3f1b579b772b3053c294c60c4ca20c602ba1376f22de9e2af88fdd3e324c9a3c7cae25836fbeecada41c0e675978e5780

data/README.md

@@ -0,0 +1,222 @@
+# Nasdaq Data Link API and Command Line
+
+[![Gem Version](https://badge.fury.io/rb/nasdaq.svg)](https://badge.fury.io/rb/nasdaq)
+[![Build Status](https://github.com/DannyBen/nasdaq/workflows/Test/badge.svg)](https://github.com/DannyBen/nasdaq/actions?query=workflow%3ATest)
+
+---
+
+Lightweight ruby library and command line interface for accessing the 
+[Nasdaq Data Link API][1] (formerly Quandl) with direct access to all of its
+endpoints.
+
+**This gem is not affiliated with Nasdaq or with Quandl.**
+
+---
+
+## Install
+
+```
+$ gem install nasdaq
+```
+
+Or with bundler:
+
+```ruby
+gem 'nasdaq'
+```
+
+
+## Features
+
+* Easy to use interface.
+* Use as a library or through the command line.
+* Access any of the API endpoints directly.
+* Display output in various formats.
+* Save output to a file.
+* Includes a built in file cache (disabled by default).
+
+
+## Usage
+
+First, require and initialize with your-api-key
+
+```ruby
+require 'nasdaq'
+nasdaq = Nasdaq::API.new 'your-api-key'
+```
+
+Now, you can access any API endpoint with any optional parameter, like
+this:
+
+```ruby
+result = nasdaq.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 = nasdaq.datasets "WIKI/AAPL", rows: 3
+```
+
+In other words, these calls are the same:
+
+```ruby
+nasdaq.get 'endpoint', param: value
+nasdaq.endpoint, param: value
+```
+
+as well as these two:
+
+```ruby
+nasdaq.get 'endpoint/sub', param: value
+nasdaq.endpoint 'sub', param: value
+```
+
+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
+result = nasdaq.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
+
+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 = nasdaq.get_csv "datasets/WIKI/AAPL", rows: 3
+# => CSV string
+```
+
+To save the output directly to a file, use the `save` method:
+
+```ruby
+nasdaq.save "filename.json", "datasets/WIKI/AAPL", rows: 3
+```
+
+Or, to save CSV, use the `save_csv` method:
+
+```ruby
+nasdaq.save_csv "filename.csv", "datasets/WIKI/AAPL", rows: 3
+```
+
+
+## Command Line
+
+The command line utility `nasdaq` acts in a similar way. To use your-api-key,
+simply set it in the environment variables `NASDAQ_KEY`:
+
+```
+$ export NASDAQ_KEY=your_key
+```
+
+These commands are available:
+
+```bash
+$ nasdaq get PATH [PARAMS...]        # print the output.  
+$ nasdaq pretty PATH [PARAMS...]     # print a pretty JSON.  
+$ nasdaq see PATH [PARAMS...]        # print a colored output.  
+$ nasdaq url PATH [PARAMS...]        # show the constructed URL.  
+$ nasdaq save FILE PATH [PARAMS...]  # save the output to a file.  
+```
+
+Run `nasdaq --help` for more information, or view the [full usage help][2].
+
+Examples:
+
+```bash
+# Shows the first two databases 
+$ nasdaq see databases per_page:2
+
+# Or more compactly, as CSV
+$ nasdaq get databases per_page:2
+
+# Prints CSV to screen (CSV is the default in the command line)
+$ nasdaq get datasets/WIKI/AAPL
+
+# Prints JSON instead
+$ nasdaq get datasets/WIKI/AAPL.json
+
+# Pass arguments using the same syntax - key:value
+$ nasdaq get datasets/WIKI/AAPL rows:5
+
+# Pass arguments that require spaces
+$ nasdaq get datasets.json "query:qqq index"
+
+# Prints a colored output
+$ nasdaq see datasets/WIKI/AAPL rows:5
+
+# Saves a file
+$ nasdaq save output.csv datasets/WIKI/AAPL rows:5
+
+# Shows the underlying URL for the request, good for debugging
+$ nasdaq url datasets/WIKI/AAPL rows:5
+# => https://data.nasdaq.com/api/v3/datasets/WIKI/AAPL.csv?api_key=YOUR_KEY&rows=5
+```
+
+## Caching
+
+The Nasdaq library 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 
+initialization, or by accessing the `Lightly` object directly at 
+a later stage.
+
+```ruby
+nasdaq = Nasdaq::API.new 'your-api-key', use_cache: true
+nasdaq = Nasdaq::API.new 'your-api-key', use_cache: true, cache_dir: 'tmp'
+nasdaq = Nasdaq::API.new 'your-api-key', use_cache: true, cache_life: 120
+
+# or 
+
+nasdaq = Nasdaq::API.new 'your-api-key'
+nasdaq.cache.enable
+nasdaq.cache.dir = 'tmp/cache'   # Change cache folder
+nasdaq.cache.life = 120          # Change cache life to 2 minutes
+```
+
+To enable caching for the command line, simply set one or both of 
+these environment variables:
+
+```bash
+$ export NASDAQ_CACHE_DIR=cache   # default: 'cache'
+$ export NASDAQ_CACHE_LIFE=120    # default: 3600 (1 hour)
+$ nasdaq get datasets/WIKI/AAPL
+# => This call will be cached
+```
+
+
+## Command Line Demo
+
+![Demo](https://raw.githubusercontent.com/DannyBen/nasdaq/master/demo.gif "Demo")
+
+[1]: https://docs.data.nasdaq.com/docs/getting-started
+[2]: https://github.com/DannyBen/nasdaq/blob/master/lib/nasdaq/docopt.txt
+[3]: https://github.com/DannyBen/lightly
+

data/bin/nasdaq

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require 'nasdaq'
+
+begin
+  Nasdaq::CommandLine.execute ARGV
+rescue Nasdaq::BadResponse => e
+  warn "#{e.class} - #{e.message}"
+end

data/lib/nasdaq/api.rb

@@ -0,0 +1,44 @@
+require 'apicake'
+
+module Nasdaq
+  # Provides access to all the Quandl API endpoints
+  class API < APICake::Base
+    base_uri 'https://data.nasdaq.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 = {})
+      if api_key.is_a?(Hash) && opts.empty?
+        opts = api_key
+        api_key = nil
+      end
+      @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 Nasdaq::BadResponse, "#{payload.response.code} #{payload.response.msg}"
+      end
+
+      payload.response.body
+    end
+  end
+end

data/lib/nasdaq/command_line.rb

@@ -0,0 +1,97 @@
+require 'super_docopt'
+require 'json'
+require 'lp'
+
+module Nasdaq
+  # Handles the command line interface
+  class CommandLine < SuperDocopt::Base
+    version VERSION
+    docopt File.expand_path 'docopt.txt', __dir__
+    subcommands %w[get pretty see url save]
+
+    attr_reader :path, :params, :file, :csv
+
+    def before_execute
+      @path   = args['PATH']
+      @params = translate_params args['PARAMS']
+      @file   = args['FILE']
+      @csv    = args['--csv']
+    end
+
+    def get
+      if csv
+        puts nasdaq.get_csv path, params
+      else
+        payload = nasdaq.get! path, params
+        puts payload.response.body
+      end
+    end
+
+    def save
+      success = if csv
+        nasdaq.save_csv file, path, params
+      else
+        nasdaq.save file, path, params
+      end
+      puts success ? "Saved #{file}" : 'Saving failed'
+    end
+
+    def pretty
+      payload = nasdaq.get path, params
+      puts JSON.pretty_generate payload
+    end
+
+    def see
+      lp nasdaq.get path, params
+    end
+
+    def url
+      puts nasdaq.url path, params
+    end
+
+    def nasdaq
+      @nasdaq ||= nasdaq!
+    end
+
+  private
+
+    def nasdaq!
+      API.new api_key, options
+    end
+
+    # Convert a params array like [key:value, key:value] to a hash like
+    # {key: value, key: value}
+    def translate_params(pairs)
+      result = {}
+      return result if pairs.empty?
+
+      pairs.each do |pair|
+        key, value = pair.split ':'
+        result[key.to_sym] = value
+      end
+      result
+    end
+
+    def options
+      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['NASDAQ_KEY']
+    end
+
+    def cache_dir
+      ENV['NASDAQ_CACHE_DIR']
+    end
+
+    def cache_life
+      ENV['NASDAQ_CACHE_LIFE']
+    end
+  end
+end

data/lib/nasdaq/docopt.txt

@@ -0,0 +1,68 @@
+Nasdaq Data Link
+
+Usage:
+  nasdaq get [--csv] PATH [PARAMS...]
+  nasdaq pretty PATH [PARAMS...]
+  nasdaq see PATH [PARAMS...]
+  nasdaq url PATH [PARAMS...]
+  nasdaq save [--csv] FILE PATH [PARAMS...]
+  nasdaq (-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 Nasdaq Data Link API path without the query string.
+    For example: datasets/WIKI/AAPL.
+
+  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.
+
+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:
+  NASDAQ_KEY=y0urAP1k3y
+    Set Your Nasdaq Data Link API key. This variable is optional.
+
+  NASDAQ_CACHE_LIFE=360
+    Set the number of seconds to consider the cache fresh. This variable
+    it optional.
+
+  NASDAQ_CACHE_DIR=./cache
+    Set the cache directory. This variable is optional.
+    If both NASDAQ_CACHE_DIR and NASDAQ_CACHE_LIFE are not set, requests
+    will not be cached.
+
+Examples:
+  nasdaq get databases per_page:2
+  nasdaq get datasets/WIKI/AAPL
+  nasdaq get --csv datasets/WIKI/AAPL rows:5
+  nasdaq get datasets source_code:WIKI query:* 
+  nasdaq get datasets query:oil
+  nasdaq url datasets/WIKI/AAPL rows:5
+  nasdaq save --csv output.csv datasets/WIKI/AAPL rows:5
+  nasdaq save output.json datasets/WIKI/AAPL rows:5
+  nasdaq pretty datasets "query:qqq index" per_page:2

data/lib/nasdaq/exceptions.rb

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

data/lib/nasdaq/version.rb

@@ -0,0 +1,3 @@
+module Nasdaq
+  VERSION = '0.3.0.rc1'
+end

data/lib/nasdaq.rb

@@ -0,0 +1,5 @@
+require 'nasdaq/version'
+require 'nasdaq/api'
+require 'nasdaq/command_line'
+require 'nasdaq/exceptions'
+require 'byebug' if ENV['BYEBUG']

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: nasdaq
+version: !ruby/object:Gem::Version
+  version: 0.3.0.rc1
+platform: ruby
+authors:
+- Danny Ben Shitrit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: apicake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: lp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: super_docopt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Easy to use API for the Nasdaq Data Link API with a command line interface
+email: db@dannyben.com
+executables:
+- nasdaq
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/nasdaq
+- lib/nasdaq.rb
+- lib/nasdaq/api.rb
+- lib/nasdaq/command_line.rb
+- lib/nasdaq/docopt.txt
+- lib/nasdaq/exceptions.rb
+- lib/nasdaq/version.rb
+homepage: https://github.com/DannyBen/nasdaq
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/DannyBen/nasdaq/issues
+  changelog_uri: https://github.com/DannyBen/nasdaq/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/DannyBen/nasdaq
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.4.9
+signing_key: 
+specification_version: 4
+summary: Nasdaq Data Link API Library and Command Line
+test_files: []