nexus_mods 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6490bd894c40f7806bb126cb70ade888ab5121499b86ff2cc959ee663dd223d
-  data.tar.gz: d9fdeb53c88c27ce9503e328a261ddb31a0facbbe0b6c35c304628c6e9580790
+  metadata.gz: c2325f79c99fb7304d16a0e4b12682229d8187ae30f6d0321796a4d3d5e587fb
+  data.tar.gz: 1cce0b8b4a82f8c903be9d6b7441d739d3b5dffa375c699444e8f2e87af4f2be
 SHA512:
-  metadata.gz: 7c8f9576edd38dab0076f24ad1d396973c9d1ab8542ff4eef548d9b49758f85b6da465465b10b1e53dbb2db6d8312f31e9b88649916f654e7b8c1a12092aaadb
-  data.tar.gz: 1b2d1e915594af39c9bd793a8f216fc2796024e2729a2b5596c35b546e04c8e2bb96dce77aa35e11f5d7a98fba1652c79f77f01648a363cfdf9b93ec40ee7602
+  metadata.gz: 3d868fa12c0e79385a7377e08ff5c4d4b0ccab2b3c78bedfc99cc9761c7a85c98073260c1409534b2ba8ccebdf74e10f03ddb7dd619901a05c809514798818d9
+  data.tar.gz: 45b7c418a3c0aeeac13b3b6e5d7a2d095513cc96e78e30f9900bee7852ff17389a512afe347fe345b33cd97ab099831cd020ee09c1aab70241f576c980447f5b

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [v2.0.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v1.1.1...v2.0.0) (2023-04-11 10:15:58)
+
+### Breaking changes
+
+* [[Breaking] Remove http cache file and useless support for etags as the API does not cache at http level](https://github.com/Muriel-Salvan/nexus_mods/commit/e157524e17ef0ed1a7013f14b15eaa35bb309592)
+
+# [v1.1.1](https://github.com/Muriel-Salvan/nexus_mods/compare/v1.1.0...v1.1.1) (2023-04-10 19:39:28)
+
+### Patches
+
+* [Improved documentation and added examples](https://github.com/Muriel-Salvan/nexus_mods/commit/0eb3fd00e0d1ad34db04a30ab2043a49371dc64f)
+
 # [v1.1.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v1.0.0...v1.1.0) (2023-04-10 19:19:16)
 
 ### Features

data/README.md

@@ -2,6 +2,17 @@
 
 Simple Ruby API letting you handle [NexusMods](https://www.nexusmods.com/) REST API.
 
+## Main features
+
+* Get the API **limits**.
+* Get the **games** information.
+* Get individual **mods** and **mod files** information.
+* Configurable **caching** with expiry times to save API calls to nexusmods.com.
+* All served in an object-oriented **API in full Ruby**.
+
+See the [examples](examples) for more details on how to use it.
+Those examples expect that you set a valid NexusMods API key in the `NEXUS_MODS_API_KEY` environment variable.
+
 ## Install
 
 Via gem
@@ -54,7 +65,7 @@ Any contribution is welcome:
 
 ## Credits
 
-- [Muriel Salvan][link-author]
+- [Muriel Salvan](https://x-aeon.com/muriel)
 
 ## License
 

data/examples/api_caching.rb

@@ -0,0 +1,41 @@
+require 'nexus_mods'
+require 'fileutils'
+
+# Make sure a previous file for caching was not here before
+test_api_cache_file = 'nexus_mods_test_api_cache.json'
+FileUtils.rm_f test_api_cache_file
+
+nexus_mods = NexusMods.new(
+  api_key: ENV.fetch('NEXUS_MODS_API_KEY'),
+  api_cache_file: test_api_cache_file
+)
+
+initial_remaining = nexus_mods.api_limits.daily_remaining
+puts "Before fetching anything, daily API remaining is #{initial_remaining}"
+
+puts 'Fetch the list of games (without using cache)...'
+puts "Fetched #{nexus_mods.games.size} games."
+
+puts "After fetching those games, daily API remaining is #{nexus_mods.api_limits.daily_remaining}"
+
+puts 'Now we fetch again the list of games (this should use the cache)...'
+puts "Fetched #{nexus_mods.games.size} games."
+
+puts "After fetching those games a second time, daily API remaining is #{nexus_mods.api_limits.daily_remaining}"
+
+puts 'Now we close the current NexusMods instance ad re-instantiate a new one from scratch using the same API cache file'
+
+new_nexus_mods = NexusMods.new(
+  api_key: ENV.fetch('NEXUS_MODS_API_KEY'),
+  api_cache_file: test_api_cache_file
+)
+
+puts "Before fetching anything from the new instance, daily API remaining is #{new_nexus_mods.api_limits.daily_remaining}"
+
+puts 'Now we fetch the list of games from the new instance (this should use the cache that was stored in the file)...'
+puts "Fetched #{new_nexus_mods.games.size} games."
+
+puts "After fetching those games from the new instance, daily API remaining is #{new_nexus_mods.api_limits.daily_remaining}"
+
+puts
+puts "As a conclusion, we used 2 instances of NexusMods that have fetched games 3 times, and it consumed #{initial_remaining - new_nexus_mods.api_limits.daily_remaining} real API call."

data/examples/api_limits.rb

@@ -0,0 +1,12 @@
+require 'nexus_mods'
+
+api_limits = NexusMods.new(api_key: ENV.fetch('NEXUS_MODS_API_KEY')).api_limits
+puts <<~EO_OUTPUT
+  API limits:
+    daily_limit: #{api_limits.daily_limit}
+    daily_remaining: #{api_limits.daily_remaining}
+    daily_reset: #{api_limits.daily_reset}
+    hourly_limit: #{api_limits.hourly_limit}
+    hourly_remaining: #{api_limits.hourly_remaining}
+    hourly_reset: #{api_limits.hourly_reset}
+EO_OUTPUT

data/examples/games.rb

@@ -0,0 +1,8 @@
+require 'nexus_mods'
+
+games = NexusMods.new(api_key: ENV.fetch('NEXUS_MODS_API_KEY')).games
+puts "Found a total of #{games.size} games."
+puts 'Here is the top 10 by number of downloads:'
+games.sort_by { |game| -game.downloads_count }[0..9].each do |game|
+  puts "* #{game.name} (#{game.mods_count} mods, #{game.downloads_count} downloads)"
+end

data/examples/log_debug.rb

@@ -0,0 +1,10 @@
+require 'nexus_mods'
+
+puts 'Example of fetching a mod with log debug activated, and without using the cache (so that we always see the query):'
+puts
+NexusMods.new(
+  api_key: ENV.fetch('NEXUS_MODS_API_KEY'),
+  log_level: :debug,
+  game_domain_name: 'skyrimspecialedition',
+  mod_id: 42_521
+).mod(clear_cache: true)

data/examples/mods.rb

@@ -0,0 +1,24 @@
+require 'nexus_mods'
+
+nexus_mods = NexusMods.new(
+  api_key: ENV.fetch('NEXUS_MODS_API_KEY'),
+  game_domain_name: 'skyrimspecialedition'
+)
+some_mod_ids = [
+  266,
+  2_347,
+  17_230,
+  42_521
+]
+puts 'Here are some details about a few mods for Skyrim Special Edition:'
+puts
+some_mod_ids.each do |mod_id|
+  mod = nexus_mods.mod(mod_id:)
+  mod_files = nexus_mods.mod_files(mod_id:)
+  puts <<~EO_OUTPUT
+    ===== #{mod.name} (v#{mod.version}) by #{mod.uploader.name} (#{mod.downloads_count} downloads)
+    #{mod.summary}
+    * Last 5 files: #{mod_files.reverse[0..4].map(&:file_name).join(', ')}
+
+  EO_OUTPUT
+end

data/lib/nexus_mods/api_client.rb

@@ -1,7 +1,5 @@
 require 'fileutils'
 require 'faraday'
-require 'faraday-http-cache'
-require 'nexus_mods/file_cache'
 require 'nexus_mods/cacheable_api'
 
 class NexusMods
@@ -23,7 +21,6 @@ class NexusMods
     #
     # Parameters::
     # * *api_key* (String or nil): The API key to be used, or nil for another authentication [default: nil]
-    # * *http_cache_file* (String): File used to store the HTTP cache, or nil for no cache [default: "#{Dir.tmpdir}/nexus_mods_http_cache.json"]
     # * *api_cache_expiry* (Hash<Symbol,Integer>): Expiry times in seconds, per expiry key. Possible keys are:
     #   * *games*: Expiry associated to queries on games [default: 1 day]
     #   * *mod*: Expiry associated to queries on mod [default: 1 day]
@@ -32,7 +29,6 @@ class NexusMods
     # * *logger* (Logger): The logger to be used for log messages [default: Logger.new(STDOUT)]
     def initialize(
       api_key: nil,
-      http_cache_file: "#{Dir.tmpdir}/nexus_mods_http_cache.json",
       api_cache_expiry: DEFAULT_API_CACHE_EXPIRY,
       api_cache_file: "#{Dir.tmpdir}/nexus_mods_api_cache.json",
       logger: Logger.new($stdout)
@@ -43,16 +39,7 @@ class NexusMods
       ApiClient.api_client = self
       @logger = logger
       # Initialize our HTTP client
-      @http_cache = http_cache_file.nil? ? nil : FileCache.new(http_cache_file)
-      @http_client = Faraday.new do |builder|
-        # Indicate that the cache is not shared, meaning that private resources (depending on the session) can be cached as we consider only 1 user is using it for a given file cache.
-        # Use Marshal serializer as some URLs can't get decoded correctly due to UTF-8 issues
-        builder.use :http_cache,
-                    store: @http_cache,
-                    shared_cache: false,
-                    serializer: Marshal
-        builder.adapter Faraday.default_adapter
-      end
+      @http_client = Faraday.new
       Cacheable.cache_adapter = :persistent_json
       load_api_cache
     end

data/lib/nexus_mods/version.rb

@@ -1,5 +1,5 @@
 class NexusMods
 
-  VERSION = '1.1.0'
+  VERSION = '2.0.0'
 
 end

data/lib/nexus_mods.rb

@@ -39,7 +39,6 @@ class NexusMods
   # * *game_domain_name* (String): Game domain name to query by default [default: 'skyrimspecialedition']
   # * *mod_id* (Integer): Mod to query by default [default: 1]
   # * *file_id* (Integer): File to query by default [default: 1]
-  # * *http_cache_file* (String): File used to store the HTTP cache, or nil for no cache [default: "#{Dir.tmpdir}/nexus_mods_http_cache.json"]
   # * *api_cache_expiry* (Hash<Symbol,Integer>): Expiry times in seconds, per expiry key. Possible keys are:
   #   * *games*: Expiry associated to queries on games [default: 1 day]
   #   * *mod*: Expiry associated to queries on mod [default: 1 day]
@@ -52,7 +51,6 @@ class NexusMods
     game_domain_name: 'skyrimspecialedition',
     mod_id: 1,
     file_id: 1,
-    http_cache_file: "#{Dir.tmpdir}/nexus_mods_http_cache.json",
     api_cache_expiry: {},
     api_cache_file: "#{Dir.tmpdir}/nexus_mods_api_cache.json",
     logger: Logger.new($stdout),
@@ -66,7 +64,6 @@ class NexusMods
     @premium = false
     @api_client = ApiClient.new(
       api_key:,
-      http_cache_file:,
       api_cache_expiry:,
       api_cache_file:,
       logger:

data/spec/nexus_mods_test/helpers.rb

@@ -56,7 +56,6 @@ module NexusModsTest
       if @nexus_mods.nil?
         args[:api_key] = MOCKED_API_KEY unless args.key?(:api_key)
         # By default running tests should not persistent cache files
-        args[:http_cache_file] = nil unless args.key?(:http_cache_file)
         args[:api_cache_file] = nil unless args.key?(:api_cache_file)
         # Redirect any log into a string so that they don't pollute the tests output and they could be asserted.
         @nexus_mods_logger = StringIO.new
@@ -115,11 +114,6 @@ module NexusModsTest
         'User-Agent' => "nexus_mods (#{RUBY_PLATFORM}) Ruby/#{RUBY_VERSION}",
         'apikey' => api_key
       }
-      if @expected_returned_etags.include? mocked_etag
-        expected_request_headers['If-None-Match'] = mocked_etag
-      else
-        @expected_returned_etags << mocked_etag
-      end
       @expected_stubs << [
         stub_request(http_method, "https://#{host}#{path}").with(headers: expected_request_headers).to_return(
           status: [code, message],
@@ -190,9 +184,6 @@ RSpec.configure do |config|
     @nexus_mods = nil
     # Reload the ApiClient as it stores caches at class level
     NexusMods::ApiClient.clear_cacheable_expiry_caches
-    # Keep a list of the etags we should have returned, so that we know when queries should contain them
-    # Array<String>
-    @expected_returned_etags = []
     # List of expected stubs and the number of times they were supposed to mock
     # Array< [ WebMock::RequestStub, Integer ] >
     @expected_stubs = []
@@ -205,6 +196,7 @@ RSpec.configure do |config|
   config.around do |example|
     example.call
   ensure
+    # This would dump the logs in case of debug mode
     reset_nexus_mods
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus_mods
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Muriel Salvan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-10 00:00:00.000000000 Z
+date: 2023-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,20 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-- !ruby/object:Gem::Dependency
-  name: faraday-http-cache
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: cacheable
   requirement: !ruby/object:Gem::Requirement
@@ -131,10 +117,20 @@ extra_rdoc_files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
+- examples/api_caching.rb
+- examples/api_limits.rb
+- examples/games.rb
+- examples/log_debug.rb
+- examples/mods.rb
 files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
+- examples/api_caching.rb
+- examples/api_limits.rb
+- examples/games.rb
+- examples/log_debug.rb
+- examples/mods.rb
 - lib/nexus_mods.rb
 - lib/nexus_mods/api/api_limits.rb
 - lib/nexus_mods/api/category.rb
@@ -147,7 +143,6 @@ files:
 - lib/nexus_mods/cacheable_with_expiry.rb
 - lib/nexus_mods/core_extensions/cacheable/cache_adapters/persistent_json_adapter.rb
 - lib/nexus_mods/core_extensions/cacheable/method_generator.rb
-- lib/nexus_mods/file_cache.rb
 - lib/nexus_mods/version.rb
 - spec/nexus_mods_test/factories/games.rb
 - spec/nexus_mods_test/factories/mod_files.rb

data/lib/nexus_mods/file_cache.rb

@@ -1,71 +0,0 @@
-class NexusMods
-
-  # Simple key/value file cache
-  class FileCache
-
-    # Constructor
-    #
-    # Parameters::
-    # * *file* (String): File to use as a cache
-    def initialize(file)
-      @file = file
-      @cache_content = File.exist?(file) ? JSON.parse(File.read(file)) : {}
-    end
-
-    # Dump the cache in file
-    def dump
-      File.write(@file, @cache_content.to_json)
-    end
-
-    # Get the cache content as a Hash
-    #
-    # Result::
-    # * Hash<String, Object>: Cache content
-    def to_h
-      @cache_content
-    end
-
-    # Is a given key present in the cache?
-    #
-    # Parameters::
-    # * *key* (String): The key
-    # Result::
-    # * Boolean: Is a given key present in the cache?
-    def key?(key)
-      @cache_content.key?(key)
-    end
-
-    # Read a key from the cache
-    #
-    # Parameters:
-    # * *key* (String): The cache key
-    # Result::
-    # * Object or nil: JSON-serializable object storing the value, or nil in case of cache-miss
-    def read(key)
-      @cache_content.key?(key) ? @cache_content[key] : nil
-    end
-
-    alias [] read
-
-    # Write a key/value in the cache
-    #
-    # Parameters:
-    # * *key* (String): The key
-    # * *value* (Object): JSON-serializable object storing the value
-    def write(key, value)
-      @cache_content[key] = value
-    end
-
-    alias []= write
-
-    # Delete a key in the cache
-    #
-    # Parameters:
-    # * *key* (String): The key
-    def delete(key)
-      @cache_content.delete(key)
-    end
-
-  end
-
-end