subliminal 2.5.0__tar.gz → 2.6.0__tar.gz

{subliminal-2.5.0 → subliminal-2.6.0}/HISTORY.rst

@@ -2,6 +2,29 @@
 
 .. towncrier release notes start
 
+2.6.0 (2026-02-20)
+^^^^^^^^^^^^^^^^^^
+
+Provider Changes
+----------------
+
+- OpenSubtitlesCom: replace recursive ``_search()`` implementation to prevent a stack overflow in some edge case (`#1336 <https://github.com/Diaoul/subliminal/issues/1336>`__)
+- Add Subtis provider for Spanish subtitles (`#1337 <https://github.com/Diaoul/subliminal/issues/1337>`__)
+
+
+Refiner Changes
+---------------
+
+- hash: cache the result of hash_opensubtitles so it can be reused costlessly (`#1340 <https://github.com/Diaoul/subliminal/issues/1340>`__)
+
+
+Misc
+----
+
+- Fixes for some scheduled tests failures (`#1339 <https://github.com/Diaoul/subliminal/issues/1339>`__)
+- add a gif to show CLI usage (`#1341 <https://github.com/Diaoul/subliminal/issues/1341>`__)
+
+
 2.5.0 (2025-12-14)
 ^^^^^^^^^^^^^^^^^^
 

{subliminal-2.5.0 → subliminal-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subliminal
-Version: 2.5.0
+Version: 2.6.0
 Summary: Subtitles, faster than your thoughts
 Project-URL: homepage, https://github.com/Diaoul/subliminal
 Project-URL: repository, https://github.com/Diaoul/subliminal
@@ -103,6 +103,10 @@ Subtitles, faster than your thoughts.
 
 Usage
 -----
+
+.. image:: https://github.com/Diaoul/subliminal/blob/main/docs/assets/demo.gif
+    :alt: Demo of the app CLI usage
+
 CLI
 ^^^
 Download English subtitles::
@@ -120,7 +124,7 @@ By default it looks for a `subliminal.toml` file in the default configuration fo
 (see the CLI help for the exact platform-specific default path).
 Or use the `-c` option to specify the path to the configuration file.
 
-`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/config.toml>`__
+`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/assets/config.toml>`__
 or use the `generate_default_config` function from the `subliminal.cli` module to generate a
 configuration file with all the options and their default values::
 

{subliminal-2.5.0 → subliminal-2.6.0}/README.rst

@@ -30,6 +30,10 @@ Subtitles, faster than your thoughts.
 
 Usage
 -----
+
+.. image:: https://github.com/Diaoul/subliminal/blob/main/docs/assets/demo.gif
+    :alt: Demo of the app CLI usage
+
 CLI
 ^^^
 Download English subtitles::
@@ -47,7 +51,7 @@ By default it looks for a `subliminal.toml` file in the default configuration fo
 (see the CLI help for the exact platform-specific default path).
 Or use the `-c` option to specify the path to the configuration file.
 
-`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/config.toml>`__
+`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/assets/config.toml>`__
 or use the `generate_default_config` function from the `subliminal.cli` module to generate a
 configuration file with all the options and their default values::
 

{subliminal-2.5.0 → subliminal-2.6.0}/docs/api/providers.rst

@@ -43,6 +43,11 @@ Subtitulamos
 .. automodule:: subliminal.providers.subtitulamos
    :members:
 
+Subtis
+------
+.. automodule:: subliminal.providers.subtis
+   :members:
+
 TVsubtitles
 -----------
 .. automodule:: subliminal.providers.tvsubtitles

{subliminal-2.5.0 → subliminal-2.6.0}/docs/user/configuration_file.rst

@@ -34,7 +34,7 @@ Example
 
 An example of configuration file:
 
-.. literalinclude:: ../config.toml
+.. literalinclude:: ../assets/config.toml
     :language: toml
 
 

{subliminal-2.5.0 → subliminal-2.6.0}/docs/user/how_it_works.rst

@@ -13,6 +13,7 @@ subtitles. Current supported providers are:
 * OpenSubtitles
 * OpenSubtitles.com
 * Podnapisi
+* Subtis
 * Subtitulamos
 * TvSubtitles
 

{subliminal-2.5.0 → subliminal-2.6.0}/pyproject.toml

@@ -106,6 +106,7 @@ opensubtitlesvip = "subliminal.providers.opensubtitles:OpenSubtitlesVipProvider"
 opensubtitlescom = "subliminal.providers.opensubtitlescom:OpenSubtitlesComProvider"
 opensubtitlescomvip = "subliminal.providers.opensubtitlescom:OpenSubtitlesComVipProvider"
 podnapisi = "subliminal.providers.podnapisi:PodnapisiProvider"
+subtis = "subliminal.providers.subtis:SubtisProvider"
 subtitulamos = "subliminal.providers.subtitulamos:SubtitulamosProvider"
 tvsubtitles = "subliminal.providers.tvsubtitles:TVsubtitlesProvider"
 

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/extensions.py

@@ -157,6 +157,7 @@ provider_manager = RegistrableExtensionManager(
         'opensubtitlescomvip = subliminal.providers.opensubtitlescom:OpenSubtitlesComVipProvider',
         'opensubtitlesvip = subliminal.providers.opensubtitles:OpenSubtitlesVipProvider',
         'podnapisi = subliminal.providers.podnapisi:PodnapisiProvider',
+        'subtis = subliminal.providers.subtis:SubtisProvider',
         'subtitulamos = subliminal.providers.subtitulamos:SubtitulamosProvider',
         'tvsubtitles = subliminal.providers.tvsubtitles:TVsubtitlesProvider',
     ],

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/providers/__init__.py

@@ -24,7 +24,6 @@ from subliminal.subtitle import Subtitle
 from subliminal.video import Episode, Movie, Video
 
 if TYPE_CHECKING:
-    import os
     from collections.abc import Sequence, Set
     from http.client import HTTPSConnection
     from types import TracebackType
@@ -146,7 +145,7 @@ class Provider(Generic[S]):
     user_agent: str = f'Subliminal/{__short_version__}'
 
     @staticmethod
-    def hash_video(video_path: str | os.PathLike) -> str | None:
+    def hash_video(video_path: str) -> str | None:
         """Hash the video to be used by the provider."""
         return None
 

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/providers/bsplayer.py

@@ -200,7 +200,7 @@ class BSPlayerProvider(Provider):
         self.search_url = search_url or get_sub_domain()
 
     @staticmethod
-    def hash_video(video_path: str | os.PathLike) -> str | None:
+    def hash_video(video_path: str) -> str | None:
         """Compute a hash using BSPlayer algorithm.
 
         :param str video_path: path of the video.

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/providers/napiprojekt.py

@@ -17,7 +17,6 @@ from subliminal.subtitle import Subtitle, fix_line_ending
 from . import Provider
 
 if TYPE_CHECKING:
-    import os
     from collections.abc import Set
 
     from subliminal.video import Video
@@ -98,7 +97,7 @@ class NapiProjektProvider(Provider):
         self.session = None
 
     @staticmethod
-    def hash_video(video_path: str | os.PathLike) -> str | None:
+    def hash_video(video_path: str) -> str | None:
         """Compute a hash using NapiProjekt's algorithm.
 
         :param str video_path: path of the video.

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/providers/opensubtitles.py

@@ -196,7 +196,6 @@ class OpenSubtitlesProvider(Provider):
         username: str | None = None,
         password: str | None = None,
         *,
-        max_result_pages: int = 0,
         timeout: int = 10,
     ) -> None:
         transport = TimeoutSafeTransport(timeout=timeout, user_agent='VLSub')

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/providers/opensubtitlescom.py

@@ -31,7 +31,7 @@ from subliminal.video import Episode, Movie, Video
 from . import Provider
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping, Set
+    from collections.abc import Generator, Mapping, Set
 
 C = TypeVar('C', bound=Callable)
 
@@ -595,30 +595,28 @@ class OpenSubtitlesComProvider(Provider):
 
         return r.json()  # type: ignore[no-any-return]
 
-    def _search(self, *, page: int = 1, **params: Any) -> list[dict[str, Any]]:
-        # Extended params with page
-        ext_params = {'page': page, **params}
+    def _search(self, **params: Any) -> Generator[dict[str, Any], None, None]:
+        page = 1
 
-        # query the server
-        logger.info('Searching subtitles %r', ext_params)
+        while True:
+            # Extended params with page
+            ext_params = {'page': page, **params}
+            logger.info('Searching subtitles %r', ext_params)
+            # GET request and add page information
+            response = self.api_get('subtitles', ext_params)
+            if not response or not response['data']:
+                break
+            yield from response['data']
 
-        # GET request and add page information
-        response = self.api_get('subtitles', ext_params)
+            page += 1
 
-        if not response or not response['data']:
-            return []
+            # check that the maximum number of pages has not been exceeded
+            if self.max_result_pages > 0 and page > self.max_result_pages:
+                break
 
-        ret = response['data']
-
-        # check that the maximum number of pages has not been exceeded
-        allow_more_pages = self.max_result_pages <= 0 or page < self.max_result_pages
-
-        # retrieve other pages maybe
-        if allow_more_pages and 'total_pages' in response and page < response['total_pages']:
-            # missing pages
-            ret.extend(self._search(page=page + 1, **params))
-
-        return ret  # type: ignore[no-any-return]
+            # check if we fetched all pages already
+            if 'total_pages' not in response or page > response['total_pages']:
+                break
 
     def _make_query(
         self,
@@ -711,14 +709,11 @@ class OpenSubtitlesComProvider(Provider):
             # add the language and query the server
             criterion.update({'languages': ','.join(sorted(lang.opensubtitlescom for lang in languages))})
 
-            # query the server
-            responses = self._search(**criterion)
-
             imdb_match = 'imdb_id' in criterion or 'show_imdb_id' in criterion
             tmdb_match = 'tmdb_id' in criterion or 'show_tmdb_id' in criterion
 
             # loop over subtitle items
-            for response in responses:
+            for response in self._search(**criterion):
                 # read single response
                 subtitle = self.subtitle_class.from_response(
                     response,

subliminal-2.6.0/src/subliminal/providers/subtis.py

@@ -0,0 +1,336 @@
+"""Provider for Subtis."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+from urllib.parse import quote
+
+from babelfish import Language
+from guessit import guessit
+from requests import Session
+from requests.exceptions import HTTPError, JSONDecodeError, RequestException
+
+from subliminal.exceptions import NotInitializedProviderError, ProviderError
+from subliminal.matches import guess_matches
+from subliminal.subtitle import Subtitle
+from subliminal.video import Movie
+
+from . import Provider
+
+if TYPE_CHECKING:
+    from collections.abc import Set
+
+    from subliminal.video import Video
+
+logger = logging.getLogger(__name__)
+
+subtis_languages: set[Language] = {
+    Language('spa', country)
+    for country in [
+        'AR',
+        'BO',
+        'CL',
+        'CO',
+        'CR',
+        'DO',
+        'EC',
+        'GT',
+        'HN',
+        'MX',
+        'NI',
+        'PA',
+        'PE',
+        'PR',
+        'PY',
+        'SV',
+        'US',
+        'UY',
+        'VE',
+    ]
+} | {Language('spa')}
+
+
+class SubtisSubtitle(Subtitle):
+    """Subtis Subtitle."""
+
+    provider_name: ClassVar[str] = 'subtis'
+
+    def __init__(
+        self,
+        language: Language,
+        subtitle_id: str = '',
+        *,
+        page_link: str | None = None,
+        title: str | None = None,
+        download_link: str | None = None,
+        is_synced: bool = True,
+        video_hash: str | None = None,
+    ) -> None:
+        super().__init__(
+            language=language,
+            subtitle_id=subtitle_id,
+            hearing_impaired=False,
+            page_link=page_link,
+        )
+        self.title = title
+        self.download_link = download_link
+        self.is_synced = is_synced
+        self.video_hash = video_hash
+
+    @property
+    def info(self) -> str:
+        """Information about the subtitle."""
+        if not self.title:
+            return self.id
+        sync_indicator = '' if self.is_synced else ' [fuzzy match]'
+        return f'{self.title}{sync_indicator}'
+
+    def get_matches(self, video: Video) -> set[str]:
+        """Get the matches against the `video`."""
+        matches: set[str] = set()
+
+        if not isinstance(video, Movie):
+            return matches
+
+        if self.video_hash and 'subtis' in video.hashes and self.video_hash == video.hashes['subtis']:
+            matches.add('hash')
+
+        if self.is_synced and video.name:
+            matches |= guess_matches(video, guessit(os.path.basename(video.name), {'type': 'movie'}))
+        elif self.title:
+            matches |= guess_matches(video, guessit(self.title, {'type': 'movie'}))
+
+        return matches
+
+
+class SubtisProvider(Provider[SubtisSubtitle]):
+    """Subtis Provider.
+
+    Provides Spanish subtitles for movies from the subt.is API.
+    """
+
+    languages: ClassVar[Set[Language]] = subtis_languages
+    video_types: ClassVar = (Movie,)
+    subtitle_class: ClassVar = SubtisSubtitle
+
+    server_url: ClassVar[str] = 'https://api.subt.is/v1'
+
+    timeout: int
+    session: Session | None
+
+    def __init__(self, *, timeout: int = 10) -> None:
+        self.timeout = timeout
+        self.session = None
+
+    @staticmethod
+    def hash_video(video_path: str) -> str | None:
+        """Compute a hash using OpenSubtitles' algorithm.
+
+        :param video_path: path of the video file.
+        :return: the hash string, or None if file is too small or error occurs.
+        """
+        from subliminal.refiners.hash import hash_opensubtitles
+
+        video_path = os.fspath(video_path)
+        try:
+            return hash_opensubtitles(video_path)
+        except OSError:
+            logger.debug('Could not compute hash for %s', video_path)
+            return None
+
+    def initialize(self) -> None:
+        """Initialize the provider."""
+        self.session = Session()
+        self.session.headers['User-Agent'] = self.user_agent
+        self.session.headers['Accept'] = 'application/json'
+
+    def terminate(self) -> None:
+        """Terminate the provider."""
+        if self.session is None:
+            raise NotInitializedProviderError
+        self.session.close()
+        self.session = None
+
+    def _session_request(self, url: str) -> dict[str, Any] | None:
+        """Perform a GET request to the provider."""
+        if self.session is None:
+            raise NotInitializedProviderError
+
+        try:
+            r = self.session.get(url, timeout=self.timeout)
+        except RequestException:
+            logger.exception('Request error for %s', url)
+            raise SubtisError from None
+
+        if r.status_code in (400, 404):
+            return None
+
+        try:
+            r.raise_for_status()
+        except HTTPError:
+            msg = f'Unexpected status {r.status_code}'
+            logger.warning('%s for %s', msg, url)
+            raise SubtisError(msg) from None
+
+        try:
+            return cast('dict[str, Any]', r.json())
+        except JSONDecodeError:
+            msg = 'Invalid JSON response'
+            logger.exception('%s for %s', msg, url)
+            raise SubtisError(msg) from None
+
+    def _parse_response(self, data: dict[str, Any]) -> tuple[str, str] | None:
+        """Parse API response and extract subtitle link and title.
+
+        Returns:
+            Tuple of (subtitle_link, title_name), or None if required fields are missing.
+        """
+        subtitle_data = data.get('subtitle')
+        if not isinstance(subtitle_data, dict):
+            return None
+
+        subtitle_link = subtitle_data.get('subtitle_link')
+        if not isinstance(subtitle_link, str) or not subtitle_link:
+            return None
+
+        title_data = data.get('title', {})
+        title_name = title_data.get('title_name', 'Unknown') if isinstance(title_data, dict) else 'Unknown'
+
+        return subtitle_link, str(title_name)
+
+    def query(self, video: Movie, languages: Set[Language]) -> list[SubtisSubtitle]:
+        """Query the provider for subtitles using cascade search.
+
+        Cascade order (from most to least specific):
+        1. Hash - OpenSubtitles video hash (most precise)
+        2. Bytes - File size match
+        3. Filename - Exact filename match
+        4. Alternative - Fuzzy match (fallback)
+        """
+        if not video.name:
+            return []
+
+        language = next((lang for lang in languages if lang.alpha3 == 'spa'), Language('spa'))
+
+        filename = os.path.basename(video.name)
+        encoded_filename = quote(filename, safe='')
+
+        if video.name and os.path.isfile(video.name):
+            video_hash = video.hashes.get('subtis')
+            if video_hash:
+                hash_url = f'{self.server_url}/subtitle/find/file/hash/{video_hash}'
+                logger.info('Searching subtitles by hash for %s', filename)
+                data = self._session_request(hash_url)
+                if data:
+                    parsed = self._parse_response(data)
+                    if parsed:
+                        subtitle_link, title_name = parsed
+                        logger.debug('Found subtitle via hash search')
+                        return [
+                            SubtisSubtitle(
+                                language=language,
+                                subtitle_id=subtitle_link,
+                                page_link=hash_url,
+                                title=title_name,
+                                download_link=subtitle_link,
+                                is_synced=True,
+                                video_hash=video_hash,
+                            )
+                        ]
+
+        if video.size:
+            bytes_url = f'{self.server_url}/subtitle/find/file/bytes/{video.size}'
+            logger.info('Searching subtitles by bytes for %s', filename)
+            data = self._session_request(bytes_url)
+            if data:
+                parsed = self._parse_response(data)
+                if parsed:
+                    subtitle_link, title_name = parsed
+                    logger.debug('Found subtitle via bytes search')
+                    return [
+                        SubtisSubtitle(
+                            language=language,
+                            subtitle_id=subtitle_link,
+                            page_link=bytes_url,
+                            title=title_name,
+                            download_link=subtitle_link,
+                            is_synced=True,
+                        )
+                    ]
+
+        filename_url = f'{self.server_url}/subtitle/find/file/name/{encoded_filename}'
+        logger.info('Searching subtitles by filename for %s', filename)
+        data = self._session_request(filename_url)
+        if data:
+            parsed = self._parse_response(data)
+            if parsed:
+                subtitle_link, title_name = parsed
+                logger.debug('Found subtitle via filename search')
+                return [
+                    SubtisSubtitle(
+                        language=language,
+                        subtitle_id=subtitle_link,
+                        page_link=filename_url,
+                        title=title_name,
+                        download_link=subtitle_link,
+                        is_synced=True,
+                    )
+                ]
+
+        alternative_url = f'{self.server_url}/subtitle/file/alternative/{encoded_filename}'
+        logger.info('Searching subtitles (alternative) for %s', filename)
+        data = self._session_request(alternative_url)
+        if data:
+            parsed = self._parse_response(data)
+            if parsed:
+                subtitle_link, title_name = parsed
+                logger.debug('Found subtitle via alternative search (fuzzy)')
+                return [
+                    SubtisSubtitle(
+                        language=language,
+                        subtitle_id=subtitle_link,
+                        page_link=alternative_url,
+                        title=title_name,
+                        download_link=subtitle_link,
+                        is_synced=False,
+                    )
+                ]
+
+        logger.info('No subtitle found for %s', filename)
+        return []
+
+    def list_subtitles(self, video: Video, languages: Set[Language]) -> list[SubtisSubtitle]:
+        """List all the subtitles for the video."""
+        if not isinstance(video, Movie):
+            return []
+
+        return self.query(video, languages)
+
+    def download_subtitle(self, subtitle: SubtisSubtitle) -> None:
+        """Download the content of the subtitle."""
+        if self.session is None:
+            raise NotInitializedProviderError
+
+        if not subtitle.download_link:
+            return
+
+        logger.info('Downloading subtitle %s', subtitle.download_link)
+
+        try:
+            r = self.session.get(subtitle.download_link, timeout=self.timeout)
+            r.raise_for_status()
+        except RequestException:
+            logger.exception('Download error for %s', subtitle.download_link)
+            raise SubtisError from None
+
+        if not r.content:
+            logger.warning('Empty subtitle content from %s', subtitle.download_link)
+            return
+
+        subtitle.set_content(r.content)
+
+
+class SubtisError(ProviderError):
+    """Base class for non-generic :class:`SubtisProvider` exceptions."""

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/providers/subtitulamos.py

@@ -182,21 +182,25 @@ class SubtitulamosProvider(Provider):
 
     @region.cache_on_arguments(expiration_time=SHOW_EXPIRATION_TIME)
     def _read_episode_page(
-        self, series: str, season: int, episode: int, year: int | None = None
+        self,
+        series: str,
+        season: int,
+        episode: int,
+        year: int | None = None,
     ) -> tuple[ParserBeautifulSoup, str]:
         """Search the URL titles by kind for the given `title`, `season` and `episode`.
 
         :param str series: Series to search for.
         :param int season: Season to search for.
         :param int episode: Episode to search for.
-        :param int year: Year to search for.
+        :param (int | None) year: Year to search for.
         :return: The episode URL.
 
         """
         logger.info('Searching episode url for %s, season %d, episode %d', series, season, episode)
 
         # attempt first with year
-        series_response = self._query_search(f'{series} ({year})')
+        series_response = self._query_search(f'{series} ({year})') if year else []
         if len(series_response) == 0:
             series_response = self._query_search(series)
 

{subliminal-2.5.0 → subliminal-2.6.0}/src/subliminal/refiners/hash.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import logging
 import os
 import struct
+from functools import cache
 from typing import TYPE_CHECKING, Any, cast
 
 from subliminal.extensions import get_default_providers, provider_manager
@@ -18,23 +19,26 @@ if TYPE_CHECKING:
     from subliminal.providers import Provider
     from subliminal.video import Video
 
-    HashFunc: TypeAlias = Callable[[str | os.PathLike], str | None]
+    HashFunc: TypeAlias = Callable[[str], str | None]
 
 logger = logging.getLogger(__name__)
 
 
-def hash_opensubtitles(video_path: str | os.PathLike) -> str | None:
+@cache
+def hash_opensubtitles(video_name: str) -> str | None:
     """Compute a hash using OpenSubtitles' algorithm.
 
-    :param (str | os.PathLike) video_path: path of the video.
-    :return: the hash.
-    :rtype: str
+    The result is cached so it can be reused by several providers without cost.
+
+    :param str video_name: filename of the video.
+    :return: the hash or None if it failed.
+    :rtype: str | None
 
     """
-    video_path = os.fspath(video_path)
+    video_name = os.fspath(video_name)
     bytesize = struct.calcsize(b'<q')
-    with open(video_path, 'rb') as f:
-        filesize = os.path.getsize(video_path)
+    with open(video_name, 'rb') as f:
+        filesize = os.path.getsize(video_name)
         filehash = filesize
         if filesize < 65536 * 2:
             return None