comic_vine 0.1.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5282482a38f24a137b4df6914ae771b6d3c02ee8
-  data.tar.gz: b6439f9bbf3ccd569910b8fac4a5c74105fb3d0c
+SHA256:
+  metadata.gz: 73bf9362c8e1a01699796797ec6173bf728515de3d87f7e9d00643eb9da79a8d
+  data.tar.gz: bb9a531d2ba69cc53bbc8933e70f49527892367d79f6c1c6f8c3fcc57a82f573
 SHA512:
-  metadata.gz: 2db1172216e1a4cce6f619d7daf800b4ecae51673c1adb2d5618b33e5a1e385ed5de8a91ece3b395b75323ac126b6bb9c537eb792cd3cbed94e85585732eb2bd
-  data.tar.gz: e40e0b8b5ff5d04f24667ed1d28098434780d8a14a29d064cc337bd7081bf9826c389673893f8052b34033f2847b5e6db3095325751364aaba85c4f817f95ed0
+  metadata.gz: 94931bde6c6ece327e406c8cddb65c6049b13c78b16d346aaa06b87ac74d3c6decae2b7adb9dd26abd0bd9a07367de44c36ecdfdfb00daf519e0e1a9eea237fd
+  data.tar.gz: ccd3b165209efde156dc98cc6a9de098578f4f5a805dc0bcfeb540fe7aa5e95de9bd3e3368d367acc14c893f45f7c269319c83aebe6b08cd2b590a66109f1b7d

data/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+Notable changes to this project are documented in this file. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); dates for releases
+before 2026 are taken from the git history.
+
+## [1.0.0] — 2026-07-08
+
+First stable release. **Breaking**: requires Ruby >= 3.4, and error handling
+and pagination behavior have changed as described below.
+
+### Added
+
+- Error hierarchy under `ComicVine::CVError`: `CVAPIError`, `CVHTTPError`
+  (with `#status`), `CVRateLimitError`, `CVConnectionError`, and `CVParseError`.
+- Connection timeouts (`open_timeout` 10s, `read_timeout` 30s), configurable via
+  `ComicVine::API.open_timeout = ...` / `read_timeout = ...`.
+- Automatic retries with exponential backoff on HTTP 420/429/5xx and connection
+  failures; honors `Retry-After`. Configurable via `max_retries` and
+  `retry_base_delay`.
+- Custom User-Agent header, overridable via `ComicVine::API.user_agent = ...`.
+- `respond_to_missing?` on `ComicVine::API` and `CVObject`, so `respond_to?`
+  and `method(...)` work for dynamic methods.
+- `ComicVine::API.reset_types_cache!` for tests.
+- RuboCop and YARD configuration; API documentation comments.
+
+### Changed
+
+- JSON parsing uses the Ruby standard library; the gem now has **no runtime
+  dependencies** (`multi_json`, `oj`, and `gson` removed).
+- Class variables replaced with class-level instance variables; the `/types/`
+  cache is guarded by a mutex and no longer poisoned by a failed fetch.
+- `next_page`/`prev_page` return `self` on success and `nil` at either end,
+  and preserve the original `filter`/`sort`/`field_list` options.
+- Modernized gemspec (metadata URIs, `Dir` glob instead of `git ls-files`),
+  RSpec 3 configuration, and WebMock-stubbed specs.
+
+### Fixed
+
+- Query values are URL-encoded (`CGI.escape`); search queries are no longer
+  double-encoded.
+- `search` no longer mutates the caller's options hash.
+- `prev_page` offset math stepped by the current page's size instead of `limit`.
+- `get_details` with an unknown type raises a descriptive `CVError` instead of
+  `NoMethodError`.
+- `CVObject#get_*` on a plain value returns the value instead of `nil`.
+- `CVObject` readers are defined on the singleton class instead of polluting
+  the shared class.
+
+### Removed
+
+- Travis CI configuration.
+- Committed build artifacts (`coverage/`, packaged `.gem`, `.DS_Store`).
+
+## [0.1.5] — 2017-03-25
+
+- Use ComicVine URL with SSL.
+
+## [0.1.4] — 2016-02-12
+
+- Update ComicVine API URL.
+
+## [0.1.1] — 2012-04-27
+
+- Escape query on search; remove spaces from resources.
+
+## [0.1.0] — 2012-04-24
+
+- Fix small bug with types cache; full coverage with RSpec.
+
+## [0.0.8] — 2012-04-18
+
+- Fix bug exposing API key.
+
+## [0.0.7] — 2012-04-18
+
+- Fix bug with search.
+
+## [0.0.6] — 2012-04-18
+
+- Expose the helper methods; add `get_details_by_url`; allow `get_*` for any of
+  the resource items returned in the body.
+
+## [0.0.5] — 2012-04-12
+
+- Behind-the-scenes cleanup. Pure Ruby implementation; `API.key` is set
+  manually instead of read from a config file. Removed generator and railties.
+
+## [0.0.4] — 2012-04-11
+
+- Add `CVObjectList` to carry count vars from result. Simple pagination.
+  Include `Enumerable` in the list classes.
+
+## [0.0.3] — 2012-04-10
+
+- Simple associations; error check on ComicVine response; allow options.
+
+## [0.0.2] — 2012-04-09
+
+- Create `CVObject`s from resource returns.
+
+## [0.0.1] — 2012-04-09
+
+- First check-in.

data/README.md

@@ -1,79 +1,137 @@
-[![Build Status](https://secure.travis-ci.org/Jakanapes/ComicVine.png?branch=master)](http://travis-ci.org/Jakanapes/ComicVine)
-
 # ComicVine
 
-VERY simple first cut at a gem to interface with the ComicVine api.  http://api.comicvine.com/
+A simple Ruby interface to the [ComicVine API](https://comicvine.gamespot.com/api/).
+Search for volumes, issues, characters, and other resources, or fetch them by id.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'comic_vine'
-
-And then execute:
+```ruby
+gem "comic_vine"
+```
 
-    $ bundle install
+And then run `bundle install`, or install it directly:
 
-Or install it yourself as:
+```console
+$ gem install comic_vine
+```
 
-    $ gem install comic_vine
-    
-You will also need to have a ComicVine API key.
+You will also need a [ComicVine API key](https://comicvine.gamespot.com/api/).
 
 ## Usage
 
-Requires that API key be set manually.  This is a breaking change from 0.0.4.
+Set your API key first:
+
+```ruby
+ComicVine::API.key = "your-api-key"
+```
+
+Calls to plural resources return a `CVObjectList`, which carries the result
+array along with the values from the response (`total_count`, `page_count`,
+`offset`, `limit`):
+
+```ruby
+chars = ComicVine::API.characters
+```
+
+`CVObjectList` includes `Enumerable`, so lists can be looped:
+
+```ruby
+chars.each { |c| puts c.name }
+```
 
-    ComicVine::API.key = xxxxxx
+Pagination updates the list in place and returns the list, or returns `nil` at
+either end, so it can be used in a loop:
 
+```ruby
+chars.next_page
+chars.prev_page
+```
 
-Calls to plurals return a CVObjectList, which contains the result array as well as the values from the return (total_count, offset, limit, resource).
+Calls to singular resources take an id and return a `CVObject`:
 
-    chars = ComicVine::API.characters
+```ruby
+ComicVine::API.volume 766
+```
 
-CVObjectLists include enumerable, so they can be looped.
+`search` takes a resource type or types (comma-separated, e.g.
+`"volume,issue"`) and a query string, and returns a `CVSearchList` (also
+paginated):
 
-    chars.each do |c|
-    
-Pagination will return nil if you are at either end of the list, otherwise it will update the object allowing for looping
-    
-    chars.next_page
-    chars.prev_page
+```ruby
+results = ComicVine::API.search "volume", "batman"
+```
 
-Calls to singulars require an id and return a CVObject:
+Call `fetch` to retrieve the full object behind a search result or association:
 
-    ComicVine::API.volume 766
+```ruby
+results.first.fetch
+```
 
-Search takes a resource type or types, separated by a comma(ex. "volume,issue"), and a query string and returns a CVSearchList (also with pagination)
+### Options: `limit`, `offset`, `filter`, `sort`, `field_list`
 
-    results = ComicVine::API.search 'volume', 'batman'
-    
-Call fetch to retrieve the full object
-    
-    results.first.fetch
+List and detail calls accept an options hash, passed through to the API as
+query parameters (values are URL-encoded for you). The most useful ones:
 
-Pass in options as a hash
+```ruby
+# Page size and starting offset
+ComicVine::API.characters(limit: 5, offset: 10)
 
-    ComicVine::API.characters {:limit=>5, :offset=>10}
+# Filter results — field:value pairs, comma-separated
+ComicVine::API.volumes(filter: "name:Walking Dead")
 
-There are associations.  Call the association by the key name, prefaced by get_ and the gem will return either a CVList or a CVObject from the API.
+# Sort by a field — field:asc or field:desc
+ComicVine::API.issues(sort: "cover_date:desc")
 
-    volume = ComicVine::API.volume 766
-    issues = volume.get_issues
-    chars = volume.get_character_credits
+# Only return the fields you need (faster, smaller responses)
+ComicVine::API.characters(field_list: "name,id,image")
+```
 
-Error responses from the API will raise a CVError with the error message
+These options are remembered across `next_page`/`prev_page`, so a filtered or
+sorted list stays filtered and sorted while you page through it. See the
+[ComicVine API documentation](https://comicvine.gamespot.com/api/documentation)
+for the fields each resource supports.
 
+### Associations
 
-This gem is released under the MIT license, if you find it useful in your application, drop me a line and I'll post a link!
+Call an association by its key name, prefaced by `get_`, and the gem will
+return either an array of fetched objects or a `CVObject` from the API:
 
+```ruby
+volume = ComicVine::API.volume 766
+issues = volume.get_issues
+chars  = volume.get_character_credits
+```
 
-## ToDos
-More Error checking
+### Errors
 
-Documentation
+All errors raised by the gem inherit from `ComicVine::CVError`:
 
-Tests
+| Class | Raised when |
+| --- | --- |
+| `CVAPIError` | the API answers with an error status code (bad key, not found, …) |
+| `CVHTTPError` | the server answers with a non-2xx HTTP status (`#status` has the code) |
+| `CVRateLimitError` | HTTP 420/429 persists after retries (~200 requests/resource/hour) |
+| `CVConnectionError` | the connection fails or times out after all retries |
+| `CVParseError` | the response body is not valid JSON |
+
+### Configuration
+
+Timeouts, retries, and the User-Agent header can be tuned on `ComicVine::API`:
+
+```ruby
+ComicVine::API.open_timeout     = 10    # seconds (default 10)
+ComicVine::API.read_timeout     = 30    # seconds (default 30)
+ComicVine::API.max_retries      = 3     # retries on 420/429/5xx and connection errors
+ComicVine::API.retry_base_delay = 1.0   # exponential backoff base, honors Retry-After
+ComicVine::API.user_agent       = "my-app/1.0"
+```
+
+## Development
+
+Run the test suite with `bundle exec rake spec`, the linter with
+`bundle exec rubocop`, and generate API docs with `bundle exec yard`.
 
 ## Contributing
 
@@ -82,3 +140,8 @@ Tests
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## License
+
+This gem is released under the [MIT license](LICENSE). If you find it useful
+in your application, drop me a line and I'll post a link!

data/lib/comic_vine/cv_list.rb

@@ -1,83 +1,139 @@
+# frozen_string_literal: true
+
 module ComicVine
+  # Base class for paginated result lists. Carries the count values from the
+  # API response (`total_count`, `page_count`, `offset`, `limit`) and includes
+  # `Enumerable` over the contained {CVObject}s.
   class CVList
     include Enumerable
-    
+
+    # @return [Integer] total results across all pages
     attr_reader :total_count
+    # @return [Integer] results on the current page
     attr_reader :page_count
+    # @return [Integer] offset of the current page
     attr_reader :offset
+    # @return [Integer] page size
     attr_reader :limit
+    # @return [Array<CVObject>] the objects on the current page
     attr_reader :cvos
-    
-    def initialize(resp)      
+
+    # @param resp [Hash] a list response from the API
+    def initialize(resp)
       @total_count = resp['number_of_total_results']
       @page_count = resp['number_of_page_results']
       @offset = resp['offset']
       @limit = resp['limit']
     end
-    
-    def each
-      @cvos.each { |c| yield c }
+
+    # Yields each {CVObject} on the current page.
+    def each(&)
+      @cvos.each(&)
     end
-    
+
+    # @return [CVObject, nil] the last object on the current page
     def last
       @cvos.last
     end
-    
+
+    # @return [Integer] the current page number (1-based)
     def page
       (@offset / @limit) + 1
     end
-    
+
     protected
-      def update_ivals(new_cvol)
-        @total_count = new_cvol.total_count
-        @offset = new_cvol.offset
-        @limit = new_cvol.limit
 
-        @cvos = new_cvol.cvos
-      end
+    def update_ivals(new_cvol)
+      @total_count = new_cvol.total_count
+      @page_count = new_cvol.page_count
+      @offset = new_cvol.offset
+      @limit = new_cvol.limit
+
+      @cvos = new_cvol.cvos
+    end
   end
-  
+
+  # A paginated list of resources (e.g. from `ComicVine::API.characters`).
+  # {#next_page} and {#prev_page} update the list in place, preserving the
+  # original options (`:filter`, `:sort`, `:field_list`, ...).
   class CVObjectList < CVList
+    # @return [String] the plural resource name this list was fetched from
     attr_reader :resource
-    
-    def initialize(resp, resc)      
+
+    # @param resp [Hash] a list response from the API
+    # @param resc [String] the plural resource name
+    # @param opts [Hash] the options the list was fetched with
+    def initialize(resp, resc, opts = {})
       super(resp)
-      
+
       @resource = resc
-      @cvos = resp['results'].map{ |r| ComicVine::CVObject.new(r)}
+      @opts = opts || {}
+      @cvos = resp['results'].map { |r| ComicVine::CVObject.new(r) }
     end
-    
+
+    # Advances to the next page, updating the list in place.
+    #
+    # @return [CVObjectList, nil] `self`, or `nil` if already on the last page
+    # @raise [CVError]
     def next_page
       return nil if (@offset + @page_count) >= @total_count
-      update_ivals(ComicVine::API.send(@resource, {:limit => @limit, :offset => (@offset + @page_count)}))
+
+      update_ivals(ComicVine::API.send(@resource, @opts.merge(:limit => @limit, :offset => (@offset + @limit))))
+      self
     end
-    
+
+    # Steps back to the previous page, updating the list in place.
+    #
+    # @return [CVObjectList, nil] `self`, or `nil` if already on the first page
+    # @raise [CVError]
     def prev_page
       return nil if @offset == 0
-      update_ivals(ComicVine::API.send(@resource, {:limit => @limit, :offset => (@offset - @page_count)}))
+
+      update_ivals(ComicVine::API.send(@resource, @opts.merge(:limit => @limit, :offset => [@offset - @limit, 0].max)))
+      self
     end
   end
-  
+
+  # A paginated list of search results (from {ComicVine::API.search}).
   class CVSearchList < CVList
+    # @return [String] the resource type(s) searched
     attr_reader :resource
+    # @return [String] the search query
     attr_reader :query
-    
-    def initialize(resp, resc, query)      
+
+    # @param resp [Hash] a search response from the API
+    # @param resc [String] the resource type(s) searched
+    # @param query [String] the search query
+    # @param opts [Hash] the options the search was made with
+    def initialize(resp, resc, query, opts = {})
       super(resp)
-      
+
       @resource = resc
       @query = query
-      @cvos = resp['results'].map{ |r| ComicVine::CVObject.new(r)}
+      @opts = opts || {}
+      @cvos = resp['results'].map { |r| ComicVine::CVObject.new(r) }
     end
-    
+
+    # Advances to the next page of results, updating the list in place.
+    #
+    # @return [CVSearchList, nil] `self`, or `nil` if already on the last page
+    # @raise [CVError]
     def next_page
       return nil if (@offset + @page_count) >= @total_count
-      update_ivals(ComicVine::API.search(@resource, @query, {:limit => @limit, :page => (((@offset + @page_count) / @limit) + 1)}))
+
+      update_ivals(ComicVine::API.search(@resource, @query, @opts.merge(:limit => @limit, :page => page + 1)))
+      self
     end
-    
+
+    # Steps back to the previous page of results, updating the list in place.
+    #
+    # @return [CVSearchList, nil] `self`, or `nil` if already on the first page
+    # @raise [CVError]
     def prev_page
       return nil if @offset == 0
-      update_ivals(ComicVine::API.search(@resource, @query, {:limit => @limit, :page => (@offset / @limit)}))
+
+      update_ivals(ComicVine::API.search(@resource, @query, @opts.merge(:limit => @limit, :page => page - 1)))
+      self
     end
   end
-end
+end

data/lib/comic_vine/cv_object.rb

@@ -1,39 +1,52 @@
+# frozen_string_literal: true
+
 module ComicVine
+  # Wraps a single resource returned by the API. Every key in the response
+  # becomes a reader method; nested resources that carry an `api_detail_url`
+  # become {CVObject}s themselves and can be expanded with `get_<key>`.
   class CVObject
+    # @param args [Hash] a resource hash from the API response
     def initialize(args)
-      args.each do |k,v|
-        self.class.class_eval { attr_reader k }
-        v.collect! { |i| CVObject.new i } if v.kind_of?(Array) && !v.empty? && v.first.key?("api_detail_url")
-        v = CVObject.new v if v.kind_of?(Hash) && v.key?("api_detail_url")
+      args.each do |k, v|
+        singleton_class.class_eval { attr_reader k } unless respond_to?(k)
+        v.collect! { |i| CVObject.new i } if v.is_a?(Array) && v.first.is_a?(Hash) && v.first.key?("api_detail_url")
+        v = CVObject.new v if v.is_a?(Hash) && v.key?("api_detail_url")
         instance_variable_set "@#{k}", v
       end
     end
-    
+
+    # Retrieves the full object from this object's `api_detail_url`.
+    #
+    # @return [CVObject]
+    # @raise [CVError]
     def fetch
       ComicVine::API.get_details_by_url(@api_detail_url)
     end
-      
-    def method_missing(method_sym, *arguments, &block)
+
+    # Resolves `get_<key>` calls: fetches the full object(s) behind an
+    # association, or returns the plain value if it isn't an association.
+    def method_missing(method_sym, *arguments, &)
       if method_sym.to_s =~ /^get_(.*)$/
-        key = method_sym.to_s.sub "get_", ""
+        key = $1
         if instance_variable_defined?("@#{key}")
           item = instance_variable_get("@#{key}")
-          if item.kind_of?(Array) && item.first.kind_of?(CVObject)
-            res = []
-            item.each do |i|
-              res << i.fetch
-            end
-            return res
-          end
-          if item.kind_of?(CVObject)
-            return item.fetch
+          if item.is_a?(Array) && item.first.is_a?(CVObject)
+            item.map(&:fetch)
+          elsif item.is_a?(CVObject)
+            item.fetch
+          else
+            item
           end
         else
           super
         end
-      elsif
+      else
         super
       end
     end
+
+    def respond_to_missing?(method_sym, include_private = false)
+      method_sym.to_s =~ /^get_(.*)$/ ? instance_variable_defined?("@#{$1}") : super
+    end
   end
-end
+end

data/lib/comic_vine/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module ComicVine
-  VERSION = "0.1.5"
+  # The version of the comic_vine gem.
+  VERSION = "1.0.0"
 end