tmdb_client 1.0.0

data/lib/tmdb/page.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module TMDb
+  # One page of a paginated TMDb response.
+  #
+  # Every paginated endpoint in this gem returns a Page, where the old gem
+  # returned a different envelope class per endpoint (`Tmdb::Result` for
+  # searches, `Tmdb::Discover` for discover, `Tmdb::Movie` for `Movie.popular`)
+  # and left walking the pages entirely to the caller.
+  #
+  #   page = TMDb::Search.movie('blade runner')
+  #   page.results        # => [TMDb::Object, ...]
+  #   page.total_pages    # => 3
+  #   page.map(&:title)   # Enumerable over the results
+  #
+  #   page.each_page      { |p| ... }   # lazily fetches page 2, 3, ...
+  #   page.auto_paginate  { |movie| }   # lazily walks every result
+  #
+  # Envelope keys that are not part of the pagination contract (`dates` on
+  # `/movie/now_playing`, `id` on `/movie/{id}/changes`) stay readable through
+  # `meta`, and directly on the page itself.
+  class Page
+    include Enumerable
+
+    ENVELOPE_KEYS = %i[page total_pages total_results results].freeze
+
+    attr_reader :results, :page, :total_pages, :total_results, :meta
+
+    def initialize(page: nil, total_pages: nil, total_results: nil, results: [], meta: {}, &fetcher)
+      @results = results.freeze
+      @page = (page || 1).to_i
+      @total_pages = (total_pages || 1).to_i
+      @total_results = (total_results || @results.size).to_i
+      @meta = Object.new(meta)
+      @fetcher = fetcher
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @results.each(&block)
+      self
+    end
+
+    def size
+      @results.size
+    end
+    alias length size
+
+    def empty?
+      @results.empty?
+    end
+
+    def first_page?
+      page <= 1
+    end
+
+    def last_page?
+      page >= total_pages
+    end
+
+    def next_page
+      last_page? ? nil : page + 1
+    end
+
+    def previous_page
+      first_page? ? nil : page - 1
+    end
+
+    # Fetches an arbitrary page of the same query. Raises rather than lying when
+    # this page was built by hand (a test double, say) and has no query behind it.
+    def fetch_page(number)
+      raise Error, 'This page was not built from a request, so it cannot fetch another' unless @fetcher
+
+      @fetcher.call(number)
+    end
+
+    def fetch_next_page
+      next_page && fetch_page(next_page)
+    end
+
+    # Yields this page, then each following one, fetching as it goes. TMDb caps
+    # pagination at 500 pages; walking to the end of a large result set is a lot
+    # of requests, so this stays explicit rather than happening behind `each`.
+    def each_page
+      return enum_for(:each_page) unless block_given?
+
+      current = self
+
+      loop do
+        yield current
+        break if current.last_page?
+
+        current = current.fetch_next_page
+        break if current.nil?
+      end
+
+      self
+    end
+
+    # Every result from this page on, across page boundaries.
+    def auto_paginate(&block)
+      return enum_for(:auto_paginate) unless block
+
+      each_page { |current| current.results.each(&block) }
+    end
+
+    def to_h
+      meta.to_h.merge(
+        page: page, total_pages: total_pages, total_results: total_results, results: results.map(&:to_h)
+      )
+    end
+
+    def ==(other)
+      other.is_a?(Page) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    def inspect
+      "#<TMDb::Page page=#{page}/#{total_pages} total_results=#{total_results} results=#{size}>"
+    end
+
+    private
+
+    def method_missing(name, *args, &block)
+      return super unless args.empty? && block.nil?
+      return super unless meta.respond_to?(name)
+
+      meta.public_send(name)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      meta.respond_to?(name, include_private) || super
+    end
+  end
+end

data/lib/tmdb/person.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Person < Resource
+    def detail(id, filters = {})
+      object("/person/#{id}", filters)
+    end
+
+    def movie_credits(id, filters = {})
+      object("/person/#{id}/movie_credits", filters)
+    end
+
+    def tv_credits(id, filters = {})
+      object("/person/#{id}/tv_credits", filters)
+    end
+
+    def combined_credits(id, filters = {})
+      object("/person/#{id}/combined_credits", filters)
+    end
+
+    def external_ids(id, filters = {})
+      object("/person/#{id}/external_ids", filters)
+    end
+
+    def images(id, filters = {})
+      object("/person/#{id}/images", filters)
+    end
+
+    def profiles(id, filters = {})
+      list("/person/#{id}/images", :profiles, filters)
+    end
+
+    def tagged_images(id, filters = {})
+      page("/person/#{id}/tagged_images", filters)
+    end
+
+    def translations(id, filters = {})
+      list("/person/#{id}/translations", :translations, filters)
+    end
+
+    def changes(id, filters = {})
+      list("/person/#{id}/changes", :changes, filters)
+    end
+
+    def popular(filters = {})
+      page('/person/popular', filters)
+    end
+
+    def latest(filters = {})
+      object('/person/latest', filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/resource.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module TMDb
+  # Base for the endpoint classes.
+  #
+  # Each subclass is a thin map from a method to a TMDb path; the wrapping is
+  # uniform, so a subclass only ever says which path, which JSON key, and
+  # whether the answer is one object, a list, or a page.
+  #
+  # Every public instance method is also exposed as a class method backed by the
+  # default client, so both of these work:
+  #
+  #   TMDb::Movie.detail(550)                      # default client
+  #   TMDb::Movie.new(other_client).detail(550)    # an explicit one
+  #
+  # Every method takes an optional trailing `filters` Hash, merged into the
+  # query string. That is how `language:`, `append_to_response:`, `page:` and
+  # the rest are passed, and a filter always beats the client's own default.
+  class Resource
+    attr_reader :client
+
+    def initialize(client = nil)
+      @client = client || TMDb.client
+    end
+
+    class << self
+      private
+
+      def expose_class_methods
+        public_instance_methods(false).each do |name|
+          singleton_class.define_method(name) do |*args, **kwargs, &block|
+            new.public_send(name, *args, **kwargs, &block)
+          end
+        end
+      end
+    end
+
+    private
+
+    def fetch(path, filters = {})
+      client.get(path, filters)
+    end
+
+    # One object.
+    def object(path, filters = {})
+      Object.new(fetch(path, filters))
+    end
+
+    # A bare Array living under `key` in the response body.
+    def list(path, key, filters = {})
+      objects(fetch(path, filters)[key])
+    end
+
+    def objects(entries)
+      case entries
+      when ::Array then entries.map { |entry| Object.new(entry) }
+      when nil then []
+      else [Object.new(entries)]
+      end
+    end
+
+    # A paginated envelope. The returned Page can fetch its own following pages,
+    # reusing these filters with the page number swapped out.
+    def page(path, filters = {}, key: :results)
+      filters = normalize(filters)
+      fetcher = nil
+      fetcher = lambda do |number|
+        body = fetch(path, number.nil? ? filters : filters.merge(page: number))
+        build_page(body, key, &fetcher)
+      end
+
+      fetcher.call(nil)
+    end
+
+    def build_page(body, key = :results, &)
+      Page.new(
+        page: body[:page],
+        total_pages: body[:total_pages],
+        total_results: body[:total_results],
+        results: objects(body[key]),
+        meta: body.except(*Page::ENVELOPE_KEYS, key),
+        &
+      )
+    end
+
+    def normalize(filters)
+      (filters || {}).to_h.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/tmdb/review.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Review < Resource
+    def detail(id, filters = {})
+      object("/review/#{id}", filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/search.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Search < Resource
+    def movie(query, filters = {})
+      search('/search/movie', query, filters)
+    end
+
+    def tv(query, filters = {})
+      search('/search/tv', query, filters)
+    end
+
+    def person(query, filters = {})
+      search('/search/person', query, filters)
+    end
+
+    def multi(query, filters = {})
+      search('/search/multi', query, filters)
+    end
+
+    def company(query, filters = {})
+      search('/search/company', query, filters)
+    end
+
+    def collection(query, filters = {})
+      search('/search/collection', query, filters)
+    end
+
+    def keyword(query, filters = {})
+      search('/search/keyword', query, filters)
+    end
+
+    expose_class_methods
+
+    private
+
+    # themoviedb-api merged the query into the caller's own filters hash with
+    # `merge!`, quietly mutating it. This does not.
+    def search(path, query, filters)
+      page(path, normalize(filters).merge(query: query))
+    end
+  end
+end

data/lib/tmdb/tv/episode.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module TMDb
+  class TV
+    class Episode < Resource
+      def detail(id, season_number, episode_number, filters = {})
+        object(path(id, season_number, episode_number), filters)
+      end
+
+      def credits(id, season_number, episode_number, filters = {})
+        object("#{path(id, season_number, episode_number)}/credits", filters)
+      end
+
+      def cast(id, season_number, episode_number, filters = {})
+        list("#{path(id, season_number, episode_number)}/credits", :cast, filters)
+      end
+
+      def crew(id, season_number, episode_number, filters = {})
+        list("#{path(id, season_number, episode_number)}/credits", :crew, filters)
+      end
+
+      def guest_stars(id, season_number, episode_number, filters = {})
+        list("#{path(id, season_number, episode_number)}/credits", :guest_stars, filters)
+      end
+
+      def external_ids(id, season_number, episode_number, filters = {})
+        object("#{path(id, season_number, episode_number)}/external_ids", filters)
+      end
+
+      def images(id, season_number, episode_number, filters = {})
+        object("#{path(id, season_number, episode_number)}/images", filters)
+      end
+
+      # An episode's images are stills, so this is the one the API actually has.
+      def stills(id, season_number, episode_number, filters = {})
+        list("#{path(id, season_number, episode_number)}/images", :stills, filters)
+      end
+      alias posters stills
+
+      def videos(id, season_number, episode_number, filters = {})
+        list("#{path(id, season_number, episode_number)}/videos", :results, filters)
+      end
+
+      def translations(id, season_number, episode_number, filters = {})
+        list("#{path(id, season_number, episode_number)}/translations", :translations, filters)
+      end
+
+      # Addressed by the episode's own TMDb id.
+      def changes(episode_id, filters = {})
+        list("/tv/episode/#{episode_id}/changes", :changes, filters)
+      end
+
+      expose_class_methods
+
+      private
+
+      def path(id, season_number, episode_number)
+        "/tv/#{id}/season/#{season_number}/episode/#{episode_number}"
+      end
+    end
+  end
+end

data/lib/tmdb/tv/season.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TMDb
+  class TV
+    class Season < Resource
+      def detail(id, season_number, filters = {})
+        object("/tv/#{id}/season/#{season_number}", filters)
+      end
+
+      def credits(id, season_number, filters = {})
+        object("/tv/#{id}/season/#{season_number}/credits", filters)
+      end
+
+      def cast(id, season_number, filters = {})
+        list("/tv/#{id}/season/#{season_number}/credits", :cast, filters)
+      end
+
+      def crew(id, season_number, filters = {})
+        list("/tv/#{id}/season/#{season_number}/credits", :crew, filters)
+      end
+
+      def aggregate_credits(id, season_number, filters = {})
+        object("/tv/#{id}/season/#{season_number}/aggregate_credits", filters)
+      end
+
+      def external_ids(id, season_number, filters = {})
+        object("/tv/#{id}/season/#{season_number}/external_ids", filters)
+      end
+
+      def images(id, season_number, filters = {})
+        object("/tv/#{id}/season/#{season_number}/images", filters)
+      end
+
+      def posters(id, season_number, filters = {})
+        list("/tv/#{id}/season/#{season_number}/images", :posters, filters)
+      end
+
+      def videos(id, season_number, filters = {})
+        list("/tv/#{id}/season/#{season_number}/videos", :results, filters)
+      end
+
+      def translations(id, season_number, filters = {})
+        list("/tv/#{id}/season/#{season_number}/translations", :translations, filters)
+      end
+
+      # Addressed by the season's own TMDb id, not by series + season number.
+      def changes(season_id, filters = {})
+        list("/tv/season/#{season_id}/changes", :changes, filters)
+      end
+
+      expose_class_methods
+    end
+  end
+end

data/lib/tmdb/tv.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module TMDb
+  class TV < Resource
+    def detail(id, filters = {})
+      object("/tv/#{id}", filters)
+    end
+
+    def alternative_titles(id, filters = {})
+      list("/tv/#{id}/alternative_titles", :results, filters)
+    end
+
+    def credits(id, filters = {})
+      object("/tv/#{id}/credits", filters)
+    end
+
+    def cast(id, filters = {})
+      list("/tv/#{id}/credits", :cast, filters)
+    end
+
+    def crew(id, filters = {})
+      list("/tv/#{id}/credits", :crew, filters)
+    end
+
+    def content_ratings(id, filters = {})
+      list("/tv/#{id}/content_ratings", :results, filters)
+    end
+
+    def external_ids(id, filters = {})
+      object("/tv/#{id}/external_ids", filters)
+    end
+
+    def images(id, filters = {})
+      object("/tv/#{id}/images", filters)
+    end
+
+    def backdrops(id, filters = {})
+      list("/tv/#{id}/images", :backdrops, filters)
+    end
+
+    def posters(id, filters = {})
+      list("/tv/#{id}/images", :posters, filters)
+    end
+
+    def logos(id, filters = {})
+      list("/tv/#{id}/images", :logos, filters)
+    end
+
+    def keywords(id, filters = {})
+      list("/tv/#{id}/keywords", :results, filters)
+    end
+
+    def videos(id, filters = {})
+      list("/tv/#{id}/videos", :results, filters)
+    end
+
+    def translations(id, filters = {})
+      list("/tv/#{id}/translations", :translations, filters)
+    end
+
+    def watch_providers(id, filters = {})
+      object("/tv/#{id}/watch/providers", filters)
+    end
+
+    def changes(id, filters = {})
+      list("/tv/#{id}/changes", :changes, filters)
+    end
+
+    def similar(id, filters = {})
+      page("/tv/#{id}/similar", filters)
+    end
+
+    def recommendations(id, filters = {})
+      page("/tv/#{id}/recommendations", filters)
+    end
+
+    def reviews(id, filters = {})
+      page("/tv/#{id}/reviews", filters)
+    end
+
+    def latest(filters = {})
+      object('/tv/latest', filters)
+    end
+
+    def on_the_air(filters = {})
+      page('/tv/on_the_air', filters)
+    end
+
+    def airing_today(filters = {})
+      page('/tv/airing_today', filters)
+    end
+
+    def top_rated(filters = {})
+      page('/tv/top_rated', filters)
+    end
+
+    def popular(filters = {})
+      page('/tv/popular', filters)
+    end
+
+    expose_class_methods
+  end
+
+  # themoviedb-api nested the season and episode endpoints under a `Tv` module
+  # while the series lived on a `TV` class. Both spellings resolve here, so
+  # `TMDb::Tv::Season` and `TMDb::TV::Season` are the same class.
+  Tv = TV
+end

data/lib/tmdb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TMDb
+  VERSION = '1.0.0'
+end

data/lib/tmdb_client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require 'faraday'
+require 'faraday/retry'
+
+require_relative 'tmdb/version'
+require_relative 'tmdb/errors'
+require_relative 'tmdb/object'
+require_relative 'tmdb/page'
+require_relative 'tmdb/config'
+require_relative 'tmdb/client'
+require_relative 'tmdb/resource'
+require_relative 'tmdb/certification'
+require_relative 'tmdb/change'
+require_relative 'tmdb/collection'
+require_relative 'tmdb/company'
+require_relative 'tmdb/configuration'
+require_relative 'tmdb/credit'
+require_relative 'tmdb/discover'
+require_relative 'tmdb/find'
+require_relative 'tmdb/genre'
+require_relative 'tmdb/job'
+require_relative 'tmdb/keyword'
+require_relative 'tmdb/movie'
+require_relative 'tmdb/network'
+require_relative 'tmdb/person'
+require_relative 'tmdb/review'
+require_relative 'tmdb/search'
+require_relative 'tmdb/tv'
+require_relative 'tmdb/tv/season'
+require_relative 'tmdb/tv/episode'
+
+# A Ruby client for The Movie Database (TMDb) v3 API.
+#
+#   TMDb.configure do |config|
+#     config.api_key = ENV['TMDB_API_KEY']
+#     config.language = 'es'
+#   end
+#
+#   TMDb::Movie.detail(550, append_to_response: 'credits')
+module TMDb
+  class << self
+    # The settings the default client is built from.
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config)
+      # The client caches its own copy of the config and its connection, so it
+      # has to be rebuilt when the settings behind it change.
+      @client = nil
+
+      config
+    end
+
+    # The shared client every `TMDb::Movie.detail`-style class method goes
+    # through. Assign your own to swap it wholesale.
+    def client
+      @client ||= Client.new(config)
+    end
+
+    attr_writer :client
+
+    def reset!
+      @config = nil
+      @client = nil
+    end
+  end
+end