[api] Add backwards compat. helpers to avoid breaking imports

Author: Breakthrough

scenedetect/frame_timecode.py

@@ -0,0 +1,22 @@
+#
+#            PySceneDetect: Python-Based Video Scene Detector
+#   -------------------------------------------------------------------
+#     [  Site:    https://scenedetect.com                           ]
+#     [  Docs:    https://scenedetect.com/docs/                     ]
+#     [  Github:  https://github.com/Breakthrough/PySceneDetect/    ]
+#
+# Copyright (C) 2014-2025 Brandon Castellano <http://www.bcastell.com>.
+# PySceneDetect is licensed under the BSD 3-Clause License; see the
+# included LICENSE file, or visit one of the above pages for details.
+#
+"""DEPRECATED"""
+
+import warnings
+
+warnings.warn(
+    "The `frame_timecode` submodule is deprecated, import from the base package instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from scenedetect.common import *  # noqa: E402, F403

scenedetect/scene_detector.py

@@ -0,0 +1,22 @@
+#
+#            PySceneDetect: Python-Based Video Scene Detector
+#   -------------------------------------------------------------------
+#     [  Site:    https://scenedetect.com                           ]
+#     [  Docs:    https://scenedetect.com/docs/                     ]
+#     [  Github:  https://github.com/Breakthrough/PySceneDetect/    ]
+#
+# Copyright (C) 2014-2025 Brandon Castellano <http://www.bcastell.com>.
+# PySceneDetect is licensed under the BSD 3-Clause License; see the
+# included LICENSE file, or visit one of the above pages for details.
+#
+"""DEPRECATED"""
+
+import warnings
+
+warnings.warn(
+    "The `scene_detector` submodule is deprecated, import from the base package instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from scenedetect.detector import *  # noqa: E402, F403

scenedetect/scene_manager.py

@@ -95,6 +95,9 @@ def on_new_scene(frame_img: numpy.ndarray, frame_num: int):
     SceneList,
 )
 from scenedetect.detector import SceneDetector
+
+# TODO(v0.8): Remove the import * below, for backwards compatibility with v0.6 only.
+from scenedetect.output import *  # noqa: F403
 from scenedetect.platform import tqdm
 from scenedetect.stats_manager import StatsManager
 from scenedetect.video_stream import VideoStream

scenedetect/video_splitter.py

@@ -0,0 +1,22 @@
+#
+#            PySceneDetect: Python-Based Video Scene Detector
+#   -------------------------------------------------------------------
+#     [  Site:    https://scenedetect.com                           ]
+#     [  Docs:    https://scenedetect.com/docs/                     ]
+#     [  Github:  https://github.com/Breakthrough/PySceneDetect/    ]
+#
+# Copyright (C) 2014-2025 Brandon Castellano <http://www.bcastell.com>.
+# PySceneDetect is licensed under the BSD 3-Clause License; see the
+# included LICENSE file, or visit one of the above pages for details.
+#
+"""DEPRECATED"""
+
+import warnings
+
+warnings.warn(
+    "The `video_splitter` submodule is deprecated, import from the base package instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from scenedetect.output.video import *  # noqa: E402, F403

tests/test_detectors.py

@@ -224,3 +224,12 @@ def test_detectors_with_stats(test_video_file):
         scene_manager.detect_scenes(video=video, end_time=end_time)
         scene_list = scene_manager.get_scene_list()
         assert len(scene_list) == initial_scene_len
+
+
+# TODO(v0.8): Remove this test during the removal of `scenedetect.scene_detector`.
+def test_deprecated_detector_module_emits_warning_on_import():
+    SCENE_DETECTOR_WARNING = (
+        "The `scene_detector` submodule is deprecated, import from the base package instead."
+    )
+    with pytest.warns(DeprecationWarning, match=SCENE_DETECTOR_WARNING):
+        from scenedetect.scene_detector import SceneDetector as _

tests/test_output.py

@@ -191,3 +191,12 @@ def test_save_images_zero_width_scene(test_video_file, tmp_path: Path):
             total_images += 1
 
     assert total_images == len([path for path in tmp_path.glob(image_name_glob)])
+
+
+# TODO(v0.8): Remove this test during the removal of `scenedetect.video_splitter`.
+def test_deprecated_output_modules_emits_warning_on_import():
+    VIDEO_SPLITTER_WARNING = (
+        "The `video_splitter` submodule is deprecated, import from the base package instead."
+    )
+    with pytest.warns(DeprecationWarning, match=VIDEO_SPLITTER_WARNING):
+        from scenedetect.video_splitter import split_video_ffmpeg as _

tests/test_timecode.py

@@ -300,3 +300,12 @@ def test_precision():
     assert FrameTimecode(990, fps).get_timecode(precision=1, use_rounding=False) == "00:00:00.9"
     assert FrameTimecode(990, fps).get_timecode(precision=0, use_rounding=True) == "00:00:01"
     assert FrameTimecode(990, fps).get_timecode(precision=0, use_rounding=False) == "00:00:00"
+
+
+# TODO(v0.8): Remove this test during the removal of `scenedetect.scene_detector`.
+def test_deprecated_timecode_module_emits_warning_on_import():
+    FRAME_TIMECODE_WARNING = (
+        "The `frame_timecode` submodule is deprecated, import from the base package instead."
+    )
+    with pytest.warns(DeprecationWarning, match=FRAME_TIMECODE_WARNING):
+        from scenedetect.frame_timecode import FrameTimecode as _

website/pages/changelog.md

@@ -685,30 +685,28 @@ Although there have been minimal changes to most API examples, there are several
 
 #### Breaking
 
-> Note: Imports that break when upgrading to 0.7 can usually be resolved by importing from `scenedetect` directly, rather than a submodule. The package structure has changed significantly in 0.7.
-
  * Replace `frame_num` parameter (`int`) with `timecode` (`FrameTimecode`) in `SceneDetector` interface (#168)[https://github.com/Breakthrough/PySceneDetect/issues/168]:
       * The detector interface: `SceneDetector.process_frame()` and `SceneDetector.post_process()`
       * Statistics: `StatsManager.get_metrics()`, `StatsManager.set_metrics()`, and `StatsManager.metrics_exist()`
  * Move existing functionality to new submodules:
-      * `scenedetect.scene_detector` moved to `scenedetect.detector`
-      * `scenedetect.frame_timecode` moved to `scenedetect.common`
-      * Output functionality from `scenedetect.scene_manager` moved to `scenedetect.output` [#463](https://github.com/Breakthrough/PySceneDetect/issues/463)
+      * Detector interface in `scenedetect.scene_detector` moved to `scenedetect.detector`
+      * Timecode types in `scenedetect.frame_timecode` moved to `scenedetect.common`
+      * Image/HTML/CSV export in `scenedetect.scene_manager` moved to `scenedetect.output` [#463](https://github.com/Breakthrough/PySceneDetect/issues/463)
       * `scenedetect.video_splitter` moved to `scenedetect.output.video` [#463](https://github.com/Breakthrough/PySceneDetect/issues/463)
  * Remove deprecated module `scenedetect.video_manager`, use [the `scenedetect.open_video()` function](https://www.scenedetect.com/docs/head/api.html#scenedetect.open_video) instead
  * Remove deprecated parameter `base_timecode` from various functions, there is no need to provide it
  * Remove deprecated parameter `video_manager` from various functions, use `video` parameter instead
  * `FrameTimecode` fields `frame_num` and `framerate` are now read-only properties, construct a new `FrameTimecode` to change them
  * Remove `FrameTimecode.previous_frame()` method
- * Remove `SceneDetector.is_processing_required()` method, already had no effect in v0.6 as part of deprecation
+ * Remove `SceneDetector.is_processing_required()` method
  * `SceneDetector` instances can now assume they always have frame data to process when `process_frame` is called
  * Remove deprecated `SparseSceneDetector` interface
  * Remove deprecated `SceneManager.get_event_list()` method
- * Remove deprecated `AdaptiveDetector.get_content_val()` method (the same information can be obtained using a `StatsManager`)
- * Remove deprecated `AdaptiveDetector` constructor argument `min_delta_hsv` (use `min_content_val` instead)
- * Remove `advance` parameter from `VideoStream.read()` (was always set to `True`, callers should handle caching frames now if required)
- * Remove `SceneDetector.stats_manager_required` property as it is no longer required
- * Remove `SceneDetector` is now a Python abstract class (`abc.ABC`) but all method names remain the same
+ * Remove deprecated `AdaptiveDetector.get_content_val()` method (use `StatsManager` instead)
+ * Remove deprecated `AdaptiveDetector` constructor arg `min_delta_hsv` (use `min_content_val` instead)
+ * Remove `advance` parameter from `VideoStream.read()`
+ * Remove `SceneDetector.stats_manager_required` property, no longer required
+ * `SceneDetector` is now a [Python abstract class](https://docs.python.org/3/library/abc.html)
 
  #### General