weather-sage 0.1.0 → 0.1.1

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

@@ -0,0 +1,29 @@
+#
+# Create Context from environment variables.
+#
+class WeatherSage::CLI::Env::Context < ::WeatherSage::Context
+  #
+  # Create Context from environment variables.
+  #
+  # The following environment variables are supported:
+  #
+  # - WEATHER_SAGE_LOG_LEVEL: Log level.  One of "fatal", "error",
+  #   "warning", "info", or "debug".  Defaults to "warn".
+  #
+  # - WEATHER_SAGE_LOG_PATH: Path to log file.  Defaults to standard
+  #   error.
+  #
+  # - WEATHER_SAGE_CACHE_PATH: Path to HTTP cache file.  Defaults to
+  #   "~/.config/weather-sage/http-cache.pstore".
+  #
+  def initialize(env)
+    # create log from environment
+    log = ::WeatherSage::CLI::Env::Log.new(env)
+
+    # create cache from environment and log
+    cache = ::WeatherSage::CLI::Env::Cache.new(env, log)
+
+    # create context
+    super(log, cache)
+  end
+end

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

@@ -0,0 +1,35 @@
+#
+# Environment wrapper.
+#
+class WeatherSage::CLI::Env::Env
+  #
+  # Create a new environment wrapper.
+  #
+  def initialize(env)
+    @env = env
+  end
+
+  #
+  # Get the value of the given environment variable.
+  #
+  def get(id, default = nil)
+    key = expand(id)
+    @env.key?(key) ? @env[key] : default
+  end
+
+  #
+  # Does the given ID exist in the environment?
+  #
+  def key?(id)
+    @env.key?(expand(id))
+  end
+
+  private
+
+  #
+  # Prefix ID to get full environment variable name.
+  #
+  def expand(id)
+    'WEATHER_SAGE_' + id.upcase
+  end
+end

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

@@ -0,0 +1,41 @@
+require 'logger'
+
+#
+# Create Logger from environment variables.
+#
+class WeatherSage::CLI::Env::Log < ::Logger
+  #
+  # Default log level.
+  #
+  DEFAULT_LEVEL = 'WARN'
+
+  #
+  # Create Logger from environment variables.
+  #
+  # The following environment variables are supported:
+  #
+  # - WEATHER_SAGE_LOG_LEVEL: Log level.  One of "fatal", "error",
+  #   "warning", "info", or "debug".  Defaults to "warn".
+  #
+  # - WEATHER_SAGE_LOG_PATH: Path to log file.  Defaults to standard
+  #   error.
+  #
+  def initialize(env)
+    # get log level (default to "warn" if unspecified)
+    level = (env.get('LOG_LEVEL', DEFAULT_LEVEL)).upcase
+
+    # create logger
+    super(
+      # log path (default to STDERR)
+      env.get('LOG_PATH', STDERR),
+
+      # log level (default to WARN)
+      level: ::Logger.const_get(level)
+    )
+
+    # log level
+    info('Env::Log#initialize') do
+      'level = %p' % [level]
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module WeatherSage::CLI::Env
+  #
+  # Environment variables.
+  #
+  # Used by *help* command to print available environment variables.
+  #
+  VARS = [{
+    name:     'LOG_LEVEL',
+    text:     "Log level (fatal, error, warning, info, debug)",
+    default:  'warn',
+  }, {
+    name:     'LOG_PATH',
+    text:     "Path to log file",
+    default:  'standard error',
+  }, {
+    name:     'CACHE_PATH',
+    text:     "Path to HTTP cache store",
+    default:  "~/.config/weather-sage/http-cache.pstore",
+  }].freeze
+end

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

@@ -0,0 +1,14 @@
+module WeatherSage
+  module CLI
+    #
+    # Namespace for environment-related classes.
+    #
+    module Env
+      autoload :VARS, File.join(__dir__, 'env', 'vars.rb')
+      autoload :Env, File.join(__dir__, 'env', 'env.rb')
+      autoload :Log, File.join(__dir__, 'env', 'log.rb')
+      autoload :Cache, File.join(__dir__, 'env', 'cache.rb')
+      autoload :Context, File.join(__dir__, 'env', 'context.rb')
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+#
+# Namespace containing data for *forecast* and *hourly* commands.
+#
+module WeatherSage::CLI::Forecast
+  #
+  # List of forecast CSV columns and properties.
+  #
+  COLUMNS = [{
+    name: 'address',
+    prop: nil,
+    show: %i{forecast hourly_forecast},
+  }, {
+    name: 'name',
+    prop: 'name',
+    show: %i{forecast},
+  }, {
+    name: 'start_time',
+    prop: 'startTime',
+    show: %i{hourly_forecast},
+  }, {
+    name: 'end_time',
+    prop: 'endTime',
+    show: %i{hourly_forecast},
+  }, {
+    name: 'is_daytime',
+    prop: 'isDaytime',
+    show: [],
+  }, {
+    name: 'temperature',
+    prop: 'temperature',
+    show: %i{forecast hourly_forecast},
+  }, {
+    name: 'temperature_unit',
+    prop: 'temperatureUnit',
+    show: %i{forecast hourly_forecast},
+  }, {
+    name: 'temperature_trend',
+    prop: 'temperatureTrend',
+    show: [],
+  }, {
+    name: 'wind_speed',
+    prop: 'windSpeed',
+    show: %i{forecast hourly_forecast},
+  }, {
+    name: 'wind_direction',
+    prop: 'windDirection',
+    show: %i{forecast hourly_forecast},
+  }, {
+    name: 'icon',
+    prop: 'icon',
+    show: [],
+  }, {
+    name: 'short_forecast',
+    prop: 'shortForecast',
+    show: %i{forecast hourly_forecast},
+  }, {
+    name: 'detailed_forecast',
+    prop: 'detailedForecast',
+    show: [],
+  }].freeze
+
+  #
+  # Get columns for given forecast method and mode.
+  #
+  def self.columns(forecast_method, mode)
+    COLUMNS.select { |col|
+      (mode == :full) || col[:show].include?(forecast_method)
+    }
+  end
+end

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

@@ -0,0 +1,68 @@
+#
+# Namespace for data for *help* command.
+#
+module WeatherSage::CLI::Help
+  #
+  # Help templates.
+  #
+  TEMPLATES = {
+    all: [
+      '%<app>s: Weather and geocoding utility.',
+      '',
+      'This command uses the Census bureau geocoding API to convert',
+      'street addresses to latitude/longitude coordinates, and the',
+      'National Weather Service weather API to obtain observations',
+      'from the nearest weather station.',
+      '',
+      'Usage:',
+      '  %<app>s <command> [args...]',
+      '',
+      'Commands:',
+      '%<cmds>s',
+      '',
+      'Use "help <command>" to see detailed help for a command.',
+      '',
+      'Environment Variables:',
+      '%<envs>s',
+    ].join("\n"),
+
+    one: [
+      '%<label>s %<line>s',
+      '',
+      '%<full>s',
+    ].join("\n"),
+
+    cmd: '  %-10<label>s %<line>s',
+
+    env: [
+      '* WEATHER_SAGE_%<name>s: %<text>s.',
+      '  Defaults to %<default>s.',
+    ].join("\n"),
+  }.freeze
+
+  #
+  # Build map of command name to command help.
+  #
+  # Note: The keys in this hash are sorted by command name.
+  #
+  COMMANDS = WeatherSage::CLI::Commands.constants.select { |sym|
+    sym.to_s.match(/^\w+Command$/)
+  }.sort.reduce({}) do |r, sym|
+    # limit to commands with a HELP constant
+    if WeatherSage::CLI::Commands.const_get(sym).const_defined?(:HELP)
+      # get help data
+      help = WeatherSage::CLI::Commands.const_get(sym).const_get(:HELP)
+
+      # build command id
+      id = sym.to_s.gsub(/Command$/, '').downcase
+
+      # add to results
+      r[id] = help.merge({
+        label: id + ':',
+      })
+    end
+
+    # return results
+    r
+  end.freeze
+end

data/lib/weather-sage/cli.rb

@@ -0,0 +1,29 @@
+#
+# Command-line interface for weather-sage.
+#
+module WeatherSage::CLI
+  autoload :Commands, File.join(__dir__, 'cli', 'commands.rb')
+  autoload :Env, File.join(__dir__, 'cli', 'env.rb')
+  autoload :Help, File.join(__dir__, 'cli', 'help.rb')
+  autoload :Forecast, File.join(__dir__, 'cli', 'forecast.rb')
+
+  #
+  # Entry point for command-line interface.
+  #
+  def self.run(app, args)
+    require 'csv'
+    require 'logger'
+    require 'fileutils'
+
+    args = ['help'] unless args.size > 0
+
+    # wrap environment and create context
+    env = Env::Env.new(ENV)
+    ctx = Env::Context.new(env)
+
+    # map first argument to command, then run it
+    (Commands.const_get('%sCommand' % [
+      args.shift.capitalize
+    ]) || Commands::HelpCommand).run(ctx, app, args)
+  end
+end

data/lib/weather-sage/context.rb

@@ -0,0 +1,13 @@
+#
+# Minimal context containing a logger and HTTP request cache.
+#
+class WeatherSage::Context
+  attr :log, :cache
+
+  #
+  # Create context from given +log+ and +cache+.
+  #
+  def initialize(log, cache)
+    @log, @cache = log, cache
+  end
+end

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

@@ -0,0 +1,72 @@
+#
+# HTTP cache backed by file.
+#
+class WeatherSage::HTTP::Cache
+  attr :path, :timeout
+
+  #
+  # Create an HTTP cache backed by file at +path+ where entries are
+  # valid for +timeout+ seconds.
+  #
+  # +timeout+ defaults to 30 minutes if unspecified.
+  #
+  def initialize(path, log, timeout = 30 * 60)
+    @path, @log, @timeout = path.freeze, log, timeout
+    @cache = ::WeatherSage::Cache.new(@path)
+    @fetcher = ::WeatherSage::HTTP::Fetcher.new(@log)
+    @parser = ::WeatherSage::HTTP::Parser.new(@log)
+  end
+
+  #
+  # Get cached URL, or request it if it is not cached.
+  #
+  def get(url, params = {})
+    # parse URL into URI, get key
+    uri = make_uri(url, params)
+    str = uri.to_s
+
+    @log.debug('HTTP::Cache#get') { '%s' % [str] }
+
+    unless r = @cache.get(str)
+      # fetch response, parse body, and cache result
+      r = @cache.set(str, parse(fetch(uri)), @timeout)
+    end
+
+    # return result
+    r
+  end
+
+  #
+  # Returns true if the given URL in the cache.
+  #
+  def key?(url, params = {})
+    @cache.key?(make_uri(url, params).to_s)
+  end
+
+  private
+
+  #
+  # Convert a URL and parameters to a URI.
+  #
+  def make_uri(url, params = {})
+    uri = URI.parse(url)
+    uri.query = URI.encode_www_form(params) if params.size > 0
+    uri
+  end
+
+  #
+  # Fetch URI, and return response.
+  #
+  # Raises an WeatherSage::HTTP::Error on error.
+  #
+  def fetch(uri)
+    @fetcher.fetch(uri)
+  end
+
+  #
+  # Parse HTTP response body.
+  #
+  def parse(resp)
+    @parser.parse(resp)
+  end
+end

data/lib/weather-sage/http/error.rb

@@ -0,0 +1,15 @@
+#
+# HTTP error wrapper.
+#
+class WeatherSage::HTTP::Error < ::RuntimeError
+  attr :url, :code, :response
+
+  #
+  # Create Error instance from URL, response code, and response.
+  #
+  def initialize(url, code, resp)
+    @url = url.freeze
+    @code = code.freeze
+    @response = resp.freeze
+  end
+end

data/lib/weather-sage/http/fetcher.rb

@@ -0,0 +1,79 @@
+require 'net/http'
+
+#
+# HTTP fetcher.
+#
+class WeatherSage::HTTP::Fetcher
+  #
+  # Request headers.
+  #
+  HEADERS = {
+    'Accept'      => 'application/json',
+    'User-Agent'  => "weather-sage/#{WeatherSage::VERSION}"
+  }.freeze
+
+  #
+  # Create an HTTP Fetcher.
+  #
+  def initialize(log)
+    @log = log
+  end
+
+  #
+  # Fetch URI, and return response.
+  #
+  # Raises an WeatherSage::HTTP::Error on error.
+  #
+  def fetch(uri, limit = 5)
+    # log uri
+    @log.info('Fetcher#fetch') { '%p' % [uri] }
+
+    # create request, set headers
+    req = Net::HTTP::Get.new(uri)
+    HEADERS.each { |k, v| req[k] = v }
+    use_ssl = (uri.scheme == 'https')
+
+    # connect, fetch response
+    resp = Net::HTTP.start(uri.host, uri.port, use_ssl: use_ssl) do |http|
+      http.request(req)
+    end
+
+    # log response
+    @log.debug('Fetcher#fetch') { 'response: %p' % [resp] }
+
+    # check for error
+    case resp
+    when Net::HTTPSuccess
+      resp
+    when Net::HTTPRedirection
+      # have we hit the redirect limit?
+      unless limit > 0
+        # redirect limit hit, raise error
+        raise ::WeatherSage::HTTP::Error.new(uri.to_s, resp.code, resp)
+      end
+
+      # get new uri
+      new_uri = uri.merge(resp['location'])
+
+      # log redirect
+      @log.debug('Fetcher#fetch') do
+        'redirect: %s' % [JSON.unparse({
+          location: resp['location'],
+          old_uri: uri,
+          new_uri: new_uri,
+        })]
+      end
+
+      # decriment limit, redirect
+      fetch(new_uri, limit - 1)
+    else
+      # log error
+      @log.debug('Fetcher#fetch') do
+        'HTTP request failed: url = %s, response = %p' % [uri, resp]
+      end
+
+      # raise error
+      raise ::WeatherSage::HTTP::Error.new(uri.to_s, resp.code, resp)
+    end
+  end
+end

data/lib/weather-sage/http/parser.rb

@@ -0,0 +1,46 @@
+require 'json'
+
+#
+# HTTP response body parser.
+#
+class WeatherSage::HTTP::Parser
+  #
+  # Regex match for known JSON content types.
+  #
+  JSON_CONTENT_TYPE_REGEX =
+    /^application\/json|text\/json|application\/geo\+json/
+
+  #
+  # Create an HTTP response body parser.
+  #
+  def initialize(log)
+    @log = log
+  end
+
+  #
+  # Parse HTTP response body.
+  #
+  def parse(resp)
+    # FIXME: need to extract encoding from content-type
+    resp.body.force_encoding('UTF-8')
+
+    r = case resp.content_type
+    when JSON_CONTENT_TYPE_REGEX
+      # parse and return json
+      JSON.parse(resp.body)
+    else
+      # return string
+      resp.body
+    end
+
+    @log.debug('Parser#parse') do
+      JSON.unparse({
+        type: resp.content_type,
+        data: r,
+      })
+    end
+
+    # return response
+    r
+  end
+end

data/lib/weather-sage/http.rb

@@ -0,0 +1,9 @@
+#
+# Namespace for HTTP classes.
+#
+module WeatherSage::HTTP
+  autoload :Error, File.join(__dir__, 'http', 'error.rb')
+  autoload :Parser, File.join(__dir__, 'http', 'parser.rb')
+  autoload :Fetcher, File.join(__dir__, 'http', 'fetcher.rb')
+  autoload :Cache, File.join(__dir__, 'http', 'cache.rb')
+end

data/lib/weather-sage/weather/base-object.rb

@@ -0,0 +1,36 @@
+#
+# Base class for weather API objects.
+#
+class WeatherSage::Weather::BaseObject
+  attr :cache
+
+  #
+  # Create a new weather object.
+  #
+  def initialize(ctx)
+    @ctx = ctx
+  end
+
+  protected
+
+  #
+  # URL format string for API requests.
+  #
+  API_URL = 'https://api.weather.gov/%s'
+
+  #
+  # Request given API endpoint, return response.
+  #
+  # FIXME: should handle errors too.
+  #
+  def get(path)
+    # build full URL
+    url = API_URL % [path]
+
+    # log full URL
+    @ctx.log.debug('BaseObject#get') { '%s' % [url] }
+
+    # get URL from cache
+    @ctx.cache.get(url)
+  end
+end

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

@@ -0,0 +1,47 @@
+require 'time'
+
+#
+# Numerical weather forecast.
+#
+class WeatherSage::Weather::Forecast
+  attr :data,
+       :updated_at,
+       :units,
+       :generator,
+       :generated_at,
+       :update_time,
+       :valid_times,
+       :elevation,
+       :periods
+
+  #
+  # Create new forecast object from given data.
+  #
+  def initialize(ctx, data)
+    # cache context and data, get properties
+    @ctx, @data = ctx, data.freeze
+    props = @data['properties']
+
+    # log data
+    @ctx.log.debug('Forecast#initialize') do
+      'data = %p' % [@data]
+    end
+
+    @updated_at = Time.parse(props['updated'])
+    @units = props['units']
+    @generator = props['generator']
+    @generated_at = Time.parse(props['generatedAt'])
+    @update_time = Time.parse(props['updateTime'])
+    @valid_times = props['validTimes']
+    @elevation = props['elevation']['value']
+  end
+
+  #
+  # Return an array of periods for this forecast.
+  #
+  def periods
+    @periods ||= @data['properties']['periods'].map { |row|
+      ::WeatherSage::Weather::Period.new(@ctx, row)
+    }
+  end
+end

data/lib/weather-sage/weather/observation.rb

@@ -0,0 +1,33 @@
+#
+# Weather station observation metadata.
+#
+module WeatherSage::Weather::Observation
+  #
+  # Observation property types.
+  #
+  PROPERTIES = {
+    timestamp:                  :time,
+    textDescription:            :text,
+    rawMessage:                 :text,
+    icon:                       :url,
+
+    temperature:                :value,
+    dewpoint:                   :value,
+    windDirection:              :value,
+    windSpeed:                  :value,
+    windGust:                   :value,
+    barometricPressure:         :value,
+    seaLevelPressure:           :value,
+    visibility:                 :value,
+    maxTemperatureLast24Hours:  :value,
+    minTemperatureLast24Hours:  :value,
+    precipitationLastHour:      :value,
+    precipitationLast3Hours:    :value,
+    precipitationLast6Hours:    :value,
+    relativeHumidity:           :value,
+    windChill:                  :value,
+    heatIndex:                  :value,
+
+    cloudLayers:                :cloud,
+  }.freeze
+end