[BUGFIX] Fix "File name too long" error when a title is used as a folder name (#1479)

Some presets put the video title into a folder name (not just the file name). The code only shortened the file name, never the folder name. So a title with multi-byte characters (like bold/fancy Unicode, which take 4 bytes each) could make the folder name go over the OS 255-byte limit and crash with OSError: [Errno 36] File name too long.

This fix shortens every folder in the path too, not just the file name, while keeping the file extension. output_directory is left alone so real folders aren't touched.

Added a test with a title made of 4-byte bold Unicode characters.

Relates to #1092, #1189

-- Thanks @Nojyto for the contribution!

docs/source/guides/getting_started/first_config.rst

@@ -251,7 +251,7 @@ You can unpack any subscription using the ``inspect`` sub-command to see its boi
 
 .. code-block:: bash
 
-   ytdl-sub inspect --config /path/to/config.yaml --match "BBC News" /path/to/subscriptions.yaml
+   ytdl-sub inspect --match "BBC News" /path/to/subscriptions.yaml
 
 This can be utilized for numerous purposes including:
 
@@ -260,4 +260,4 @@ This can be utilized for numerous purposes including:
 * Understanding how subscription syntax translates to preset representation.
 
 The default ``--level`` of inspect will fill in defined variables. Using ``--level original`` will
-present the subscription's raw layout with no fill.
+present the subscription's raw layout with no fill.

pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
 ]
 dependencies = [
-    "yt-dlp[default]==2026.3.17",
+    "yt-dlp[default]==2026.6.9",
     "colorama~=0.4",
     "mergedeep~=1.3",
     "mediafile~=0.12",
@@ -48,7 +48,7 @@ test = [
 ]
 lint = [
     "pylint==4.0.5",
-    "ruff==0.15.10",
+    "ruff==0.15.16",
 ]
 docs = [
     "sphinx>=7,<10",

src/ytdl_sub/script/utils/type_checking.py

@@ -7,8 +7,11 @@ from typing import Callable, List, Optional, Type, TypeVar, Union, get_origin
 
 from ytdl_sub.script.types.resolvable import (
     Argument,
+    Boolean,
     BuiltInFunctionType,
+    Float,
     FutureResolvable,
+    Integer,
     Lambda,
     LambdaReduce,
     LambdaThree,
@@ -248,6 +251,17 @@ class FunctionSpec:
             return l_type
         return None
 
+    def has_sanitized_output(self) -> bool:
+        """
+        Returns
+        -------
+        If this function were to be sanitized, whether it's redundant or not based on its
+        output
+        """
+        return inspect.isclass(self.return_type) and issubclass(
+            self.return_type, (Integer, Float, Boolean)
+        )
+
     @classmethod
     def _to_human_readable_name(cls, python_type: Type[NamedType] | Type[Union[NamedType]]) -> str:
         if is_optional(python_type):

src/ytdl_sub/utils/file_path.py

@@ -51,6 +51,13 @@ class FilePathTruncater:
 
         return f"{file_sub_name}{delimiter}{file_ext}"
 
+    @classmethod
+    def _truncate_directory_name(cls, directory_name: str) -> str:
+        while len(directory_name.encode("utf-8")) > cls._MAX_BASE_FILE_NAME_BYTES:
+            directory_name = directory_name[:-1]
+
+        return directory_name
+
     @classmethod
     def maybe_truncate_file_path(cls, file_path: str) -> str:
         """Turn into a Path, then a string, to get correct directory separators"""
@@ -61,6 +68,30 @@ class FilePathTruncater:
 
         return str(file_path)
 
+    @classmethod
+    def maybe_truncate_file_name_path(cls, file_name_path: str) -> str:
+        """
+        Truncates each component of a relative output file name path. Both the
+        subdirectories (which can be derived from metadata such as the title) and the
+        final file name are truncated if they exceed the OS limit. The file name's
+        extension is always preserved.
+        """
+        parts = Path(file_name_path).parts
+        if not parts:
+            return file_name_path
+
+        *directory_parts, file_name = parts
+
+        truncated_parts = [
+            cls._truncate_directory_name(part) if cls._is_file_name_too_long(part) else part
+            for part in directory_parts
+        ]
+
+        if cls._is_file_name_too_long(file_name):
+            file_name = cls._truncate_file_name(file_name)
+
+        return str(Path(*truncated_parts, file_name))
+
     @classmethod
     def to_native_filepath(cls, file_path: str) -> str:
         """Ensures file paths use the correct separator"""

src/ytdl_sub/utils/script.py

@@ -146,8 +146,7 @@ class ScriptUtils:
             elif isinstance(sub_arg, String):
                 output += CustomFunctions.sanitize(sub_arg).native
             elif isinstance(sub_arg, BuiltInFunction) and (
-                issubclass(sub_arg.function_spec.return_type, (Integer, Float, Boolean))
-                or sub_arg.name == "pad_zero"
+                sub_arg.function_spec.has_sanitized_output() or sub_arg.name == "pad_zero"
             ):
                 # If we know the function's output is sanitized, let's not wrap it
                 output += cls._to_script_code(sub_arg, top_level=True)

src/ytdl_sub/validators/file_path_validators.py

@@ -48,7 +48,7 @@ class StringFormatterFileNameValidator(StringFormatterValidator):
 
     def post_process(self, resolved: str) -> str:
         return FilePathTruncater.to_native_filepath(
-            FilePathTruncater.maybe_truncate_file_path(resolved)
+            FilePathTruncater.maybe_truncate_file_name_path(resolved)
         )
 
 

tests/e2e/cli/test_view.py

@@ -2,12 +2,12 @@ from typing import Optional
 
 import pytest
 from conftest import mock_run_from_cli
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.utils.file_handler import FileMetadata
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestView:
     @pytest.mark.parametrize("split_chapters", [True, False])
     def test_view_from_cli(

tests/e2e/plugins/test_audio_extract.py

@@ -1,7 +1,7 @@
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.subscriptions.subscription import Subscription
 
@@ -47,7 +47,7 @@ def youtube_release_preset_dict(output_directory):
     }
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestAudioExtract:
     @pytest.mark.parametrize("dry_run", [False])
     def test_audio_extract_single_song(

tests/e2e/plugins/test_chapters.py

@@ -3,7 +3,7 @@ from typing import Dict
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.subscriptions.subscription import Subscription
 
@@ -54,7 +54,7 @@ def chapters_from_comments_preset_dict(sponsorblock_and_subs_preset_dict: Dict)
     return sponsorblock_and_subs_preset_dict
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestChapters:
     @pytest.mark.parametrize("dry_run", [True, False])
     def test_chapters_sponsorblock_and_removal_with_subs(

tests/e2e/plugins/test_date_range.py

@@ -5,7 +5,7 @@ import pytest
 from conftest import assert_logs
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.downloaders.ytdlp import YTDLP
 from ytdl_sub.subscriptions.subscription import Subscription
@@ -39,7 +39,7 @@ def rolling_recent_channel_preset_dict(recent_preset_dict):
     )
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestDateRange:
     @pytest.mark.parametrize("dry_run", [True, False])
     @pytest.mark.parametrize("date_range_breaks", [True, False])

tests/e2e/plugins/test_file_convert.py

@@ -1,7 +1,7 @@
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.subscriptions.subscription import Subscription
 
@@ -20,7 +20,7 @@ def preset_dict(output_directory):
     }
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestFileConvert:
     @pytest.mark.parametrize("dry_run", [True, False])
     def test_file_convert(

tests/e2e/plugins/test_match_filters.py

@@ -1,7 +1,7 @@
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.subscriptions.subscription import Subscription
 
@@ -46,7 +46,7 @@ def livestream_preset_dict(output_directory):
     }
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestFileConvert:
     def test_livestreams_download_filtered(
         self,

tests/e2e/plugins/test_split_by_chapters.py

@@ -4,7 +4,7 @@ import mergedeep
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.subscriptions.subscription import Subscription
 from ytdl_sub.utils.exceptions import ValidationException
@@ -58,7 +58,7 @@ def yt_album_as_chapters_with_regex_preset_dict(yt_album_as_chapters_preset_dict
     return yt_album_as_chapters_preset_dict
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestSplitByChapters:
     @pytest.mark.parametrize("dry_run", [True, False])
     def test_video_with_chapters(

tests/e2e/plugins/test_subtitles.py

@@ -1,7 +1,7 @@
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.config.config_file import ConfigFile
 from ytdl_sub.subscriptions.subscription import Subscription
@@ -32,7 +32,7 @@ def test_single_video_subs_embed_and_file_preset_dict(single_video_subs_embed_pr
     return single_video_subs_embed_preset_dict
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestSubtitles:
     def test_subtitle_lang_variable_partial_validates(self, default_config):
         default_config_dict = default_config.as_dict()

tests/e2e/presets/test_bilateral.py

@@ -2,7 +2,7 @@ from typing import Dict
 
 import pytest
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.config.config_file import ConfigFile
 from ytdl_sub.subscriptions.subscription import Subscription
@@ -51,7 +51,7 @@ def tv_show_collection_bilateral_dict(output_directory):
     }
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestBilateral:
     def test_tv_show_by_date_downloads_bilateral(
         self,

tests/e2e/presets/test_soundcloud.py

@@ -4,6 +4,7 @@ import pytest
 from conftest import assert_logs
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.downloaders.ytdlp import YTDLP
 from ytdl_sub.subscriptions.subscription import Subscription
@@ -23,6 +24,7 @@ def subscription_dict(output_directory):
     }
 
 
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="Soundcloud tests cannot run in GH")
 class TestSoundcloudDiscography:
     """
     Downloads my (bad) SC recordings I made. Ensure the above files exist and have the

tests/e2e/youtube/test_channel.py

@@ -3,7 +3,7 @@ from typing import Callable, Dict
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.config.config_file import ConfigFile
 from ytdl_sub.subscriptions.subscription import Subscription
@@ -42,7 +42,7 @@ def channel_preset_dict(output_directory):
     }
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestChannel:
     """
     Downloads my old minecraft youtube channel. Ensure the above files exist and have the

tests/e2e/youtube/test_video.py

@@ -1,7 +1,7 @@
 import pytest
 from expected_download import assert_expected_downloads
 from expected_transaction_log import assert_transaction_log_matches
-from resources import DISABLE_YOUTUBE_TESTS
+from resources import DISABLE_E2E_TESTS
 
 from ytdl_sub.subscriptions.subscription import Subscription
 
@@ -30,7 +30,7 @@ def single_video_preset_dict(output_directory):
     }
 
 
-@pytest.mark.skipif(DISABLE_YOUTUBE_TESTS, reason="YouTube tests cannot run in GH")
+@pytest.mark.skipif(DISABLE_E2E_TESTS, reason="YouTube tests cannot run in GH")
 class TestYoutubeVideo:
     @pytest.mark.parametrize("dry_run", [True, False])
     def test_single_video_download(

tests/resources.py

@@ -4,7 +4,7 @@ import shutil
 from pathlib import Path
 from typing import Dict
 
-DISABLE_YOUTUBE_TESTS: bool = True
+DISABLE_E2E_TESTS: bool = True
 REGENERATE_FIXTURES: bool = False
 
 RESOURCE_PATH: Path = Path("tests") / "resources"

tests/unit/validators/test_file_path_validators.py

@@ -77,6 +77,46 @@ class TestStringFormatterFilePathValidator:
                 assert len(dir_paths) == 1
                 assert Path(truncated_file_path) == dir_paths[0]
 
+    @pytest.mark.parametrize("ext", ["mp4", "-thumb.jpg"])
+    def test_truncates_subdirectory_in_file_name_path(self, ext: str):
+        if "thumb" not in ext:  # do not put . in front of -thumb
+            ext = f".{ext}"
+
+        # Mathematical bold unicode characters are 4 bytes each in UTF-8, so a title used
+        # as a subdirectory can easily exceed the OS file name limit (typically 255 bytes).
+        long_directory = (
+            "[2026] 𝗿𝘁𝗶𝘀𝘁 𝗢𝗻𝗲 - 𝗔 𝗩𝗲𝗿𝘆 𝗟𝗼𝗻𝗴 𝗦𝗼𝗻𝗴 𝗧𝗶𝘁𝗹𝗲 "
+            "𝗧𝗵𝗮𝘁 𝗘𝘅𝗰𝗲𝗲𝗱𝘀 𝗧𝗵𝗲 𝗟𝗶𝗺𝗶𝘁 (𝗘𝘅𝘁𝗲𝗻𝗱𝗲𝗱 𝗠𝗶𝘅 𝘅 "
+            "𝗦𝗲𝗰𝗼𝗻𝗱 𝗔𝗿𝘁𝗶𝘀𝘁 & 𝗧𝗵𝗶𝗿𝗱 𝗔𝗿𝘁𝗶𝘀𝘁)"
+        )
+        # Sanity check that the directory really does exceed the limit
+        assert len(long_directory.encode("utf-8")) > FilePathTruncater._MAX_BASE_FILE_NAME_BYTES
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = str(Path(temp_dir) / long_directory / f"video{ext}")
+
+            formatter = StringFormatterFileNameValidator(name="test", value="")
+            truncated_file_path = formatter.post_process(file_path)
+
+            truncated_directory, truncated_file_name = os.path.split(truncated_file_path)
+            _, truncated_directory_name = os.path.split(truncated_directory)
+
+            # Both the subdirectory and the file name must fit within the OS limit
+            assert (
+                len(truncated_directory_name.encode("utf-8"))
+                <= FilePathTruncater._MAX_BASE_FILE_NAME_BYTES
+            )
+            assert (
+                len(truncated_file_name.encode("utf-8"))
+                <= FilePathTruncater._MAX_BASE_FILE_NAME_BYTES
+            )
+            assert truncated_file_name.endswith(ext)
+
+            # The original bug raised "OSError: [Errno 36] Filename too long" here because
+            # the subdirectory component was never truncated.
+            os.makedirs(truncated_directory, exist_ok=True)
+            assert os.path.isdir(truncated_directory)
+
     @pytest.mark.parametrize(
         "file_name_max_bytes, expected_max",
         [