weather-sage 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 390dc567cf5a2696830a36bd2a6a27020a2310721a95f69530ccbd0688c06d28
-  data.tar.gz: 9fc5165689410c41763750e06b5590452294f2588880cb2f027dbe98191e0be6
+  metadata.gz: 2d8a169b0525d21c350826048cf01cc233741f1c1d897f88a1f2f05787aa38ad
+  data.tar.gz: 440a697b31b7e806c82afd0e572e313d1fb9e033a67cda205ba1c00be301bc6d
 SHA512:
-  metadata.gz: b23545938bb233191fb042f1cb7d45c098332421dbfb53c6fae126f5a3ef8f6543d75c16d4537582222e519e7da320fc11abbcaadaeed0f7fd4fcb31f83cdefc
-  data.tar.gz: 1541a3ef620d4667e45fe513f95f61e891ff259ab0309c4286ca709498eca8bca2972d9ede59e0587bd51dbacb9403c9ebdff1d491af33320f58400fae619c9f
+  metadata.gz: 80305e078b4be11c351509cb1aaef299ae47fb8db851f35a1ed1651319f2ff89b4dd3246c8a5b2a23ad01a87adddcb060b4353fc9001fbbcc0c997bac4df306f
+  data.tar.gz: b1f752c2f412cf374b85caec3563801d299ec17e94102276f71da9ac5be2fea5fe895c8329bbc9e2ca1c1ffd5f0fb579959282246a33bec97214e195e60ba94c

data/lib/weather-sage/cache-entry.rb

@@ -0,0 +1,13 @@
+require 'pstore'
+
+#
+# Cache entry.
+#
+class WeatherSage::CacheEntry < ::Struct.new(:expires, :value)
+  #
+  # Is this cache entry valid?
+  #
+  def valid?
+    expires ? (Time.now.to_i < expires) : true
+  end
+end

data/lib/weather-sage/cache.rb

@@ -0,0 +1,79 @@
+require 'pstore'
+
+#
+# Minimal cache implementation.
+#
+class WeatherSage::Cache
+  #
+  # Create a new Cache instance bound to file at path +path+.
+  #
+  def initialize(path)
+    @pstore = ::PStore.new(path)
+  end
+
+  #
+  # Returns true if the key exists and is it still valid.
+  #
+  def key?(key)
+    @pstore.transaction(true) do
+      return false unless entry = @pstore[key]
+      entry.valid?
+    end
+  end
+
+  #
+  # Set entry in cache with key +key+ to value +val+.
+  #
+  # An optional timeout (in seconds) may be provided with +timout+.
+  #
+  def set(key, val, timeout = nil)
+    @pstore.transaction do
+      # calculate expiration time
+      expires = timeout ? (Time.now.to_i + timeout) : nil
+
+      # save entry
+      @pstore[key] = ::WeatherSage::CacheEntry.new(expires, val)
+
+      # purge any expired entries
+      flush
+    end
+
+    # return value
+    val
+  end
+
+  #
+  # Get entry in cache with key +key+.
+  #
+  # Returns *nil* if no such entry exists.
+  #
+  def get(key)
+    @pstore.transaction(true) do
+      return nil unless entry = @pstore[key]
+      entry.valid? ? entry.value : nil
+    end
+  end
+
+  #
+  # Delete entry in cache with key +key+.
+  #
+  def delete(key)
+    @pstore.transaction do
+      @pstore.delete(key)
+    end
+  end
+
+  alias :[] :get
+  alias :[]= :set
+
+  private
+
+  #
+  # Purge expired entries.
+  #
+  def flush
+    @pstore.roots.each do |key|
+      @pstore.delete(key) unless @pstore[key].valid?
+    end
+  end
+end

data/lib/weather-sage/census/geocoder.rb

@@ -0,0 +1,48 @@
+#
+# Wrapper around Census geocoder API.
+#
+class WeatherSage::Census::Geocoder
+  #
+  # URL endpoint for Census Geocoder API.
+  #
+  URL = 'https://geocoding.geo.census.gov/geocoder/locations/onelineaddress'
+
+  #
+  # Static parameters for geocoder requests.
+  #
+  # Source:
+  # https://geocoding.geo.census.gov/geocoder/Geocoding_Services_API.pdf
+  PARAMS = {
+    returntype: 'locations',
+    benchmark:  'Public_AR_Current',
+    format:     'json',
+  }.freeze
+
+  #
+  # Create new Geocoder instance.
+  #
+  def initialize(ctx)
+    @ctx = ctx
+  end
+
+  #
+  # Geocode given address string +s+ and return an array of Match
+  # objects.
+  #
+  def run(s)
+    # exec request
+    data = @ctx.cache.get(URL, PARAMS.merge({
+      address: s,
+    }))
+
+    # log data
+    @ctx.log.debug('Geocoder#run') do
+      'data = %p' % [data]
+    end
+
+    # map matches and return result
+    data['result']['addressMatches'].map { |row|
+      ::WeatherSage::Census::Match.new(@ctx, row)
+    }
+  end
+end

data/lib/weather-sage/census/match.rb

@@ -0,0 +1,19 @@
+#
+# Matching address returned by Geocoder.
+#
+class WeatherSage::Census::Match
+  attr :point, :address, :data
+
+  #
+  # Create a new Match object.
+  #
+  def initialize(ctx, data)
+    # get coordinates
+    x, y = %w{x y}.map { |k| data['coordinates'][k] }
+
+    # cache data, address, and point
+    @data = data.freeze
+    @address = @data['matchedAddress']
+    @point = ::WeatherSage::Weather::Point.new(ctx, x, y).freeze
+  end
+end

data/lib/weather-sage/census.rb

@@ -0,0 +1,7 @@
+#
+# Thin wrapper around Census geocoder.
+#
+module WeatherSage::Census
+  autoload :Match, File.join(__dir__, 'census', 'match.rb')
+  autoload :Geocoder, File.join(__dir__, 'census', 'geocoder.rb')
+end

data/lib/weather-sage/cli/commands/base-forecast.rb

@@ -0,0 +1,70 @@
+#
+# Base forecast command.
+#
+# Used by ForecastCommand and HourlyCommand.
+#
+class WeatherSage::CLI::Commands::BaseForecastCommand < WeatherSage::CLI::Commands::Command
+  #
+  # Do not invoke this method directly; subclass this class and
+  # override the +run+ method.
+  #
+  def initialize(ctx, app)
+    super(ctx, app)
+    @forecast_method = self.class.const_get(:FORECAST_METHOD)
+  end
+
+  #
+  # Run command.
+  #
+  def run(args)
+    # get mode and args
+    mode, args = parse_args(args)
+
+    CSV(STDOUT) do |csv|
+      # write column names
+      csv << columns(mode).map { |col| col[:name] }
+
+      args.each do |arg|
+        # geocode argument, get first point
+        if pt = geocode(arg).first
+          # walk forecast periods
+          pt.point.send(@forecast_method).periods.each do |p|
+            csv << make_row(mode, arg, p)
+          end
+        end
+      end
+    end
+  end
+
+  private
+
+  #
+  # Extract mode and args from command-line arguments.
+  #
+  def parse_args(args)
+    case args.first
+    when /^-f|--full$/
+      [:full, args[1 .. -1]]
+    when /^-b|--brief$/
+      [:brief, args[1 .. -1]]
+    else
+      [:brief, args]
+    end
+  end
+
+  #
+  # Convert forecast period to CSV row.
+  #
+  def make_row(mode, address, p)
+    [address] + columns(mode).select { |col|
+      col[:prop]
+    }.map { |col| p.data[col[:prop]] }
+  end
+
+  #
+  # Get columns for given mode.
+  #
+  def columns(mode)
+    ::WeatherSage::CLI::Forecast::columns(@forecast_method, mode)
+  end
+end

data/lib/weather-sage/cli/commands/command.rb

@@ -0,0 +1,42 @@
+#
+# Base class for command-line commands.
+#
+# You should subclass this class to create new commands.
+#
+class WeatherSage::CLI::Commands::Command
+  #
+  # Do not invoke this method directly; subclass Command and
+  # override the +run+ method.
+  #
+  def initialize(ctx, app)
+    @ctx, @app = ctx, app
+
+    # create geocoder
+    @geocoder = ::WeatherSage::Census::Geocoder.new(ctx)
+  end
+
+  #
+  # Run command.
+  #
+  def self.run(ctx, app, args)
+    new(ctx, app).run(args)
+  end
+
+  #
+  # Virtual method.  You need to subclass and override this method
+  # to add a new command.
+  #
+  def run(args)
+    raise "not implemented"
+  end
+
+  protected
+
+  #
+  # Geocode given street address and return array of
+  # Census::Geocode::Match results.
+  #
+  def geocode(s)
+    @geocoder.run(s)
+  end
+end

data/lib/weather-sage/cli/commands/forecast.rb

@@ -0,0 +1,28 @@
+#
+# Implementation of *forecast* command.
+#
+class WeatherSage::CLI::Commands::ForecastCommand < WeatherSage::CLI::Commands::BaseForecastCommand
+  #
+  # Help for this command.
+  #
+  # Used by the *help* command.
+  #
+  HELP = {
+    line: '
+      Get weather forecast for address.
+    '.strip,
+
+    full: [
+      'Get weather forecast for address.',
+      '',
+      'Use --full to see additional columns.',
+    ].join("\n")
+  }.freeze
+
+  #
+  # Forecast method.
+  #
+  # Used by BaseForecastCommand to call correct forecast method.
+  #
+  FORECAST_METHOD = :forecast
+end

data/lib/weather-sage/cli/commands/geocode.rb

@@ -0,0 +1,51 @@
+module WeatherSage
+  module CLI
+    module Commands
+      #
+      # Implementation of *geocode* command.
+      #
+      class GeocodeCommand < Command
+        #
+        # Help for this command.
+        #
+        # Used by the *help* command.
+        #
+        HELP = {
+          line: '
+            Geocode address.
+          '.strip,
+
+          full: [
+            'Geocode address.',
+          ].join("\n"),
+        }.freeze
+
+        #
+        # CSV columns.
+        #
+        CSV_COLS = %w{input_address match_address x y}
+
+        #
+        # Entry point for *geocode* command-line command.
+        #
+        def run(args)
+          # create geocoder
+          geocoder = Census::Geocoder.new(@ctx)
+
+          CSV(STDOUT) do |csv|
+            # write column headers
+            csv << CSV_COLS
+
+            # iterate command-line arguments and geocode each one
+            args.each do |arg|
+              # geocode argument and write results to output CSV
+              geocoder.run(arg).each do |row|
+                csv << [arg, row.address, row.point.x, row.point.y]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/weather-sage/cli/commands/help.rb

@@ -0,0 +1,82 @@
+#
+# Implementation of *help* command-line command.
+#
+class WeatherSage::CLI::Commands::HelpCommand < ::WeatherSage::CLI::Commands::Command
+  #
+  # Help for this command.
+  #
+  # Used by the *help* command.
+  #
+  HELP = {
+    line: '
+      List commands.
+    '.strip,
+
+    full: [
+      'List commands.  Use "help <command>" to show details for a',
+      'specific command.',
+    ].join("\n"),
+  }.freeze
+
+  #
+  # Entry point for *help* command-line command.
+  #
+  def run(args)
+    if args.size > 0
+      # show details of given commands
+      show_details(args)
+    else
+      # print full list of commands
+      list_commands
+    end
+  end
+
+  private
+
+  #
+  # Print full list of commands.
+  #
+  def list_commands
+    puts template(:all, {
+      app: File.basename(@app),
+
+      cmds: ::WeatherSage::CLI::Help::COMMANDS.values.map { |cmd|
+        template(:cmd, cmd)
+      }.join("\n"),
+
+      envs: ::WeatherSage::CLI::Env::VARS.map { |row|
+        template(:env, row)
+      }.join("\n\n"),
+    })
+  end
+
+  #
+  # Print details of given commands.
+  #
+  def show_details(args)
+    # get a list of unknown commands
+    unknown_cmds = args.select do |arg|
+      !WeatherSage::CLI::Help::COMMANDS.key?(arg)
+    end
+
+    if unknown_cmds.size > 0
+      # print list of unknown commands and exit
+      puts 'Unknown commands: %s' % [unknown_cmds.join(', ')]
+      exit -1
+    end
+
+    # print detailed help for each argument
+    puts args.map { |arg| template(:one, commands[arg]) }
+  end
+
+  #
+  # Expand template.
+  #
+  def template(key, args = {})
+    unless WeatherSage::CLI::Help::TEMPLATES.key?(key)
+      raise "unknown template: #{key}"
+    end
+
+    WeatherSage::CLI::Help::TEMPLATES[key] % args
+  end
+end

data/lib/weather-sage/cli/commands/hourly.rb

@@ -0,0 +1,28 @@
+#
+# Implementation of *hourly* command.
+#
+class WeatherSage::CLI::Commands::HourlyCommand < WeatherSage::CLI::Commands::BaseForecastCommand
+  #
+  # Help for this command.
+  #
+  # Used by the *help* command.
+  #
+  HELP = {
+    line: '
+      Get hourly weather forecast for address.
+    '.strip,
+
+    full: [
+      'Get hourly weather forecast for address.',
+      '',
+      'Use --full to see additional columns.',
+    ].join("\n")
+  }.freeze
+
+  #
+  # Forecast method.
+  #
+  # Used by BaseForecastCommand to call correct forecast method.
+  #
+  FORECAST_METHOD = :hourly_forecast
+end

data/lib/weather-sage/cli/commands/now.rb

@@ -0,0 +1,87 @@
+#
+# Implementation of *now* command-line command.
+#
+class WeatherSage::CLI::Commands::NowCommand < WeatherSage::CLI::Commands::Command
+  #
+  # Help for this command.
+  #
+  # Used by the *help* command.
+  #
+  HELP = {
+    line: '
+      Get current weather from station closest to address.
+    '.strip,
+
+    full: [
+      'Get current weather at from station closest to address.',
+    ].join("\n")
+  }.freeze
+
+  #
+  # CSV column names.
+  #
+  COL_NAMES = %w{
+    address
+    name
+    type
+    value
+    unit
+    quality_control
+  }.freeze
+
+  #
+  # Run *now* command.
+  #
+  def run(args)
+    CSV(STDOUT) do |csv|
+      # write column names
+      csv << COL_NAMES
+
+      # iterate over command-line arguments and write each one
+      args.each do |arg|
+        # geocode to first point
+        if pt = geocode(arg).first
+          # get first station
+          if st = pt.point.stations.first
+            # get latest observation data
+            data = st.latest_observations
+
+            # write observations
+            make_rows(arg, data) do |row|
+              csv << row
+            end
+          end
+        end
+      end
+    end
+  end
+
+  private
+
+  #
+  # Map observation properties in result to CSV rows and yield each
+  # row.
+  #
+  # FIXME: this is a bit of a hack.
+  #
+  def make_rows(address, data, &block)
+    ::WeatherSage::Weather::Observation::PROPERTIES.each do |key, type|
+      # get observation
+      if v = data[key.to_s]
+        # map observation to row, then yield row
+        block.call(case type
+        when :text, :time, :url
+          [address, key, type, v]
+        when :value
+          [address, key, type, v['value'], v['unitCode'], v['qualityControl']]
+        when :cloud
+          # hack: only show data for first cloud layer
+          base = v.first['base']
+          [address, key, type, base['value'], base['unitCode']]
+        else
+          raise "unkown type: #{type}"
+        end)
+      end
+    end
+  end
+end

data/lib/weather-sage/cli/commands/stations.rb

@@ -0,0 +1,67 @@
+module WeatherSage
+  module CLI
+    module Commands
+      #
+      # Implementation of *stations* command.
+      #
+      class StationsCommand < Command
+        #
+        # Help for this command.
+        #
+        # Used by the *help* command.
+        #
+        HELP = {
+          line: '
+            List weather stations near address.
+          '.strip,
+
+          full: [
+            'List weather stations near address.',
+          ].join("\n")
+        }.freeze
+
+        #
+        # CSV column names.
+        #
+        COL_NAMES = %w{
+          address
+          station_id
+          station_name
+          x
+          y
+          elevation
+          time_zone
+        }.freeze
+
+        #
+        # Run *stations* command.
+        #
+        def run(args)
+          CSV(STDOUT) do |csv|
+            # write column names
+            csv << COL_NAMES
+
+            args.each do |arg|
+              # geocode argument, get first point
+              if pt = geocode(arg).first
+                # walk stations
+                pt.point.stations.each do |s|
+                  csv << make_row(arg, s)
+                end
+              end
+            end
+          end
+        end
+
+        private
+
+        #
+        # Convert station to CSV row.
+        #
+        def make_row(address, s)
+          [address, s.id, s.name, s.x, s.y, s.elevation, s.time_zone]
+        end
+      end
+    end
+  end
+end

data/lib/weather-sage/cli/commands.rb

@@ -0,0 +1,15 @@
+#
+# Namespace for command-line commands.
+#
+module WeatherSage::CLI::Commands
+  LIB_DIR = File.join(__dir__, 'commands') # :nodoc:
+
+  autoload :Command, File.join(LIB_DIR, 'command.rb')
+  autoload :HelpCommand, File.join(LIB_DIR, 'help.rb')
+  autoload :GeocodeCommand, File.join(LIB_DIR, 'geocode.rb')
+  autoload :NowCommand, File.join(LIB_DIR, 'now.rb')
+  autoload :StationsCommand, File.join(LIB_DIR, 'stations.rb')
+  autoload :BaseForecastCommand, File.join(LIB_DIR, 'base-forecast.rb')
+  autoload :ForecastCommand, File.join(LIB_DIR, 'forecast.rb')
+  autoload :HourlyCommand, File.join(LIB_DIR, 'hourly.rb')
+end

data/lib/weather-sage/cli/env/cache.rb

@@ -0,0 +1,38 @@
+require 'fileutils'
+
+#
+# Create HTTP::Cache fron environment variables.
+#
+class WeatherSage::CLI::Env::Cache < ::WeatherSage::HTTP::Cache
+  #
+  # Default cache path.
+  #
+  DEFAULT_PATH = '~/.config/weather-sage/http-cache.pstore'
+
+  #
+  # Create HTTP::Cache fron environment variables.
+  #
+  # Uses the following environment variables:
+  #
+  # - WEATHER_SAGE_CACHE_PATH: Path to HTTP cache file.  Defaults to
+  #   "~/.config/weather-sage/http-cache.pstore".
+  #
+  def initialize(env, log)
+    # get cache path
+    unless path = env.get('CACHE_PATH')
+      # use default cache path
+      path = File.expand_path(DEFAULT_PATH)
+
+      # create parent directories (if necessary)
+      FileUtils.mkdir_p(File.dirname(path))
+    end
+
+    # log cache path
+    log.info('Env::Cache#initialize') do
+      'path = %p' % [path]
+    end
+
+    # return cache instance
+    super(path, log)
+  end
+end