thetvdb_party 0.0.3.pre → 0.0.4.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 10b769b794762838282b28b80116250e5937e961
-  data.tar.gz: ed366080d1178eb6dfd17eb4b484e27ebb958a65
+  metadata.gz: 7a24afc1e632c9b90ef99ffc1637e516512d871b
+  data.tar.gz: b9108ddf1caadb00a329c1c2182d7626746aef45
 SHA512:
-  metadata.gz: c289b5d1d2fd9ace25e8f319d04e9d529a988f103fe1985a34c080c26f0b9cf689f4404bca4b4209e378244d9952d2ed2b20926b2c6621174099269988679d35
-  data.tar.gz: 77527c111bce009ac2cd1ef9da5c523d392e73fe00d0dda24e97ef493ea02d68343a4508b2001378299d8e4522317fd5de1560ceff20a5b92828934958457f08
+  metadata.gz: 0d290af51be12bd346ae205265413114b97115cfb35a54eba48895bdb6af42c9afbd3b3088175acef5db2ea172e2bbb048ac712d89ac652ca9686225d5c0047c
+  data.tar.gz: 2ea5deaa5750fe06d0f83b28609b1e91c8ae0d38fd3beaabc156dd078d66df006ad7761f9a0a2bcfb7c8005bc9867801229d6ace130ba4285a1746619237d63b

data/.gitignore

@@ -1,3 +1,4 @@
+/.idea/
 /.bundle/
 /.yardoc
 /Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/lib/thetvdb_party/baseseriesrecord.rb

@@ -0,0 +1,131 @@
+module TheTvDbParty
+  # The Base Series Record contains all of the information available about a series. It does not include any banner, season, or episode information.
+  class BaseSeriesRecord
+
+    attr_reader :client
+    attr_reader :seriesid, :actors, :added, :addedby, :airs_dayofweek, :airs_time, :bannerpath_full, :bannerpath_relative, :contentrating, :fanartpath_full, :fanartpath_relative, :firstaired, :genres, :imdb_id, :language, :lastupdated, :network, :networkid, :overview, :posterpath_full, :posterpath_relative, :rating, :ratingcount, :runtime, :seriesid, :seriesname, :status, :tvcom_id, :zap2it_id
+
+    # @param [TheTvDbParty::Client] client
+    # @param [Hash{String => String}] hashValues
+    def initialize(client, hashValues)
+      @client = client
+      @hashValues = hashValues
+    end
+
+    # The client instance that retrieved this record
+    # @return [TheTvDbParty::Client]
+    def client; @client end
+
+    # The identifier that is assigned by TheTvDb to the series
+    # @return [Fixnum] An unsigned integer assigned by our site to the series. It does not change and will always represent the same series. Cannot be nil.
+    def seriesid; hashValues["id"] ? @hashValues["id"].to_i : -1 end
+
+    # The actors that make up the main cast for the series
+    # @return [Array<String>] An array containg the names of actors as string values. Empty if none are listed.
+    def actors; hashValues["Actors"] ? @hashValues["Actors"].split('|').reject { |a| a.nil? || a.empty? } : [] end
+
+    # The day of the week the series airs
+    # @return [String] The full name in English for the day of the week the series airs in plain text. Can be nil.
+    def airs_dayofweek; @hashValues["Airs_DayOfWeek"] end
+
+    # The time of day the series airs on its original network.
+    # @return [Time, NilClass] The time of day the series airs on its original network. Can be nil
+    # @note The Date portion of the returned value is not relevant
+    def airs_time; @hashValues["Airs_Time"] ? Time.parse(@hashValues["Airs_Time"]) : nil end
+
+    # The rating given to the series based on the US rating system
+    # @return [String] Can be nil or a 4-5 character string.
+    def contentrating; @hashValues["ContentRating"] end
+
+    # The date the series first aired
+    # @return [Date, NilClass] The date the series first aired. Can be nil
+    def firstaired; @hashValues["FirstAired"] ? Date.parse(hashValues["FirstAired"]) : nil end
+
+    # The Genres of the series
+    # @return [Array<String>] A list of genre names. Empty if none are listed
+    def genres; @hashValues["Genre"] ? @hashValues["Genre"].split('|').reject { |a| a.nil? || a.empty? } : [] end
+
+    # The IMDB ID for the series.
+    # @return [String] An alphanumeric string containing the IMDB ID for the series. Can be nil.
+    def imdb_id; @hashValues["IMDB_ID"] end
+
+    # The language of the information that is included in the current record.
+    # @return [String] A two character string indicating the language in accordance with ISO-639-1. Cannot be nil.
+    def language; @hashValues["Language"] end
+
+    # The network name on which the series airs
+    # @return [String] A string containing the network name in plain text. Can be nil.
+    def network; @hashValues["Network"] end
+
+    # @return [Fixnum] Not in use, will be an unsigned integer if ever used. Can be nil.
+    def networkid; @hashValues["NetworkID"] ? @hashValues["NetworkID"].to_i : -1 end
+
+    # The overview for the series, if possible in the language requested
+    # @return [String] A string containing the overview in the language requested. Will return the English overview if no translation is available in the language requested. Can be nil.
+    def overview; @hashValues["Overview"] end
+
+    # The average rating our users have rated the series out of 10
+    # @return [Float] The average rating our users have rated the series out of 10, rounded to 1 decimal place. 0.0 if no one has rated the series.
+    def rating; @hashValues["Rating"] ? @hashValues["Rating"].to_f : 0.0 end
+
+    # The number of users who have rated the series
+    # @return [Fixnum] An unsigned integer representing the number of users who have rated the series.
+    def ratingcount; @hashValues["RatingCount"] ? @hashValues["RatingCount"].to_i : 0 end
+
+    # The runtime in minutes of an episode of the series.
+    # @return [Fixnum] An unsigned integer representing the runtime of the series in minutes. -1 if the information is not available.
+    def runtime; @hashValues["Runtime"] ? @hashValues["Runtime"].to_i : -1 end
+
+    # The series id at tv.com
+    # @deprecated As TV.com now only uses these ID's internally it's of little use and no longer updated.
+    # @return [Fixnum, NilClass] An unsigned integer representing the series ID at tv.com. Can be nil.
+    def tvcom_id; @hashValues["SeriesID"] ? @hashValues["SeriesID"].to_i : nil end
+
+    # The name of the series, if possible in the language requested
+    # @return [String] A string containing the series name in the language you requested. Will return the English name if no translation is found in the language requested. Can be nil if the name isn't known in the requested language or English.
+    def seriesname; @hashValues["SeriesName"] end
+
+    # The status of the series
+    # @return [String] A string containing either "Ended" or "Continuing". Can be nil.
+    def status; @hashValues["Status"] end
+
+    # The date and time the series was added to the TheTvDb database.
+    # @return [DateTime, NilClass] Can be nil for older series
+    def added; @hashValues["added"] ? DateTime.parse(@hashValues["added"]) : nil end
+
+    # The user account identifier of the user who added the series to the database
+    # @return [Fixnum, NilClass] An unsigned integer. The ID of the user on our site who added the series to our database. Is nil for older series.
+    def addedby; @hashValues["addedBy"] ? @hashValues["addedBy"].to_i : nil end
+
+    # The path to the highest rated banner for this series.
+    # @return [String] Returns the relative path to the highest rated banner for this series. Retrieve {#bannerpath_full} get the absolute path.
+    def bannerpath_relative; @hashValues["banner"] end
+
+    # The path to the highest rated fanart for this series.
+    # @return [String] Returns the relative path to the highest rated fanart for this series. Retrieve {#fanartpath_full} get the absolute path.
+    def fanartpath_relative; @hashValues["fanart"] end
+
+    # The path to the highest rated poster for this series.
+    # @return [String] Returns the relative path to the highest rated poster for this series. Retrieve {#posterpath_full} get the absolute path.
+    def posterpath_relative; @hashValues["poster"] end
+
+    # The zap2it id for the series
+    # @return [String] An alphanumeric string containing the zap2it id. Can be nil.
+    def zap2it_id; @hashValues["zap2it_id"] end
+
+    # The time and date of the last time any changes were made to the series
+    # @return [DateTime] An instance containing both time and date of the last update. Can be nil
+    def lastupdated; @hashValues["lastupdated"] ? Time.at(@hashValues["lastupdated"].to_i).to_datetime : nil end
+
+    # The full path to the banner for the series.
+    # @return [URI] The full path for the highest rated banner for the series, returned as a URI instance.def bannerpath_full; URI::join(BASE_URL, "banners", bannerpath_relative) end
+
+    # The full path to the banner for the series.
+    # @return [URI] The full path for the highest rated fanart for the series, returned as a URI instance.
+    def fanartpath_full; URI::join(BASE_URL, "banners", fanartpath_relative) end
+
+    # The full path to the banner for the series.
+    # @return [URI] The full path for the highest rated poster for the series, returned as a URI instance.
+    def posterpath_full; URI::join(BASE_URL, "banners", posterpath_relative) end
+  end
+end

data/lib/thetvdb_party/client.rb

@@ -0,0 +1,77 @@
+module TheTvDbParty
+  # The ThTvDb API client
+  class Client
+    include HTTParty
+
+    attr_accessor :apikey, :language
+
+    @language = nil
+
+    # Creates a new TheTvDb client with the given API key
+    # @param [String] apikey The API key to use when accessing the ThTvDb programmers API
+    # @note If nil is specified for _apikey_, the client will not be able to access the API successfully for most functions
+    #       The {#search} method will always be available, even if you do not have a valid API key.
+    def initialize(apikey)
+      @apikey = apikey
+    end
+
+    # Accesses the API key currently used by the client
+    # @return [String] The API key that is currently in use
+    def apikey; @apikey end
+    # @param [String] value The new API key to use
+    # @return [String] The new value
+    def apikey=(value) @apikey = value end
+
+    # Accesses the language currently used by the client when accessing the TheTvDb API.
+    # @return [String] A two-letter string value indicating the language used. May also be 'all' if all availabe translations are retrieved from TheTvDb
+    # @return [NilClass] nil if the default language (english) should be used.
+    def language; @language end
+    # @param [String, NilClass] value A two-letter string value indicating the language used. May also be 'all' if all availabe translations are retrieved from TheTvDb. The may also be nil if the language does not need to be specified explicitly.
+    # @return [String] The new value
+    def language=(value) @language = value end
+
+    # This interface allows you to find the id of a series based on its name.
+    # @param [String] seriesname This is the string you want to search for. If there is an exact match for the parameter, it will be the first result returned.
+    # @return [Array<TheTvDbParty::SearchSeriesRecord>] An array of records that represent the search results.
+    # @see http://thetvdb.com/wiki/index.php?title=API:GetSeries
+    # @note The method call with the account identifier is currently not supported.
+    # @see #search
+    def get_series(seriesname) search seriesname end
+
+    # This interface allows you to find the id of a series based on its name.
+    # @param [String] seriesname This is the string you want to search for. If there is an exact match for the parameter, it will be the first result returned.
+    # @return [Array<TheTvDbParty::SearchSeriesRecord>] An array of records that represent the search results.
+    # @see http://thetvdb.com/wiki/index.php?title=API:GetSeries
+    # @note The method call with the account identifier is currently not supported.
+    def search(seriesname)
+      http_query = { :seriesname => seriesname }
+      http_query[:language => @language] if @language
+      response = self.class.get(URI::join(BASE_URL, 'GetSeries.php'), { :query => http_query }).parsed_response
+      return [] unless response["Data"]
+      case response["Data"]["Series"]
+        when Array
+          response["Data"]["Series"].map {|s|SearchSeriesRecord.new(self, s)}
+        when Hash
+          [SearchSeriesRecord.new(self, response["Data"]["Series"])]
+        else
+          []
+      end
+    end
+
+    # Retrieves the Base Series Record for a given series by its series id.
+    # @param [String, Fixnum] seriesid The TheTvDb assigned unique identifier for the series to access.
+    # @return [TheTvDbParty::BaseSeriesRecord] A base series record instance or nil if the series could not be found.
+    def get_base_series_record(seriesid, language = nil)
+      unless @language
+        request_url = "#{@apikey}/series/#{seriesid}"
+      else
+        request_url = "#{@apikey}/series/#{seriesid}/#{@language}.xml"
+      end
+      request_url = URI.join(BASE_URL, request_url)
+      resp = self.class.get(request_url).parsed_response
+      return nil unless resp["Data"]["Series"]
+      BaseSeriesRecord.new(self, resp["Data"]["Series"])
+    end
+  end
+end
+

data/lib/thetvdb_party/searchseriesrecord.rb

@@ -0,0 +1,82 @@
+module TheTvDbParty
+  # Represents one record within the search results for a series search
+  # @example Getting a list of search results from a client
+  #   results = TheTvDbParty::Client.new(nil).search "The Mentalist"
+  # @example Using the search result record to fetch the Base Series Record
+  #   base_series_record = TheTvDbParty::Client.new(nil).get_base_series_record search_series_record.seriesid
+  class SearchSeriesRecord
+
+    attr_reader :client
+    attr_reader :id, :seriesid, :language, :seriesname, :aliasnames, :bannerpath_relative, :overview, :firstaired, :imdb_id, :zap2it_id, :network, :bannerpath_full
+
+    # Initializes a new Search Series Record as is was retrieved from the TheTvDb API
+    # @param [TheTvDbParty::Client] client The client instance that retrieved the record
+    # @param [Hash{String => String}] hashValues A Hash instance that maps the record attribute element names against their values represented as strings.
+    def initialize(client, hashValues)
+      @client = client
+      @hashValues = hashValues
+    end
+
+    # The client instance that retrieved this record
+    # @return [TheTvDbParty::Client]
+    def client; @client end
+
+    # The unique TheTvDb identifier to access the more detailed Base Series Record and Full Series Record
+    # @deprecated {#id} is only included to be backwards compatible with the old API and is deprecated.
+    # @return [Fixnum] Returns an unsigned integer, or -1 if the record is invalid
+    # @see #seriesid
+    def id; @hashValues["id"] ? @hashValues["id"].to_i : -1 end
+
+    # The unique TheTvDb identifier to access the more detailed Base Series Record and Full Series Record
+    # @return [Fixnum] Returns an unsigned integer, or -1 if the record is invalid
+    def seriesid; @hashValues["seriesid"] ? @hashValues["seriesid"].to_i : -1 end
+
+    # The language used for the information included in the current record
+    # @return [String] Returns a two digit string indicating the language.
+    def language; @hashValues["language"] end
+
+    # The name of the Series
+    # @return [String] Returns a string with the series name for the language indicated
+    def seriesname; @hashValues["SeriesName"] end
+
+    # Other names of the series than the information returned by {#seriesname}
+    # @return [Array<String>] An array of alias names if the series has any other names in that language. Empty if the record does not have any aliases
+    def aliasnames; @hashValues["AliasNames"] ? @hashValues["AliasNames"].split('|').reject { |a| a.nil? || a.empty? } : [] end
+
+    # The path to the highest rated banner for this series.
+    # @return [String] Returns the relative path to the highest rated banner for this series. Retrieve {#bannerpath_full} get the absolute path.
+    def bannerpath_relative; @hashValues["banner"] end
+
+    # A short summary of the series
+    # @return [String] Returns the overview for the series
+    def overview; @hashValues["Overview"] end
+
+    # The first aired date of the series
+    # @return [Date] Returns the first aired date for the series as a Date instance
+    # @return [NilClass] Returns nil if the information is not available
+    def firstaired; @hashValues["FirstAired"] ? Date.parse(@hashValues["FirstAired"]) : nil end
+
+    # The IMDB id for the series
+    # @return [String] Returns the IMDB id for the series if known. Otherwise, nil
+    def imdb_id; @hashValues["IMDB_ID"] end
+
+    # The zap2it id for the series
+    # @return [String] Returns the zap2it ID if known. Otherwise, nil
+    def zap2it_id; @hashValues["zap2it_id"] end
+
+    # The network name on which the series aires
+    # @return [String] Returns the Network name if known; Otherwise, nil.
+    def network; @hashValues["Network"] end
+
+    # The full path to the banner for the series.
+    # @return [URI] The full path for the highest rated banner for the series, returned as a URI instance.
+    def bannerpath_full; URI::join(BASE_URL, "banners", bannerpath_relative) end
+
+    # Retrieves the Base Series Record for the series
+    # @return [TheTvDbParty::BaseSeriesRecord] The Base Series Record for the series
+    # @see TheTvDbParty::Client.get_base_series_record
+    def get_base_series_record
+      client.get_base_series_record seriesid
+    end
+  end
+end

data/lib/thetvdb_party/version.rb

@@ -1,4 +1,4 @@
 module TheTvDbParty
   # The current version of the `thetvdb_party` gem
-  VERSION = "0.0.3.pre"
+  VERSION = "0.0.4.pre"
 end

data/spec/spec_helper.rb

@@ -0,0 +1,91 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end

data/spec/thetvdb_party_spec.rb

@@ -0,0 +1,32 @@
+require 'thetvdb_party'
+
+describe 'Client.search' do
+
+  before(:each) do
+    @client = TheTvDbParty::Client.new("5CB46CA60629B0DD")
+  end
+
+  it 'should return matches for "The Mentalist"' do
+    matches = @client.search "The Mentalist"
+    expect matches.count > 0
+  end
+
+  it 'should return more than one match for "Star Trek"' do
+    matches = @client.search "Star Trek"
+    expect matches.count > 1
+  end
+end
+
+describe 'Client.get_base_series_record' do
+  before(:each) do
+    @client = TheTvDbParty::Client.new("5CB46CA60629B0DD")
+  end
+
+  it 'should return records that match the search result' do
+    matches = @client.search "Star Trek"
+    matches.each do |ssr|
+      bsr = @client.get_base_series_record(ssr.seriesid)
+      expect bsr.seriesname == ssr.seriesname
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thetvdb_party
 version: !ruby/object:Gem::Version
-  version: 0.0.3.pre
+  version: 0.0.4.pre
 platform: ruby
 authors:
 - Fredrik Høisæther Rasch
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-18 00:00:00.000000000 Z
+date: 2015-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -83,12 +83,18 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/thetvdb_party.rb
+- lib/thetvdb_party/baseseriesrecord.rb
+- lib/thetvdb_party/client.rb
+- lib/thetvdb_party/searchseriesrecord.rb
 - lib/thetvdb_party/version.rb
+- spec/spec_helper.rb
+- spec/thetvdb_party_spec.rb
 - thetvdb_party.gemspec
 homepage: https://rubygems.org/gems/thetvdb_party
 licenses:
@@ -119,5 +125,7 @@ rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Ruby Gem for accessing the TheTVDB programmers API
-test_files: []
+test_files:
+- spec/spec_helper.rb
+- spec/thetvdb_party_spec.rb
 has_rdoc: