yahoo_stock 1.0.2

data/History.txt

@@ -0,0 +1,61 @@
+=== 0.1.1 2009-08-31
+
+* 1 major enhancement:
+  * Initial release
+
+=== 0.1.2 2009-09-01
+
+* 1 minor change:
+  * changed method name YahooStock::Quote#get_data to get
+
+=== 0.1.3 2009-09-05
+
+* 3 additions:
+  * adds a new class called YahooStock::ScripSymbol that allows to 
+    find out the stock symbol for a company
+  * adds specs for previous and new code
+  * adds 
+
+=== 0.1.4 2009-09-05
+
+* 2 changes related with ruby 1.9:
+  * modifies quote class to be compatible with ruby 1.9
+  * modifies interface class to be compatible with 1.9
+
+=== 0.1.5 2009-09-06
+
+* 1 changes related with ruby 1.9:
+  * modifies ScripSymbol class to be compatible with ruby 1.9
+
+=== 0.1.6 2009-09-07
+
+* 1 addition:
+  * adds convenience methods Quote#realtime, standard and extended to 
+    fetch relevant stock values
+
+=== 1.0.1 2009-09-10
+
+* 1 addition:
+  * adds feature to retreive historical stock data
+
+=== 1.0.2 2009-10-04
+Major changes in the public API. Check the README.rdoc file and individual classes for more information
+
+* 8 addition:
+  * adds YahooStock::Interface::History
+  * adds YahooStock::Interface::Quote
+  * adds YahooStock::Interface::ScripSymbol
+  * adds YahooStock::Result as a superclass for all formatter classes
+  * adds array format, Result::ArrayFormat, to generate results as an array
+  * adds hash format, Result::ArrayFormat, to generate results as key value pairs
+  * adds base class as parent for public facing classes
+  * adds observers to check when it is required to send request to yahoo again to get fresh data
+
+* 7 changes:
+  * changes YahooStock::Interface to be the main interface class. Other interface classes will inherit from this
+  * changes YahooStock::ScripSymbol to use YahooStock::Interface::ScripSymbol
+  * removes all history interface logic from YahooStock::History and uses YahooStock::Interface::History
+  * changes YahooStock::Quote, YahooStock::History, YahooStock::ScripSymbol to extend from YahooStock::Base
+  * sorts url parameters before sending request to yahoo
+  * YahooInterface::Quote#realtime, extended, and standard methods should return self to allow calling different format output method calls
+  * do not discard any empty values when finding scrip symbol options for a company as this interferes with different format options

data/Manifest.txt

@@ -0,0 +1,29 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/yahoo_stock/base.rb
+lib/yahoo_stock/history.rb
+lib/yahoo_stock/interface.rb
+lib/yahoo_stock/interface/history.rb
+lib/yahoo_stock/interface/quote.rb
+lib/yahoo_stock/interface/scrip_symbol.rb
+lib/yahoo_stock/quote.rb
+lib/yahoo_stock/result.rb
+lib/yahoo_stock/result/array_format.rb
+lib/yahoo_stock/result/hash_format.rb
+lib/yahoo_stock/scrip_symbol.rb
+lib/yahoo_stock.rb
+spec/spec_helper.rb
+spec/yahoo_stock/base_spec.rb
+spec/yahoo_stock/interface_spec.rb
+spec/yahoo_stock/interface/history_spec.rb
+spec/yahoo_stock/interface/quote_spec.rb
+spec/yahoo_stock/interface/scrip_symbol_spec.rb
+spec/yahoo_stock/quote_spec.rb
+spec/yahoo_stock/history_spec.rb
+spec/yahoo_stock/result_spec.rb
+spec/yahoo_stock/result/array_format_spec.rb
+spec/yahoo_stock/result/hash_format_spec.rb
+spec/yahoo_stock/scrip_symbol_spec.rb
+

data/README.rdoc

@@ -0,0 +1,142 @@
+= yahoo_stock
+
+* http://github.com/nas/yahoo_stock
+
+== DESCRIPTION:
+
+Provides an interface to yahoo finance to get stock related data. For instance, latest trade related data, volume, 50 day moving average, market cap, etc, virtually any thing that yahoo finance provides.
+
+If you don't know the stock / scrip symbol of the company then you can find that out by using the YahooStock::ScripSymbol class. The methods are mentioned in the Usage section below. For instance, YHOO for yahoo, GOOG for google, etc. 
+The kind of parameters to be passed can be found after initializing the 
+YahooStock::Quote object and passing valid_parameters message, example is given below in the USAGE section.
+
+== USAGE:
+
+require 'rubygems'
+
+require 'yahoo_stock'
+
+* Initialize quote object
+
+quote = YahooStock::Quote.new(:stock_symbols => ['YHOO', 'GOOG'])
+
+* To view the valid parameters that can be passed
+
+quote.valid_parameters
+
+* To view the current parameters used
+
+quote.current_parameters
+
+* To view the current stock symbols used
+
+quote.current_symbols
+
+* To add more stocks to the list
+
+quote.add_symbols('MSFT', 'AAPL')
+
+* To remove stocks from list
+
+quote.remove_symbols('MSFT', 'AAPL')
+
+* To find data for all stocks, this will give a string containing all values
+
+quote.results
+
+	to return an array instead of a string use:
+
+	quote.results(:to_array).output
+	
+	to return a hash, use:
+	
+	quote.results(:to_hash).output
+	
+	to store results in a file, use:
+	
+	quote.results.store('filename')
+
+* To find out the stock symbol for a company
+  
+symbol = YahooStock::ScripSymbol.new('Yahoo')
+
+* To find all symbols for that company, this will give a string containing all values
+
+symbol.results
+
+	to return an array instead of a string use:
+
+	symbol.results(:to_array).output
+	
+	to return a hash, use:
+	
+	symbol.results(:to_hash).output
+	
+	to store results in a file, use:
+	
+	symbol.results.store('filename')
+
+* To find symbols for multiple companies
+
+symbols = YahooStock::ScripSymbol.results('Yahoo', 'Company1', 'Company3')
+
+* to get the result in a string
+
+symbols.output
+
+* to store output in a file
+
+symbols.store('filename')
+
+* To find historical data for a stock
+
+  history = YahooStock::History.new(:stock_symbols => 'yhoo', :start_date => Date.today-20, end_date => Date.today -2)
+  
+  	to return an array instead of a string use:
+
+	history.results(:to_array).output
+	
+	to return a hash, use:
+	
+	history.results(:to_hash).output
+	
+	to store results in a file, use:
+	
+	history.results.store('filename')
+
+== INSTALL:
+
+gem sources -a http://gems.github.com
+
+sudo gem install nas-yahoo_stock
+
+== TESTS:
+
+Tests are written using Rspec 1.2.2
+
+To run all tests 'rake spec' from the root directory
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Nasir Jamal
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/yahoo_stock'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'yahoo_stock' do
+  self.developer 'Nasir Jamal', 'nas35_in@yahoo.com'
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]

data/lib/yahoo_stock.rb

@@ -0,0 +1,19 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'date'
+require 'yahoo_stock/base.rb'
+require 'yahoo_stock/interface.rb'
+require 'yahoo_stock/history.rb'
+require 'yahoo_stock/scrip_symbol.rb'
+require 'yahoo_stock/quote.rb' 
+require 'yahoo_stock/interface/quote.rb'
+require 'yahoo_stock/interface/history.rb'
+require 'yahoo_stock/interface/scrip_symbol.rb'
+require 'yahoo_stock/result.rb'
+require 'yahoo_stock/result/array_format.rb'
+require 'yahoo_stock/result/hash_format.rb'
+
+module YahooStock
+  VERSION = '1.0.2'
+end

data/lib/yahoo_stock/base.rb

@@ -0,0 +1,37 @@
+# YahooStock::Base class to find and output results.
+module YahooStock
+  
+  class Base
+    
+    def initialize(interface)
+      @interface = interface
+    end
+    
+    # Uses the values method of the interface used to show results .
+    def find
+      @interface.values
+    end
+    
+    # Method takes one parameter type or a block
+    # type uses the existing format classes namespaced in Result::ClassName.output
+    # e.g. * results :to_array
+    #      * results {YourSpecialFormat.method_name}
+    # to store
+    def results(type=nil, &block)
+      if block_given?
+        yield
+      else
+        return YahooStock::Result.new(find) if !type || type.to_s.empty?
+        format_type = type.to_s.sub(/^to_/,'').strip
+        return YahooStock::Result.const_get("#{format_type.capitalize}Format").new(find){data_attributes}
+      end
+    end
+    
+    # Abstract method
+    def data_attributes
+      raise 'Abstract method called. Use the subclass data_attributes method'
+    end
+    
+  end
+  
+end

data/lib/yahoo_stock/history.rb

@@ -0,0 +1,32 @@
+module YahooStock
+  class History < Base
+    
+    class HistoryError < RuntimeError; end
+    
+    def initialize(options)
+      unless options.is_a?(Hash)
+        raise HistoryError, 'A hash of start_date, end_date and stock_symbol is expected as parameters'
+      end
+      @interface = YahooStock::Interface::History.new(options)
+    end
+    
+    def find
+      @find_values = super()
+      @find_values.sub(/Date.*\s/,'') if @find_values
+    end
+    
+    def values_with_header
+      @interface.values
+    end
+    
+    def data_attributes
+      return unless values_with_header
+      data_attributes = /Date.*\s/.match(values_with_header)
+      unless data_attributes.nil?
+        @data_attributes = data_attributes[0].sub(/\s*$/,'').split(',')
+        @data_attributes.map &:strip
+      end
+    end
+    
+  end
+end

data/lib/yahoo_stock/interface.rb

@@ -0,0 +1,71 @@
+=begin
+  Main class to interface with Yahoo
+=end
+
+require 'net/http'
+require 'observer'
+module YahooStock
+   # ==DESCRIPTION:
+   # 
+   # Class to generate the right url and interface with yahoo
+   #
+  class Interface
+    include Observable
+    class InterfaceError < RuntimeError ; end
+
+    BASE_URLS = {
+      :quote        => "http://download.finance.yahoo.com/d/quotes.csv",
+      :history      => "http://ichart.finance.yahoo.com/table.csv",
+      :scrip_symbol => "http://finance.yahoo.com/lookup/all"
+    } unless defined?(BASE_URLS)
+    
+    attr_accessor :base_url, :uri_parameters
+    
+    # Send request to the uri and get results
+    def get
+      begin
+        response = Net::HTTP.get_response(URI.parse(uri))
+      rescue => e
+        raise InterfaceError, "#{e.message}\n\n#{e.backtrace}"
+      end
+      response.code == '200' ? response.body : response_error(response)
+    end
+    
+    # Generates full url to connect to yahoo
+    def uri
+      raise InterfaceError, 'Base url is require to generate full uri.' unless @base_url
+      return @base_url if @uri_parameters.nil? || @uri_parameters.empty?
+      params_with_values = []
+      @uri_parameters.each {|k,v| params_with_values << "#{k}=#{v}"}
+      @base_url+'?'+params_with_values.join('&')
+    end
+    
+    # Get result string
+    def values
+      @values ||= get
+    end
+    
+    def update
+      @values = nil
+    end
+    
+    private 
+    
+    # Generate error for debugging when something goes wrong while sending
+    # request to yahoo
+    def response_error(response)
+      trace = "Response \n\nbody : #{response.body}\n\ncode: #{response.code}\n\nmessage: #{response.message}"
+      case @base_url
+        when BASE_URLS[:quote]
+          raise InterfaceError, "Error :: Could not get stock data \n\n#{trace}"
+        when BASE_URLS[:history]
+          raise InterfaceError, "Error :: Could not get historical data \n\n#{trace}"
+        when BASE_URLS[:scrip_symbol]
+          raise InterfaceError, "Error :: Could not get stock symbol \n\n#{trace}"
+        else
+          raise InterfaceError, "Error connecting to #{@base_url} \n\n#{trace}"
+      end
+    end
+    
+  end
+end

data/lib/yahoo_stock/interface/history.rb

@@ -0,0 +1,186 @@
+=begin
+params:
+ s=stock symbol
+ a=month-1
+ b=date
+ c=year
+ d=month-1
+ e=date
+ f=year
+ g=d or w or m
+ ignore=.csv
+
+=end
+
+module YahooStock
+   # ==DESCRIPTION:
+   # 
+   # Class to generate the right url and interface with yahoo to get history of a stock
+   #
+  class Interface::History < Interface
+
+    class HistoryError < RuntimeError ; end
+    
+    attr_reader :stock_symbol, :start_date, :end_date, :interval
+    
+    # The options parameter expects a hash with 4 key value pairs
+    #
+    # :stock_symbol => 'goog', :start_date => Date.today-30,
+    # :end_date => Date.today-10, :interval => :weekly
+    #
+    # The interval option accepts :daily, :monthly and :weekly values
+    #
+    # The interval key is optional, if not used then by default uses :daily
+    #
+    # and provides daily history for the specified date range
+    #
+    def initialize(options)
+      @base_url = BASE_URLS[:history]
+      validate_keys(options)
+      
+      @stock_symbol = options[:stock_symbol]
+      @start_date   = options[:start_date]
+      @end_date     = options[:end_date]
+      @interval     = options[:interval].nil? ? :daily : options[:interval].to_sym
+      
+      validate_interval_values(options[:interval]) if options[:interval]
+      validate_stock_symbol(options)
+      validate_start_date(options)
+      validate_end_date(options)
+      validate_history_range
+    end
+    
+    # Make sure that stock symbol is not nil or an empty string before setting it
+    def stock_symbol=(stock_symbol)
+      validate_stock_symbol_attribute(stock_symbol)
+      @stock_symbol = stock_symbol
+    end
+    
+    # Before setting start date
+    #   - Make sure that it is of type date
+    #   - Make sure that it is before the end date
+    def start_date=(start_date)
+      validate_start_date_type(start_date)
+      validate_history_range(start_date)
+      @start_date = start_date
+    end
+    
+    # Before setting end date
+    #   - Make sure that it is of type date
+    #   - Make sure that it is after the start date
+    def end_date=(end_date)
+      validate_end_date_type(end_date)
+      validate_history_range(start_date, end_date)
+      @end_date = end_date
+    end
+    
+    # Set interval to specify whether daily, weekly or monthly histroy required
+    def interval=(interval)
+      validate_interval_values(interval)
+      @interval = interval
+    end
+    
+    # Generate full uri with the help of uri method of the superclass
+    def uri
+      frequency = case interval
+                    when :daily   : 'd'
+                    when :weekly  : 'w'
+                    when :monthly : 'm'
+                  end
+      @uri_parameters = {:a => sprintf("%02d", start_date.month-1), :b => start_date.day, 
+                         :c => start_date.year, :d => sprintf("%02d", end_date.month-1),
+                         :e => end_date.day, :f => end_date.year, :s => stock_symbol,
+                         :g => frequency, :ignore => '.csv'}
+      super()  
+    end
+
+    # Get uri content with the help of get method of the super class
+    def get
+      if stock_symbol.nil? || start_date.nil? || end_date.nil?
+        raise HistoryError, 'Cannot send request unless all parameters, ie stock_symbol, start and end date are present'
+      end
+      if !(start_date.is_a?(Date) || end_date.is_a?(Date))
+        raise HistoryError, 'Start and end date should be of type Date'
+      end
+      uri
+      super()
+    end
+    
+    private
+    
+    def validate_interval_values(interval_value=interval)
+      valid_values = [:daily, :weekly, :monthly]
+      unless valid_values.include?(interval_value)
+        raise HistoryError, "Allowed values for interval are #{valid_values.join(', ')}"
+      end
+    end
+    
+    def validate_stock_symbol(options)
+      unless options.keys.include?(:stock_symbol)
+        raise HistoryError, ':stock_symbol key is not present in the parameter hash'
+      end
+      validate_stock_symbol_attribute
+    end
+    
+    def validate_stock_symbol_attribute(symbol=stock_symbol)
+      if symbol.nil? || symbol.empty?
+        raise HistoryError, ':stock_symbol value cannot be nil or blank'
+      end
+    end
+    
+    def validate_start_date(options)
+      validate_date_options(:start_date, options)
+      validate_start_date_type
+    end
+    
+    def validate_end_date(options)
+      validate_date_options(:end_date, options)
+      validate_end_date_type
+    end
+    
+    def validate_history_range(s_date = start_date, e_date = end_date)
+      if s_date >= Date.today
+        raise HistoryError, "Start date must be in the past"
+      end
+      if e_date >= Date.today
+        raise HistoryError, "End date must be in the past"
+      end
+      if e_date < s_date
+        raise HistoryError, "End date must be greater than the start date"
+      end
+    end
+    
+    def validate_end_date_type(e_date=end_date)
+      unless e_date.is_a?(Date)
+        raise HistoryError, "End date must be of type Date"
+      end
+    end
+    
+    def validate_start_date_type(s_date=start_date)
+      unless s_date.is_a?(Date)
+        raise HistoryError, "Start date must be of type Date"
+      end
+    end
+    
+    def validate_date_options(date_type, options)
+      unless options.keys.include?(date_type)
+        raise HistoryError, ":#{date_type} key is not present in the parameter hash"
+      end
+      
+      if options[date_type].nil? || options[date_type].to_s.empty?
+        raise HistoryError, ":#{date_type} value cannot be blank"
+      end
+    end
+    
+    def validate_keys(options)
+      valid_keys   = [:stock_symbol, :start_date, :end_date, :interval]
+      invalid_keys = []
+      options.keys.each{|key| invalid_keys << key unless valid_keys.include?(key) }
+      unless invalid_keys.length.zero?
+        raise HistoryError, "An invalid key '#{invalid_keys.join(',')}' is passed in the parameters. Allowed keys are #{valid_keys.join(', ')}"
+      end
+    end
+    
+  end
+  
+end