[api] Upgrade deprecation logs to warnings

Author: Breakthrough

README.md

@@ -66,8 +66,8 @@ scene_list = detect('my_video.mp4', ContentDetector())
 for i, scene in enumerate(scene_list):
     print('    Scene %2d: Start %s / Frame %d, End %s / Frame %d' % (
         i+1,
-        scene[0].get_timecode(), scene[0].get_frames(),
-        scene[1].get_timecode(), scene[1].get_frames(),))
+        scene[0].get_timecode(), scene[0].frame_num,
+        scene[1].get_timecode(), scene[1].frame_num,))
 ```
 
 We can also split the video into each scene if `ffmpeg` is installed (`mkvmerge` is also supported):

scenedetect/_cli/commands.py

@@ -158,9 +158,9 @@ def list_scenes(
                     " |  %5d  | %11d | %s | %11d | %s |"
                     % (
                         i + 1,
-                        start_time.get_frames() + 1,
+                        start_time.frame_num + 1,
                         start_time.get_timecode(),
-                        end_time.get_frames(),
+                        end_time.frame_num,
                         end_time.get_timecode(),
                     )
                     for i, (start_time, end_time) in enumerate(scenes)
@@ -278,11 +278,11 @@ def save_edl(
     # Converts FrameTimecode to HH:MM:SS:FF
     # TODO: This should be part of the FrameTimecode object itself.
     def get_edl_timecode(timecode: FrameTimecode):
-        total_seconds = timecode.get_seconds()
+        total_seconds = timecode.seconds
         hours = int(total_seconds // 3600)
         minutes = int((total_seconds % 3600) // 60)
         seconds = int(total_seconds % 60)
-        frames_part = int((total_seconds * timecode.get_framerate()) % timecode.get_framerate())
+        frames_part = int((total_seconds * timecode.framerate) % timecode.framerate)
         return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames_part:02d}"
 
     edl_content = []
@@ -331,7 +331,7 @@ def _save_xml_fcpx(
 
     # TODO: We should calculate duration from the scene list.
     duration = context.video_stream.duration
-    duration = str(duration.get_seconds()) + "s"  # TODO: Is float okay here?
+    duration = str(duration.seconds) + "s"  # TODO: Is float okay here?
     path = Path(context.video_stream.path).absolute()
     ElementTree.SubElement(
         resources,
@@ -355,8 +355,8 @@ def _save_xml_fcpx(
     spine = ElementTree.SubElement(sequence, "spine")
 
     for i, (start, end) in enumerate(scenes):
-        start_seconds = start.get_seconds()
-        duration_seconds = (end - start).get_seconds()
+        start_seconds = start.seconds
+        duration_seconds = (end - start).seconds
         clip = ElementTree.SubElement(
             spine,
             "clip",
@@ -402,7 +402,7 @@ def _save_xml_fcp(
     ElementTree.SubElement(sequence, "name").text = context.video_stream.name
 
     duration = scenes[-1][1] - scenes[0][0]
-    ElementTree.SubElement(sequence, "duration").text = f"{duration.get_frames()}"
+    ElementTree.SubElement(sequence, "duration").text = f"{duration.frame_num}"
 
     rate = ElementTree.SubElement(sequence, "rate")
     ElementTree.SubElement(rate, "timebase").text = str(context.video_stream.frame_rate)
@@ -430,10 +430,10 @@ def _save_xml_fcp(
             ElementTree.fromstring(f"<timebase>{context.video_stream.frame_rate}</timebase>")
         )
         # TODO: Are these supposed to be frame numbers or another format?
-        ElementTree.SubElement(clip, "start").text = str(start.get_frames())
-        ElementTree.SubElement(clip, "end").text = str(end.get_frames())
-        ElementTree.SubElement(clip, "in").text = str(start.get_frames())
-        ElementTree.SubElement(clip, "out").text = str(end.get_frames())
+        ElementTree.SubElement(clip, "start").text = str(start.frame_num)
+        ElementTree.SubElement(clip, "end").text = str(end.frame_num)
+        ElementTree.SubElement(clip, "in").text = str(start.frame_num)
+        ElementTree.SubElement(clip, "out").text = str(end.frame_num)
 
         file_ref = ElementTree.SubElement(clip, "file", id=f"file{i + 1}")
         ElementTree.SubElement(file_ref, "name").text = context.video_stream.name
@@ -534,12 +534,12 @@ def save_otio(
                                 "duration": {
                                     "OTIO_SCHEMA": "RationalTime.1",
                                     "rate": frame_rate,
-                                    "value": float((end - start).get_frames()),
+                                    "value": float((end - start).frame_num),
                                 },
                                 "start_time": {
                                     "OTIO_SCHEMA": "RationalTime.1",
                                     "rate": frame_rate,
-                                    "value": float(start.get_frames()),
+                                    "value": float(start.frame_num),
                                 },
                             },
                             "enabled": True,

scenedetect/_cli/config.py

@@ -297,11 +297,11 @@ class TimecodeFormat(Enum):
 
     def format(self, timecode: FrameTimecode) -> str:
         if self == TimecodeFormat.FRAMES:
-            return str(timecode.get_frames())
+            return str(timecode.frame_num)
         if self == TimecodeFormat.TIMECODE:
             return timecode.get_timecode()
         if self == TimecodeFormat.SECONDS:
-            return "%.3f" % timecode.get_seconds()
+            return "%.3f" % timecode.seconds
         raise RuntimeError("Unhandled format specifier.")
 
 

scenedetect/_cli/controller.py

@@ -68,7 +68,7 @@ def run_scenedetect(context: CliContext):
             logger.info(
                 "Detected %d scenes, average shot length %.1f seconds.",
                 len(scenes),
-                sum([(end_time - start_time).get_seconds() for start_time, end_time in scenes])
+                sum([(end_time - start_time).seconds for start_time, end_time in scenes])
                 / float(len(scenes)),
             )
         else:
@@ -106,7 +106,7 @@ def _detect(context: CliContext) -> ty.Optional[ty.Tuple[SceneList, CutList]]:
             logger.critical(
                 "Failed to seek to %s / frame %d: %s",
                 context.start_time.get_timecode(),
-                context.start_time.get_frames(),
+                context.start_time.frame_num,
                 str(ex),
             )
             return None

scenedetect/backends/moviepy.py

@@ -143,7 +143,7 @@ def position_ms(self) -> float:
         The first frame has a time of 0.0 ms.
 
         This method will always return 0.0 if no frames have been `read`."""
-        return self.position.get_seconds() * 1000.0
+        return self.position.seconds * 1000.0
 
     @property
     def frame_number(self) -> int:
@@ -176,7 +176,7 @@ def seek(self, target: ty.Union[FrameTimecode, float, int]):
         if not isinstance(target, FrameTimecode):
             target = FrameTimecode(target, self.frame_rate)
         try:
-            self._last_frame = self._reader.get_frame(target.get_seconds())
+            self._last_frame = self._reader.get_frame(target.seconds)
             if hasattr(self._reader, "last_read") and target >= self.duration:
                 raise SeekError("MoviePy > 2.0 does not have proper EOF semantics (#461).")
             self._frame_number = min(

scenedetect/backends/opencv.py

@@ -20,6 +20,7 @@
 import math
 import os.path
 import typing as ty
+import warnings
 from fractions import Fraction
 from logging import getLogger
 
@@ -89,9 +90,12 @@ def __init__(
             ValueError: specified framerate is invalid
         """
         super().__init__()
-        # TODO(v0.7): Replace with DeprecationWarning that `path_or_device` will be removed in v0.8.
         if path_or_device is not None:
-            logger.error("path_or_device is deprecated, use path or VideoCaptureAdapter instead.")
+            warnings.warn(
+                "The `path_or_device` argument is deprecated, use `path` or `VideoCaptureAdapter` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             path = path_or_device
         if path is None:
             raise ValueError("Path must be specified!")
@@ -224,7 +228,7 @@ def seek(self, target: ty.Union[FrameTimecode, float, int]):
 
         # Have to seek one behind and call grab() after to that the VideoCapture
         # returns a valid timestamp when using CAP_PROP_POS_MSEC.
-        target_frame_cv2 = (self.base_timecode + target).get_frames()
+        target_frame_cv2 = (self.base_timecode + target).frame_num
         if target_frame_cv2 > 0:
             target_frame_cv2 -= 1
         self._cap.set(cv2.CAP_PROP_POS_FRAMES, target_frame_cv2)

scenedetect/backends/pyav.py

@@ -252,7 +252,7 @@ def seek(self, target: ty.Union[FrameTimecode, float, int]) -> None:
         if target >= 1:
             target = target - 1
         target_pts = self._video_stream.start_time + int(
-            (self.base_timecode + target).get_seconds() / self._video_stream.time_base
+            (self.base_timecode + target).seconds / self._video_stream.time_base
         )
         self._frame = None
         self._container.seek(target_pts, stream=self._video_stream)

scenedetect/common.py

@@ -63,6 +63,7 @@
 
 import math
 import typing as ty
+import warnings
 from dataclasses import dataclass
 from enum import Enum
 from fractions import Fraction
@@ -220,28 +221,32 @@ def frame_num(self) -> ty.Optional[int]:
     def framerate(self) -> ty.Optional[int]:
         return self._framerate
 
-    # TODO(v0.7): Mark this as deprecated (use frame_num instead).
     def get_frames(self) -> int:
-        """Get the current time/position in number of frames.  This is the
-        equivalent of accessing the self.frame_num property (which, along
-        with the specified framerate, forms the base for all of the other
-        time measurement calculations, e.g. the :meth:`get_seconds` method).
+        """[DEPRECATED] Get the current time/position in number of frames.
 
-        If using to compare a :class:`FrameTimecode` with a frame number,
-        you can do so directly against the object (e.g. ``FrameTimecode(10, 10.0) <= 10``).
+        Use the `frame_num` property instead.
 
-        Returns:
-            int: The current time in frames (the current frame number).
+        :meta private:
         """
+        warnings.warn(
+            "get_frames() is deprecated, use the `frame_num` property instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.frame_num
 
-    # TODO(v0.7): Mark this as deprecated (use framerate instead).
     def get_framerate(self) -> float:
-        """Get Framerate: Returns the framerate used by the FrameTimecode object.
+        """[DEPRECATED] Get Framerate: Returns the framerate used by the FrameTimecode object.
 
-        Returns:
-            float: Framerate of the current FrameTimecode object, in frames per second.
+        Use the `framerate` property instead.
+
+        :meta private:
         """
+        warnings.warn(
+            "get_framerate() is deprecated, use the `framerate` property instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.framerate
 
     # TODO(v0.7): Figure out how to deal with VFR here.
@@ -258,20 +263,33 @@ def equal_framerate(self, fps) -> bool:
         # TODO(v0.7): Support this comparison in the case FPS is not set but a timecode is.
         return math.fabs(self.framerate - fps) < MAX_FPS_DELTA
 
-    # TODO(v0.7): Add a `seconds` property to replace this and deprecate the existing one.
+    @property
+    def seconds(self) -> float:
+        """The frame's position in number of seconds."""
+        if self._timecode:
+            return self._timecode.seconds
+        # Assume constant framerate if we don't have timing information.
+        return float(self._frame_num) / self._framerate
+
     def get_seconds(self) -> float:
-        """Get the frame's position in number of seconds.
+        """[DEPRECATED] Get the frame's position in number of seconds.
+
+        Use the `seconds` property instead.
 
         If using to compare a :class:`FrameTimecode` with a frame number,
         you can do so directly against the object (e.g. ``FrameTimecode(10, 10.0) <= 1.0``).
 
         Returns:
             float: The current time/position in seconds.
+
+        :meta private:
         """
-        if self._timecode:
-            return self._timecode.seconds
-        # Assume constant framerate if we don't have timing information.
-        return float(self._frame_num) / self._framerate
+        warnings.warn(
+            "get_seconds() is deprecated, use the `seconds` property instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.seconds
 
     def get_timecode(self, precision: int = 3, use_rounding: bool = True) -> str:
         """Get a formatted timecode string of the form HH:MM:SS[.nnn].
@@ -285,7 +303,7 @@ def get_timecode(self, precision: int = 3, use_rounding: bool = True) -> str:
             str: The current time in the form ``"HH:MM:SS[.nnn]"``.
         """
         # Compute hours and minutes based off of seconds, and update seconds.
-        secs = self.get_seconds()
+        secs = self.seconds
         hrs = int(secs / _SECONDS_PER_HOUR)
         secs -= hrs * _SECONDS_PER_HOUR
         mins = int(secs / _SECONDS_PER_MINUTE)
@@ -438,7 +456,7 @@ def __eq__(self, other: ty.Union[int, float, str, "FrameTimecode"]) -> "FrameTim
         if isinstance(other, int):
             return self._frame_num == other
         elif isinstance(other, float):
-            return self.get_seconds() == other
+            return self.seconds == other
         elif isinstance(other, str):
             return self._frame_num == self._parse_timecode_string(other)
         elif isinstance(other, FrameTimecode):
@@ -462,7 +480,7 @@ def __lt__(self, other: ty.Union[int, float, str, "FrameTimecode"]) -> bool:
         if isinstance(other, int):
             return self._frame_num < other
         elif isinstance(other, float):
-            return self.get_seconds() < other
+            return self.seconds < other
         elif isinstance(other, str):
             return self._frame_num < self._parse_timecode_string(other)
         elif isinstance(other, FrameTimecode):
@@ -481,7 +499,7 @@ def __le__(self, other: ty.Union[int, float, str, "FrameTimecode"]) -> bool:
         if isinstance(other, int):
             return self._frame_num <= other
         elif isinstance(other, float):
-            return self.get_seconds() <= other
+            return self.seconds <= other
         elif isinstance(other, str):
             return self._frame_num <= self._parse_timecode_string(other)
         elif isinstance(other, FrameTimecode):
@@ -500,7 +518,7 @@ def __gt__(self, other: ty.Union[int, float, str, "FrameTimecode"]) -> bool:
         if isinstance(other, int):
             return self._frame_num > other
         elif isinstance(other, float):
-            return self.get_seconds() > other
+            return self.seconds > other
         elif isinstance(other, str):
             return self._frame_num > self._parse_timecode_string(other)
         elif isinstance(other, FrameTimecode):
@@ -519,7 +537,7 @@ def __ge__(self, other: ty.Union[int, float, str, "FrameTimecode"]) -> bool:
         if isinstance(other, int):
             return self._frame_num >= other
         elif isinstance(other, float):
-            return self.get_seconds() >= other
+            return self.seconds >= other
         elif isinstance(other, str):
             return self._frame_num >= self._parse_timecode_string(other)
         elif isinstance(other, FrameTimecode):
@@ -541,7 +559,7 @@ def __int__(self) -> int:
         return self._frame_num
 
     def __float__(self) -> float:
-        return self.get_seconds()
+        return self.seconds
 
     def __str__(self) -> str:
         return self.get_timecode()

scenedetect/detectors/threshold_detector.py

@@ -16,6 +16,7 @@
 """
 
 import typing as ty
+import warnings
 from enum import Enum
 from logging import getLogger
 
@@ -68,9 +69,12 @@ def __init__(
             method: How to treat `threshold` when detecting fade events.
             block_size: [DEPRECATED] DO NOT USE. For backwards compatibility.
         """
-        # TODO(v0.7): Replace with DeprecationWarning that `block_size` will be removed in v0.8.
         if block_size is not None:
-            logger.error("block_size is deprecated.")
+            warnings.warn(
+                "The `block_size` argument is deprecated and will be removed in v0.8.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
         super().__init__()
         self.threshold = int(threshold)