[cli] Strengthen type guards

Breakthrough · Breakthrough · commit c5084417aff3 · 2026-04-25T01:22:48.000-04:00
diff --git a/scenedetect/_cli/__init__.py b/scenedetect/_cli/__init__.py
@@ -27,14 +27,15 @@
 
 import click
 
-import scenedetect
+import scenedetect as scenedetect_pkg
 import scenedetect._cli.commands as cli_commands
 from scenedetect._cli.config import (
     CHOICE_MAP,
     CONFIG_FILE_PATH,
     CONFIG_MAP,
     DEFAULT_JPG_QUALITY,
     DEFAULT_WEBP_QUALITY,
+    RangeValue,
 )
 from scenedetect._cli.context import USER_CONFIG, CliContext, check_split_video_requirements
 from scenedetect.backends import AVAILABLE_BACKENDS
@@ -47,13 +48,24 @@
 )
 from scenedetect.platform import get_cv2_imwrite_params, get_system_version_info
 
-PROGRAM_VERSION = scenedetect.__version__
+PROGRAM_VERSION = scenedetect_pkg.__version__
 """Used to avoid name conflict with named `scenedetect` command below."""
 
 logger = logging.getLogger("pyscenedetect")
 
 LINE_SEPARATOR = "-" * 72
 
+
+def _click_range(section: str, key: str) -> "click.IntRange | click.FloatRange":
+    """Return a `click` parameter type matching the `RangeValue` at `CONFIG_MAP[section][key]`.
+
+    Used in `@click.option(... type=...)` decorators so each option's bounds and value type are
+    sourced from the canonical `CONFIG_MAP` entry.
+    """
+    val = CONFIG_MAP[section][key]
+    assert isinstance(val, RangeValue), f"Expected RangeValue at {section}/{key}, got {type(val)}"
+    return val.click_range
+
 # About & copyright message string shown for the 'about' CLI command (scenedetect about).
 ABOUT_STRING = """
 Site: http://scenedetect.com/
@@ -375,7 +387,8 @@ def add_hidden_alias(command: click.Command, alias: str):
 def help_command(ctx: click.Context, command_name: str):
     """Print full help reference."""
     # TODO: Other commands still seem to run if this is specified.
-    assert isinstance(ctx.parent.command, click.MultiCommand)
+    assert ctx.parent is not None
+    assert isinstance(ctx.parent.command, click.Group)
     parent_command = ctx.parent.command
     all_commands = set(parent_command.list_commands(ctx))
     if command_name is not None:
@@ -386,11 +399,15 @@ def help_command(ctx: click.Context, command_name: str):
             ]
             raise click.BadParameter("\n".join(error_strs), param_hint="command")
         click.echo("")
-        print_command_help(ctx, parent_command.get_command(ctx, command_name))
+        target = parent_command.get_command(ctx, command_name)
+        assert target is not None
+        print_command_help(ctx, target)
     else:
         click.echo(ctx.parent.get_help())
         for command in sorted(all_commands):
-            print_command_help(ctx, parent_command.get_command(ctx, command))
+            target = parent_command.get_command(ctx, command)
+            assert target is not None
+            print_command_help(ctx, target)
     ctx.exit()
 
 
@@ -509,10 +526,7 @@ def time_command(
     "--threshold",
     "-t",
     metavar="VAL",
-    type=click.FloatRange(
-        CONFIG_MAP["detect-content"]["threshold"].min_val,
-        CONFIG_MAP["detect-content"]["threshold"].max_val,
-    ),
+    type=_click_range("detect-content", "threshold"),
     default=None,
     help='The max difference (0.0 to 255.0) that adjacent frames score must exceed to trigger a cut. Lower values are more sensitive to shot changes. Refers to "content_val" in stats file.{}'.format(
         USER_CONFIG.get_help_string("detect-content", "threshold")
@@ -720,10 +734,7 @@ def detect_adaptive_command(
     "--threshold",
     "-t",
     metavar="VAL",
-    type=click.FloatRange(
-        CONFIG_MAP["detect-threshold"]["threshold"].min_val,
-        CONFIG_MAP["detect-threshold"]["threshold"].max_val,
-    ),
+    type=_click_range("detect-threshold", "threshold"),
     default=None,
     help='Threshold (integer) that frame score must exceed to start a new scene. Refers to "delta_rgb" in stats file.{}'.format(
         USER_CONFIG.get_help_string("detect-threshold", "threshold")
@@ -733,10 +744,7 @@ def detect_adaptive_command(
     "--fade-bias",
     "-f",
     metavar="PERCENT",
-    type=click.FloatRange(
-        CONFIG_MAP["detect-threshold"]["fade-bias"].min_val,
-        CONFIG_MAP["detect-threshold"]["fade-bias"].max_val,
-    ),
+    type=_click_range("detect-threshold", "fade-bias"),
     default=None,
     help="Percent (%) from -100 to 100 of timecode skew of cut placement. -100 indicates the start frame, +100 indicates the end frame, and 0 is the middle of both.{}".format(
         USER_CONFIG.get_help_string("detect-threshold", "fade-bias")
@@ -802,10 +810,7 @@ def detect_threshold_command(
     "--threshold",
     "-t",
     metavar="VAL",
-    type=click.FloatRange(
-        CONFIG_MAP["detect-hist"]["threshold"].min_val,
-        CONFIG_MAP["detect-hist"]["threshold"].max_val,
-    ),
+    type=_click_range("detect-hist", "threshold"),
     default=None,
     help="Max difference (0.0 to 1.0) between histograms of adjacent frames. Lower "
     "values are more sensitive to changes.{}".format(
@@ -816,9 +821,7 @@ def detect_threshold_command(
     "--bins",
     "-b",
     metavar="NUM",
-    type=click.IntRange(
-        CONFIG_MAP["detect-hist"]["bins"].min_val, CONFIG_MAP["detect-hist"]["bins"].max_val
-    ),
+    type=_click_range("detect-hist", "bins"),
     default=None,
     help="The number of bins to use for the histogram calculation.{}".format(
         USER_CONFIG.get_help_string("detect-hist", "bins")
@@ -873,10 +876,7 @@ def detect_hist_command(
     "--threshold",
     "-t",
     metavar="VAL",
-    type=click.FloatRange(
-        CONFIG_MAP["detect-hash"]["threshold"].min_val,
-        CONFIG_MAP["detect-hash"]["threshold"].max_val,
-    ),
+    type=_click_range("detect-hash", "threshold"),
     default=None,
     help=(
         "Max distance between hash values (0.0 to 1.0) of adjacent frames. Lower values are "
@@ -889,9 +889,7 @@ def detect_hist_command(
     "--size",
     "-s",
     metavar="SIZE",
-    type=click.IntRange(
-        CONFIG_MAP["detect-hash"]["size"].min_val, CONFIG_MAP["detect-hash"]["size"].max_val
-    ),
+    type=_click_range("detect-hash", "size"),
     default=None,
     help="Size of square of low frequency data to include from the discrete cosine transform.{}".format(
         USER_CONFIG.get_help_string("detect-hash", "size")
@@ -901,9 +899,7 @@ def detect_hist_command(
     "--lowpass",
     "-l",
     metavar="FRAC",
-    type=click.IntRange(
-        CONFIG_MAP["detect-hash"]["lowpass"].min_val, CONFIG_MAP["detect-hash"]["lowpass"].max_val
-    ),
+    type=_click_range("detect-hash", "lowpass"),
     default=None,
     help=(
         "How much high frequency information to filter from the DCT. 2 means keep lower 1/2 of "
@@ -984,6 +980,8 @@ def load_scenes_command(ctx: click.Context, input: str | None, start_col_name: s
         raise click.ClickException("The load-scenes command cannot be used with detectors.")
     if ctx.load_scenes_input:
         raise click.ClickException("The load-scenes command must only be specified once.")
+    if input is None:
+        raise click.BadParameter("Input file is required.", param_hint="-i/--input")
     input = os.path.abspath(input)
     if not os.path.exists(input):
         raise click.BadParameter(
@@ -1066,6 +1064,7 @@ def save_html_command(
     # to include images.
     include_images = not ctx.config.get_value("save-html", "no-images", no_images)
     if include_images and not ctx.save_images:
+        assert save_images_command.callback is not None
         save_images_command.callback()
     save_html_args = {
         "filename": ctx.config.get_value("save-html", "filename", filename),
@@ -1239,10 +1238,7 @@ def list_scenes_command(
     "-crf",
     metavar="RATE",
     default=None,
-    type=click.IntRange(
-        CONFIG_MAP["split-video"]["rate-factor"].min_val,
-        CONFIG_MAP["split-video"]["rate-factor"].max_val,
-    ),
+    type=_click_range("split-video", "rate-factor"),
     help="Video encoding quality (x264 constant rate factor), from 0-100, where lower is higher quality (larger output). 0 indicates lossless.{}".format(
         USER_CONFIG.get_help_string("split-video", "rate-factor")
     ),
diff --git a/scenedetect/_cli/config.py b/scenedetect/_cli/config.py
@@ -23,6 +23,7 @@
 from configparser import Error as ConfigParserError
 from enum import Enum
 
+import click
 from platformdirs import user_config_dir
 
 from scenedetect.common import FrameTimecode
@@ -124,6 +125,13 @@ def max_val(self) -> int | float:
         """Maximum value of the range."""
         return self._max_val
 
+    @property
+    def click_range(self) -> "click.IntRange | click.FloatRange":
+        """A `click` parameter type matching this range's bounds and value type."""
+        if isinstance(self._value, int):
+            return click.IntRange(int(self._min_val), int(self._max_val))
+        return click.FloatRange(float(self._min_val), float(self._max_val))
+
     @staticmethod
     def from_config(config_value: str, default: "RangeValue") -> "RangeValue":
         try:
@@ -757,9 +765,14 @@ def get_value(
         self,
         command: str,
         option: str,
-        override: ConfigValue | None = None,
-    ) -> ConfigValue:
-        """Get the current setting or default value of the specified command option."""
+        override: ty.Any = None,
+    ) -> ty.Any:
+        """Get the current setting or default value of the specified command option.
+
+        Returns ``ty.Any`` because each (command, option) pair has a known concrete type at
+        the call site, but the union across all options is too wide to be useful as a return
+        annotation. Callers should know the expected type for the option they are reading.
+        """
         assert command in CONFIG_MAP and option in CONFIG_MAP[command]
         if override is not None:
             value = override
diff --git a/scenedetect/_cli/context.py b/scenedetect/_cli/context.py
@@ -133,6 +133,22 @@ def ensure_detector(self):
             (detector_type, detector_args) = self.default_detector
             self.add_detector(detector_type, detector_args)
 
+    def _resolve_min_scene_len(self, command: str, override: str | None) -> int:
+        """Resolve the minimum scene length (in frames) for a `detect-*` command, honoring
+        the `--drop-short-scenes` flag, command-specific config, and global default."""
+        if self.drop_short_scenes:
+            return 0
+        if override is not None:
+            parsed = self.parse_timecode(override)
+            assert parsed is not None
+            return parsed.frame_num
+        if self.config.is_default(command, "min-scene-len"):
+            assert self.min_scene_len is not None
+            return self.min_scene_len.frame_num
+        parsed = self.parse_timecode(self.config.get_value(command, "min-scene-len"))
+        assert parsed is not None
+        return parsed.frame_num
+
     def parse_timecode(self, value: str | None, correct_pts: bool = False) -> FrameTimecode | None:
         """Parses a user input string into a FrameTimecode assuming the given framerate. If `value`
         is None it will be passed through without processing.
@@ -328,18 +344,7 @@ def get_detect_content_params(
         filter_mode: str | None = None,
     ) -> dict[str, ty.Any]:
         """Get a dict containing user options to construct a ContentDetector with."""
-        if self.drop_short_scenes:
-            min_scene_len = 0
-        else:
-            if min_scene_len is None:
-                if self.config.is_default("detect-content", "min-scene-len"):
-                    assert self.min_scene_len is not None
-                    min_scene_len = self.min_scene_len.frame_num
-                else:
-                    min_scene_len = self.config.get_value("detect-content", "min-scene-len")
-            parsed = self.parse_timecode(min_scene_len)
-            assert parsed is not None
-            min_scene_len = parsed.frame_num
+        min_scene_len_frames = self._resolve_min_scene_len("detect-content", min_scene_len)
 
         if weights is not None:
             try:
@@ -354,7 +359,7 @@ def get_detect_content_params(
             "weights": self.config.get_value("detect-content", "weights", weights),
             "kernel_size": self.config.get_value("detect-content", "kernel-size", kernel_size),
             "luma_only": luma_only or self.config.get_value("detect-content", "luma-only"),
-            "min_scene_len": min_scene_len,
+            "min_scene_len": min_scene_len_frames,
             "threshold": self.config.get_value("detect-content", "threshold", threshold),
             "filter_mode": self.config.get_value("detect-content", "filter-mode", filter_mode),
         }
@@ -371,18 +376,7 @@ def get_detect_adaptive_params(
     ) -> dict[str, ty.Any]:
         """Handle detect-adaptive command options and return args to construct one with."""
 
-        if self.drop_short_scenes:
-            min_scene_len = 0
-        else:
-            if min_scene_len is None:
-                if self.config.is_default("detect-adaptive", "min-scene-len"):
-                    assert self.min_scene_len is not None
-                    min_scene_len = self.min_scene_len.frame_num
-                else:
-                    min_scene_len = self.config.get_value("detect-adaptive", "min-scene-len")
-            parsed = self.parse_timecode(min_scene_len)
-            assert parsed is not None
-            min_scene_len = parsed.frame_num
+        min_scene_len_frames = self._resolve_min_scene_len("detect-adaptive", min_scene_len)
 
         if weights is not None:
             try:
@@ -400,7 +394,7 @@ def get_detect_adaptive_params(
             "min_content_val": self.config.get_value(
                 "detect-adaptive", "min-content-val", min_content_val
             ),
-            "min_scene_len": min_scene_len,
+            "min_scene_len": min_scene_len_frames,
             "window_width": self.config.get_value("detect-adaptive", "frame-window", frame_window),
         }
 
@@ -413,24 +407,13 @@ def get_detect_threshold_params(
     ) -> dict[str, ty.Any]:
         """Handle detect-threshold command options and return args to construct one with."""
 
-        if self.drop_short_scenes:
-            min_scene_len = 0
-        else:
-            if min_scene_len is None:
-                if self.config.is_default("detect-threshold", "min-scene-len"):
-                    assert self.min_scene_len is not None
-                    min_scene_len = self.min_scene_len.frame_num
-                else:
-                    min_scene_len = self.config.get_value("detect-threshold", "min-scene-len")
-            parsed = self.parse_timecode(min_scene_len)
-            assert parsed is not None
-            min_scene_len = parsed.frame_num
+        min_scene_len_frames = self._resolve_min_scene_len("detect-threshold", min_scene_len)
         # TODO(v1.0): add_last_scene cannot be disabled right now.
         return {
             "add_final_scene": add_last_scene
             or self.config.get_value("detect-threshold", "add-last-scene"),
             "fade_bias": self.config.get_value("detect-threshold", "fade-bias", fade_bias),
-            "min_scene_len": min_scene_len,
+            "min_scene_len": min_scene_len_frames,
             "threshold": self.config.get_value("detect-threshold", "threshold", threshold),
         }
 
@@ -442,21 +425,10 @@ def get_detect_hist_params(
     ) -> dict[str, ty.Any]:
         """Handle detect-hist command options and return args to construct one with."""
 
-        if self.drop_short_scenes:
-            min_scene_len = 0
-        else:
-            if min_scene_len is None:
-                if self.config.is_default("detect-hist", "min-scene-len"):
-                    assert self.min_scene_len is not None
-                    min_scene_len = self.min_scene_len.frame_num
-                else:
-                    min_scene_len = self.config.get_value("detect-hist", "min-scene-len")
-            parsed = self.parse_timecode(min_scene_len)
-            assert parsed is not None
-            min_scene_len = parsed.frame_num
+        min_scene_len_frames = self._resolve_min_scene_len("detect-hist", min_scene_len)
         return {
             "bins": self.config.get_value("detect-hist", "bins", bins),
-            "min_scene_len": min_scene_len,
+            "min_scene_len": min_scene_len_frames,
             "threshold": self.config.get_value("detect-hist", "threshold", threshold),
         }
 
@@ -469,21 +441,10 @@ def get_detect_hash_params(
     ) -> dict[str, ty.Any]:
         """Handle detect-hash command options and return args to construct one with."""
 
-        if self.drop_short_scenes:
-            min_scene_len = 0
-        else:
-            if min_scene_len is None:
-                if self.config.is_default("detect-hash", "min-scene-len"):
-                    assert self.min_scene_len is not None
-                    min_scene_len = self.min_scene_len.frame_num
-                else:
-                    min_scene_len = self.config.get_value("detect-hash", "min-scene-len")
-            parsed = self.parse_timecode(min_scene_len)
-            assert parsed is not None
-            min_scene_len = parsed.frame_num
+        min_scene_len_frames = self._resolve_min_scene_len("detect-hash", min_scene_len)
         return {
             "lowpass": self.config.get_value("detect-hash", "lowpass", lowpass),
-            "min_scene_len": min_scene_len,
+            "min_scene_len": min_scene_len_frames,
             "size": self.config.get_value("detect-hash", "size", size),
             "threshold": self.config.get_value("detect-hash", "threshold", threshold),
         }
diff --git a/scenedetect/common.py b/scenedetect/common.py
