tvdb2 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: baf228f33001b998ffe4e51e2f5eb125e82207a9
+  data.tar.gz: ec4b8845798bc1479584c053eb8cf6ab5974fb37
+SHA512:
+  metadata.gz: 011fa05b1d23010ee94b08900a036f5ee650d36b2d0505ee05a0f38c25947d939f5be036111d740dc99bde64c164d6fb1875e133aa1e36ade391f4523a21cd47
+  data.tar.gz: bd63f54b18a16de2c6deaeabe57ab1971b13566c7b536e2b88dd58ced9ad264ab9705e4638ec5d18f9f0434d52c4cd52389a226d247d5ec7aa7f3c25d6809b5b

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+main.rb

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tvdb2.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 pioz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# TVDB2 API for Ruby
+
+Ruby wrapper for TVDB json api version 2.
+
+The TVDB api version 2 documentation [can be found here](https://api.thetvdb.com/swagger).
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tvdb2'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tvdb2
+
+
+## Usage
+
+First of all you need to get your API key:
+
+* Register an account on http://thetvdb.com/?tab=register
+* When you are logged register an api key on http://thetvdb.com/?tab=apiregister
+* View your api keys on http://thetvdb.com/?tab=userinfo
+
+```
+require 'tvdb2'
+
+# Create a client object with your api key
+client = TVDB.new(apikey: 'YOUR_API_KEY', language: 'en')
+
+# Search series by name
+results = client.search(name: 'Game of Thrones')
+puts results.map(&:name).inspect
+# Get best series result by name
+got = best_result = client.best_search('Game of Thrones')
+puts got.name
+
+# Get list of actors
+actors = got.actors
+puts actors.first.name
+puts actors.first.role
+puts actors.first.image_url
+
+# Print some info about all episodes
+got.episodes.each do |episode|
+  puts episode.x
+  puts episode.absoluteNumber
+  puts episode.seasonNumber
+  puts episode.number
+  puts episode.overview
+end
+# Get only episodes from 101 and 200
+episodes = got.episodes(page: 2)
+# Get all episodes of season 1
+episodes = got.episodes(airedSeason: 1)
+# Get episode by index
+puts got[3].name
+# Get episode by x syntax (SEASON_NUMBERxEPISODE_NUMBER)
+ep = got['3x9']
+puts ep.name
+puts ep.x # print '3x9'
+
+# Get banner
+url = got.banner_url
+# Get random banner
+url = got.banner_url(random: true)
+# Get poster
+url = got.poster_url
+# Get random poster
+url = got.poster_url(random: true)
+# Get all posters
+posters = got.posters
+puts posters.first.url
+# or
+posters = got.images(keyType: 'poster')
+# Get all season images
+images = got.season_images
+puts images.first.url
+# Get all season images of season 2
+images = got.season_images(season: 2)
+puts images.first.url
+
+# Switch language
+client.language = 'it'
+ep = got['3x9'] # retrieve the episodes with the new language
+puts ep.name
+client.language = 'en'
+# or you can swith language only in a block
+client.with_language(:it) do
+  ep = got['3x9']
+  puts ep.name
+end
+```
+
+The complete __documentation__ can be found [here](https://pioz.github.io/tvdb2).
+
+
+## Missing REST endpoints
+
+This wrapper do not coverage all 100% api REST endpoints.
+Missing methods are:
+
+* __Series__
+    * filter: `GET /series/{id}/filter`
+* __Updates__
+    * updadad: `GET /updated/query`
+* __Users__
+    * user: `GET /user`
+    * favorites: `GET /user/favorites`
+    * delete favorites: `DELETE /user/favorites/{id}`
+    * add favorites: `PUT /user/favorites/{id}`
+    * ratings: `GET /user/ratings`
+    * ratings with query: `GET /user/ratings/query`
+    * delete rating: `DELETE /user/ratings/{itemType}/{itemId}`
+    * add rating: `PUT /user/ratings/{itemType}/{itemId}/{itemRating}`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pioz/tvdb2.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rd|
+  rd.title = 'TVDB2'
+  rd.main = 'README.md'
+  rd.rdoc_dir = 'rdoc'
+  rd.rdoc_files.include('README.md', 'lib/**/*.rb')
+  rd.generator = 'darkfish'
+  rd.markup = 'markdown'
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+ t.files = ['lib/**/*.rb']
+ t.options << '-rREADME.md'
+ t.options << '--title=TVDB2'
+ t.options << '-mmarkdown'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "tvdb2"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/tvdb2/api.rb

@@ -0,0 +1,153 @@
+require 'tvdb2/series'
+require 'tvdb2/episode'
+
+module Tvdb2
+  # Methods in this module wrap the TVDB api endpoints.
+  #
+  # @todo Missing endpoints are:
+  #
+  #   * __Series__
+  #       * filter: `GET /series/{id}/filter`
+  #   * __Updates__
+  #       * updadad: `GET /updated/query`
+  #   * __Users__
+  #       * user: `GET /user`
+  #       * favorites: `GET /user/favorites`
+  #       * delete favorites: `DELETE /user/favorites/{id}`
+  #       * add favorites: `PUT /user/favorites/{id}`
+  #       * ratings: `GET /user/ratings`
+  #       * ratings with query: `GET /user/ratings/query`
+  #       * delete rating: `DELETE /user/ratings/{itemType}/{itemId}`
+  #       * add rating: `PUT /user/ratings/{itemType}/{itemId}/{itemRating}`
+  module API
+
+    # Perform a request to the endpoint `GET /languages`.
+    #
+    # @return [Array<TvdbStruct>] all available languages. These language
+    #   abbreviations can be used in the Accept-Language header for routes that
+    #   return translation records.
+    # @raise [RequestError]
+    def languages
+      build_array_result('/languages')
+    end
+
+    # Perform a request to the endpoint `GET /languages/{id}`.
+    #
+    # @param [Integer] id language id.
+    # @return [TvdbStruct] Information about a particular language.
+    # @raise [RequestError]
+    def language(id)
+      build_object_result("/languages/#{id}")
+    end
+
+    # Perform a request to the endpoint `GET /search/series`.
+    #
+    # @param [Hash] params the params of the request.
+    # @option params [String] :name name of the series to search for;
+    # @option params [String] :imdbId IMDB id of the series;
+    # @option params [String] :zap2itId Zap2it id of the series to search for.
+    # @return [Array<Series>] list of series found.
+    # @raise [RequestError]
+    def search(params)
+      build_array_result('/search/series', params, Series)
+    end
+
+    # @param [String] name name of the series to search for.
+    # @return [Series] the series that best match the `name` passed as parameter.
+    # @raise [RequestError]
+    def best_search(name)
+      results = search(name: name)
+      chosen = results.select{|x| x.seriesName.downcase == name.downcase}.first
+      chosen ||= results.select{|x| x.aliases.map(&:downcase).include?(name.downcase)}.first
+      return chosen || results.first
+    end
+
+    # Perform a request to the endpoint `GET /series/{id}`.
+    #
+    # @param [Integer] id the id of the series.
+    # @return [Series] a series record that contains all information
+    #   known about a particular series id.
+    # @raise [RequestError]
+    def series(id)
+      build_object_result("/series/#{id}", {}, Series)
+    end
+
+    # Perform a request to the endpoint `GET /series/{id}/episodes/summary`.
+    #
+    # @param [Integer] id the id of the series.
+    # @return [TvdbStruct] a summary of the episodes and seasons
+    #   available for the series.
+    # @raise [RequestError]
+    def series_summary(id)
+      build_object_result("/series/#{id}/episodes/summary")
+    end
+
+    # Perform a request to the endpoint `GET /series/{id}/episodes`.
+    #
+    # @param [Integer] id the id of the series.
+    # @param [Hash] params the params of the request to retrieve the episodes of
+    #   the series.
+    # @option params [String, Integer] :absoluteNumber absolute number of the
+    #   episode;
+    # @option params [String, Integer] :airedSeason aired season number;
+    # @option params [String, Integer] :airedEpisode aired episode number;
+    # @option params [String, Integer] :dvdSeason DVD season number;
+    # @option params [String, Integer] :dvdEpisode DVD episode number;
+    # @option params [String, Integer] :imdbId IMDB id of the series;
+    # @option params [Integer] :page page of results to fetch (100
+    #   episodes per page).
+    # @return [Array<Episode>] episodes found.
+    # @raise [RequestError]
+    def episodes(id, params = {})
+      if params.nil? || params.empty?
+        build_array_result("/series/#{id}/episodes", {}, Episode)
+      else
+        build_array_result("/series/#{id}/episodes/query", params, Episode)
+      end
+    end
+
+    # Perform a request to the endpoint `GET /series/{id}/actors`.
+    #
+    # @param [Integer] id the id of the series.
+    # @return [Array<TvdbStruct>] actors for the given series id.
+    # @raise [RequestError]
+    def actors(id)
+      build_array_result("/series/#{id}/actors")
+    end
+
+    # Perform a request to the endpoint `GET /episodes/{id}`.
+    #
+    # @param [Integer] id the id of the episode.
+    # @return [Episode] the full information for a given episode id.
+    # @raise [RequestError]
+    def episode(id)
+      build_object_result("/episodes/#{id}", {}, Episode)
+    end
+
+    # Perform a request to the endpoint `GET /series/{id}/images`.
+    #
+    # @param [Integer] id the id of the series.
+    # @return [Array<TvdbStruct>] a summary of the images for a
+    #   particular series.
+    # @raise [RequestError]
+    def images_summary(id)
+      build_object_result("/series/#{id}/images")
+    end
+
+    # Perform a request to the endpoint `GET /series/{id}/images/query`.
+    #
+    # @param [Integer] id the id of the series.
+    # @param [Hash] params the params of the request to retrieve the images.
+    # @option params [String] :keyType type of image you're querying for
+    #   (fanart, poster, season, seasonwide, series);
+    # @option params [String] :resolution resolution to filter by (1280x1024 for
+    #   example);
+    # @option params [String] :subKey subkey for the above query keys.
+    # @return [Array<TvdbStruct>] the images for a particular series.
+    # @raise [RequestError]
+    def images(id, params)
+      build_array_result("/series/#{id}/images/query", params)
+    end
+
+  end
+end

data/lib/tvdb2/client.rb

@@ -0,0 +1,151 @@
+require 'httparty'
+require 'uri'
+require 'memoist'
+require 'tvdb2/request_error'
+require 'tvdb2/tvdb_struct'
+require 'tvdb2/api'
+
+# Module that works like a namespace of the library.
+# @author Enrico Pilotto
+module Tvdb2
+
+  # This class works as a client to retrieve data from TVDB json api version 2.
+  # Make http requests to
+  # [https://api.thetvdb.com](https://api.thetvdb.com/swagger).
+  #
+  # This class cache all http requests so only the first time a request is made
+  # ([Memoist gem](https://github.com/matthewrudy/memoist) is used).
+  # @see https://api.thetvdb.com/swagger TVDB api version 2 documentation
+  class Client
+
+    # The language in which you want get data.
+    # @example
+    #   got = client.best_search('Game of Thrones')
+    #   puts got.name         # print 'Game of Thrones'
+    #   client.language = :it # change language to italian
+    #   got.series!           # make a request to get new data
+    #   puts got.name         # print 'Il Trono di Spade'
+    attr_accessor :language
+
+    extend Memoist
+    include HTTParty
+    base_uri 'https://api.thetvdb.com'
+
+    include Tvdb2::API
+
+    # Create an object client. Take 2 keyword arguments:
+    #
+    # @param [String] apikey your tvdb apikey (you can get one at
+    #   https://thetvdb.com/?tab=apiregister). Required.
+    # @param [Symbol, String] language the language in which you want get data.
+    #   You can change later. Optional. Default is `nil` that is `EN`.
+    def initialize(apikey:, language: nil)
+      @language = language
+      response = post('/login', apikey: apikey)
+      raise RequestError.new(response) if response.code != 200
+      @token = response.parsed_response['token']
+    end
+
+    # Refresh your api token.
+    #
+    # @return [String] the new token
+    def refresh_token!
+      response = get('/refresh_token')
+      raise RequestError.new(response) if response.code != 200
+      @token = response['token']
+      return @token
+    end
+
+    # Inside the block change the language in which you want get data.
+    #
+    # @example
+    #   got = client.best_search('Game of Thrones')
+    #   client.with_language(:it) do |c|
+    #     ep = got['1x1'] # Get episode data in italian
+    #     puts ep.name    # print the title of episode 1x1 in italian
+    #   end
+    #   ep = got['1x1']   # Get episode data in default language
+    #   puts ep.name      # print the title of episode 1x1 in english
+    #
+    # @param [Symbol, String] locale the language in which you want get data.
+    # @yield block called with the selected language.
+    def with_language(locale, &block)
+      tmp_language = @language
+      @language = locale.to_s
+      block.call(self)
+      @language = tmp_language
+    end
+
+
+    # Helper method to get the full url of an image from the relative path
+    # retrieved from api.
+    #
+    # @example
+    #   got = client.best_search('Game of Thrones')
+    #   puts got.posters.first.fileName # posters/121361-1.jpg
+    #   puts TVDB.image_url(got.posters.first.fileName) # http://thetvdb.com/banners/posters/121361-1.jpg
+    #   # or
+    #   puts got.posters.first.fileName_url # http://thetvdb.com/banners/posters/121361-1.jpg
+    #
+    # @param [String] path the relative path of an image.
+    # @return [String] the complete url of the image.
+    def self.image_url(path)
+      URI::join("https://thetvdb.com/banners/", path).to_s
+    end
+
+    protected
+
+    # :nodoc:
+    # language param is required to invalidate memoist cache on different language
+    def get(path, params = {}, language = @language)
+      self.class.get(URI.escape(path), headers: build_headers, query: params)
+    end
+    memoize :get
+
+    # :nodoc:
+    def post(path, params = {}, language = @language)
+      self.class.post(URI.escape(path), headers: build_headers, body: params.to_json)
+    end
+    memoize :post
+
+    # :nodoc:
+    def build_result(path, params = {}, return_type = nil, &block)
+      response = get(path, params, @language)
+      if response.code === 200
+        return block.call(response['data'])
+      elsif response.code === 404
+        return return_type
+      else
+        raise RequestError.new(response)
+      end
+    end
+
+    # :nodoc:
+    def build_object_result(path, params = {}, klass = TvdbStruct)
+      build_result(path, params, nil) do |data|
+        klass.new(self, data)
+      end
+    end
+
+    # :nodoc:
+    def build_array_result(path, params = {}, klass = TvdbStruct)
+      build_result(path, params, []) do |data|
+        data.map{|x| klass.new(self, x)}
+      end
+    end
+
+    private
+
+    # :nodoc:
+    def build_headers
+      headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
+      headers.merge!('Accept-Language': @language.to_s) if @language
+      headers.merge!('Authorization': "Bearer #{@token}") if @token
+      return headers
+    end
+
+  end
+end
+
+# Alias of {Client}
+TVDB = Tvdb2::Client

data/lib/tvdb2/episode.rb

@@ -0,0 +1,62 @@
+module Tvdb2
+
+  # This class rappresent a series episode retrieved from TVDB api.
+  class Episode
+
+    # All episode fields returned from TVDB api.
+    FIELDS = [
+      :absoluteNumber, :airedEpisodeNumber, :airedSeason,
+      :airsAfterSeason, :airsBeforeEpisode, :airsBeforeSeason, :direcotor,
+      :directors, :dvdChapter, :dvdDiscid, :dvdEpisodeNumber, :dvdSeason,
+      :episodeName, :filename, :firstAired, :guestStars, :id, :imdbId,
+      :lastUpdated, :lastUpdatedBy, :overview, :productionCode, :seriesId,
+      :showUrl, :siteRating, :siteRatingCount, :thumbAdded, :thumbAuthor,
+      :thumbHeight, :thumbWidth, :writers, :errors
+    ]
+
+    attr_reader *FIELDS
+
+    alias_method :name, :episodeName
+    alias_method :number, :airedEpisodeNumber
+    alias_method :seasonNumber, :airedSeason
+
+    # @param [Client] tvdb a TVDB api client.
+    # @param [Hash] data the data retrieved from api.
+    #
+    # @note The Episode object may not have all fields filled because it can be
+    #   initialized from not completed data like when is build from a call like
+    #   `series.episodes` (`GET /series/{id}/episodes`): in this case the api
+    #   call return a subset of all avaiable data for the episodes. To get the
+    #   complete data of a specific episode use `#episode!` method.
+    # @note You should never need to create this object manually.
+    def initialize(tvdb, data = {})
+      @tvdb = tvdb
+      FIELDS.each do |field|
+        instance_variable_set("@#{field}", data[field.to_s])
+      end
+    end
+
+    # Get all data for this episode. Calling api endpoint `GET /episodes/{id}`.
+    #
+    # @return [Episode] the episode object with all fields filled from
+    #   the api response.
+    # @raise [RequestError]
+    def episode!
+      if self.lastUpdated.nil?
+        e = @tvdb.episode(self.id)
+        FIELDS.each do |field|
+          instance_variable_set("@#{field}", e.send(field))
+        end
+      end
+      return self
+    end
+    alias_method :get_data!, :episode!
+
+    # @return [String] the episode number with the "_x_" syntax:
+    #   `"#{season_number}x#{episode_number}` (3x9)".
+    def x
+      "#{self.airedSeason}x#{self.airedEpisodeNumber}"
+    end
+
+  end
+end

data/lib/tvdb2/request_error.rb

@@ -0,0 +1,19 @@
+module Tvdb2
+
+  # Exception raised when an http request to an endpoint return a status code
+  # different from 200 or 404.
+  class RequestError < StandardError
+
+    attr_reader :response, :code, :error
+
+    # @param [HTTParty::Response] response the HTTParty response object.
+    def initialize(response)
+      super(response['Error'] || response.message)
+      @response = response
+      @code = response.code
+      @error = response['Error']
+    end
+
+  end
+
+end

data/lib/tvdb2/series.rb

@@ -0,0 +1,188 @@
+module Tvdb2
+
+  # This class rappresent a series retrieved from TVDB api.
+  class Series
+
+    # All series fields returned from TVDB api.
+    FIELDS = [
+      :added, :airsDayOfWeek, :airsTime, :aliases, :banner, :firstAired, :genre,
+      :id, :imdbId, :lastUpdated, :network, :networkId, :overview, :rating,
+      :runtime, :seriesId, :seriesName, :siteRating, :siteRatingCount, :status,
+      :zap2itId, :errors
+    ]
+
+    attr_reader *FIELDS
+
+    alias_method :name, :seriesName
+
+    # @param [Client] tvdb a TVDB api client.
+    # @param [Hash] data the data retrieved from api.
+    #
+    # @note The {Series} object may not have all fields filled because it
+    #   can be initialized from not completed data like when is build from a
+    #   call like {Client#search} (`GET /search/series`): in this case the api
+    #   call return a subset of all avaiable data for the series. To get the
+    #   complete data of a specific episode use {Series#series!} method.
+    # @note You should never need to create this object manually.
+    def initialize(tvdb, data = {})
+      @tvdb = tvdb
+      FIELDS.each do |field|
+        instance_variable_set("@#{field}", data[field.to_s])
+      end
+    end
+
+    # Get all data for this series. Calling api endpoint `GET /series/{id}`.
+    #
+    # @return [Series] the {Series} object with all fields filled
+    #   from the api response.
+    # @raise [RequestError]
+    def series!
+      if self.added.nil?
+        s = @tvdb.series(self.id)
+        FIELDS.each do |field|
+          instance_variable_set("@#{field}", s.send(field))
+        end
+      end
+      return self
+    end
+    alias_method :get_data!, :series!
+
+    # @return [TvdbStruct] return the summary of the series.
+    # @raise [RequestError]
+    def series_summary
+      @tvdb.series_summary(self.id)
+    end
+
+    # Retrieve the episodes of the series.
+    #
+    # @param params (see API#episodes)
+    # @option params (see API#episodes)
+    # @return [Array<Episode>]
+    # @raise [RequestError]
+    def episodes(params = {})
+      return @tvdb.episodes(self.id, params) if params && params.key?(:page)
+      episodes = []
+      page = 1
+      loop do
+        params.merge!(page: page)
+        result = @tvdb.episodes(self.id, params)
+        episodes += result
+        page += 1
+        break if result.size < 100
+      end
+      return episodes.sort_by{|x| [x.airedSeason, x.airedEpisodeNumber]}
+    end
+
+    # @return [Array<TvdbStruct>] the list of actors in the series.
+    # @raise [RequestError]
+    def actors
+      @tvdb.actors(self.id)
+    end
+
+    # Get the episode of the series identified by the index.
+    # @param [String, Integer] index the index of the episode to retrieve. Can be and
+    #   Integer (`absoluteNumber`) or a String
+    #   `"#{season_number}x#{episode_number}"` (3x9).
+    # @return [Episode] the episode.
+    # @raise [RequestError]
+    #
+    # @example
+    #   got = client.best_search('Game of Thrones')
+    #   puts got[29].name
+    #   puts got['3x9'].name
+    def [](index)
+      episodes = self.episodes
+      if index.is_a?(Integer)
+        return episodes.select{|e| e.absoluteNumber == index}.first
+      else
+        series, ep = index.split('x')
+        return episodes.select{|e| e.airedSeason == series.to_i && e.airedEpisodeNumber == ep.to_i}.first
+      end
+    end
+
+    # @!group Instance Method Summary to retrieve images
+
+    # @return [Array<TvdbStruct>] the image summary of the series.
+    # @raise [RequestError]
+    def images_summary
+      @tvdb.images_summary(self.id)
+    end
+
+    # Retrieve the images of the series.
+    #
+    # @param params (see API#images)
+    # @option params (see API#images)
+    # @return [Array<TvdbStruct>] the list of images.
+    # @raise [RequestError]
+    #
+    # @example
+    #   got = client.best_search('Game of Thrones')
+    #   puts got.images(keyType: 'poster').first.fileName_url # print the url of a poster of the series
+    def images(params)
+      @tvdb.images(self.id, params)
+    end
+
+    # @return [Array<TvdbStruct>] the list of fanart images.
+    # @raise [RequestError]
+    def fanarts
+      self.images(keyType: 'fanart')
+    end
+
+    # @return [Array<TvdbStruct>] the list of poster images.
+    # @raise [RequestError]
+    def posters
+      self.images(keyType: 'poster')
+    end
+
+    # @param [Integer] season If present return the images only for that
+    #   `season` number.
+    # @return [Array<TvdbStruct>] the list of season images.
+    # @raise [RequestError]
+    def season_images(season: nil)
+      r = self.images(keyType: 'season')
+      r.select!{|x| x.subKey == season.to_s} if season
+      r.sort{|x,y| x.subKey <=> y.subKey}
+    end
+
+    # @param [Integer] season if present return the images only for that
+    #   `season` number.
+    # @return [Array<TvdbStruct>] the list of season wide images.
+    # @raise [RequestError]
+    def seasonwide_images(season: nil)
+      r = self.images(keyType: 'seasonwide')
+      r.select!{|x| x.subKey == season.to_s} if season
+      r.sort{|x,y| x.subKey <=> y.subKey}
+    end
+
+    # @return [Array<TvdbStruct>] the list of banner images of the
+    #   series.
+    # @raise [RequestError]
+    def banners
+      self.images(keyType: 'series')
+    end
+
+    # @param [Boolean] random If `true` return a random banner image url.
+    # @return [String] the banner image url of the series.
+    # @raise [RequestError]
+    def banner_url(random: false)
+      if random
+        b = self.banners.shuffle.first
+        b ? b.url : nil
+      else
+        @banner ? Client.image_url(@banner) : nil
+      end
+    end
+
+    # @param [Boolean] random If `true` return a random poster image url.
+    # @return [String] the poster image url of the series.
+    # @raise [RequestError]
+    def poster_url(random: false)
+      ps = self.posters
+      ps.shuffle! if random
+      ps.first ? ps.first.url : nil
+    end
+
+    # @!endgroup
+
+  end
+end

data/lib/tvdb2/tvdb_struct.rb

@@ -0,0 +1,41 @@
+require 'ostruct'
+
+module Tvdb2
+  # OpenStruct that define `_url` methods to get url from images relative paths
+  # returned from api.
+  #
+  # @example
+  #   got = client.best_search('Game of Thrones')
+  #   puts got.posters.first.fileName     # print relative path posters/121361-1.jpg
+  #   puts got.posters.first.fileName_url # print url https://thetvdb.com/banners/posters/121361-1.jpg
+  class TvdbStruct < OpenStruct
+
+    # @param [Client] tvdb a TVDB api client. Only to compatibily with {Client}
+    #   and {Episode} constructor.
+    # @param [Hash] hash the optional hash, if given, will generate attributes
+    #   and values (can be a Hash, an OpenStruct or a Struct).
+    #
+    # @note You should never need to create this object manually.
+    def initialize(tvdb = nil, hash = {})
+      super(hash)
+    end
+
+    # @!parse
+    #  # @return [String] the url string of relative image path stored in
+    #  #  `image` field. `nil` if `image` field is `nil`.
+    #  def image_url; end
+    #  # @return [String] the url string of relative image path stored in
+    #  #  `fileName` field. `nil` if `fileName` field is `nil`.
+    #  def fileName_url; end
+    #  # @return [String] the url string of relative image path stored in
+    #  #  `thumbnail` field. `nil` if `thumbnail` field is `nil`.
+    #  def thumbnail_url; end
+    %w(image fileName thumbnail).each do |field|
+      define_method "#{field}_url" do
+        self.send(field) ? Client.image_url(self.send(field)) : nil
+      end
+    end
+    alias_method :url, :fileName_url
+
+  end
+end

data/lib/tvdb2/version.rb

@@ -0,0 +1,4 @@
+module Tvdb2
+  # The library version.
+  VERSION = '0.1.0'
+end

data/lib/tvdb2.rb

@@ -0,0 +1,2 @@
+require 'tvdb2/version'
+require 'tvdb2/client'

data/test.rb

@@ -0,0 +1,9 @@
+module Ciccio
+
+  def pluto
+    puts 'ciccio'
+  end
+
+end
+
+Ciccio.pluto

data/tvdb2.gemspec

@@ -0,0 +1,39 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'tvdb2/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "tvdb2"
+  spec.version       = Tvdb2::VERSION
+  spec.authors       = ["pioz"]
+  spec.email         = ["epilotto@gmx.com"]
+
+  spec.summary       = %q{Ruby wrapper for TVDB api version 2}
+  spec.description   = %q{Ruby wrapper for TVDB api version 2 (https://api.thetvdb.com/swagger).}
+  spec.homepage      = "https://github.com/pioz/tvdb2"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+
+  spec.add_runtime_dependency "httparty", "~> 0.15"
+  spec.add_runtime_dependency "memoist", "~> 0.16"
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: tvdb2
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- pioz
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-08-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: memoist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+description: Ruby wrapper for TVDB api version 2 (https://api.thetvdb.com/swagger).
+email:
+- epilotto@gmx.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/tvdb2.rb
+- lib/tvdb2/api.rb
+- lib/tvdb2/client.rb
+- lib/tvdb2/episode.rb
+- lib/tvdb2/request_error.rb
+- lib/tvdb2/series.rb
+- lib/tvdb2/tvdb_struct.rb
+- lib/tvdb2/version.rb
+- test.rb
+- tvdb2.gemspec
+homepage: https://github.com/pioz/tvdb2
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for TVDB api version 2
+test_files: []