stocks 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14f408a3cbba0b2f34f833d80ffae64d800e96aa
-  data.tar.gz: 29f789edf2db4baeb8d0b4b33ce49a4330150f92
+  metadata.gz: e8a32a3160735bcc269c2da3567553382d56c810
+  data.tar.gz: b443130a3470403e57cd9bad82688c6b915c1f70
 SHA512:
-  metadata.gz: afef568d14ca8380dd14e52b2ce32dec19160ca4b72fd6d684c32c41764fe1f02164a5e5178d3f06a08b2afc45c0bccb444f1e3c33389e9f3a545929316881a4
-  data.tar.gz: 87a7fbbf6601f962f2e07aabbb22ec251cd172a6a23ed5f39ab7bbe19b05a25816497765db1e62a1df526bf2c3632e03f40d49760dd3a414e385bdb8ea8b3be0
+  metadata.gz: 59f678bceefd7903c2444c1e452a67243668f7c0a8bbe3e2b6b2254b24b6e876a7c66fc2fc25ab5ba069d1806fd062e192d6ee841105a4db4b689126a2f8af37
+  data.tar.gz: 066a218fe46f8a47647945a37fa1f15ec33b577f90505558c63d4443eb1c6fb9e65c3c4cada46a0bd54fd6d2defa560cde2079464aff2a1d33682e574e7c5c3c

data/lib/stocks.rb

@@ -2,6 +2,7 @@
 # License::   MIT
 
 # Require external libraries
+require 'lrucache'
 require 'yahoofinance'
 
 # Require all Stocks related files
@@ -9,54 +10,53 @@ require 'stocks/errors'
 require 'stocks/historical'
 require 'stocks/validators/exists'
 
-# TODO test this module
-# TODO add a caching layer with 1-min TTL
+# Provides an interface to do real-time analysis of stocks.
 module Stocks
-  COMMISSION_RANGE = {greater_than_or_equal_to: 0}
-  EPSILON = 0.00001
-  NA = 'N/A'
-  PRICE_RANGE = {greater_than: 0}
-  PRICE_SCALE = 5
-  PERCENTAGE_RANGE =  {greater_than: 0, less_than: 100}
-  QUANTITY_RANGE = {greater_than: 0}
-
-  # TODO move to another lib module
-  def self.equal?(value, other)
-    (value-other).abs < EPSILON
-  end
-
   # Determines whether or not the provided symbol exists.
   #
-  # * *Args*:
-  #   - +symbol+ The symbol to evaluate
-  # * *Returns*:
-  #   - Whether or not the provided symbol exists
+  # ===== *Args*
+  # - +symbol+ The symbol to evaluate for existence
+  # ===== *Returns*
+  # Whether or not the provided symbol exists
   def self.exists?(symbol)
-    quote(symbol.upcase, [:date])[:date] != NA
+    symbol.upcase!
+    EXISTS_CACHE.fetch(symbol) { !quote(symbol, [:date])[:date].nil? }
+  end
+
+  # Raises an exception if the provided symbol does not exist.
+  #
+  # ===== *Args*
+  # - +symbol+ The symbol to evaluate for existence
+  # ===== *Raises*
+  # - +RetrievalError+ If the provided symbol does not exist
+  # Whether or not the provided symbol exists
+  def self.exists!(symbol)
+    raise RetrievalError.new(symbol) if !Stocks.exists?(symbol)
   end
 
   # Fetches the last trade for the provided symbol.
   #
-  # * *Args*:
-  #   - +symbol+ The symbol to evaluate
-  # * *Returns*:
-  #   - The last trade for the provided symbol
-  # * *Raises*:
-  #   - +RetrievalError+ If the provided symbol does not exist
+  # ===== *Args*
+  # - +symbol+ The symbol to evaluate
+  # ===== *Returns*
+  # The last trade for the provided symbol
+  # ===== *Raises*
+  # - +RetrievalError+ If the provided symbol does not exist
   def self.last_trade(symbol)
     last_trade = quote(symbol)[:lastTrade]
-    raise RetrievalError.new("Could not retrieve last trade for '#{symbol}'") if last_trade == 0 or last_trade == NA
+    raise RetrievalError.new(symbol) if last_trade.nil?
     last_trade
   end
 
   private
 
+  EXISTS_CACHE = LRUCache.new(max_size: 500, ttl: 1.month) # :nodoc:
+
   def self.quote(symbol, fields = [:lastTrade])
     data = {}
-    # TODO use the fields map to decide which method to use
     standard_quote = YahooFinance::get_standard_quotes(symbol)[symbol]
     fields.each do |field|
-      data[field] = standard_quote.send(field) rescue NA
+      data[field] = standard_quote.send(field) rescue nil
     end
     data
   end

data/lib/stocks/errors.rb

@@ -2,10 +2,47 @@
 # License::   MIT
 
 module Stocks
-  class RetrievalError < RuntimeError
-    def new(message)
-      super(message)
+  # An error raised when data retrieval fails
+  class RetrievalError < ArgumentError
+    def initialize(symbol) # :nodoc:
+      super(self.class.message(symbol))
     end
+
+    # Generates the error message that is to be displayed.
+    #
+    # ===== *Args*
+    # - +symbol+ The symbol to insert into the error message
+    # ===== *Returns*
+    # An error message representing the error
+    def self.message(symbol)
+      ERROR_MESSAGE % symbol
+    end
+
+    private
+
+    ERROR_MESSAGE = "Unable to retrieve quote for '%s'" # :nodoc:
+  end
+
+  # An error raised when an unsupported value is provided
+  class UnsupportedError < ArgumentError
+    def initialize(provided, supported) # :nodoc:
+      super(self.class.message(provided, supported))
+    end
+
+    # Generates the error message that is to be displayed.
+    #
+    # ===== *Args*
+    # - +provided+ The value that was provided
+    # - +provided+ A list of valid values
+    # ===== *Returns*
+    # An error message representing the error
+    def self.message(provided, supported)
+      ERROR_MESSAGE % [provided, supported.map { |s| "'#{s}'" }.join(', ')]
+    end
+
+    private
+
+    ERROR_MESSAGE = "'%s' is not supported. Try %s" # :nodoc:
   end
 end
 

data/lib/stocks/historical.rb

@@ -4,6 +4,7 @@
 require 'active_support/core_ext/integer/time'
 
 module Stocks
+  # Provides an interface to do historical analysis of stocks.
   module Historical
     PERIODS = {
       one_month: {label: '1 Month', offset: 1.months},
@@ -11,29 +12,66 @@ module Stocks
       six_months: {label: '6 Months', offset: 6.months},
       one_year: {label: '1 Year', offset: 1.years},
       five_years: {label: '5 Years', offset: 5.years}
-    }
+    } # :nodoc:
 
-    def self.macd(symbol, days)
+    # Calculates the Moving Average Convergence Divergence.
+    #
+    # ===== *Args*
+    # +symbol+ The symbol for which to calculate the MACD
+    # +days+ The number of days for which to calculate the MACD
+    # ===== *Returns*
+    # An array of values for the number of days provided
+    # ===== *Raises*
+    # - +RetrievalError+ If the provided symbol does not exist
+    def self.macd(symbol, days = DEFAULT_DAYS)
       sma12 = self.sma(symbol, 12, days)
       sma26 = self.sma(symbol, 26, days)
       (0...days).collect { |day| sma12[day] - sma26[day] }
     end
 
-    def self.sma(symbol, periods, days)
+    # Calculates the Simple Moving Average.
+    #
+    # ===== *Args*
+    # +symbol+ The symbol for which to calculate the SMA
+    # +periods+ The number of periods to include in the average
+    # +days+ The number of days for which to calculate the SMA
+    # ===== *Returns*
+    # An array of averages for the number of days provided
+    # ===== *Raises*
+    # - +RetrievalError+ If the provided symbol does not exist
+    def self.sma(symbol, days = DEFAULT_DAYS, periods = DEFAULT_PERIODS)
+      Stocks.exists!(symbol)
+
       sma = []
-      days.downto(1).each do |day|
+      (days <= 0 ? DEFAULT_DAYS : days).downto(1).each do |day|
         date = Date.today - day
-        quotes = YahooFinance::get_HistoricalQuotes(symbol, date - periods, date)
+        quotes = YahooFinance::get_HistoricalQuotes(symbol, date - (periods <= 0 ? DEFAULT_PERIODS : periods), date)
         sma << quotes.reduce(0) { |total, q| total += q.close } / quotes.size
       end
       sma
     end
 
+    # Determines whether or not the provided symbol exists.
+    #
+    # ===== *Args*
+    # +symbol+ The symbol for which to retrieve a quote
+    # +period+ The period the quote should span
+    # ===== *Returns*
+    # A quote for the provided symbol over the provided period
+    # ===== *Raises*
+    # - +RetrievalError+ If the provided symbol does not exist
+    # - +UnsupportedError+ If the provided period is not supported
     def self.quote(symbol, period)
-      raise ArgumentError.new("Period must be provided for a historical quote") if period.nil?
-      raise ArgumentError.new("'#{period}' is not a supported period") if !PERIODS.has_key?(period.to_sym)
+      Stocks.exists!(symbol)
+      raise UnsupportedError.new(period, PERIODS.keys) if !PERIODS.has_key?(period.try(:to_sym))
+
       YahooFinance::get_HistoricalQuotes(symbol, Date.today - PERIODS[period.to_sym][:offset], Date.today)
     end
+
+    private
+
+    DEFAULT_DAYS = 7 # :nodoc:
+    DEFAULT_PERIODS = 7 # :nodoc:
   end
 end
 

data/lib/stocks/validators.rb

@@ -0,0 +1,10 @@
+# Author::    Matt Fornaciari (mailto:mattforni@gmail.com)
+# License::   MIT
+
+module Stocks
+  # Provides an interface for validating ActiveRecord models.
+  module Validators
+    require 'active_model/validator'
+  end
+end
+

data/lib/stocks/validators/exists.rb

@@ -1,16 +1,46 @@
 # Author::    Matt Fornaciari (mailto:mattforni@gmail.com)
 # License::   MIT
 
-require 'active_model/validator'
-
-module Stocks 
+module Stocks
   module Validators
+    # An ActiveRecord validator which validates that an attribute on a model is a
+    # valid ticker symbol. The default attribute is +:symbol+ but may be specified
+    # by defining +symbol_field+ when declaring the validator.
+    #
+    # Example Usage:
+    #
+    #   require 'stocks/validators/exists'
+    #
+    #   class Position < ActiveRecord::Base
+    #     validates_with Stocks::Validators::Exists, symbol_field: :field_name
+    #   end
     class Exists < ActiveModel::Validator
+
+      # Generates the error message that is inserted into +record.errors+.
+      #
+      # ===== *Args*
+      # - +symbol+ The symbol to insert into the error message
+      # ===== *Returns*
+      # An error message representing the validation failure
+      def self.message(symbol)
+        ERROR_MESSAGE % symbol
+      end
+
+      # Validates that a record have a valid symbol.
+      #
+      # ===== *Args*
+      # - +record+ The record to validate
       def validate(record)
-        if (!Stocks.exists?(record.symbol))
-          record.errors[:symbol] << "'#{record.symbol}' is not a valid symbol."
+        field = options[:symbol_field] || :symbol
+        symbol = record.send(field)
+        if (!Stocks.exists?(symbol))
+          record.errors[field] << self.class.message(symbol)
         end
       end
+
+      private
+
+      ERROR_MESSAGE = '%s is not a valid ticker symbol.' # :nodoc:
     end
   end
 end

metadata

@@ -1,57 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: stocks
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Matthew Fornaciari
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-05 00:00:00.000000000 Z
+date: 2015-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: yahoofinance
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '4'
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: yahoofinance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
-  type: :development
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: lrucache
+  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: '4.2'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 description: A programmatic approach to performing various financial analysis
 email: mattforni@gmail.com
 executables: []
@@ -75,6 +103,7 @@ files:
 - lib/stocks.rb
 - lib/stocks/errors.rb
 - lib/stocks/historical.rb
+- lib/stocks/validators.rb
 - lib/stocks/validators/exists.rb
 homepage: http://rubygems.org/gems/stocks
 licenses: