Core¶
-
subliminal.core.
ARCHIVE_EXTENSIONS
¶ Supported archive extensions
-
class
subliminal.core.
ProviderPool
(providers=None, provider_configs=None)[source]¶ 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
= 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)[source]¶ List subtitles with a single provider.
The video and languages are checked against the provider.
Parameters: Returns: found subtitles.
Return type: list of
Subtitle
or None
-
list_subtitles
(video, languages)[source]¶ List subtitles.
Parameters: Returns: found subtitles.
Return type: list of
Subtitle
-
download_subtitle
(subtitle)[source]¶ 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)[source]¶ 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
- subtitles (list of
-
terminate
()[source]¶ Terminate all the
initialized_providers
.
- Lazy loads providers when needed and supports the with statement to
-
class
subliminal.core.
AsyncProviderPool
(max_workers=None, *args, **kwargs)[source]¶ Subclass of
ProviderPool
with asynchronous support forlist_subtitles()
.Parameters: max_workers (int) – maximum number of threads to use. If None, max_workers
will be set to the number ofproviders
.-
max_workers
= None¶ Maximum number of threads to use
-
-
subliminal.core.
check_video
(video, languages=None, age=None, undefined=False)[source]¶ 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: - languages already exist in video‘s
-
subliminal.core.
search_external_subtitles
(path, directory=None)[source]¶ 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: Returns: found subtitles with their languages.
Return type:
-
subliminal.core.
scan_video
(path)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Refine a video using Refiners.
Note
Exceptions raised in refiners are silently passed and logged.
Parameters:
-
subliminal.core.
list_subtitles
(videos, languages, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)[source]¶ 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: - videos (set of
-
subliminal.core.
download_subtitles
(subtitles, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)[source]¶ 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.
- subtitles (list of
-
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)[source]¶ 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: - videos (set of
-
subliminal.core.
save_subtitles
(video, subtitles, single=False, directory=None, encoding=None)[source]¶ 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
- video (