Class: Tvdb2::Series

Inherits:
Object
  • Object
show all
Defined in:
lib/tvdb2/series.rb

Overview

This class rappresent a series retrieved from TVDB api.

Constant Summary

INDEX_FIELDS =

Fields returned from api endpoint GET /search/series (search)

[
  :aliases, :banner, :firstAired, :id, :network, :overview, :seriesName,
  :status
]
SHOW_FIELDS =

Other fields with INDEX_FIELDS returned from api endpoint GET /series/{id}

[
  :added, :airsDayOfWeek, :airsTime, :genre, :imdbId, :lastUpdated,
  :networkId, :rating, :runtime, :seriesId, :siteRating, :siteRatingCount,
  :zap2itId
]
FIELDS =

All possible data fields returned from api for a series.

INDEX_FIELDS + SHOW_FIELDS

Instance Attribute Summary collapse

Instance Method Summary to retrieve images collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, data = {}) ⇒ Series

Note:

The Tvdb2::Series object may not have all fields filled because it can be initialized from not completed data like when is build from the call API#search (GET /search/series): in this case the api call return a subset of all avaiable data for the series (INDEX_FIELDS). But no warries! When you call a method to get one SHOW_FIELDS the library automatically call the endpoint GET /series/{id} to retrieve the missing fields.

Note:

You should never need to create this object manually.

Returns a new instance of Series

Parameters:

  • client (Client) —

    a TVDB api client.

  • data (Hash) (defaults to: {}) —

    the data retrieved from api.



64
65
66
67
68
69
70
 
# File 'lib/tvdb2/series.rb', line 64

def initialize(client, data = {})
  @client = client
  FIELDS.each do |field|
    instance_variable_set("@#{field}", data[field.to_s])
  end
  @completed = {@client.language => data.key?('added')}
end

Instance Attribute Details

#added ⇒ Object (readonly)

Returns the value of attribute added



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def added
  @added
end

#airsDayOfWeek ⇒ Object (readonly)

Returns the value of attribute airsDayOfWeek



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def airsDayOfWeek
  @airsDayOfWeek
end

#airsTime ⇒ Object (readonly)

Returns the value of attribute airsTime



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def airsTime
  @airsTime
end

#aliases ⇒ Object (readonly)

Returns the value of attribute aliases



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def aliases
  @aliases
end

Returns the value of attribute banner



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def banner
  @banner
end

#firstAired ⇒ Object (readonly)

Returns the value of attribute firstAired



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def firstAired
  @firstAired
end

#genre ⇒ Object (readonly)

Returns the value of attribute genre



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def genre
  @genre
end

#id ⇒ Object (readonly)

Returns the value of attribute id



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def id
  @id
end

#imdbId ⇒ Object (readonly)

Returns the value of attribute imdbId



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def imdbId
  @imdbId
end

#lastUpdated ⇒ Object (readonly)

Returns the value of attribute lastUpdated



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def lastUpdated
  @lastUpdated
end

#network ⇒ Object (readonly)

Returns the value of attribute network



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def network
  @network
end

#networkId ⇒ Object (readonly)

Returns the value of attribute networkId



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def networkId
  @networkId
end

#overview ⇒ Object (readonly)

Returns the value of attribute overview



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def overview
  @overview
end

#rating ⇒ Object (readonly)

Returns the value of attribute rating



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def rating
  @rating
end

#runtime ⇒ Object (readonly)

Returns the value of attribute runtime



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def runtime
  @runtime
end

#seriesId ⇒ Object (readonly)

Returns the value of attribute seriesId



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def seriesId
  @seriesId
end

#seriesName ⇒ Object (readonly) Also known as: name

Returns the value of attribute seriesName



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def seriesName
  @seriesName
end

#siteRating ⇒ Object (readonly)

Returns the value of attribute siteRating



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def siteRating
  @siteRating
end

#siteRatingCount ⇒ Object (readonly)

Returns the value of attribute siteRatingCount



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def siteRatingCount
  @siteRatingCount
end

#status ⇒ Object (readonly)

Returns the value of attribute status



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def status
  @status
end

#zap2itId ⇒ Object (readonly)

Returns the value of attribute zap2itId



23
24
25
 
# File 'lib/tvdb2/series.rb', line 23

def zap2itId
  @zap2itId
end

Instance Method Details

#[](index) ⇒ Episode

Get the episode of the series identified by the index.

Examples:

got = client.best_search('Game of Thrones')
puts got[29].name
puts got['3x9'].name

Parameters:

  • index (String, Integer) —

    the index of the episode to retrieve. Can be and Integer (absoluteNumber) or a String "#{season_number}x#{episode_number}" (3x9).

Returns:

Raises:



116
117
118
119
120
121
122
123
124
 
# File 'lib/tvdb2/series.rb', line 116

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

#actors ⇒ Array<TvdbStruct>

Returns the list of actors in the series.

Returns:

  • (Array<TvdbStruct>) —

    the list of actors in the series.

Raises:



101
102
103
 
# File 'lib/tvdb2/series.rb', line 101

def actors
  @client.actors(self.id)
end

Returns the banner image url of the series.

Parameters:

  • random (Boolean) —

    If true return a random banner image url.

Returns:

  • (String) —

    the banner image url of the series.

Raises:



190
191
192
193
194
195
196
197
 
# File 'lib/tvdb2/series.rb', line 190

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

#banners ⇒ Array<TvdbStruct>

Returns the list of banner images of the series.

Returns:

  • (Array<TvdbStruct>) —

    the list of banner images of the series.

Raises:



183
184
185
 
# File 'lib/tvdb2/series.rb', line 183

def banners
  self.images(keyType: 'series')
end

#episodes(params = {}) ⇒ Array<Episode>

Retrieve the episodes of the series.

Parameters:

  • params (Hash) (defaults to: {}) —

    the params of the request to retrieve the episodes of the series.

Options Hash (params):

  • :absoluteNumber (String, Integer) —

    absolute number of the episode;

  • :airedSeason (String, Integer) —

    aired season number;

  • :airedEpisode (String, Integer) —

    aired episode number;

  • :dvdSeason (String, Integer) —

    DVD season number;

  • :dvdEpisode (String, Integer) —

    DVD episode number;

  • :imdbId (String, Integer) —

    IMDB id of the series;

  • :page (Integer) —

    page of results to fetch (100 episodes per page).

Returns:

Raises:



85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/tvdb2/series.rb', line 85

def episodes(params = {})
  return @client.episodes(self.id, params) if params && params.key?(:page)
  episodes = []
  page = 1
  loop do
    params.merge!(page: page)
    result = @client.episodes(self.id, params)
    episodes += result
    page += 1
    break if result.size < 100
  end
  return episodes.sort_by{|x| [x.airedSeason, x.airedEpisodeNumber]}
end

#fanarts ⇒ Array<TvdbStruct>

Returns the list of fanart images.

Returns:

  • (Array<TvdbStruct>) —

    the list of fanart images.

Raises:



150
151
152
 
# File 'lib/tvdb2/series.rb', line 150

def fanarts
  self.images(keyType: 'fanart')
end

#images(params) ⇒ Array<TvdbStruct>

Retrieve the images of the series.

Examples:

got = client.best_search('Game of Thrones')
puts got.images(keyType: 'poster').first.fileName_url # print the url of a poster of the series

Parameters:

  • params (Hash) —

    the params of the request to retrieve the images.

Options Hash (params):

  • :keyType (String) —

    type of image you're querying for (fanart, poster, season, seasonwide, series);

  • :resolution (String) —

    resolution to filter by (1280x1024 for example);

  • :subKey (String) —

    subkey for the above query keys.

Returns:

Raises:



144
145
146
 
# File 'lib/tvdb2/series.rb', line 144

def images(params)
  @client.images(self.id, params)
end

#images_summary ⇒ Array<TvdbStruct>

Returns the image summary of the series.

Returns:

  • (Array<TvdbStruct>) —

    the image summary of the series.

Raises:



130
131
132
 
# File 'lib/tvdb2/series.rb', line 130

def images_summary
  @client.images_summary(self.id)
end

#poster_url(random: false) ⇒ String

Returns the poster image url of the series.

Parameters:

  • random (Boolean) —

    If true return a random poster image url.

Returns:

  • (String) —

    the poster image url of the series.

Raises:



202
203
204
205
206
 
# File 'lib/tvdb2/series.rb', line 202

def poster_url(random: false)
  ps = self.posters
  ps.shuffle! if random
  ps.first ? ps.first.url : nil
end

#posters ⇒ Array<TvdbStruct>

Returns the list of poster images.

Returns:

  • (Array<TvdbStruct>) —

    the list of poster images.

Raises:



156
157
158
 
# File 'lib/tvdb2/series.rb', line 156

def posters
  self.images(keyType: 'poster')
end

#season_images(season: nil) ⇒ Array<TvdbStruct>

Returns the list of season images.

Parameters:

  • season (Integer) —

    If present return the images only for that season number.

Returns:

  • (Array<TvdbStruct>) —

    the list of season images.

Raises:



164
165
166
167
168
 
# File 'lib/tvdb2/series.rb', line 164

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

#seasonwide_images(season: nil) ⇒ Array<TvdbStruct>

Returns the list of season wide images.

Parameters:

  • season (Integer) —

    if present return the images only for that season number.

Returns:

  • (Array<TvdbStruct>) —

    the list of season wide images.

Raises:



174
175
176
177
178
 
# File 'lib/tvdb2/series.rb', line 174

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

#series_summary ⇒ TvdbStruct Also known as: summary

Return the summary of the series.

Returns:

  • (TvdbStruct) —

    return the summary of the series.

Raises:



74
75
76
 
# File 'lib/tvdb2/series.rb', line 74

def series_summary
  @client.series_summary(self.id)
end

#to_h(episodes: false, retrieve_all_fields: false) ⇒ Hash

Returns the series to hash.

Parameters:

  • episodes (Boolean) —

    if true include all episodes (Episode#to_h) on the hash.

  • retrieve_all_fields (Boolean) —

    if true retrieve all fields (from api) of the series.

Returns:

  • (Hash) —

    the series to hash.



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/tvdb2/series.rb', line 215

def to_h(episodes: false, retrieve_all_fields: false)
  get_all_fields! if retrieve_all_fields
  hash = {}
  FIELDS.each do |field|
    hash[field.to_sym] = instance_variable_get("@#{field}")
  end
  hash[:name] = @seriesName
  hash[:poster_url] = self.poster_url
  hash[:banner_url] = self.banner_url
  hash[:episodes] = self.episodes.map(&:to_h) if episodes
  return hash
end