Core
****

subliminal.core.ARCHIVE_EXTENSIONS

   Supported archive extensions

class subliminal.core.ProviderPool(providers=None, provider_configs=None)

   A pool of providers with the same API as a single "Provider".

   It has a few extra features:

      * Lazy loads providers when needed and supports the *with*
        statement to "terminate()" the providers on exit.

      * Automatically discard providers on failure.

   Parameters:
      * **providers** (*list*) – name of providers to use, if not
        all.

      * **provider_configs** (*dict*) – provider configuration as
        keyword arguments per provider name to pass when instanciating
        the "Provider".

   providers = None

      Name of providers to use

   provider_configs = None

      Provider configuration

   initialized_providers = None

      Initialized providers

   discarded_providers = None

      Discarded providers

   list_subtitles_provider(provider, video, languages)

      List subtitles with a single provider.

      The video and languages are checked against the provider.

      Parameters:
         * **provider** (*str*) – name of the provider.

         * **video** ("Video") – video to list subtitles for.

         * **languages** (set of "Language") – languages to search
           for.

      Returns:
         found subtitles.

      Return type:
         list of "Subtitle" or None

   list_subtitles(video, languages)

      List subtitles.

      Parameters:
         * **video** ("Video") – video to list subtitles for.

         * **languages** (set of "Language") – languages to search
           for.

      Returns:
         found subtitles.

      Return type:
         list of "Subtitle"

   download_subtitle(subtitle)

      Download *subtitle*’s "content".

      Parameters:
         **subtitle** ("Subtitle") – subtitle to download.

      Returns:
         *True* if the subtitle has been successfully downloaded,
         *False* otherwise.

      Return type:
         bool

   download_best_subtitles(subtitles, video, languages, min_score=0, hearing_impaired=False, only_one=False, compute_score=None)

      Download the best matching subtitles.

      Parameters:
         * **subtitles** (list of "Subtitle") – the subtitles to
           use.

         * **video** ("Video") – video to download subtitles for.

         * **languages** (set of "Language") – languages to
           download.

         * **min_score** (*int*) – minimum score for a subtitle to
           be downloaded.

         * **hearing_impaired** (*bool*) – hearing impaired
           preference.

         * **only_one** (*bool*) – download only one subtitle, not
           one per language.

         * **compute_score** – function that takes *subtitle* and
           *video* as positional arguments, *hearing_impaired* as
           keyword argument and returns the score.

      Returns:
         downloaded subtitles.

      Return type:
         list of "Subtitle"

   terminate()

      Terminate all the "initialized_providers".

class subliminal.core.AsyncProviderPool(max_workers=None, *args, **kwargs)

   Subclass of "ProviderPool" with asynchronous support for
   "list_subtitles()".

   Parameters:
      **max_workers** (*int*) – maximum number of threads to use. If
      *None*, "max_workers" will be set to the number of "providers".

   max_workers = None

      Maximum number of threads to use

   list_subtitles_provider(provider, video, languages)

      List subtitles with a single provider.

      The video and languages are checked against the provider.

      Parameters:
         * **provider** (*str*) – name of the provider.

         * **video** ("Video") – video to list subtitles for.

         * **languages** (set of "Language") – languages to search
           for.

      Returns:
         found subtitles.

      Return type:
         list of "Subtitle" or None

   list_subtitles(video, languages)

      List subtitles.

      Parameters:
         * **video** ("Video") – video to list subtitles for.

         * **languages** (set of "Language") – languages to search
           for.

      Returns:
         found subtitles.

      Return type:
         list of "Subtitle"

subliminal.core.check_video(video, languages=None, age=None, undefined=False)

   Perform some checks on the *video*.

   All the checks are optional. Return *False* if any of this check
   fails:

      * *languages* already exist in *video*’s "subtitle_languages".

      * *video* is older than *age*.

      * *video* has an *undefined* language in "subtitle_languages".

   Parameters:
      * **video** ("Video") – video to check.

      * **languages** (set of "Language") – desired languages.

      * **age** (*datetime.timedelta*) – maximum age of the video.

      * **undefined** (*bool*) – fail on existing undefined
        language.

   Returns:
      *True* if the video passes the checks, *False* otherwise.

   Return type:
      bool

subliminal.core.search_external_subtitles(path, directory=None)

   Search for external subtitles from a video *path* and their
   associated language.

   Unless *directory* is provided, search will be made in the same
   directory as the video file.

   Parameters:
      * **path** (*str*) – path to the video.

      * **directory** (*str*) – directory to search for subtitles.

   Returns:
      found subtitles with their languages.

   Return type:
      dict

subliminal.core.scan_video(path)

   Scan a video from a *path*.

   Parameters:
      **path** (*str*) – existing path to the video.

   Returns:
      the scanned video.

   Return type:
      "Video"

subliminal.core.scan_archive(path)

   Scan an archive from a *path*.

   Parameters:
      **path** (*str*) – existing path to the archive.

   Returns:
      the scanned video.

   Return type:
      "Video"

subliminal.core.scan_videos(path, age=None, archives=True)

   Scan *path* for videos and their subtitles.

   See "refine()" to find additional information for the video.

   Parameters:
      * **path** (*str*) – existing directory path to scan.

      * **age** (*datetime.timedelta*) – maximum age of the video or
        archive.

      * **archives** (*bool*) – scan videos in archives.

   Returns:
      the scanned videos.

   Return type:
      list of "Video"

subliminal.core.refine(video, episode_refiners=None, movie_refiners=None, **kwargs)

   Refine a video using Refiners.

   Note: Exceptions raised in refiners are silently passed and
     logged.

   Parameters:
      * **video** ("Video") – the video to refine.

      * **episode_refiners** (*tuple*) – refiners to use for
        episodes.

      * **movie_refiners** (*tuple*) – refiners to use for movies.

      * ****kwargs** – additional parameters for the "refine()"
        functions.

subliminal.core.list_subtitles(videos, languages, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)

   List subtitles.

   The *videos* must pass the *languages* check of "check_video()".

   Parameters:
      * **videos** (set of "Video") – videos to list subtitles for.

      * **languages** (set of "Language") – languages to search for.

      * **pool_class** ("ProviderPool", "AsyncProviderPool" or
        similar) – class to use as provider pool.

      * ****kwargs** – additional parameters for the provided
        *pool_class* constructor.

   Returns:
      found subtitles per video.

   Return type:
      dict of "Video" to list of "Subtitle"

subliminal.core.download_subtitles(subtitles, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)

   Download "content" of *subtitles*.

   Parameters:
      * **subtitles** (list of "Subtitle") – subtitles to download.

      * **pool_class** ("ProviderPool", "AsyncProviderPool" or
        similar) – class to use as provider pool.

      * ****kwargs** – additional parameters for the provided
        *pool_class* constructor.

subliminal.core.download_best_subtitles(videos, languages, min_score=0, hearing_impaired=False, only_one=False, compute_score=None, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)

   List and download the best matching subtitles.

   The *videos* must pass the *languages* and *undefined* (*only_one*)
   checks of "check_video()".

   Parameters:
      * **videos** (set of "Video") – videos to download subtitles
        for.

      * **languages** (set of "Language") – languages to download.

      * **min_score** (*int*) – minimum score for a subtitle to be
        downloaded.

      * **hearing_impaired** (*bool*) – hearing impaired preference.

      * **only_one** (*bool*) – download only one subtitle, not one
        per language.

      * **compute_score** – function that takes *subtitle* and
        *video* as positional arguments, *hearing_impaired* as keyword
        argument and returns the score.

      * **pool_class** ("ProviderPool", "AsyncProviderPool" or
        similar) – class to use as provider pool.

      * ****kwargs** – additional parameters for the provided
        *pool_class* constructor.

   Returns:
      downloaded subtitles per video.

   Return type:
      dict of "Video" to list of "Subtitle"

subliminal.core.save_subtitles(video, subtitles, single=False, directory=None, encoding=None)

   Save subtitles on filesystem.

   Subtitles are saved in the order of the list. If a subtitle with a
   language has already been saved, other subtitles with the same
   language are silently ignored.

   The extension used is *.lang.srt* by default or *.srt* is *single*
   is *True*, with *lang* being the IETF code for the "language" of
   the subtitle.

   Parameters:
      * **video** ("Video") – video of the subtitles.

      * **subtitles** (list of "Subtitle") – subtitles to save.

      * **single** (*bool*) – save a single subtitle, default is to
        save one subtitle per language.

      * **directory** (*str*) – path to directory where to save the
        subtitles, default is next to the video.

      * **encoding** (*str*) – encoding in which to save the
        subtitles, default is to keep original encoding.

   Returns:
      the saved subtitles

   Return type:
      list of "Subtitle"
