wits 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 405518ecbb7d7831e79f9e53aa4bbded89d02c21
-  data.tar.gz: 97431b6410ad15f43722ec3a977471d1f2160bcc
+  metadata.gz: 3664d73942923431552b9c6d8aa451590ffecfa7
+  data.tar.gz: a2d63096f181f9919b9829418808030df37a68a5
 SHA512:
-  metadata.gz: e13d97969d1483d1e36bcbc5e0bb99f9b402edc6546818ec988e6acc48050fda1164fcfd92d1f698e277594d45085d81720a1af1d48226163bf5f24ebeadbadc
-  data.tar.gz: e7cab915488442a13fff5233745891f4914aad3c6e1ec489f85aa39be6a928d5328be977312eeec2be9f2c25e42f39999494855b3023a5321fcbda3b976ce35c
+  metadata.gz: 7e3151dde9f5638672f86f4eeac6980a84007e05cb9c5c01164016cf0853eda924672eca5ef60aa06c0b95f632033ab387ee741abe4f6ba43378fb982bfad788
+  data.tar.gz: 1f7effc8f248e35f38e9329cafd3030ee64264544ee8045d1ead1ab339266506798edfc5ffac933ca8ffe0d75811a8556d782b66e3dd8168df67dd23b3e58dc4

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+0.3.0 / 2015-04-09
+------
+* Changed the default date to be NZ's current date for five minute prices and averaged five minute prices.
+* Updated the data format to handle NZ daylight savings.
+* Updated the default dates to be agnostic of local/server time zones.
+
+0.2.0 / 2015-04-03
+------
+No changes
+
+0.1.0 / 2015-04-03
+------
+First release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Gordon Chan, YouDo Limited
+
+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/README.md

@@ -0,0 +1,199 @@
+# wits
+[![Gem Version](https://badge.fury.io/rb/wits.svg)](http://badge.fury.io/rb/wits) [![Dependency Status](https://gemnasium.com/gchan/wits.svg?branch=master)](https://gemnasium.com/gchan/wits) ![License](https://img.shields.io/badge/license-MIT-blue.svg)
+
+[![Build Status](https://travis-ci.org/gchan/wits.svg?branch=master)](https://travis-ci.org/gchan/wits) [![Coverage Status](https://coveralls.io/repos/gchan/wits/badge.svg?branch=master)](https://coveralls.io/r/gchan/wits?branch=master) [![Code Climate](https://codeclimate.com/github/gchan/wits/badges/gpa.svg)](https://codeclimate.com/github/gchan/wits)
+
+Retrieve electricity data from [WITS Free to air](http://electricityinfo.co.nz/) via a friendly Ruby interface.
+
+WITS (Wholesale and information trading system) currently does not provide a public API but data can be retrieved through web forms and file downloads.
+
+This client library interfaces with WITS to make data retrieval and formatting a breeze.
+
+#### Quick Example
+
+```ruby
+Wits.benmore
+
+=> {:node_code=>"BEN2201",
+ :node_short_code=>"BEN",
+ :node_name=>"Benmore",
+ :price_type=>"Final",
+ :date=>#<Date: 2015-04-01 ((2457114j,0s,0n),+0s,2299161j)>,
+ :prices=>
+  [{:time=>2015-04-01 00:00:00 +1300, :trading_period=>1, :price=>95.82},
+   {:time=>2015-04-01 00:30:00 +1300, :trading_period=>2, :price=>90.24},
+   ...
+  ]
+ }
+```
+
+See the 'Usage' section for more examples.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wits'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install wits
+
+
+## Supported Ruby versions
+wits supports MRI Ruby 1.9+ and the JRuby and Rubinius equivalent. The specific Ruby versions we build and test on can be found at [TravisCI](https://travis-ci.org/gchan/wits).
+
+## Usage
+
+wits can retrieve [Final/Interim Prices](http://electricityinfo.co.nz/comitFta/ftaPage.pricesMain) and [5 Minute Prices](http://electricityinfo.co.nz/comitFta/five_min_prices.main) for a given node and date.
+
+#### Final/Interim Prices
+Half-hourly final/interim prices can be retrieved in the following ways:
+
+```ruby
+Wits.prices('ben2201') # Defaults to the day before yesterday
+Wits.prices('BEN', '29/03/2015')
+Wits.prices('ben', Time.parse('29/03/2015 13:37'))
+Wits.prices('BEN2201', Date.parse('29/03/2015'))
+```
+
+If no date-like argument is provided, data for the day before yesterday will be retrieved.
+
+There are convenient methods for known nodes. Use `Wits::Nodes.nodes` to see a list of nodes this library is aware of.
+
+```ruby
+Wits.ben_prices
+Wits.benmore_prices('29/03/2015')
+Wits.ben2201_prices(Time.parse('29/03/2015 13:37'))
+```
+
+For Final/Interim prices, there are shorter methods without the `_prices` suffix.
+
+```ruby
+Wits.ben
+Wits.benmore
+Wits.ben2201
+```
+
+All of the above methods can be called on `Wits::FinalInterimPrices`.
+
+```ruby
+Wits::FinalInterimPrices.benmore_prices
+```
+
+#### 5 Minute Prices
+Five minute electricity prices can be retrieved in a similar fashion:
+
+```ruby
+Wits.five_minute_prices('hay2201') # Defaults to the day before yesterday
+Wits.five_minute_prices('HAY', '29/03/2015')
+Wits.five_minute_prices('hay', Time.parse('29/03/2015 13:37'))
+Wits.five_minute_prices('HAY2201', Date.parse('29/03/2015'))
+```
+
+If no date-like argument is provided, data for today's date will be retrieved.
+
+There are convenient methods for known nodes. Use `Wits::Nodes.nodes` to see a list of nodes this library is aware of.
+
+```ruby
+Wits.hay_five_minute_prices
+Wits.haywards_five_minute_prices('29/03/2015')
+Wits.hay2201_five_minute_prices(Time.parse('29/03/2015 13:37'))
+```
+
+All of the above methods can be called on `Wits::FiveMinutePrices`.
+
+```ruby
+Wits::FiveMinutePrices.hay_five_minute_prices
+```
+
+#### Average 5 Minute Prices
+Average 5 Minute Prices can be retrieved by passing the `:average` argument (in conjunction with a date argument) to the above 5 Minute Prices methods:
+
+```ruby
+Wits.five_minute_prices('HAY', '29/03/2015', :average)
+Wits.haywards_five_minute_prices('29/03/2015', :average)
+Wits.hay2201_five_minute_prices(Date.parse('29/03/2015'), :average)
+```
+
+There is also a method to retrieve average prices without passing through an `:average` argument.
+
+```ruby
+Wits.average_five_minute_prices('hay2201')
+Wits.average_five_minute_prices('HAY', '29/03/2015')
+```
+
+If no date-like argument is provided, data for today's date will be retrieved.
+
+Again there are convenient methods for known nodes. The `:average` argument is not required.
+
+```ruby
+Wits.hay_average_five_minute_prices
+Wits.haywards_average_five_minute_prices('29/03/2015')
+Wits.hay2201_average_five_minute_prices(Date.parse('29/03/2015'))
+```
+
+All of the above methods can be called on `Wits::FiveMinutePrices`.
+
+```ruby
+Wits::FiveMinutePrices.hay_average_five_minute_prices
+Wits::FiveMinutePrices.average_five_minute_prices('hay2201')
+```
+
+#### Errors
+
+In addition to the usual Ruby errors and exceptions, wits can raise the following errors:
+
+* `Wits::Error::ClientError`
+* `Wits::Error::ConnectionFailed`
+* `Wits::Error::TimeoutError`
+* `Wits::Error::ResourceNotFound`
+* `Wits::Error::ParsingError`
+
+All of the above error classes inherit `Wits::Error::ClientError`, `Wits::Error`, and `StandardError`.
+
+#### Time Zones
+
+wits will respect the local (server) time zone and correctly return Time instances in the local time zone. Daylight savings adjustments are accounted for.
+
+For instance, if the NZT time for the first trading period is `2015-03-29 00:00:00 +1300`, wits will return `2015-03-28 07:00:00 -0400` for an 'America/New_York' local time zone.
+
+`Date` instances are always in the context of New Zealand.
+
+#### Known Issues
+
+There is no reliable method (without web scraping) of distinguishing interim half-hourly prices from final prices. Until the WITS CSV file correctly reports the price type, the half-hourly prices are always reported as 'Final'
+
+The CSV files for five minute prices and average five minute prices are missing some data rows on days when daylight savings ends. As a result, wits will return incomplete (and possibly invalid) data for dates when daylight savings ends (e.g. 5 April 2015).
+
+## Possible Enhancements
+
+WITS also provides [Price Index](http://electricityinfo.co.nz/comitFta/price_index.summary) and [Demand](http://electricityinfo.co.nz/comitFta/ftaPage.demand) information which could be retrieved and delivered through a client library. Pull Requests are welcome!
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+Run `bin/guard` to automatically launch specs when files are modified.
+
+Run `bundle exec rake spec` to manually launch specs.
+
+## Contributing
+
+1. Fork it ( https://github.com/gchan/wits/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+wits is Copyright (c) 2015 Gordon Chan and is released under the MIT License. It is free software, and may be redistributed under the terms specified in the LICENSE file.

data/lib/wits/final_interim_prices/convenience_methods.rb

@@ -3,35 +3,34 @@ require 'wits/nodes'
 module Wits
   module FinalInterimPrices
     module ConvenienceMethods
-      Wits::Nodes.nodes.each do |node, name|
-        # def ben2201
-        define_method node.downcase do |*args|
-          prices(node, *args)
-        end
 
-        # def hay
-        define_method node.downcase[0..2] do |*args|
-          prices(node, *args)
-        end
+      def self.extended(_base)
+        Wits::Nodes.nodes.each do |node, name|
+          # def ben2201
+          create_prices_method(node.downcase, node)
 
-        # def halfway_bush
-        define_method name.downcase.tr(' ', '_') do |*args|
-          prices(node, *args)
-        end
+          # def hay
+          create_prices_method(node.downcase[0..2], node)
 
+          # def halfway_bush
+          create_prices_method(name.downcase.tr(' ', '_'), node)
 
-        # def ben2201_prices
-        define_method "#{node.downcase}_prices" do |*args|
-          prices(node, *args)
-        end
 
-        # def hay_prices
-        define_method "#{node.downcase[0..2]}_prices" do |*args|
-          prices(node, *args)
+          # def ben2201_prices
+          create_prices_method("#{node.downcase}_prices", node)
+
+          # def hay_prices
+          create_prices_method("#{node.downcase[0..2]}_prices", node)
+
+          # def halfway_bush_prices
+          create_prices_method("#{name.downcase.tr(' ', '_')}_prices", node)
         end
+      end
+
+      private
 
-        # def halfway_bush_prices
-        define_method "#{name.downcase.tr(' ', '_')}_prices" do |*args|
+      def self.create_prices_method(method_name, node)
+        define_method method_name do |*args|
           prices(node, *args)
         end
       end

data/lib/wits/final_interim_prices.rb

@@ -16,7 +16,7 @@ module Wits
       base.extend ConvenienceMethods
     end
 
-    def prices(node, date = Date.today - 2)
+    def prices(node, date = nz_current_date - 2)
       node = format_node(node)
       date = format_date(date)
 
@@ -62,8 +62,13 @@ module Wits
     end
 
     def process_prices(csv, date)
+      times = []
+
       csv.map do |time, trading_period, price|
-        format_price(date, time, trading_period, price)
+        repeated_time = times.include?(time)
+        times << time
+
+        format_price(date, time, trading_period, price, repeated_time)
       end
     end
   end

data/lib/wits/five_minute_prices/convenience_methods.rb

@@ -3,38 +3,43 @@ require 'wits/nodes'
 module Wits
   module FiveMinutePrices
     module ConvenienceMethods
-      Wits::Nodes.nodes.each do |node, name|
-        # def ben2201_five_minute_prices
-        define_method "#{node.downcase}_five_minute_prices" do |*args|
-          five_minute_prices(node, *args)
-        end
 
-        # def hay_five_minute_prices
-        define_method "#{node.downcase[0..2]}_five_minute_prices" do |*args|
-          five_minute_prices(node, *args)
-        end
+      def self.extended(base)
+        Wits::Nodes.nodes.each do |node, name|
+          # def ben2201_five_minute_prices
+          create_five_min_method(node.downcase, node)
 
-        # def halfway_bush_five_minute_prices
-        define_method "#{name.downcase.tr(' ', '_')}_five_minute_prices" do |*args|
-          five_minute_prices(node, *args)
-        end
+          # def hay_five_minute_prices
+          create_five_min_method(node.downcase[0..2], node)
 
+          # def halfway_bush_five_minute_prices
+          create_five_min_method(name.downcase.tr(' ', '_'), node)
 
-        # def ben2201_avgerage_five_minute_prices
-        define_method "#{node.downcase}_average_five_minute_prices" do |*args|
-          average_five_minute_prices(node, *args)
+
+          # def ben2201_avgerage_five_minute_prices
+          create_avg_five_min_method(node.downcase, node)
+
+          # def hay_avgerage_five_minute_prices
+          create_avg_five_min_method(node.downcase[0..2], node)
+
+          # def halfway_bush_avgerage_five_minute_prices
+          create_avg_five_min_method(name.downcase.tr(' ', '_'), node)
         end
+      end
 
-        # def hay_avgerage_five_minute_prices
-        define_method "#{node.downcase[0..2]}_average_five_minute_prices" do |*args|
-          average_five_minute_prices(node, *args)
+      private
+
+      def self.create_five_min_method(method_prefix, node)
+        define_method "#{method_prefix}_five_minute_prices" do |*args|
+          five_minute_prices(node, *args)
         end
+      end
 
-        # def halfway_bush_avgerage_five_minute_prices
-        define_method "#{name.downcase.tr(' ', '_')}_average_five_minute_prices" do |*args|
+      def self.create_avg_five_min_method(method_prefix, node)
+        define_method "#{method_prefix}_average_five_minute_prices" do |*args|
           average_five_minute_prices(node, *args)
         end
       end
     end
   end
-end
+end

data/lib/wits/five_minute_prices.rb

@@ -16,11 +16,11 @@ module Wits
       base.extend ConvenienceMethods
     end
 
-    def average_five_minute_prices(node, date = Date.today - 2)
+    def average_five_minute_prices(node, date = nz_current_date)
       five_minute_prices(node, date, :average)
     end
 
-    def five_minute_prices(node, date = Date.today - 2, type = :price )
+    def five_minute_prices(node, date = nz_current_date, type = :price )
       node = format_node(node)
       date = format_date(date)
       type = format_price_type(type)
@@ -78,8 +78,13 @@ module Wits
     end
 
     def process_five_min_prices(csv)
+      times = []
+
       csv.map do |_node, date, trading_period, time, price, *_|
-        format_price(date, time, trading_period, price)
+        repeated_time = times.include?(time)
+        times << time
+
+        format_price(date, time, trading_period, price, repeated_time)
       end
     end
   end

data/lib/wits/helpers.rb

@@ -23,9 +23,9 @@ module Wits
       end
     end
 
-    def format_price(date, time, trading_period, price)
+    def format_price(date, time, trading_period, price, repeated_time)
       {
-        time: parse_nz_time(date, time),
+        time: parse_nz_time(date, time, repeated_time),
         trading_period: trading_period.to_i,
         price: price.to_f
       }
@@ -42,14 +42,30 @@ module Wits
       }
     end
 
-    def parse_nz_time(date, time)
-      tz = TZInfo::Timezone.get('Pacific/Auckland')
+    def parse_nz_time(date, time, repeated_time)
+      date = Date.parse(date) unless date.is_a?(Date)
 
-      # Timezone information of the Time object is ignored by TZInfo
+      # TimezonePeriod for local Time (midnight)
+      tz_period = nz_time_zone.period_for_local(date.to_time)
+
+      # Assume we transitioned between NZST and NZDT if
+      # a time is repeated
+      dst = tz_period.dst?
+      dst = !dst if repeated_time
+
+      # Time zone information of the Time object is ignored by TZInfo
       time = Time.parse("#{date} #{time}")
 
       # Output in local time
-      tz.local_to_utc(time).localtime
+      nz_time_zone.local_to_utc(time, dst).localtime
+    end
+
+    def nz_time_zone
+      @nz_time_zone ||= TZInfo::Timezone.get('Pacific/Auckland')
+    end
+
+    def nz_current_date
+      nz_time_zone.utc_to_local(Time.now.utc).to_date
     end
   end
 end

data/lib/wits/nodes.rb

@@ -18,19 +18,16 @@ module Wits
 
     NODE_NAMES = NODES.invert.freeze
 
-    SHORT_CODES = {
-      BEN: 'BEN2201',
-      HWB: 'HWB2201',
-      HAY: 'HAY2201',
-      HLY: 'HLY2201',
-      INV: 'INV2201',
-      ISL: 'ISL2201',
-      OTA: 'OTA2201',
-      STK: 'STK2201',
-      SFD: 'SFD2201',
-      TUI: 'TUI1101',
-      WKM: 'WKM2201'
-    }.freeze
+    # {
+    #   BEN: 'BEN2201',
+    #   HWB: 'HWB2201'
+    #   ...
+    # }
+    SHORT_CODES = Hash[
+      NODES.keys.map { |node| node[0..2].to_sym }
+        .zip(NODES.keys.map(&:to_s))
+    ].freeze
+
 
     def nodes
       NODES

data/lib/wits/version.rb

@@ -1,3 +1,3 @@
 module Wits
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/wits.gemspec

@@ -0,0 +1,40 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'wits/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'wits'
+  spec.version       = Wits::VERSION
+  spec.authors       = ['Gordon Chan']
+  spec.email         = ['developer.gordon@gmail.com']
+
+  spec.summary       = %q{Retrieves electricity data from WITS Free to Air}
+  spec.description   = %q{A Ruby interface for WITS (Wholesale and
+    information trading system) to retrieve New Zealand electricity data.}
+  spec.homepage      = 'https://www.github.com/gchan/wits'
+  spec.license       = 'MIT'
+
+  spec.files         = Dir['lib/**/*.rb'] + %w(CHANGELOG.md LICENSE.txt README.md wits.gemspec)
+  spec.bindir        = 'bin'
+  spec.require_paths = ['lib']
+  spec.platform      = Gem::Platform::RUBY
+
+  spec.add_runtime_dependency 'faraday', '~> 0.9.1'
+  spec.add_runtime_dependency 'tzinfo', '~> 1.2.2'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'pry', '~> 0.10.1'
+
+  spec.add_development_dependency 'guard-rspec', '~> 4.5.0'
+  spec.add_development_dependency 'rspec', '~> 3.2.0'
+  spec.add_development_dependency 'vcr', '~> 2.9.3'
+  spec.add_development_dependency 'webmock', '~> 1.21.0'
+  spec.add_development_dependency 'multi_json', '~> 1.11.0'
+  spec.add_development_dependency 'timecop', '~> 0.7.3'
+  spec.add_development_dependency 'simplecov', '~> 0.9.2'
+  spec.add_development_dependency 'rubocop', '~> 0.29.1'
+  spec.add_development_dependency 'coveralls', '~> 0.8.0'
+  spec.add_development_dependency 'codeclimate-test-reporter', '~> 0.4.7'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wits
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Gordon Chan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-03 00:00:00.000000000 Z
+date: 2015-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -206,6 +206,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.7
 description: |-
   A Ruby interface for WITS (Wholesale and
       information trading system) to retrieve New Zealand electricity data.
@@ -215,6 +229,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
 - lib/wits.rb
 - lib/wits/client.rb
 - lib/wits/error.rb
@@ -225,6 +242,7 @@ files:
 - lib/wits/helpers.rb
 - lib/wits/nodes.rb
 - lib/wits/version.rb
+- wits.gemspec
 homepage: https://www.github.com/gchan/wits
 licenses:
 - MIT