addic7ed 3.0.0 → 4.0.0.pre.beta.5

data/lib/addic7ed/errors.rb

@@ -1,9 +1,10 @@
 module Addic7ed
-  exceptions = [
-    :InvalidFilename,       :ShowNotFound,    :EpisodeNotFound, :LanguageNotSupported,
-    :ParsingError,          :NoSubtitleFound, :DownloadError,   :DownloadLimitReached,
-    :SubtitleCannotBeSaved, :HTTPError
-  ]
-
-  exceptions.each { |e| const_set(e, Class.new(StandardError)) }
+  class InvalidFilename       < StandardError; end
+  class ShowNotFound          < StandardError; end
+  class EpisodeNotFound       < StandardError; end
+  class LanguageNotSupported  < StandardError; end
+  class ParsingError          < StandardError; end
+  class NoSubtitleFound       < StandardError; end
+  class DownloadError         < StandardError; end
+  class DailyLimitExceeded    < DownloadError; end
 end

data/lib/addic7ed/models/episode.rb

@@ -0,0 +1,112 @@
+require "net/http"
+require "open-uri"
+
+module Addic7ed
+  # Represents a TV show episode.
+  #
+  # @attr showname [String] TV show name.
+  # @attr season [Numeric] Season number.
+  # @attr episode [Numeric] Episode number in the season.
+
+  class Episode
+    attr_reader :showname, :season, :episode
+
+    # Creates a new instance of {Episode}.
+    #
+    # @param showname [String] TV show name, as extracted from the video file name
+    #   (_e.g._ both +"Game.of.Thrones"+ and +"Game of Thrones"+ are valid)
+    # @param season [Numeric] Season number
+    # @param episode [Numeric] Episode number in the season
+    #
+    # @example
+    #   Addic7ed::Episode.new("Game of Thrones", 6, 9)
+    #   #=> #<Addic7ed::Episode
+    #   #       @episode=9,
+    #   #       @season=6,
+    #   #       @showname="Game.of.Thrones",
+    #   #       @subtitles={:fr=>nil, :ar=>nil, :az=>nil, ..., :th=>nil, :tr=>nil, :vi=>nil}
+    #   #    >
+
+    def initialize(showname, season, episode)
+      @showname  = showname
+      @season    = season
+      @episode   = episode
+      @subtitles = languages_hash { |code, _| { code => nil } }
+    end
+
+    # Returns a list of all available {Subtitle}s for this {Episode} in the given +language+.
+    #
+    # @param language [String] Language code we want returned {Subtitle}s to be in.
+    #
+    # @return [Array<Subtitle>] List of {Subtitle}s available on Addic7ed for the given +language+.
+    #
+    # @example
+    #   Addic7ed::Episode.new("Game.of.Thrones", 3, 9).subtitles(:fr)
+    #   #=> [
+    #   #      #<Addic7ed::Subtitle
+    #   #          @comment="works with ctrlhd",
+    #   #          @downloads=28130,
+    #   #          @hi=false,
+    #   #          @language="French",
+    #   #          @source="http://addic7ed.com",
+    #   #          @status="Completed",
+    #   #          @url="http://www.addic7ed.com/updated/8/76081/0",
+    #   #          @version="EVOLVE">,
+    #   #      #<Addic7ed::Subtitle
+    #   #          @comment="la fabrique",
+    #   #          @downloads=1515,
+    #   #          @hi=false,
+    #   #          @language="French",
+    #   #          @source="http://sous-titres.eu",
+    #   #          @status="Completed",
+    #   #          @url="http://www.addic7ed.com/original/76081/11",
+    #   #          @version="EVOLVE">,
+    #   #      #<Addic7ed::Subtitle
+    #   #          @comment="la fabrique",
+    #   #          @downloads=917,
+    #   #          @hi=false,
+    #   #          @language="French",
+    #   #          @source="http://sous-titres.eu",
+    #   #          @status="Completed",
+    #   #          @url="http://www.addic7ed.com/original/76081/12",
+    #   #          @version="WEB,DL,NTB,&,YFN">
+    #   #     ]
+
+    def subtitles(language)
+      @subtitles[language] ||= Addic7ed::ParsePage.call(page_url(language))
+    end
+
+    # Returns the URL of the Addic7ed webpage listing subtitles for this {Episode}
+    # in the given +language+.
+    #
+    # @param language [String] Language code we want the webpage to list subtitles in.
+    #
+    # @return [String] Fully qualified URL of the webpage on Addic7ed.
+    #
+    # @example
+    #   Addic7ed::Episode.new("Game of Thrones", 6, 9).page_url
+    #   #=> "http://www.addic7ed.com/serie/Game_of_Thrones/6/9/8"
+
+    def page_url(language)
+      localized_urls[language]
+    end
+
+  private
+
+    def localized_urls
+      @localized_urls ||= languages_hash { |code, lang| { code => localized_url(lang[:id]) } }
+    end
+
+    def url_encoded_showname
+      @url_encoded_showname ||= URLEncodeShowName.call(showname)
+    end
+
+    def localized_url(lang)
+      "http://www.addic7ed.com/serie/#{url_encoded_showname}/#{season}/#{episode}/#{lang}"
+    end
+
+    def languages_hash(&block)
+      Hash.new { raise LanguageNotSupported }.merge(LANGUAGES.map(&block).reduce(&:merge))
+    end
+  end
+end

data/lib/addic7ed/models/search.rb

@@ -0,0 +1,90 @@
+module Addic7ed
+  # Represents a subtitle search for a +video_filename+ in a +language+ with
+  # multiple search +criterias+.
+  #
+  # @attr video_filename [String] Video file name we're searching subtitles for.
+  # @attr language [String] ISO code of language (_e.g._ "en", "fr", "es").
+  # @attr criterias [Hash] List of search criterias as a {Hash}.
+
+  class Search
+    attr_reader :video_filename, :language,  :criterias
+
+    # Creates a new instance of {Search}.
+    #
+    # Currently supported search criterias are:
+    # * +no_hi+: do not include hearing impaired subtitles (defaults to +false+)
+    #
+    # @param video_filename [String] Path to the video file for which we search subtitles
+    #   (either relative or absolute path)
+    # @param language [String] ISO code of target subtitles language
+    # @param criterias [Hash] List of search criterias the subtitles must match
+    #   (will be merged with default criterias as described above)
+    #
+    # @example
+    #   Addic7ed::Search.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv", :fr)
+    #   #=> #<Addic7ed::Search
+    #   #       @criterias={:no_hi=>false},
+    #   #       @language=:fr,
+    #   #       @video_filename="Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv"
+    #   #   >
+
+    def initialize(video_filename, language, criterias = {})
+      @video_filename = video_filename
+      @language       = language
+      @criterias      = default_criterias.merge(criterias)
+    end
+
+    # Returns the {VideoFile} object representing the video file we're searching subtitles for.
+    #
+    # @return [VideoFile] the {VideoFile} associated with this {Search}
+
+    def video_file
+      @video_file ||= VideoFile.new(video_filename)
+    end
+
+    # Returns the {Episode} object we're searching subtitles for.
+    #
+    # @return [Episode] the {Episode} associated with this {Search}
+
+    def episode
+      @episode ||= Episode.new(video_file.showname, video_file.season, video_file.episode)
+    end
+
+    # Returns the list of all available subtitles for this search,
+    # regardless of completeness, compatibility or search +criterias+.
+    #
+    # @return [SubtitlesCollection] all subtitles for the searched episode
+
+    def all_subtitles
+      @all_subtitles ||= SubtitlesCollection.new(episode.subtitles(language))
+    end
+
+    # Returns the list of subtitles completed and compatible with the episode we're searching
+    # subtitles for, regardless of search +criterias+.
+    #
+    # @return [SubtitlesCollection] subtitles completed and compatible with the searched episode
+
+    def matching_subtitles
+      @matching_subtitles ||= all_subtitles.completed.compatible_with(video_file.group)
+    end
+
+    # Returns the best subtitle for the episode we're searching subtitles for.
+    #
+    # The best subtitle means the more popular (_i.e._ most downloaded) subtitle among completed,
+    # compatible subtitles for the episode we're searching subtitles for.
+    #
+    # @return [SubtitlesCollection] subtitles completed and compatible with the searched episode
+
+    def best_subtitle
+      @best_subtitle ||= matching_subtitles.most_popular
+    end
+
+  private
+
+    def default_criterias
+      {
+        no_hi: false
+      }
+    end
+  end
+end

data/lib/addic7ed/models/subtitle.rb

@@ -0,0 +1,109 @@
+module Addic7ed
+  # Represents a subtitle on Addic7ed.
+  #
+  # This model contains as much information as possible for a subtitle
+  # as parsed on Addic7ed website.
+  #
+  # @attr version [String] Main compatible release group(s)
+  #   (evenually as a comma-separated list).
+  # @attr language [String] Language the subtitle is written in
+  #   (_e.g._: "French", "English").
+  # @attr status [String] Translation/synchronization advancement status
+  #   (_e.g._: "60%"" or "Completed").
+  # @attr source [String] URL of website the subtitle was first published on.
+  # @attr downloads [Numeric] Number of times this subtitle has been downloaded.
+  # @attr comment [String] Comment manually added by the subtitle author/publisher
+  #   (usually related to extra-compatibilities or resync source).
+  # @attr hi [Boolean] Hearing-impaired support.
+  # @attr url [String] Download URL of actual subtitle file (warning: Addic7ed servers
+  #   won't serve a subtite file without a proper +Referer+ HTTP header which can be
+  #   retrieved from +episode.page_url+).
+
+  class Subtitle
+    attr_reader :version, :language, :status, :source, :downloads, :comment, :hi
+    attr_accessor :url
+
+    # Creates a new instance of {Subtitle} created using +options+,
+    # usually from data parsed from an Addic7ed page.
+    #
+    # The +options+ hash can have the following keys as symbols:
+    # * +version+: main compatible release group(s) as parsed on the Addic7ed website
+    # * +language+: language full name
+    # * +status+: full-text advancement status
+    # * +source+: URL of website the subtitle was originally published on
+    # * +downloads+: number of times the subtitle has been downloaded
+    # * +comment+: manually added comment from the author or publisher
+    # * +hi+: hearing-impaired support
+    # * +url+: download URL for the subtitle file
+    #
+    # @param options [Hash] subtitle information as a {Hash}
+    #
+    # @example
+    #   Addic7ed::Subtitle.new(
+    #     version:   "Version KILLERS, 720p AVS, 0.00 MBs",
+    #     language:  "French",
+    #     status:    "Completed",
+    #     source:    "http://sous-titres.eu",
+    #     downloads: 10335,
+    #     comment:   "works with 1080p.BATV",
+    #     hi:        false,
+    #     url:       "http://www.addic7ed.com/original/113643/4"
+    #   )
+    #   #=> #<Addic7ed::Subtitle
+    #   #       @version="KILLERS,AVS",
+    #   #       @language="French"
+    #   #       @status="Completed"
+    #   #       @url="http://www.addic7ed.com/original/113643/4"
+    #   #       @source="http://sous-titres.eu"
+    #   #       @hi=false
+    #   #       @downloads=10335
+    #   #       @comment="works with 1080p.batv"
+    #   #   >
+
+    def initialize(options = {})
+      @version   = NormalizeVersion.call(options[:version])
+      @language  = options[:language]
+      @status    = options[:status]
+      @url       = options[:url]
+      @source    = options[:source]
+      @hi        = options[:hi]
+      @downloads = options[:downloads].to_i || 0
+      @comment   = NormalizeComment.call(options[:comment])
+    end
+
+    # Returns a human-friendly readable string representing the {Subtitle}
+    #
+    # TODO: move to the CLI codebase
+    #
+    # @return [String]
+    #
+    # @example
+    #   Addic7ed::Subtitle.new(
+    #     version:   "Version 720p AVS, 0.00 MBs",
+    #     language:  "French",
+    #     status:    "Completed",
+    #     downloads: 42,
+    #     url:       "http://www.addic7ed.com/original/113643/4"
+    #   ).to_s
+    #   #=> "http://www.addic7ed.com/original/113643/4\t->\tAVS (French, Completed) [42 downloads]"
+
+    def to_s
+      str = "#{url}\t->\t#{version} (#{language}, #{status}) [#{downloads} downloads]"
+      str += " (source #{source})" if source
+      str
+    end
+
+    # Completeness status of the {Subtitle}.
+    #
+    # @return [Boolean] Returns +true+ if {Subtitle} is complete,
+    #   +false+ otherwise (partially complete)
+    #
+    # @example
+    #   Addic7ed::Subtitle.new(status: "50%").completed?       #=> false
+    #   Addic7ed::Subtitle.new(status: "Completed").completed? #=> true
+
+    def completed?
+      status == "Completed"
+    end
+  end
+end

data/lib/addic7ed/models/subtitles_collection.rb

@@ -0,0 +1,63 @@
+module Addic7ed
+  # Represents a collection of {Subtitle} objects.
+  #
+  # This collection inherits from {Array} so it behaves exaclty like it,
+  # but it also provides some methods to filter, order and choose the best subtitle.
+  class SubtitlesCollection < Array
+    # Returns only subtitles that are compatible with +group+.
+    # @param group [String] Release group we want the returned subtitles to be compatible with
+    #
+    # @return [SubtitleCollection] Copy of collection with subtitles compatible with +group+ only
+    #
+    # @example
+    #   fov        = Addic7ed::Subtitle.new(version: "FOV")
+    #   lol        = Addic7ed::Subtitle.new(version: "LOL")
+    #   dimension  = Addic7ed::Subtitle.new(version: "DIMENSION")
+    #   collection = Addic7ed::SubtitlesCollection.new([fov, lol, dimension])
+    #
+    #   collection.compatible_with("DIMENSION")
+    #   #=> [#<Addic7ed::Subtitle @version="LOL">, #<Addic7ed::Subtitle @version="DIMENSION">]
+
+    def compatible_with(group)
+      select { |subtitle| CheckCompatibility.call(subtitle, group) }
+    end
+
+    # Returns only completed subtitles.
+    #
+    # @return [SubtitleCollection] Copy of collection with completed subtitles only
+    #
+    # @example
+    #   complete   = Addic7ed::Subtitle.new(status: "Completed")
+    #   wip        = Addic7ed::Subtitle.new(status: "50%")
+    #   collection = Addic7ed::SubtitlesCollection.new([complete, wip])
+    #
+    #   collection.completed
+    #   #=> [#<Addic7ed::Subtitle @status="Completed">]
+
+    def completed
+      select(&:completed?)
+    end
+
+    # Returns the most downloaded subtitle.
+    #
+    # @return [Subtitle] Subtitle of the collection with the more downloads
+    #
+    # @example
+    #   popular    = Addic7ed::Subtitle.new(downloads: 1000)
+    #   unpopular  = Addic7ed::Subtitle.new(downloads: 3)
+    #   collection = Addic7ed::SubtitlesCollection.new([popular, unpopular])
+    #
+    #   collection.most_popular
+    #   #=> #<Addic7ed::Subtitle @downloads=1000>
+
+    def most_popular
+      sort_by(&:downloads).last
+    end
+
+  private
+
+    def select
+      SubtitlesCollection.new(super)
+    end
+  end
+end

data/lib/addic7ed/models/video_file.rb

@@ -0,0 +1,147 @@
+module Addic7ed
+  # Represents the video file you're looking a subtitle for.
+  #
+  # This class will extract from the video file name the show name, season, episode, group, etc.
+  #
+  # It expects the file to be named according to The Scene rules,
+  # but actually supports a wide variety of common naming schemes.
+  class VideoFile
+    # @!visibility private
+    TVSHOW_REGEX = /\A(?<showname>.*\w)[\[\. ]+S?(?<season>\d{1,2})[-\. ]?[EX]?(?<episode>\d{2})([-\. ]?[EX]?\d{2})*[\]\. ]+(?<tags>.*)-(?<group>\w*)\[?(?<distribution>\w*)\]?(\.\w{3})?\z/i # rubocop:disable Metrics/LineLength
+
+    # @!visibility private
+    attr_reader :filename, :regexp_matches
+
+    # Returns a new instance of {VideoFile}.
+    # It expects a video file name, either with or without path and
+    # either absolute or relative.
+    #
+    # @param filename [String] File name of the video file on disk
+    #   (either relative or absolute).
+    #
+    # @return [String] Distribution group name
+    #
+    # @example
+    #   Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   Addic7ed::VideoFile.new("/home/mike/Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   Addic7ed::VideoFile.new("../Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+
+    def initialize(filename)
+      @filename = filename
+      @regexp_matches = TVSHOW_REGEX.match(basename)
+      raise InvalidFilename if regexp_matches.nil?
+    end
+
+    # Returns the TV show name extracted from the file name.
+    #
+    # @return [String] TV show name
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.showname #=> "Game.of.Thrones"
+
+    def showname
+      @showname ||= regexp_matches[:showname]
+    end
+
+    # Returns the TV show season number extracted from the file name.
+    #
+    # @return [Integer] TV show season number
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.season #=> 6
+
+    def season
+      @season ||= regexp_matches[:season].to_i
+    end
+
+    # Returns the TV show episode number extracted from the file name.
+    #
+    # @return [Integer] TV show episode number
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.episode #=> 9
+
+    def episode
+      @episode ||= regexp_matches[:episode].to_i
+    end
+
+    # Returns the upcased release tags extracted from the file name
+    # (like +HDTV+, +720P+, +XviD+, +PROPER+, ...).
+    #
+    # @return [Array<String>] Release video, audio or packaging tags
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.tags #=> ["720P", "HDTV", "X264"]
+
+    def tags
+      @tags ||= regexp_matches[:tags].upcase.split(/[\. ]/)
+    end
+
+    # Returns the upcased release group extracted from the file name.
+    #
+    # @return [String] Release group name
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.group #=> "AVS"
+
+    def group
+      @group ||= regexp_matches[:group].upcase
+    end
+
+    # Returns the upcased distribution group extracted from the file name.
+    #
+    # @return [String] Distribution group name
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("Game.of.Thrones.S06E09.720p.HDTV.x264-AVS[eztv].mkv")
+    #   video_file.distribution #=> "EZTV"
+
+    def distribution
+      @distribution ||= regexp_matches[:distribution].upcase
+    end
+
+    # Returns the base file name (without path).
+    #
+    # @return [String] Base file name
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("../Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.basename #=> "Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv"
+
+    def basename
+      @basename ||= File.basename(filename)
+    end
+
+    # Returns the video file name as passed to {#initialize}.
+    #
+    # @return [String] File name
+    #
+    # @example
+    #   video_file = Addic7ed::VideoFile.new("../Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv")
+    #   video_file.to_s #=> "../Game.of.Thrones.S06E09.720p.HDTV.x264-AVS.mkv"
+
+    def to_s
+      filename
+    end
+
+    # Returns a multiline, human-readable breakdown of the file name
+    # including all detected attributes (show name, season, episode, tags, ...).
+    #
+    # @return [String] a human-readable breakdown of the file name
+
+    def inspect
+      "Guesses for #{filename}:\n"      \
+      "  show:         #{showname}\n"   \
+      "  season:       #{season}\n"     \
+      "  episode:      #{episode}\n"    \
+      "  tags:         #{tags}\n"       \
+      "  group:        #{group}\n"      \
+      "  distribution: #{distribution}"
+    end
+  end
+end