open_weather_client 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e71860d474b67b88ec968c56ca18bfcd98029b9078bbd73fef481bd1dcf8736
-  data.tar.gz: 8eb818af6393f4cbbac4dddea37800911ebe58a0dd10bc323f337251596cd088
+  metadata.gz: 0dec682ab56d84b58d75c7cee7e1741ea87e5a38e8cedec1ef927b35014108be
+  data.tar.gz: ed092b5ca8ddeb5bffdb77d1abcacbb52cc5c37a317cee41aacd4063fd680a25
 SHA512:
-  metadata.gz: 85a0e87c06cfa1753b6c3b2baaa251fd864fc03e50af861b86d015dc5a37739f043361c82fafea26794877b0652821a65b27f04efaab905ffb903bca22fedba5
-  data.tar.gz: 31ad8150d112bfcfd0b7b5e0b62830d3d5336968a76754dad1dc16e255ff0916901fd176fe8557688492101e2ed147392210cda1e4c6dd1920166d3c1bff477b
+  metadata.gz: 84de4f4266c121d44033694c6dbca2519db1f87976dd420ec64711831e45957ceb827a33b60a30a045ac6b7734760c85f7404654332c4d22fd9a7fb1423c05be
+  data.tar.gz: 037bcb2ff6e0fdf53023520b290fc0cfc821c0184a94208dfd9d108a86852998d5af7ff23a1aa4d8ceb73f2dacc46d9bb64d0e01a7e096c198ff121aab7a2fff

data/.rubocop.yml

@@ -0,0 +1,6 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*

data/CHANGES.md

@@ -1,5 +1,19 @@
 # Open Weather Client Changelog
 
+## 0.1.3
+Re-release of 0.1.2 since this version was released from an incorrect branch.
+
+## 0.1.2 [yanked]
+- Enable Rubocop Linter
+- Add caching of requests (#1)
+- Add location quantization (#3)
+- Reset gem before every example in spec (#2)
+
+## 0.1.1
+- Raise `OpenWeatherClient::AuthenticationError` if the request is not authorized
+- Raise `RangeError` if latitude or longitude is out of the allowed range
+- Raise `Faraday::Error` if the request fails otherwise 
+
 ## 0.1.0
 - Initial commit of the Open Weather Client gem
 - Configuration of OpenWeatherClient

data/Gemfile

@@ -1,6 +1,8 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in open_weather_client.gemspec
 gemspec

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/open_weather_client.svg)](https://badge.fury.io/rb/open_weather_client)
 ![RSpec](https://github.com/qurasoft/open_weather_client/actions/workflows/ruby.yml/badge.svg)
 
-Welcome to Open Weather Client. This gem allows you to easily send messages from your ruby project to Microsoft Teams channels.
+Welcome to Open Weather Client. This gem allows you to easily request weather information from OpenWeatherMap.
 It integrates in your rails project, when you are using bundler or even in plain ruby projects.
 
 ## Installation
@@ -35,6 +35,11 @@ end
 OpenWeatherClient::Weather.current(lat: 50.3569, lon: 7.5890)
 ```
 
+### Exceptions during requests
+When an error occurs during a request, an exception is raised.
+If the request is not authorized `OpenWeatherClient::AutheniticationError` is raied.
+When attributes like latitude or longitude are outside of the expected range a `RangeError` is raised.
+
 ### Secure Configuration
 In Rails provides the credentials functionality for [environmental security](https://edgeguides.rubyonrails.org/security.html#environmental-security). This mechanism can be used by OpenWeatherClient to load the API key from an encrypted file. This also allows easy separation of production and development channel configuration.
 All settings are defined under the top-level entry `open_weather_client`.
@@ -53,6 +58,46 @@ OpenWeatherClient.configure do |config|
 end
 ```
 
+### Caching
+By default Open Weather Client does not cache any data and every request will be send to the OpenWeatherMap servers.
+
+To speed up requests and reduce the number network requests caching can be enabled.
+When Open Weather Client is reset, the cache is also reset.
+The cache may be accessed directly through the singleton `OpenWeatherClient.cache`.
+
+Whether requests are only performed when the requested time is within the last hour.
+If caching is enabled, requests with a time older than one hour might still be answered with a response.
+
+```ruby
+OpenWeatherClient.configure do |config|
+  config.caching = OpenWeatherClient::Caching::Memory
+  config.max_memory_entries = 100 # Maximum number of entries in memory cache
+end
+```
+
+#### Memory Caching
+`OpenWeatherClient` supports simple in memory caching.
+A hash is used to store and look up the cached responses.
+
+#### Custom Caching
+To implement custom caching, the interface of `OpenWeatherClient::Caching` is used.
+A custom caching solution must implement its specific `caching_get(key)`, `caching_store(key, data)` and `present?(key)` methods.
+
+### Spatial Quantization
+Since weather is more often than not a wider phenomenon, the high resolution location data, commonly available today may interfere with the performance even when using caching.
+Caching uses the full resolution of the location data.
+By default no quantization is performed.
+
+OpenWeatherClient allows defining a quantization function to transform the latitude and longitude data before making requests or hitting the cache.
+The quantization receives latitude and longitude.
+The result is coerced back into latitude and longitude.
+
+```ruby
+OpenWeatherClient.configure do |config|
+  config.spatial_quantization = proc { |lat, lon| [lat.round(2), lon.round(2)] }
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'open_weather_client'

data/lib/open_weather_client/caching/memory.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenWeatherClient
+  class Caching
+    ##
+    # Memory cache of OpenWeatherMap requests
+    #
+    # The requests are cached in memory up to the number specified in config.max_memory_entries.
+    # When the limit is reached the least recently used entry is evicted.
+    class Memory < OpenWeatherClient::Caching
+      # Memory cache to store a hash of keys and request data
+      attr :memory_cache
+      # Key registry of the memory cache. The first entry is the key of the least recently accessed data
+      attr :memory_keys
+
+      ##
+      # Initialize an empty cache
+      def initialize
+        super
+        @memory_cache = {}
+        @memory_keys = []
+      end
+
+      private
+
+      def caching_get(key)
+        @memory_keys.delete(key)
+        @memory_keys << key if @memory_cache.key? key
+        @memory_cache[key]
+      end
+
+      def caching_store(key, data)
+        @memory_cache[key] = data
+        @memory_keys.delete(key)
+        @memory_keys << key
+
+        if @memory_keys.count > OpenWeatherClient.configuration.max_memory_entries
+          @memory_cache.delete(@memory_keys.shift)
+        end
+
+        data
+      end
+
+      def present?(key)
+        @memory_keys.include?(key)
+      end
+    end
+  end
+end

data/lib/open_weather_client/caching.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module OpenWeatherClient
+  ##
+  # Caching of OpenWeatherMap requests
+  #
+  # The entries are cached according to latitude, longitude and time of the request.
+  # The time is clamped to the current hour
+  #
+  # This is the caching interface and equals a none cache. Get requests raise an error.
+  class Caching
+    ##
+    # Get an entry out of the cache defined by its +lat+, +lon+ and +time+.
+    #
+    # @param lat[Float] latitude of the requests location
+    # @param lon[Float] longitude of the requests location
+    # @param time[Time] time of the request
+    #
+    # @raise [KeyError] if no entry is present
+    # @raise [NotImplementedError] if an unsupported caching method is used
+    #
+    # @return [Hash] the stored data
+    def get(lat:, lon:, time:)
+      key = cache_key(lat, lon, time)
+      raise KeyError unless present?(key)
+
+      caching_get(key)
+    end
+
+    ##
+    # Store the data by its +lat+, +lon+ and +time+.
+    #
+    # @param data[Hash] data to be stored, must be able to be formatted and parsed as text
+    # @param lat[Float] latitude of the requests location
+    # @param lon[Float] longitude of the requests location
+    # @param time[Time] time of the request
+    #
+    # @return [Hash] the input data
+    def store(data:, lat:, lon:, time:)
+      key = cache_key(lat, lon, time)
+
+      caching_store(key, data)
+
+      data
+    end
+
+    private
+
+    ##
+    # Calculate the key for storage in the cache
+    #
+    # @param lat[Float] latitude of the requests location
+    # @param lon[Float] longitude of the requests location
+    # @param time[Time] time of the request
+    def cache_key(lat, lon, time)
+      "#{lat}_#{lon}_#{time.strftime('%Y-%m-%dT%H')}"
+    end
+
+    ##
+    # Read an entry out of the memory cache
+    #
+    # @param key[String] key into the cache. Is stored at the end of the key registry
+    #
+    # @return [Hash] the stored data
+    def caching_get(key)
+      raise NotImplementedError
+    end
+
+    ##
+    # Store an entry in the memory cache
+    #
+    # Evicts the entry with the least recent access if the memory cache is full
+    #
+    # @param key[String] key into the cache. Is stored at the end of the key registry
+    # @param data[Hash] data to be stored, must be able to be formatted and parsed as text
+    #
+    # @return [Hash] the input data
+    def caching_store(key, data)
+      data
+    end
+
+    ##
+    # Check whether a key is present in the cache
+    #
+    # @return always false when the cache method is not supported or caching is not enabled
+    def present?(_key)
+      false
+    end
+  end
+end

data/lib/open_weather_client/configuration.rb

@@ -1,18 +1,53 @@
+# frozen_string_literal: true
+
 module OpenWeatherClient
+  ##
+  # Configuratin of OpenWeatherClient
   class Configuration
-    attr_accessor :appid, :lang, :units, :url, :user_agent
+    # [String] API key to access OpenWeatherMap
+    attr_accessor :appid
+    # Caching method. One of :none, :memory
+    attr_reader :caching
+    # [String] Requested language of the result
+    attr_accessor :lang
+    # [Integer] Maximum allowed number of entries when using caching method :memory
+    attr_accessor :max_memory_entries
+    # [Proc] Quantization of latitude and longitude
+    attr_accessor :spatial_quantization
+    # [String] Requested units of the result
+    attr_accessor :units
+    # [String] Base URL of the requests to OpenWeatherMap
+    attr_accessor :url
+    # [String] User-Agent of the requests made to OpenWeatherMap
+    attr_accessor :user_agent
 
+    ##
+    # Initialize a new Configuration with the default settings
     def initialize
+      @caching = OpenWeatherClient::Caching.new
       @lang = 'de'
+      @max_memory_entries = 10_000
       @units = 'metric'
       @url = 'https://api.openweathermap.org/data'
       @user_agent = "Open Weather Client/#{OpenWeatherClient::VERSION}"
     end
 
+    ##
+    # Set the caching method
+    #
+    # @param cache_class[Class] class definition adhering to the OpenWeatherClient::Caching interface
+    def caching=(cache_class)
+      @caching = cache_class.new
+    end
+
+    ##
+    # Load appid from Rails credentials
+    #
+    # Load the appid from Rails credentials using the top-level key 'open_weather_client'
+    #
+    # @raise [RuntimeError] if not using Rails
     def load_from_rails_credentials
-      unless defined? Rails
-        raise RuntimeError, 'This method is only available in Ruby on Rails.'
-      end
+      raise 'This method is only available in Ruby on Rails.' unless defined? Rails
 
       settings = Rails.application.credentials.open_weather_client!
       self.appid = settings[:appid]

data/lib/open_weather_client/request.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module OpenWeatherClient
+  ##
+  # Request the weather from OpenWeatherMap
+  class Request
+    ##
+    # Request the current weather
+    #
+    # @param lat[Float] latitude of the requests location
+    # @param lon[Float] longitude of the requests location
+    # @param time[Time] time of the request
+    #
+    # @raise [AuthenticationError] if the request is not authorized, e.g in case the API key is not correct
+    # @raise [NotCurrentError] if the requested time is older than 1 hour
+    #
+    # @return the response body
+    def self.get(lat:, lon:, time: Time.now)
+      raise OpenWeatherClient::NotCurrentError if time < Time.now - 1 * 60 * 60
+
+      connection = Faraday.new(
+        url: OpenWeatherClient.configuration.url,
+        params: {
+          appid: OpenWeatherClient.configuration.appid,
+          lat: lat,
+          lon: lon,
+          lang: OpenWeatherClient.configuration.lang,
+          units: OpenWeatherClient.configuration.units
+        },
+        headers: {
+          'User-Agent': OpenWeatherClient.configuration.user_agent
+        }
+      ) do |f|
+        f.response :raise_error
+        f.response :json
+      end
+
+      begin
+        response = connection.get('2.5/weather')
+        OpenWeatherClient.cache.store(lat: lat, lon: lon, data: response.body, time: time)
+      rescue Faraday::UnauthorizedError
+        raise OpenWeatherClient::AuthenticationError
+      end
+    end
+  end
+end

data/lib/open_weather_client/version.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
 module OpenWeatherClient
-  VERSION = "0.1.0"
+  ##
+  # Version of OpenWeatherClient
+  VERSION = '0.1.3'
 end

data/lib/open_weather_client/weather.rb

@@ -1,27 +1,47 @@
-require 'faraday'
+# frozen_string_literal: true
 
 module OpenWeatherClient
+  ##
+  # Request weather information from OpenWeatherMap or the cache
   class Weather
-    def self.current(lat:, lon:)
-      connection = Faraday.new(
-        url: OpenWeatherClient.configuration.url,
-        params: {
-          appid: OpenWeatherClient.configuration.appid,
-          lat: lat,
-          lon: lon,
-          lang: OpenWeatherClient.configuration.lang,
-          units: OpenWeatherClient.configuration.units
-        },
-        headers: {
-          'User-Agent': OpenWeatherClient.configuration.user_agent
-        }
-      ) do |f|
-        f.response :json
+    # [Float] latitude of the requested location
+    attr_accessor :lat
+    # [Float] longitude of the requested location
+    attr_accessor :lon
+    # [Time] time of the requested weather
+    attr_accessor :time
+
+    ##
+    # Initialize a new Weather request
+    #
+    # @param lat[Float] latitude of the requests location
+    # @param lon[Float] longitude of the requests location
+    # @param time[Time] time of the request
+    #
+    # @raise [RangeError] if one +lat+ or +lon+ are out of the expected ranges
+    def initialize(lat:, lon:, time: Time.now)
+      if OpenWeatherClient.configuration.spatial_quantization.respond_to?(:call)
+        lat, lon = OpenWeatherClient.configuration.spatial_quantization.call(lat, lon)
       end
 
-      response = connection.get('2.5/weather')
+      raise RangeError unless (-90..90).member?(lat)
+      raise RangeError unless (-180..180).member?(lon)
+
+      @lat = lat
+      @lon = lon
+      @time = time
+    end
 
-      response.body
+    ##
+    # get the weather according to the specified parameters
+    #
+    # @raise [AuthenticationError] if the request is not authorized, e.g in case the API key is not correct
+    #
+    # @return the stored or received data
+    def get
+      OpenWeatherClient.cache.get(lat: lat, lon: lon, time: time)
+    rescue KeyError
+      OpenWeatherClient::Request.get(lat: lat, lon: lon)
     end
   end
 end

data/lib/open_weather_client.rb

@@ -1,38 +1,71 @@
+# frozen_string_literal: true
+
+require 'open_weather_client/caching'
 require 'open_weather_client/configuration'
+require 'open_weather_client/request'
 require 'open_weather_client/version'
 require 'open_weather_client/weather'
 
+##
+# Get weather data from OpenWeatherMap
 module OpenWeatherClient
+  # Error during authentication with the OpenWeatherMap servers
+  class AuthenticationError < StandardError; end
+
+  # The rquested time is not current enough for getting weather data from the OpenWeatherMap server
+  class NotCurrentError < StandardError; end
+
   class << self
-    attr_accessor :configuration, :testing
+    # Caching singleton to access the cache
+    attr_writer :cache
+    # Configuration singleton to access the configuration
+    attr_writer :configuration
   end
 
+  ##
+  # Get the singleton cache instance
+  #
+  # @return [Caching] the cache
+  def self.cache
+    @cache ||= Caching.new
+  end
+
+  ##
+  # Get the singleton configuration instance
+  #
+  # @return [Configuration] the configuration
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  ##
+  # Reset cache and configuration
   def self.reset
+    @cache = Caching.new
     @configuration = Configuration.new
   end
 
+  ##
+  # Configure OpenWeatherClient
   def self.configure
     yield configuration
   end
 
+  ##
+  # Get the project root
   def self.project_root
-    if defined?(Rails)
-      return Rails.root
-    end
-
-    if defined?(Bundler)
-      return Bundler.root
-    end
+    return Rails.root if defined?(Rails)
+    return Bundler.root if defined?(Bundler)
 
     Dir.pwd
   end
 
+  ##
+  # Get the gem root
   def self.gem_root
-    spec = Gem::Specification.find_by_name("open_weather_client")
-    spec.gem_dir rescue project_root
+    spec = Gem::Specification.find_by_name('open_weather_client')
+    spec.gem_dir
+  rescue NoMethodError
+    project_root
   end
 end

data/open_weather_client.gemspec

@@ -1,43 +1,41 @@
+# frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "open_weather_client/version"
+require 'open_weather_client/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "open_weather_client"
+  spec.name          = 'open_weather_client'
   spec.version       = OpenWeatherClient::VERSION
-  spec.authors       = ["Lucas Keune"]
-  spec.email         = ["lucas.keune@qurasoft.de"]
+  spec.required_ruby_version = '>= 3.0'
+  spec.required_rubygems_version = '>= 2'
+  spec.authors       = ['Lucas Keune']
+  spec.email         = ['lucas.keune@qurasoft.de']
 
-  spec.summary       = %q{Access weather data from OpenWeatherMap}
-  spec.description   = %q{}
-  spec.homepage      = "https://github.com/Qurasoft/open_weather_client"
-  spec.license       = "MIT"
+  spec.summary       = 'Access weather data from OpenWeatherMap'
+  spec.description   = ''
+  spec.homepage      = 'https://github.com/Qurasoft/open_weather_client'
+  spec.license       = 'MIT'
 
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-    spec.metadata["homepage_uri"] = spec.homepage
-    spec.metadata["source_code_uri"] = "https://github.com/Qurasoft/open_weather_client"
-    spec.metadata["changelog_uri"] = "https://github.com/Qurasoft/open_weather_client/blob/main/CHANGES.md"
-  else
-    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
-  end
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Qurasoft/open_weather_client'
+  spec.metadata['changelog_uri'] = 'https://github.com/Qurasoft/open_weather_client/blob/main/CHANGES.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.bindir        = 'bin'
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
 
-  spec.add_dependency "faraday", ">= 2"
+  spec.add_dependency 'faraday', '>= 2'
 
-  spec.add_development_dependency "bundler", ">= 1.17"
-  spec.add_development_dependency "rake", ">= 10.0"
-  spec.add_development_dependency "rspec", ">= 3.0"
-  spec.add_development_dependency "webmock"
-  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency 'bundler', '>= 1.17'
+  spec.add_development_dependency 'rake', '>= 10.0'
+  spec.add_development_dependency 'rspec', '>= 3.0'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'webmock'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open_weather_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Lucas Keune
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2023-01-26 00:00:00.000000000 Z
+date: 2023-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: webmock
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -94,10 +94,27 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: ''
 email:
 - lucas.keune@qurasoft.de
-executables: []
+executables:
+- ".gitignore"
+- console
+- setup
 extensions: []
 extra_rdoc_files: []
 files:
@@ -106,6 +123,7 @@ files:
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGES.md
 - Gemfile
@@ -116,7 +134,10 @@ files:
 - bin/console
 - bin/setup
 - lib/open_weather_client.rb
+- lib/open_weather_client/caching.rb
+- lib/open_weather_client/caching/memory.rb
 - lib/open_weather_client/configuration.rb
+- lib/open_weather_client/request.rb
 - lib/open_weather_client/version.rb
 - lib/open_weather_client/weather.rb
 - open_weather_client.gemspec
@@ -135,12 +156,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2'
 requirements: []
 rubygems_version: 3.4.1
 signing_key: