fredric 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4ab13d78501098fa5e1cafb3c9089f7deefac6f6
+  data.tar.gz: a8413186c16bff59656c73441a53fd94e75d0e11
+SHA512:
+  metadata.gz: 0f95fb9b07eb270839e83bd0af6c1545a447d98cf7fa3f9365cfeffd1006d9645d1c06ea69110de171132363195f2a5adf8655a0690a49202bd5f25d483d0ed5
+  data.tar.gz: a2d276a7191adce89b28e5a774c9e146c8d1205a3239decb56c3c42a6cd93e63bffac613987a67aeb9517ccb410013fa5d5d68f46bcdd35ae6700bdf275f687d

data/README.md

@@ -0,0 +1,203 @@
+FRED API Library and Command Line
+==================================================
+
+[![Gem](https://img.shields.io/gem/v/fredric.svg?style=flat-square)](https://rubygems.org/gems/fredric)
+[![Travis](https://img.shields.io/travis/DannyBen/fredric.svg?style=flat-square)](https://travis-ci.org/DannyBen/fredric)
+[![Code Climate](https://img.shields.io/codeclimate/github/DannyBen/fredric.svg?style=flat-square)](https://codeclimate.com/github/DannyBen/fredric)
+[![Gemnasium](https://img.shields.io/gemnasium/DannyBen/fredric.svg?style=flat-square)](https://gemnasium.com/DannyBen/fredric)
+
+---
+
+This gem provides both a Ruby library and a command line interface for the 
+[FRED][1] data service.
+
+---
+
+
+Install
+--------------------------------------------------
+
+```
+$ gem install fredric
+```
+
+Or with bundler:
+
+```ruby
+gem 'fredric'
+```
+
+
+Features
+--------------------------------------------------
+
+* Easy to use interface.
+* Use as a library or through the command line.
+* Access any FRED endpoint and option directly.
+* Display output as JSON, XML or CSV.
+* Save output to a file as JSON, XML or CSV.
+* Includes a built in file cache (disabled by default).
+
+
+Usage
+--------------------------------------------------
+
+First, require and initialize with your [FRED API Key][4].
+
+```ruby
+require 'fredric'
+fredric = Fredric::API.new api_key: 'y0urAP1k3y'
+```
+
+Now, you can access any FRED endpoint with any optional parameter, like
+this:
+
+```ruby
+result = fredric.get "series/observations", series_id: 'GNPCA'
+```
+
+In addition, for convenience, you can use the first part of the endpoint as
+a method name, like this:
+
+```ruby
+result = fredric.series 'observations', series_id: 'GNPCA'
+```
+
+In other words, these calls are the same:
+
+```ruby
+fredric.get 'endpoint', param: value
+fredric.endpoint, param: value
+```
+
+as well as these two:
+
+```ruby
+fredric.get 'endpoint/sub', param: value
+fredric.endpoint 'sub', param: value
+```
+
+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 = fredric.get! "series/ovservations", series_id: 'GNPCA'
+# => JSON string
+```
+
+You can get the response as CSV by calling `get_csv`:
+
+```ruby
+result = fredric.get_csv "series/overvations", series_id: 'GNPCA'
+# => CSV string
+```
+
+Fredric automatically decides which part of the data to convert to CSV.
+When there is an array in the response (for example, in the case of 
+`observations`), it will be used as the CSV data. Otherwise, the entire
+response will be treated as a single-row CSV.
+
+To save the output directly to a file, use the `save` method:
+
+```ruby
+fredric.save "filename.json", "series/overvations", series_id: 'GNPCA'
+```
+
+Or, to save CSV, use the `save_csv` method:
+
+```ruby
+fredric.save_csv "filename.csv", "series/overvations", series_id: 'GNPCA'
+```
+
+Debugging your request and adding "sticky" query parameters that stay with
+you for the following requests is also easy:
+
+```ruby
+fredric.debug = true
+fredric.param limit: 10, sort_order: :asc, file_type: :xml
+puts fredric.series 'observations', series_id: 'GNPCA'
+# => https://api.stlouisfed.org/fred/series/observations?api_key=...&file_type=xml&limit=10&sort_order=asc&series_id=GNPCA
+
+fredric.param sort_order: nil # remove param
+```
+
+
+Command Line
+--------------------------------------------------
+
+The command line utility `fred` acts in a similar way. To set your 
+FRED API Key, simply set it in the environment variables 
+`FREDRIC_KEY`:
+
+`$ export FREDRIC_KEY=y0urAP1k3y`
+
+These commands are available:
+
+`$ fred get [--csv] PATH [PARAMS...]` - print the output.  
+`$ fred pretty PATH [PARAMS...]` - print a pretty JSON.  
+`$ fred see PATH [PARAMS...]` - print a colored output.  
+`$ fred url PATH [PARAMS...]` - show the constructed URL.  
+`$ fred save [--csv] FILE PATH [PARAMS...]` - save the output to a file.  
+
+Run `fred --help` for more information, or view the [full usage help][2].
+
+Examples:
+
+```bash
+# Shows details about a data series
+$ fred see series series_id:GNPCA
+
+# Shows data as CSV
+$ fred get --csv series/observations series_id:GNPCA
+
+# Pass arguments that require spaces
+$ fred see series/search "search_text:consumer price index" limit:3
+
+# Saves a file
+$ fred save --csv result.csv series/search search_text:cpi limit:3
+
+# Shows the URL that Fredric has constructed, good for debugging
+$ fred url series/observations query:interest limit:5
+# => https://api.stlouisfed.org/fred/series/observations?api_key=ce1e45e6551de5db555a09b88d23682f&file_type=json&query=interest&limit=5
+
+```
+
+
+Caching
+--------------------------------------------------
+
+We are using the [WebCache][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 `WebCache` object directly at 
+a later stage.
+
+```ruby
+fredric = Fredric::API.new 'apikey', use_cache: true
+fredric = Fredric::API.new 'apikey', use_cache: true, cache_dir: 'tmp'
+fredric = Fredric::API.new 'apikey', use_cache: true, cache_life: 120
+
+# or 
+
+fredric = Fredric::API.new 'apikey'
+fredric.cache.enable
+fredric.cache.dir = 'tmp/cache'   # Change cache folder
+fredric.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:
+
+```
+$ export FREDRIC_CACHE_DIR=cache   # default: 'cache'
+$ export FREDRIC_CACHE_LIFE=120    # default: 3600 (1 hour)
+$ fredric get indices
+# => This call will be cached
+```
+
+
+[1]: https://research.stlouisfed.org/docs/api/fred/
+[2]: https://github.com/DannyBen/fredric/blob/master/lib/fredric/docopt.txt
+[3]: https://github.com/DannyBen/webcache
+[4]: https://research.stlouisfed.org/docs/api/api_key.html

data/bin/fred

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

data/lib/fredric.rb

@@ -0,0 +1,5 @@
+require 'fredric/version'
+require 'fredric/exceptions'
+require 'fredric/web_api'
+require 'fredric/api'
+require 'fredric/command_line'

data/lib/fredric/api.rb

@@ -0,0 +1,74 @@
+require 'json'
+require 'csv'
+
+module Fredric
+  # Provides access to all the FRED API endpoints
+  class API < WebAPI
+    attr_reader :api_key, :opts
+
+    def initialize(api_key, opts={})
+      @api_key = api_key
+
+      defaults = {
+        use_cache: false,
+        cache_dir: nil,
+        cache_life: nil,
+        base_url: "https://api.stlouisfed.org/fred"
+      }
+
+      opts = defaults.merge! opts
+      @opts = opts
+
+      cache.disable unless opts[:use_cache]
+      cache.dir = opts[:cache_dir] if opts[:cache_dir]
+      cache.life = opts[:cache_life] if opts[:cache_life]
+
+      param api_key: api_key if api_key
+      param file_type: :json
+
+      after_request do |response| 
+        begin
+          JSON.parse response, symbolize_names: true
+        rescue JSON::ParserError
+          response
+        end
+      end
+      
+      super opts[:base_url]
+    end
+
+    def get_csv(*args)
+      response = get *args
+
+      raise Fredric::BadResponse, "API said '#{response}'" if response.is_a? String
+      raise Fredric::BadResponse, "Got a #{response.class}, expected a Hash" unless response.is_a? Hash
+      
+      data = csv_node response
+
+      header = data.first.keys
+      result = CSV.generate do |csv|
+        csv << header
+        data.each { |row| csv << row.values }
+      end
+
+      result
+    end
+
+    def save_csv(file, *args)
+      data = get_csv *args
+      File.write file, data
+    end
+
+    private
+
+    # Determins which part of the data is best suited to be displayed 
+    # as CSV. 
+    # - In case there is an array in the data (like 'observations' or
+    #   'seriess'), it will be returned
+    # - Otherwise, we will use the entire response as a single row CSV
+    def csv_node(data)
+      arrays = data.keys.select { |key| data[key].is_a? Array }
+      arrays.empty? ? [data] : data[arrays.first]
+    end
+  end
+end

data/lib/fredric/command_line.rb

@@ -0,0 +1,122 @@
+require 'singleton'
+require 'docopt'
+require 'json'
+require 'awesome_print'
+
+module Fredric
+
+  # Handles the command line interface
+  class CommandLine
+    include Singleton
+
+    # 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
+        args = Docopt::docopt(doc, argv: argv, version: VERSION)
+        handle args
+      rescue Docopt::Exit, Fredric::MissingAuth => e
+        puts e.message
+      end
+    end
+
+    def fredric
+      @fredric ||= fredric!
+    end
+
+    private
+
+    attr_reader :path, :params, :file, :csv
+
+    def fredric!
+      Fredric::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 = translate_params args['PARAMS']
+      @file   = args['FILE']
+      @csv    = args['--csv']
+
+      unless api_key
+        raise Fredric::MissingAuth, "Missing Authentication\nPlease set FREDRIC_KEY=y0urAP1k3y"
+      end
+      
+      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
+      if csv
+        puts fredric.get_csv path, params
+      else
+        puts fredric.get! path, params
+      end
+    end
+
+    def save
+      if csv
+        success = fredric.save_csv file, path, params
+      else
+        success = fredric.save file, path, params
+      end
+      puts success ? "Saved #{file}" : "Saving failed"
+    end
+
+    def pretty
+      response = fredric.get path, params
+      puts JSON.pretty_generate response
+    end
+
+    def see
+      ap fredric.get path, params
+    end
+
+    def url
+      fredric.debug = true
+      puts fredric.get path, params
+      fredric.debug = false
+    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['FREDRIC_KEY']
+    end
+
+    def cache_dir
+      ENV['FREDRIC_CACHE_DIR']
+    end
+
+    def cache_life
+      ENV['FREDRIC_CACHE_LIFE']
+    end
+
+  end
+end

data/lib/fredric/docopt.txt

@@ -0,0 +1,61 @@
+Fredric
+
+Usage:
+  fred get [--csv] PATH [PARAMS...]
+  fred pretty PATH [PARAMS...]
+  fred see PATH [PARAMS...]
+  fred url PATH [PARAMS...]
+  fred save [--csv] FILE PATH [PARAMS...]
+  fred (-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 awesome-prints it.
+
+  url
+    Shows the URL constructed from the request.
+
+  save
+    Downloads data and saves it to a file.
+
+Parameters:
+  PATH:
+    This is the FRED API path, without the query string.
+    For example: `series` or `series/ovservations`.
+
+  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: limit:25 offset:3
+
+  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:
+  FREDRIC_KEY=y0urAP1k3y
+    Set Your FRED api key. This variable is required.
+
+  FREDRIC_CACHE_LIFE=360
+    Set the number of seconds to consider the cache fresh. This variable
+    it optional.
+
+  FREDRIC_CACHE_DIR=./cache
+    Set the cache directory. This variable is optional.
+    If both FREDRIC_CACHE_DIR and FREDRIC_CACHE_LIFE are not set, requests
+    will not be cached.
+
+Examples:
+  fred see series/observations series_id:GNPCA
+  fred get --csv series/observations series_id:GNPCA

data/lib/fredric/exceptions.rb

@@ -0,0 +1,4 @@
+module Fredric
+  class BadResponse < StandardError; end
+  class MissingAuth < StandardError; end
+end

data/lib/fredric/version.rb

@@ -0,0 +1,3 @@
+module Fredric
+  VERSION = "0.0.1"
+end

data/lib/fredric/web_api.rb

@@ -0,0 +1,93 @@
+require 'uri'
+require 'open-uri'
+require 'webcache'
+
+module Fredric
+
+  # 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

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: fredric
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Danny Ben Shitrit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docopt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: webcache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: runfile
+  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'
+- !ruby/object:Gem::Dependency
+  name: runfile-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !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 the Federal Reserve Economic Data service with a
+  command line interface
+email: db@dannyben.com
+executables:
+- fred
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/fred
+- lib/fredric.rb
+- lib/fredric/api.rb
+- lib/fredric/command_line.rb
+- lib/fredric/docopt.txt
+- lib/fredric/exceptions.rb
+- lib/fredric/version.rb
+- lib/fredric/web_api.rb
+homepage: https://github.com/DannyBen/fred
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.6
+signing_key: 
+specification_version: 4
+summary: FRED API Library and Command Line
+test_files: []