method renames and minior refactor

Author: jtgrenz

README.md

@@ -38,14 +38,15 @@ ShopifyAPI::Session.temp(domain: domain, token: token, api_version: api_version)
 end
 ```
 
-The `api_version` attribute can take the string or symbol name of any known version and correctly coerce it to a `ShopifyAPI::ApiVersion`.
-By default any string or symbol will naïvely coerce into an ApiVersion. To ensure only known and active versions can be set, call
+The `api_version` attribute takes a version handle (ie `'2019-07'` or `:unstable`) sets an instance of `ShopifyAPI::ApiVersion` matching the handle.
+By default, any handle will naïvely create a new `ApiVersion` if the version is not in the known versions returned by `ShopifyAPI::ApiVersion.versions`. To ensure only known and active versions can be set, call
 
 ```ruby
-ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
 ShopifyAPI::ApiVersion.fetch_known_versions
 ```
-Known versions are fetched and cached from https://app.shopify.com/services/apis.json. Trying to use a version outside this set will raise an error. To switch back to naïve coercion, call `ShopifyAPI::ApiVersion.coercion_mode = :define_on_unknown` (the default mode).
+
+Known versions are fetched and cached from https://app.shopify.com/services/apis.json. Trying to use a version outside this set will raise an error. To switch back to naïve lookup and create a version if its not found, call `ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown` (this is the default mode).
 
 For example if you want to use the `2019-04` version you would create a session like this:
 ```ruby

lib/shopify_api/api_version.rb

@@ -9,40 +9,42 @@ class InvalidVersion < StandardError; end
     UNSTABLE_HANDLE = 'unstable'
     UNSTABLE_AS_DATE = Time.utc(3000, 1, 1)
     API_PREFIX = '/admin/api/'
-    COERSION_MODES = [:predefined_only, :define_on_unknown].freeze
+    LOOKUP_MODES = [:raise_on_unknown, :define_on_unknown].freeze
 
     class << self
       attr_reader :versions
 
-      def coercion_mode
-        @coercion_mode ||= :define_on_unknown
+      def version_lookup_mode
+        @version_lookup_mode ||= :define_on_unknown
       end
 
-      def coercion_mode=(mode)
-        raise ArgumentError, "Mode must be one of #{COERSION_MODES}" unless COERSION_MODES.include?(mode)
-        sanitize_known_versions if mode == :predefined_only
-        @coercion_mode = mode
+      def version_lookup_mode=(mode)
+        raise ArgumentError, "Mode must be one of #{LOOKUP_MODES}" unless LOOKUP_MODES.include?(mode)
+        sanitize_known_versions if mode == :raise_on_unknown
+        @version_lookup_mode = mode
       end
 
-      def coerce_to_version(version_or_handle)
+      def find_version(version_or_handle)
         return version_or_handle if version_or_handle.is_a?(ApiVersion)
         handle = version_or_handle.to_s
-
         @versions ||= {}
         @versions.fetch(handle) do
-          if @coercion_mode == :predefined_only
-            error_msg = if @versions.empty?
-              "No versions defined. You must call `ApiVersion.fetch_known_versions` first."
-            else
-              "`#{handle}` is not in the defined version set. Available versions: #{@versions.keys}"
-            end
-            raise UnknownVersion, "ApiVersion.coercion_mode is set to `:predefined_only`. #{error_msg}"
+          if @version_lookup_mode == :raise_on_unknown
+            raise UnknownVersion, unknown_version_error_message(handle)
           else
-            @versions[handle] = ApiVersion.new(handle: handle)
+            add_to_known_versions(ApiVersion.new(handle: handle))
           end
         end
       end
 
+      def coerce_to_version(version_or_handle)
+        warn(
+          '[DEPRECATED] ShopifyAPI::ApiVersion.coerce_to_version be removed in a future version. ' \
+            'Use `find_version` instead.'
+        )
+        find_version(version_or_handle)
+      end
+
       def fetch_known_versions
         @versions = Meta.admin_versions.map do |version|
           [version.handle, ApiVersion.new(version.attributes.merge(verified: version.persisted?))]
@@ -57,6 +59,10 @@ def define_known_versions
         fetch_known_versions
       end
 
+      def add_to_known_versions(version)
+        @versions[version.handle] = version
+      end
+
       def clear_known_versions
         @versions = {}
       end
@@ -86,6 +92,12 @@ def sanitize_known_versions
           [handle, @versions[handle]]
         end.compact.to_h
       end
+
+      def unknown_version_error_message(handle)
+        msg = "ApiVersion.version_lookup_mode is set to `:raise_on_unknown`. \n"
+        return msg + "No versions defined. You must call `ApiVersion.fetch_known_versions` first." if @versions.empty?
+        msg + "`#{handle}` is not in the defined version set. Available versions: #{@versions.keys}"
+      end
     end
 
     attr_reader :handle, :display_name, :supported, :latest_supported, :verified

lib/shopify_api/resources/base.rb

@@ -66,7 +66,7 @@ def api_version
       end
 
       def api_version=(version)
-        self._api_version = version.nil? ? nil : ApiVersion.coerce_to_version(version)
+        self._api_version = version.nil? ? nil : ApiVersion.find_version(version)
       end
 
       def prefix(options = {})

lib/shopify_api/session.rb

@@ -127,7 +127,7 @@ def site
     end
 
     def api_version=(version)
-      @api_version = version.nil? ? nil : ApiVersion.coerce_to_version(version)
+      @api_version = version.nil? ? nil : ApiVersion.find_version(version)
     end
 
     def valid?

test/api_version_test.rb

@@ -2,51 +2,51 @@
 require 'test_helper'
 
 class ApiVersionTest < Test::Unit::TestCase
-  test "coerce_to_version returns any version object given" do
+  test "find_version returns any version object given" do
     version = ShopifyAPI::ApiVersion.new(handle: :unstable)
-    assert_same(version, ShopifyAPI::ApiVersion.coerce_to_version(version))
+    assert_same(version, ShopifyAPI::ApiVersion.find_version(version))
   end
 
-  test "coerce_to_version converts a known version into a version object" do
+  test "find_version converts a known version into a version object" do
     versions = [
       ShopifyAPI::ApiVersion.new(handle: :unstable),
       ShopifyAPI::ApiVersion.new(handle: '2019-01'),
     ]
 
     assert_equal(versions, [
-      ShopifyAPI::ApiVersion.coerce_to_version('unstable'),
-      ShopifyAPI::ApiVersion.coerce_to_version('2019-01'),
+      ShopifyAPI::ApiVersion.find_version('unstable'),
+      ShopifyAPI::ApiVersion.find_version('2019-01'),
     ])
   end
 
-  test "coerce_to_version removes unverified versions from version set if mode is set to :predefined_only" do
-    ShopifyAPI::ApiVersion.coercion_mode = :define_on_unknown
+  test "find_version removes unverified versions from version set if mode is set to :raise_on_unknown" do
+    ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown
     assert ShopifyAPI::ApiVersion.versions.values.all?(&:verified?)
     assert_equal 5, ShopifyAPI::ApiVersion.versions.size
 
-    ShopifyAPI::ApiVersion.coerce_to_version('2019-30')
+    ShopifyAPI::ApiVersion.find_version('2019-30')
     refute ShopifyAPI::ApiVersion.versions.values.all?(&:verified?)
     assert_equal 6, ShopifyAPI::ApiVersion.versions.size
-    ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+    ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
 
     assert ShopifyAPI::ApiVersion.versions.values.all?(&:verified?)
     assert_equal 5, ShopifyAPI::ApiVersion.versions.size
   end
 
-  test "coerce_to_version does not raise when coercing a string if no versions are defined when coercion_mode is :define_on_unknown" do
+  test "find_version does not raise when coercing a string if no versions are defined when version_lookup_mode is :define_on_unknown" do
     ShopifyAPI::ApiVersion.clear_known_versions
-    ShopifyAPI::ApiVersion.coercion_mode = :define_on_unknown
-    assert_equal :define_on_unknown, ShopifyAPI::ApiVersion.coercion_mode
+    ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown
+    assert_equal :define_on_unknown, ShopifyAPI::ApiVersion.version_lookup_mode
     assert_nothing_raised do
-      ShopifyAPI::ApiVersion.coerce_to_version('made up version')
+      ShopifyAPI::ApiVersion.find_version('made up version')
     end
   end
 
-  test "coerce_to_version does raise when coercing a string if no versions are defined when coercion_mode is :predefined_only" do
+  test "find_version does raise when coercing a string if no versions are defined when version_lookup_mode is :raise_on_unknown" do
     refute ShopifyAPI::ApiVersion.versions['made up version']
-    ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+    ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
     assert_raises ShopifyAPI::ApiVersion::UnknownVersion do
-      ShopifyAPI::ApiVersion.coerce_to_version('made up version')
+      ShopifyAPI::ApiVersion.find_version('made up version')
     end
   end
 

test/detailed_log_subscriber_test.rb

@@ -37,7 +37,7 @@ def setup
   def teardown
     super
     ShopifyAPI::ApiVersion.clear_known_versions
-    ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+    ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
   end
 
   def set_logger(logger)

test/pagination_test.rb

@@ -4,7 +4,7 @@ class PaginationTest < Test::Unit::TestCase
   def setup
     super
 
-    @version = ShopifyAPI::ApiVersion.coerce_to_version('2019-10')
+    @version = ShopifyAPI::ApiVersion.find_version('2019-10')
     ShopifyAPI::Base.api_version = @version.to_s
     @next_page_info = "eyJkaXJlY3Rpb24iOiJuZXh0IiwibGFzdF9pZCI6NDQwMDg5NDIzLCJsYXN0X3ZhbHVlIjoiNDQwMDg5NDIzIn0%3D"
     @previous_page_info = "eyJsYXN0X2lkIjoxMDg4MjgzMDksImxhc3RfdmFsdWUiOiIxMDg4MjgzMDkiLCJkaXJlY3Rpb24iOiJuZXh0In0%3D"
@@ -131,7 +131,7 @@ def setup
   end
 
   test "raises on an invalid API version" do
-    version = ShopifyAPI::ApiVersion.coerce_to_version('2019-04')
+    version = ShopifyAPI::ApiVersion.find_version('2019-04')
     ShopifyAPI::Base.api_version = version.to_s
 
     fake 'orders', :method => :get, :status => 200, api_version: version, :body => load_fixture('orders')
@@ -143,7 +143,7 @@ def setup
   end
 
   test "does not raise on the unstable version" do
-    version = ShopifyAPI::ApiVersion.coerce_to_version('unstable')
+    version = ShopifyAPI::ApiVersion.find_version('unstable')
     ShopifyAPI::Base.api_version = version.to_s
     @next_link_header = "<https://this-is-my-test-shop.myshopify.com/admin/api/unstable/orders.json?page_info=#{@next_page_info}>; rel=\"next\""
 

test/session_test.rb

@@ -345,6 +345,6 @@ def generate_signature(params)
 
   def any_api_version
     version_name = ['2019-01', :unstable].sample(1).first
-    ShopifyAPI::ApiVersion.coerce_to_version(version_name)
+    ShopifyAPI::ApiVersion.find_version(version_name)
   end
 end

test/test_helper.rb

@@ -63,7 +63,7 @@ def teardown
         ShopifyAPI::Base.user = nil
 
         ShopifyAPI::ApiVersion.clear_known_versions
-        ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+        ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
       end
 
       # Custom Assertions
@@ -95,7 +95,7 @@ def fake(endpoint, options={})
         body   = options.has_key?(:body) ? options.delete(:body) : load_fixture(endpoint)
         format = options.delete(:format) || :json
         method = options.delete(:method) || :get
-        api_version = options.delete(:api_version) || ShopifyAPI::ApiVersion.coerce_to_version('2019-01')
+        api_version = options.delete(:api_version) || ShopifyAPI::ApiVersion.find_version('2019-01')
         extension = ".#{options.delete(:extension)||'json'}" unless options[:extension]==false
         status = options.delete(:status) || 200
         url = if options.has_key?(:url)