oxr 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66eacf6ebbb7f1ae8119dee57fc9f567c091bf9dcfc56991503e75feeb88e141
-  data.tar.gz: a1f43993c6a057ffbd668ef67fb126e6046fcf53897e1d16d001c9c023a8d9d2
+  metadata.gz: 92128e15490b54bf144c83a1d16f81f950f7178a88d6b4138b6fe7a3da31043a
+  data.tar.gz: 42a8dea111e46dff4030d8a626e0b5f7e6e0dd653e1df82bd4436f88fd3d4c06
 SHA512:
-  metadata.gz: 6a24056f9f8345d88faf2e7bbabd554186c6f6811d00affaca19a6a7d75fcc00cdaafd0da6dc998728de7925bca59e1119d146040e19dd36761e7bf7cd0cf9f3
-  data.tar.gz: 80878e29a28157acf0571402db5669c1ec817a5e74a143f116df482c098d2bb1d77528e0b361777ac50bc665eb17605d653a588668bcafb9e9db3feed467ec59
+  metadata.gz: ae7a594268c345b4ec69cf93829a904b1ce2345cc432174292f684740b37d1add47b61c1e62df5728f42fe8eade1472dee810c42326513cf9611792e9f5e7093
+  data.tar.gz: 7c1eb6b5a21118673857b42dec90878de993d47206cb98672e7cc46c4538774e775c51fef1b9892eaf3152f21468f58c8f306a8bdff08aef94d0748567b9a008

data/.gitlab-ci.yml

@@ -0,0 +1,23 @@
+before_script:
+  - gem install bundler --no-document -v '~> 2.2.15'
+  - bundle install --jobs="$(nproc)" --retry=3
+
+build:rubocop:
+  image: "ruby:3.0"
+  script:
+    - bundle exec rubocop
+
+test:ruby-2.6:
+  image: "ruby:2.6"
+  script:
+    - bundle exec rake test
+
+test:ruby-2.7:
+  image: "ruby:2.7"
+  script:
+    - bundle exec rake test
+
+test:ruby-3.0:
+  image: "ruby:3.0"
+  script:
+    - bundle exec rake test

data/.rubocop.yml

@@ -0,0 +1,11 @@
+AllCops:
+  Exclude:
+    - bin/*
+    - Gemfile
+    - oxr.gemspec
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.5
+Metrics/AbcSize:
+  Exclude:
+    - test/oxr_test.rb

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.0.1

data/.travis.yml

@@ -1,6 +1,5 @@
 language: ruby
 rvm:
-  - 2.2.7
-  - 2.3.4
-  - 2.4.1
-before_install: gem install bundler -v 1.14.6
+  - "2.6"
+  - "2.7"
+  - "3.0"

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## OXR 0.6.0 (April 15, 2021) ##
+
+*   Now works on Ruby 3.0
+*   Gem now requires Ruby >= 2.5, only testing >= 2.6
+*   Addressed Rubocop warnings
+*   Code comments
+
 ## OXR 0.5.0 (December 16, 2017) ##
 
 *   Added `base` option for performing queries with custom base currencies.

data/README.md

@@ -65,7 +65,7 @@ You perform more complex operations by using the lower-level API calls. These
 methods return the raw JSON responses returned by Open Exchange Rates (parsed
 using the [json](https://rubygems.org/gems/json) gem).
 
-Get the latest exchange rates with `OXR#latest`.
+Get the latest exchange rates with `OXR.latest`.
 
 ```ruby
 OXR.latest
@@ -92,7 +92,7 @@ This will return a JSON object with a structure similar to the following:
 }
 ```
 
-Get historical exchange rates for specific dates with `OXR#historical`. This
+Get historical exchange rates for specific dates with `OXR.historical`. This
 method requires you to provide the date you wish to lookup. The date argument
 should respond to `#strftime`.
 
@@ -100,16 +100,16 @@ should respond to `#strftime`.
 OXR.historical on: Date.new(2016, 3, 24)
 ```
 
-This will return a JSON object with a structure similar to that returned by `OXR#latest`.
+This will return a JSON object with a structure similar to that returned by `OXR.latest`.
 
-Get a list of available currencies with `OXR#currencies`.
+Get a list of available currencies with `OXR.currencies`.
 
 ```ruby
 OXR.currencies
 ```
 
 Get information about your account including your usage for the current period
-with `OXR#usage`.
+with `OXR.usage`.
 
 ```ruby
 OXR.usage
@@ -170,15 +170,23 @@ warning.)
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also 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`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jparker/oxr.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/jparker/oxr.
 
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 

data/lib/oxr.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oxr/version'
 require 'oxr/configuration'
 
@@ -5,10 +7,62 @@ require 'date'
 require 'json'
 require 'open-uri'
 
+##
+# All use of OXR takes place through module methods.
+#
+# Before you can make API calls, you must configure OXR with your Open Exchange
+# Rates App ID. Visit https://openexchangerates.org to sign up and generate one.
+#
+#   OXR.configure do |config|
+#     config.app_id = 'XXXX'
+#   end
+#
+# Optionally you may also specify the base currency for the conversion rates.
+# The default base currency is USD.
+#
+#   OXR.configure do |config|
+#     config.app_id = 'XXXX'
+#     config.base = 'JPY'
+#   end
+#
+# If you will be using OXR in a test environment, you may want to test the
+# substitute local files for the API endpoints to provide deterministic results
+# and avoid running over your Open Exchange Rates API request quota.
+#
+#   class ThisIsATest < Minitest::Test
+#     def setup
+#       OXR.configure do |config|
+#         config.latest = 'test/fixtures/sample.json'
+#       end
+#     end
+#
+#     def teardown
+#       OXR.reset_sources
+#     end
+#   end
+#
+# To quickly get an exchange rate from the base currency to a given currency,
+# use `OXR.get_rate`.
+#
+#   OXR.get_rate 'GBP' # => 0.703087
+#   OXR.get_rate 'JPY' # => 111.7062
+#
+# This method is aliased as `OXR.[]`.
+#
+#   OXR['GBP'] # => 0.703087
+#
+# Pass the `:on` keyword argument to get an historical exchange rate on a given
+# date.
+#
+#   OXR.get_rate 'GBP', on: Date.new(2015, 6, 14) # => 0.642607
+#
 module OXR
   class Error < StandardError
   end
 
+  ##
+  # ApiError is raised when OXR encounters an error connecting to the Open
+  # Exchange Rates API server.
   class ApiError < Error
     def message
       cause.message
@@ -24,8 +78,15 @@ module OXR
   end
 
   class << self
+    ##
+    # DEPRECATED: TO BE REMOVED IN 0.7.
+    #
+    # OXR should no longer be instantiated explicitly.
+    #
+    # Call OXR.configure to specify the application ID and use the module
+    # methods below to access the different API endpoints.
     def new(app_id)
-      warn '[DEPRECATION WARNING] OXR.new is deprecated.' \
+      warn '[DEPRECATION] OXR.new is deprecated and will be removed from 0.7.' \
         " Use OXR class methods instead (from #{caller(1..1).first})."
       configure do |config|
         config.app_id = app_id
@@ -33,6 +94,11 @@ module OXR
       self
     end
 
+    ##
+    # Get the latest exchange rate for currency identified by +code+.
+    #
+    # If the optional +on+ keyword is provided, it instead returns the
+    # historical exchange rate on the given date.
     def get_rate(code, on: nil)
       data = if on
                historical on: on
@@ -44,31 +110,53 @@ module OXR
 
     alias [] get_rate
 
+    ##
+    # Returns a Hash mapping currency codes to full currency names.
     def currencies
       call configuration.currencies
     end
 
+    ##
+    # Returns a Hash mapping currency codes to their historical exchange rate
+    # on the date given by the +on+ keyword argument.
+    #
+    # The exchange rate is relative to the configured base currency.
     def historical(on:)
       call configuration.historical on
     end
 
+    ##
+    # Returns a Hash mapping currency codes to their latest exchange rate.
+    #
+    # The exchange rate is relative to the configured base currency.
     def latest
       call configuration.latest
     end
 
+    ##
+    # Returns a Hash containinng details about the Open Exchange Rates account
+    # and current usage statistics.
     def usage
       call configuration.usage
     end
 
+    ##
+    # Resets API endpoints to their defaults.
     def reset_sources
       configure(&:reset_sources)
     end
 
+    ##
+    # Returns the OXR configuration struct.
+    #
+    # If given a block, the configuration will be yielded to the block.
     def configure
       yield configuration if block_given?
       configuration
     end
 
+    ##
+    # Returns the OXR configuration struct.
     def configuration
       @configuration ||= Configuration.new
     end
@@ -76,7 +164,9 @@ module OXR
     private
 
     def call(endpoint)
-      JSON.parse(open(endpoint).read)
+      uri = URI.parse endpoint
+      data = uri.scheme ? uri.read : File.read(uri.path)
+      JSON.parse data
     rescue OpenURI::HTTPError => e
       raise ApiError, e
     end

data/lib/oxr/configuration.rb

@@ -1,18 +1,55 @@
+# frozen_string_literal: true
+
 require 'uri'
 
 module OXR
+  ##
+  # A container for OXR configuration options.
+  #
+  # Stores the API application ID and the base currency for which to request
+  # exchange rates.
+  #
+  # Also stores the URI endpoints for fetching currencies, the latest exchange
+  # ranges,  historical exchange rates, and current account usage statistics.
+  #
+  # By default, endpoints are generated dynamically, allowing them to
+  # automatically adapte to changes to the app_id, but they may be set to a
+  # fixed path, including a local file path. This is useful during testing when
+  # you might want deterministic results and do not want to waste real API
+  # requests.
   class Configuration
-    ENDPOINT = 'https://openexchangerates.org/api/'.freeze
+    ENDPOINT = 'https://openexchangerates.org/api/'
+
+    ##
+    # Get and set the application ID that will be sent to the API server.
+    attr_accessor :app_id
+
+    ##
+    # Get and set the base currency to be used when fetching exchange rates.
+    attr_accessor :base
 
-    attr_accessor :app_id, :base
+    ##
+    # Set respective API endpoints. Use these if you want to sidestep the API
+    # server, e.g., for testing.
     attr_writer :currencies, :historical, :latest, :usage
 
+    def initialize
+      reset_sources
+    end
+
+    ##
+    # Returns the endpoint for listing known currencies.
     def currencies
       @currencies || URI.join(ENDPOINT, 'currencies.json').tap do |uri|
         uri.query = "app_id=#{app_id}"
       end.to_s
     end
 
+    ##
+    # Returns the endpoint for historical currency exchange rates on the given
+    # date.
+    #
+    # Expects +date+ to respond #strftime.
     def historical(date)
       @historical || URI.join(ENDPOINT, "historical/#{date.strftime('%F')}.json").tap do |uri|
         uri.query = "app_id=#{app_id}"
@@ -20,6 +57,8 @@ module OXR
       end.to_s
     end
 
+    ##
+    # Returns the endpoint for the latest currency exchange rates.
     def latest
       @latest || URI.join(ENDPOINT, 'latest.json').tap do |uri|
         uri.query = "app_id=#{app_id}"
@@ -27,12 +66,16 @@ module OXR
       end.to_s
     end
 
+    ##
+    # Returns the endpoint for fetch current API usage statistics.
     def usage
       @usage || URI.join(ENDPOINT, 'usage.json').tap do |uri|
         uri.query = "app_id=#{app_id}"
       end.to_s
     end
 
+    ##
+    # Resets all API endpoints back to their default (dynamic generation).
     def reset_sources
       @currencies = nil
       @historical = nil

data/lib/oxr/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OXR
-  VERSION = '0.5.0'.freeze
+  VERSION = '0.6.0'
 end

data/oxr.gemspec

@@ -1,4 +1,3 @@
-
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'oxr/version'
@@ -19,14 +18,14 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.1'
+  spec.required_ruby_version = '>= 2.5'
 
-  spec.add_development_dependency 'bundler', '~> 1.11'
+  spec.add_development_dependency 'bundler', '>= 1.17'
   spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'minitest-focus'
   spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'webmock', '~> 2.3'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'webmock', '~> 3.0'
 
   spec.add_dependency 'json'
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: oxr
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-16 00:00:00.000000000 Z
+date: 2021-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.17'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.17'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: minitest-focus
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,47 +53,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -116,6 +116,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".gitlab-ci.yml"
+- ".rubocop.yml"
+- ".tool-versions"
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile
@@ -140,15 +143,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.1'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.2.15
 signing_key: 
 specification_version: 4
 summary: Interface for Open Exchange Rates API.