oxr 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. checksums.yaml +4 -4
  2. data/.travis.yml +5 -4
  3. data/README.md +91 -30
  4. data/lib/oxr.rb +60 -55
  5. data/lib/oxr/configuration.rb +41 -0
  6. data/lib/oxr/version.rb +2 -2
  7. data/oxr.gemspec +2 -1
  8. metadata +20 -5
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 61911998061bee0501d6db3d1fe3f3f00dcc7c9b
4
- data.tar.gz: 4afda8ff15cf6b26a1728d3ae1b50d2b270305cb
3
+ metadata.gz: 387efd5944296a8914dfe3f5c8c8ff54d4089fe0
4
+ data.tar.gz: 6ba3228cc4c48d2a8dc4a4526ea7272afb0df4d7
5
5
  SHA512:
6
- metadata.gz: 8798474d8dbb3e53954857a2c7c56515a92eacc0674b5cdad083591927fb2794728f470a91bbb6ebe40db872b16499880d0b72e80d19c54cf41bdf8943ca76ff
7
- data.tar.gz: 5108175cb8ac1ee4d79b4ecbd7b2c207c7f616b57ced79e7bcb60a85d1181e1e402cb7085b3243c00b40c974b409270b5d443240ba93c88536c6a11b9305fe64
6
+ metadata.gz: 03d9f43350b618d6cbd56f7266f3ba86bb280cd83e0ac6342546596955e5cdbb331e852de00088f7e543d49a430695bb70d5b06016ef04208a49005a0c60ec95
7
+ data.tar.gz: ec14398cdd653786cc2837552848df9f5d9867449205dd3e7630e03a8b29947b6de7015f3e23a69f2f7d863cce3df360bde0095775387946dae616bf16d3369f
data/.travis.yml CHANGED
@@ -1,6 +1,7 @@
1
1
  language: ruby
2
2
  rvm:
3
- - 2.1.8
4
- - 2.2.4
5
- - 2.3.0
6
- before_install: gem install bundler -v 1.11.2
3
+ - 2.1.10
4
+ - 2.2.6
5
+ - 2.3.3
6
+ - 2.4.1
7
+ before_install: gem install bundler -v 1.14.6
data/README.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  # OXR
4
4
 
5
- This gem provides a basic interface to the [Open Exchange Rates](https://openexchangerates.org) API.
5
+ This gem provides a basic interface to the
6
+ [Open Exchange Rates](https://openexchangerates.org) API. At present, only the
7
+ API calls available to free plans have been implemented.
6
8
 
7
9
  ## Installation
8
10
 
@@ -22,88 +24,147 @@ Or install it yourself as:
22
24
 
23
25
  ## Usage
24
26
 
25
- If you have not done so already, sign up for account on [Open Exchange Rates](https://openexchangerates.org). Once you have an account, go to Your Dashboard and locate your App ID.
27
+ If you have not done so already, sign up for account on
28
+ [Open Exchange Rates](https://openexchangerates.org). Once you have an account,
29
+ go to Your Dashboard and locate your App ID.
26
30
 
27
- Instantiate a new OXR object, passing your App ID as an argument.
31
+ Configure OXR with your App ID by calling `OXR.configure`:
28
32
 
29
33
  ```ruby
30
- oxr = OXR.new 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
34
+ OXR.configure do |config|
35
+ config.app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
36
+ end
31
37
  ```
32
38
 
33
- The Open Exchange Rates API returns results as JSON objects. OXR parses these (using the [json](https://rubygems.org/gems/json) gem) and returns the resulting Hashes. To see the exact structure of the responses for different queries, check the [Open Exchange Rates documentation](https://docs.openexchangerates.org/) or examine the sample responses in `test/fixtures`.
39
+ (If you are using OXR within a Rails application, you will probably want to put
40
+ this in an initializer.)
41
+
42
+ You can get current exchange rates using `OXR.get_rate`:
43
+
44
+ ```ruby
45
+ OXR.get_rate 'GBP' # => 0.703087
46
+ OXR.get_rate 'JPY' # => 111.7062
47
+ ```
34
48
 
35
- Get the latest conversion rates with `OXR#latest`.
49
+ You can also use the `OXR.[]` shortcut method.
36
50
 
37
51
  ```ruby
38
- oxr.latest
52
+ OXR['GBP'] # => 0.703087
53
+ ```
54
+
55
+ `OXR.get_rate` accepts an optional keyword argument to retrieve historical
56
+ exchange rates for given dates. The provided date should be an object which
57
+ responds to `#strftime`.
58
+
59
+ ```ruby
60
+ OXR.get_rate 'GBP', on: Date.new(2015, 6, 14) # => 0.642607
61
+ ```
62
+
63
+ You perform more complex operations by using the lower-level API calls. These
64
+ methods return the raw JSON responses returned by Open Exchange Rates (parsed
65
+ using the [json](https://rubygems.org/gems/json) gem).
66
+
67
+ Get the latest exchange rates with `OXR#latest`.
68
+
69
+ ```ruby
70
+ OXR.latest
39
71
  ```
40
72
 
41
73
  This will return a JSON object with a structure similar to the following:
42
74
 
43
75
  ```json
44
76
  {
45
- "disclaimer": "...",
46
- "license": "...",
77
+ "disclaimer": "…",
78
+ "license": "…",
47
79
  "timestamp": 1234567890,
48
80
  "base": "USD",
49
81
  "rates": {
50
82
  "AED": 3.672995,
51
83
  "AFN": 68.360001,
52
84
  "ALL": 123.0332,
53
- /* ... */
85
+ /* … */
86
+ "ZMK": 5252.024745,
87
+ "ZMW": 11.332275,
88
+ "ZWL": 322.387247
54
89
  }
55
90
  }
56
91
  ```
57
92
 
58
- `OXR#[]` is a shortcut for looking up the conversion rate for a single currency without digging through the JSON object returned by `OXR#latest` yourself.
59
-
60
- ```ruby
61
- oxr['GBP'] # => 0.642607
62
- oxr['JPY'] # => 123.3267
63
- ```
64
-
65
- Get historical conversion rates for specific dates with `OXR#historical`. This method requires you to provide a Date object for the date you wish to query.
93
+ Get historical exchange rates for specific dates with `OXR#historical`. This
94
+ method requires you to provide the date you wish to lookup. The date argument
95
+ should respond to `#strftime`.
66
96
 
67
97
  ```ruby
68
- oxr.historical on: Date.new(2016, 3, 24)
98
+ OXR.historical on: Date.new(2016, 3, 24)
69
99
  ```
70
100
 
71
101
  This will return a JSON object with a structure similar to that returned by `OXR#latest`.
72
102
 
73
- Get a list of currently supported currencies with `OXR#currencies`.
103
+ Get a list of available currencies with `OXR#currencies`.
74
104
 
75
105
  ```ruby
76
- oxr.currencies
106
+ OXR.currencies
77
107
  ```
78
108
 
79
- Get information about your account (including your usage for the current period) with `OXR#usage`.
109
+ Get information about your account including your usage for the current period
110
+ with `OXR#usage`.
80
111
 
81
112
  ```ruby
82
- oxr.usage
113
+ OXR.usage
83
114
  ```
84
115
 
85
116
  ## Testing
86
117
 
87
- Normally, any API call will result in a live request to Open Exchange Rates. This probably isn't what you want when you're running tests. You can optionally stub the responses of specific API calls by adding an entry to `OXR.sources`. If you want to stop using custom sources, you can restore normal behavior by calling `OXR.reset_sources`. For example:
118
+ Normally, any API call will send a request to Open Exchange Rates. Since your
119
+ plan allows a limited number of requests per month, you probably want to avoid
120
+ this when running in a test environment. You can stub the responses of specific
121
+ API calls by configuring the endpoint for specific calls to use a local file
122
+ instead of an HTTP request. Just provide a JSON file that reflects the payload
123
+ of an actual API call. (You will find usable JSON files in test/fixtures
124
+ included with this gem.)
125
+
126
+ When you're done, you can call `OXR.reset_sources` to restore the default behavior.
127
+
128
+ Below is an example of configuring OXR within a test.
88
129
 
89
130
  ```ruby
90
131
  class SomeTest < Minitest::Test
91
132
  def setup
92
- OXR.sources[:latest] = 'test/fixtures/sample_data.json'
133
+ OXR.configure do |config|
134
+ config.latest = 'test/fixtures/sample.json'
135
+ end
93
136
  end
94
137
 
95
138
  def teardown
96
139
  OXR.reset_sources
97
140
  end
141
+ end
142
+ ```
98
143
 
99
- def test_something
100
- oxr = OXR.new('XXX')
101
- assert_equal 42, oxr.latest['rates']['GBP']
102
- end
144
+ (You might consider doing this in your development environment as well.)
145
+
146
+ ## Upgrading
147
+
148
+ The interface has changed between the 0.2.0 and 0.3.0 tags. It is no longer
149
+ necessary to instantiate an OXR object. The API calls are available as class
150
+ methods directly on the OXR module.
151
+
152
+ ```ruby
153
+ # Before
154
+ oxr = OXR.new 'YOUR_APP_ID'
155
+ oxr['JPY']
156
+ oxr.usage
157
+
158
+ # Now
159
+ OXR.configure do |config|
160
+ config.app_id = 'YOUR_APP_ID'
103
161
  end
162
+ OXR['JPY']
163
+ OXR.usage
104
164
  ```
105
165
 
106
- In this example `test/fixtures/sample_data.json` should contain JSON data matching the structure of an actual Open Exchange Rates response. If you want to stop using custom sources, you can restore normal behavior by calling `OXR.reset_sources`.
166
+ (You can still call `OXR.new`, but this behavior will generate a deprecation
167
+ warning.)
107
168
 
108
169
  ## Development
109
170
 
data/lib/oxr.rb CHANGED
@@ -1,81 +1,86 @@
1
- require "oxr/version"
1
+ require 'oxr/version'
2
+ require 'oxr/configuration'
2
3
 
3
4
  require 'date'
4
5
  require 'json'
5
6
  require 'open-uri'
6
7
 
7
- class OXR
8
- BASE_PATH = 'https://openexchangerates.org/api/'.freeze
8
+ module OXR
9
+ class Error < StandardError
10
+ end
9
11
 
10
- class OXRError < StandardError
11
- def initialize(message, response)
12
- super message
13
- @response = response
12
+ class ApiError < Error
13
+ def message
14
+ cause.message
14
15
  end
15
16
 
16
- attr_reader :response
17
- end
17
+ def description
18
+ response['description']
19
+ end
18
20
 
19
- def initialize(app_id)
20
- @app_id = app_id
21
+ def response
22
+ @response ||= JSON.load cause.io
23
+ end
21
24
  end
22
25
 
23
- attr_reader :app_id
26
+ class << self
27
+ def new(app_id)
28
+ warn '[DEPRECATION WARNING] OXR.new is depr4ecated.' \
29
+ " Use OXR class methods instead (from #{caller.first})."
30
+ configure do |config|
31
+ config.app_id = app_id
32
+ end
33
+ self
34
+ end
24
35
 
25
- def [](code)
26
- latest['rates'][code]
27
- end
36
+ def get_rate(code, on: nil)
37
+ data = if on
38
+ historical on: on
39
+ else
40
+ latest
41
+ end
42
+ data['rates'][code.to_s]
43
+ end
28
44
 
29
- def latest
30
- endpoint = sources[:latest] || build_uri_endpoint('latest.json')
31
- call endpoint
32
- end
45
+ alias_method :[], :get_rate
33
46
 
34
- def historical(on:)
35
- endpoint = sources[:historical] || \
36
- build_uri_endpoint('historical/', "#{on.strftime '%Y-%m-%d'}.json")
37
- call endpoint
38
- end
47
+ def currencies
48
+ call configuration.currencies
49
+ end
39
50
 
40
- def currencies
41
- endpoint = sources[:currencies] || build_uri_endpoint('currencies.json')
42
- call endpoint
43
- end
51
+ def historical(on:)
52
+ call configuration.historical on
53
+ end
44
54
 
45
- def usage
46
- endpoint= sources[:usage] || build_uri_endpoint('usage.json')
47
- call endpoint
48
- end
55
+ def latest
56
+ call configuration.latest
57
+ end
49
58
 
50
- private
59
+ def usage
60
+ call configuration.usage
61
+ end
51
62
 
52
- def build_uri_endpoint(*path, **params)
53
- URI.join(BASE_PATH, *path).tap do |uri|
54
- uri.query = "app_id=#{app_id}"
63
+ def reset_sources
64
+ configure do |config|
65
+ config.reset_sources
66
+ end
55
67
  end
56
- end
57
68
 
58
- def call(endpoint)
59
- JSON.load open endpoint
60
- rescue OpenURI::HTTPError => e
61
- case e.message
62
- when /\A4[[:digit:]]{2}/
63
- response = JSON.load e.io
64
- raise OXRError.new response['description'], response
65
- else
66
- raise
69
+ def configure
70
+ yield configuration if block_given?
71
+ configuration
67
72
  end
68
- end
69
73
 
70
- def sources
71
- self.class.sources
72
- end
74
+ def configuration
75
+ @configuration ||= Configuration.new
76
+ end
73
77
 
74
- def self.sources
75
- @sources ||= {}
76
- end
78
+ private
77
79
 
78
- def self.reset_sources
79
- sources.clear
80
+ def call(endpoint)
81
+ JSON.load open endpoint
82
+ rescue OpenURI::HTTPError => e
83
+ raise ApiError.new e
84
+ end
80
85
  end
81
86
  end
data/lib/oxr/configuration.rb ADDED
@@ -0,0 +1,41 @@
1
+ require 'uri'
2
+
3
+ module OXR
4
+ class Configuration
5
+ ENDPOINT = 'https://openexchangerates.org/api/'
6
+
7
+ attr_accessor :app_id
8
+ attr_writer :currencies, :historical, :latest, :usage
9
+
10
+ def currencies
11
+ @currencies || URI.join(ENDPOINT, 'currencies.json').tap { |uri|
12
+ uri.query = "app_id=#{app_id}"
13
+ }.to_s
14
+ end
15
+
16
+ def historical(date)
17
+ @historical || URI.join(ENDPOINT, "historical/#{date.strftime('%F')}.json").tap { |uri|
18
+ uri.query = "app_id=#{app_id}"
19
+ }.to_s
20
+ end
21
+
22
+ def latest
23
+ @latest || URI.join(ENDPOINT, 'latest.json').tap { |uri|
24
+ uri.query = "app_id=#{app_id}"
25
+ }.to_s
26
+ end
27
+
28
+ def usage
29
+ @usage || URI.join(ENDPOINT, 'usage.json').tap { |uri|
30
+ uri.query = "app_id=#{app_id}"
31
+ }.to_s
32
+ end
33
+
34
+ def reset_sources
35
+ @currencies = nil
36
+ @historical = nil
37
+ @latest = nil
38
+ @usage = nil
39
+ end
40
+ end
41
+ end
data/lib/oxr/version.rb CHANGED
@@ -1,3 +1,3 @@
1
- class OXR
2
- VERSION = "0.2.0"
1
+ module OXR
2
+ VERSION = "0.4.0"
3
3
  end
data/oxr.gemspec CHANGED
@@ -24,8 +24,9 @@ Gem::Specification.new do |spec|
24
24
  spec.add_development_dependency "bundler", "~> 1.11"
25
25
  spec.add_development_dependency "rake", "~> 10.0"
26
26
  spec.add_development_dependency "minitest", "~> 5.0"
27
+ spec.add_development_dependency 'minitest-focus'
27
28
  spec.add_development_dependency 'pry'
28
- spec.add_development_dependency 'webmock'
29
+ spec.add_development_dependency 'webmock', '~> 2.3'
29
30
 
30
31
  spec.add_dependency 'json'
31
32
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: oxr
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - John Parker
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2016-03-26 00:00:00.000000000 Z
11
+ date: 2017-03-29 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -53,7 +53,7 @@ dependencies:
53
53
  - !ruby/object:Gem::Version
54
54
  version: '5.0'
55
55
  - !ruby/object:Gem::Dependency
56
- name: pry
56
+ name: minitest-focus
57
57
  requirement: !ruby/object:Gem::Requirement
58
58
  requirements:
59
59
  - - ">="
@@ -67,7 +67,7 @@ dependencies:
67
67
  - !ruby/object:Gem::Version
68
68
  version: '0'
69
69
  - !ruby/object:Gem::Dependency
70
- name: webmock
70
+ name: pry
71
71
  requirement: !ruby/object:Gem::Requirement
72
72
  requirements:
73
73
  - - ">="
@@ -80,6 +80,20 @@ dependencies:
80
80
  - - ">="
81
81
  - !ruby/object:Gem::Version
82
82
  version: '0'
83
+ - !ruby/object:Gem::Dependency
84
+ name: webmock
85
+ requirement: !ruby/object:Gem::Requirement
86
+ requirements:
87
+ - - "~>"
88
+ - !ruby/object:Gem::Version
89
+ version: '2.3'
90
+ type: :development
91
+ prerelease: false
92
+ version_requirements: !ruby/object:Gem::Requirement
93
+ requirements:
94
+ - - "~>"
95
+ - !ruby/object:Gem::Version
96
+ version: '2.3'
83
97
  - !ruby/object:Gem::Dependency
84
98
  name: json
85
99
  requirement: !ruby/object:Gem::Requirement
@@ -110,6 +124,7 @@ files:
110
124
  - bin/console
111
125
  - bin/setup
112
126
  - lib/oxr.rb
127
+ - lib/oxr/configuration.rb
113
128
  - lib/oxr/version.rb
114
129
  - oxr.gemspec
115
130
  homepage: https://github.com/jparker/oxr
@@ -132,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
132
147
  version: '0'
133
148
  requirements: []
134
149
  rubyforge_project:
135
- rubygems_version: 2.5.2
150
+ rubygems_version: 2.6.11
136
151
  signing_key:
137
152
  specification_version: 4
138
153
  summary: Interface for Open Exchange Rates API.