yta-video-frame-time 0.0.16__py3-none-any.whl → 0.0.17__py3-none-any.whl

yta_video_frame_time/interval.py

@@ -14,7 +14,7 @@ Number = Union[int, float, Fraction]
 """
 Custom type to represent numbers.
 """
-TimeIntervalType = Union['TimeInterval', tuple[float, float]]
+TimeIntervalType = Union['NewTimeInterval', tuple[float, float]]
 """
 The type we accept as time interval, that could be a
 tuple we transform into a time interval.
@@ -765,8 +765,8 @@ class NewTimeInterval:
         A copy of this instance.
         """
         time_interval = NewTimeInterval(
-            start = self.start,
-            end = self.end,
+            start = self.original_start,
+            end = self.original_end,
             fps = self.fps
         )
         
@@ -793,6 +793,16 @@ class NewTimeInterval:
         is capable of cutting time intervals.
         """
         return TimeIntervalCutter
+    
+    @property
+    def extender(
+        self
+    ) -> 'TimeIntervalExtender':
+        """
+        Shortcut to the static class `TimeIntervalExtender` that
+        is capable of extending time intervals.
+        """
+        return TimeIntervalExtender
 
     def __init__(
         self,
@@ -856,29 +866,6 @@ class NewTimeInterval:
         The current `end` value of this time interval.
         """
 
-    # TODO: Is this that necessary (?)
-    def _validate_t(
-        self,
-        t: Number,
-        do_include_start: bool = False,
-        do_include_end: bool = False
-    ) -> None:
-        """
-        Validate that the provided `t` value is between the `start`
-        and the `end` parameters provided, including them or not
-        according to the boolean parameters provided.
-        """
-        # TODO: Maybe we should validate also according to the
-        # original values
-        ParameterValidator.validate_mandatory_number_between(
-            name = 't',
-            value = t,
-            lower_limit = self.start,
-            upper_limit = self.end,
-            do_include_lower_limit = do_include_start,
-            do_include_upper_limit = do_include_end
-        )
-
     """
     Apparently, the professional video editors use always
     the `truncate` method to obtain the `start` of the
@@ -1047,8 +1034,7 @@ class NewTimeInterval:
     # TODO: Rename, please
     def get_trim_starts(
         self,
-        t_variation: Number,
-        limit: Union[Number, None] = None
+        t_variation: Number
     ) -> tuple['NewTimeInterval', 'NewTimeInterval']:
         """
         Get a tuple containing the 2 new `TimeInterval` instances
@@ -1073,15 +1059,13 @@ class NewTimeInterval:
         return self.cutter.trim_start(
             time_interval = self,
             # TODO: maybe a 'decorator' to do this '_truncate' (?)
-            t_variation = self._truncate(t_variation),
-            limit = limit
+            t_variation = self._truncate(t_variation)
         )
     
     # TODO: Rename, please
     def get_trim_start(
         self,
-        t_variation: Number,
-        limit: Union[Number, None] = None
+        t_variation: Number
     ) -> 'NewTimeInterval':
         """
         Get this time interval instance but trimmed from the `start`
@@ -1096,14 +1080,12 @@ class NewTimeInterval:
         returns a new one.
         """
         return self.get_trim_starts(
-            t_variation = t_variation,
-            limit = limit
+            t_variation = t_variation
         )[1]
     
-    def trim_start(
+    def _trim_start(
         self,
-        t_variation: Number,
-        limit: Union[Number, None] = None
+        t_variation: Number
     ) -> 'NewTimeInterval':
         """
         (!) This method will modify this instance.
@@ -1115,8 +1097,7 @@ class NewTimeInterval:
         This method returns this same instance but modified.
         """
         cut = self.get_trim_start(
-            t_variation = t_variation,
-            limit = limit
+            t_variation = t_variation
         )
 
         self.start = cut.start
@@ -1149,18 +1130,18 @@ class NewTimeInterval:
         The `t_variation` must be a positive value, the amount of
         seconds to be trimmed.
         """
+        ParameterValidator.validate_number_between('limit', limit, self.start, self.original_end)
+
         return self.cutter.trim_end(
             time_interval = self,
             # TODO: maybe a 'decorator' to do this '_truncate' (?)
-            t_variation = self._truncate(t_variation),
-            limit = limit
+            t_variation = self._truncate(t_variation)
         )
     
     # TODO: Rename, please
     def get_trim_end(
         self,
-        t_variation: Number,
-        limit: Union[Number, None] = None
+        t_variation: Number
     ) -> 'NewTimeInterval':
         """
         Get this time interval instance but trimmed from the `end`
@@ -1175,14 +1156,12 @@ class NewTimeInterval:
         returns a new one.
         """
         return self.get_trim_ends(
-            t_variation = t_variation,
-            limit = limit
+            t_variation = t_variation
         )[0]
     
-    def trim_end(
+    def _trim_end(
         self,
-        t_variation: Number,
-        limit: Union[Number, None] = None
+        t_variation: Number
     ) -> 'NewTimeInterval':
         """
         (!) This method will modify this instance.
@@ -1194,8 +1173,7 @@ class NewTimeInterval:
         This method returns this same instance but modified.
         """
         cut = self.get_trim_end(
-            t_variation = t_variation,
-            limit = limit
+            t_variation = t_variation
         )
 
         self.start = cut.start
@@ -1268,6 +1246,186 @@ class NewTimeInterval:
             split_left, split_right
         )
     
+    def _extend_end(
+        self,
+        t_variation: Number
+    ) -> 'NewTimeInterval':
+        """
+        (!) This method will modify this instance.
+
+        Transform this time interval into a new one in which
+        the `end` has been extended the `t_variation` provided
+        if the result respected the also given `limit`.
+
+        This method returns this same instance but modified.
+        """
+        ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
+
+        extended = self.extender.extend_end(
+            time_interval = self,
+            t_variation = (
+                self._truncate(t_variation)
+                if self.fps is not None else
+                t_variation
+            )
+        )
+
+        # TODO: Is this above a bit useless (?)
+        self.end = extended.end
+
+        return self
+    
+    def _extend_start(
+        self,
+        t_variation: Number
+    ) -> 'NewTimeInterval':
+        """
+        (!) This method will modify this instance.
+
+        Transform this time interval into a new one in which
+        the `start` has been extended the `t_variation` provided
+        if the result respected the also given `limit`.
+
+        This method returns this same instance but modified.
+        """
+        ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
+
+        extended = self.extender.extend_start(
+            time_interval = self,
+            t_variation = (
+                self._truncate(t_variation)
+                if self.fps is not None else
+                t_variation
+            )
+        )
+
+        # TODO: Is this above a bit useless (?)
+        self.start = extended.start
+
+        return self
+    
+    def modify_start(
+        self,
+        t_variation: Number
+    ) -> 'NewTimeInterval':
+        """
+        (!) This method will modify this instance.
+
+        Giving a negative `t_variation` value will make the
+        time interval longer, extending the `start` value.
+
+        Transform this time interval into a new one in which
+        the `start` has been extended or trimmed the
+        `t_variation` value provided if the result respects 
+        the also given `limit`.
+
+        The new `start` can never be lower than the original
+        (min) `start` value of this time interval instance.
+
+        This method returns this same instance but modified.
+        """
+        ParameterValidator.validate_mandatory_number(t_variation, t_variation, do_include_zero = False)
+
+        return (
+            self._trim_start(
+                t_variation = abs(t_variation)
+            )
+            if t_variation > 0 else
+            self._extend_start(
+                t_variation = abs(t_variation)
+            )
+        )
+    
+    def modify_start_to(
+        self,
+        start: Number
+    ) -> 'NewTimeInterval':
+        """
+        (!) This method will modify this instance.
+
+        Transform this time interval into a new one in which
+        the `start` has been extended or trimmed until
+        reaching the new `start` parameter value provided (if
+        valid).
+
+        The new `start` can never be lower than the original
+        (min) `start` value of this time interval instance.
+
+        This method returns this same instance but modified.
+        """
+        ParameterValidator.validate_mandatory_number(start, start, do_include_zero = True)
+
+        if (
+            start >= self.original_start and
+            start < self.end and
+            start != self.start
+        ):
+            self.start = start
+
+        return self
+    
+    def modify_end(
+        self,
+        t_variation: Number,
+        limit: Union[Number, None] = None
+    ) -> 'NewTimeInterval':
+        """
+        (!) This method will modify this instance.
+
+        Giving a positive `t_variation` value will make the
+        time interval longer, extending the `end` value.
+
+        Transform this time interval into a new one in which
+        the `end` has been extended or trimmed the
+        `t_variation` value provided if the result respects 
+        the also given `limit`.
+
+        The new `end` can never be greater than the original
+        (min) `end` value of this time interval instance.
+
+        This method returns this same instance but modified.
+        """
+        ParameterValidator.validate_mandatory_number(t_variation, t_variation, do_include_zero = False)
+
+        return (
+            self._trim_end(
+                t_variation = abs(t_variation)
+            )
+            if t_variation < 0 else
+            self._extend_end(
+                t_variation = abs(t_variation)
+            )
+        )
+    
+    def modify_end_to(
+        self,
+        t: Number
+    ) -> 'NewTimeInterval':
+        """
+        (!) This method will modify this instance.
+
+        Transform this time interval into a new one in which
+        the `end` has been extended or trimmed until
+        reaching the new `t` parameter value provided (if
+        valid).
+
+        The new `end` can never be greater than the original
+        (min) `end` value of this time interval instance.
+
+        This method returns this same instance but modified.
+        """
+        ParameterValidator.validate_mandatory_number(t, t, do_include_zero = True)
+
+        if (
+            t <= self.original_end and
+            t > self.start and
+            t != self.end
+        ):
+            self.end = t
+
+        return self
+        
+    
     # TODO: Implement 'extend' methods using the 'original'
     # values
         
@@ -1452,14 +1610,6 @@ class TimeIntervalCutter:
     time intervals.
     """
 
-    """
-    TODO: Methods I have to implement:
-    trim_end → recorta la parte final
-    trim_start → recorta la parte inicial
-    cut_segment → elimina un tramo [a, b)
-    split_at → divide en dos en un punto dado
-    """
-
     @staticmethod
     # @parameter_to_time_interval('time_interval')
     @parameter_to_new_time_interval('time_interval')
@@ -1476,8 +1626,8 @@ class TimeIntervalCutter:
         The `t` time moment provided must be a value between the
         `start` and `end` of the `time_interval` provided.
         """
-        time_interval._validate_t(t)
-
+        _validate_new_time_interval_current_limits(time_interval, t)
+        
         return (
             TimeInterval(
                 start = time_interval.start,
@@ -1494,8 +1644,7 @@ class TimeIntervalCutter:
     @parameter_to_new_time_interval('time_interval')
     def trim_end(
         time_interval: TimeIntervalType,
-        t_variation: Number,
-        limit: Union[Number, None] = None,
+        t_variation: Number
     ) -> tuple['TimeInterval', 'TimeInterval']:
         """
         Get a tuple containing the 2 new `TimeInterval` instances
@@ -1504,39 +1653,14 @@ class TimeIntervalCutter:
         first tuple is the requested by the user, and the second one
         is the remaining.
 
-        This method will raise an exception if the new `end` value
-        becomes a value under the time interval `start` value or
-        the `limit`, that must be greater than the `start` and lower
-        than the time interval `end` value.
-
         The `t_variation` must be a positive value, the amount of
         seconds to be trimmed.
         """
         ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
-        ParameterValidator.validate_number_between('limit', limit, time_interval.start, time_interval.end, False, False)
-
-        new_end = time_interval.end - t_variation
-        limit = (
-            time_interval.start
-            if limit is None else
-            limit
-        )
 
-        if new_end <= time_interval.start:
-            raise Exception('The "t_variation" value provided makes the new end value be lower than the "start" value.')
-        
-        if new_end <= limit:
-            raise Exception('The "t_variation" value provided makes the new end value be lower than the "limit" value provided.')
-        
-        return (
-            TimeInterval(
-                start = time_interval.start,
-                end = new_end
-            ),
-            TimeInterval(
-                start = new_end,
-                end = time_interval.end
-            )
+        return TimeIntervalCutter.trim_end_to(
+            time_interval = time_interval,
+            t = time_interval.end - t_variation
         )
     
     @staticmethod
@@ -1555,8 +1679,8 @@ class TimeIntervalCutter:
         The `t` time moment provided must be a value between the
         `start` and `end` of the `time_interval` provided.
         """
-        time_interval._validate_t(t)
-
+        _validate_new_time_interval_current_limits(time_interval, t)
+        
         return (
             TimeInterval(
                 start = time_interval.start,
@@ -1573,8 +1697,7 @@ class TimeIntervalCutter:
     @parameter_to_new_time_interval('time_interval')
     def trim_start(
         time_interval: TimeIntervalType,
-        t_variation: Number,
-        limit: Union[Number, None] = None,
+        t_variation: Number
     ) -> tuple['TimeInterval', 'TimeInterval']:
         """
         Get a tuple containing the 2 new `TimeInterval` instances
@@ -1583,39 +1706,14 @@ class TimeIntervalCutter:
         first tuple is the remaining, and the second one is the
         new time interval requested by the user.
 
-        This method will raise an exception if the new `end` value
-        becomes a value under the time interval `start` value or
-        the `limit`, that must be greater than the `start` and lower
-        than the time interval `end` value.
-
         The `t_variation` must be a positive value, the amount of
         seconds to be trimmed.
         """
         ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
-        ParameterValidator.validate_number_between('limit', limit, time_interval.start, time_interval.end, False, False)
 
-        new_start = time_interval.start + t_variation
-        limit = (
-            time_interval.end
-            if limit is None else
-            limit
-        )
-
-        if new_start >= time_interval.end:
-            raise Exception('The "t_variation" value provided makes the new end value be lower than the "end" value.')
-        
-        if new_start >= limit:
-            raise Exception('The "t_variation" value provided makes the new end value be greater than the "limit" value provided.')
-        
-        return (
-            TimeInterval(
-                start = time_interval.start,
-                end = new_start
-            ),
-            TimeInterval(
-                start = new_start,
-                end = time_interval.end
-            )
+        return TimeIntervalCutter.trim_start_to(
+            time_interval = time_interval,
+            t = time_interval.start + t_variation
         )
     
     @staticmethod
@@ -1654,8 +1752,8 @@ class TimeIntervalCutter:
         which you are calling to this one) to choose the tuple you
         want to return.
         """
-        time_interval._validate_t(start, do_include_start = True)
-        time_interval._validate_t(end, do_include_end = True)
+        _validate_new_time_interval_current_limits(time_interval, start)
+        _validate_new_time_interval_current_limits(time_interval, end)
 
         return (
             # TODO: What about this case, should we raise except (?)
@@ -1716,9 +1814,9 @@ class TimeIntervalCutter:
     # @parameter_to_time_interval('time_interval')
     @parameter_to_new_time_interval('time_interval')
     def split(
-        time_interval: 'TimeInterval',
+        time_interval: NewTimeInterval,
         t: Number,
-    ) -> tuple['TimeInterval', 'TimeInterval']:
+    ) -> tuple[NewTimeInterval, NewTimeInterval]:
         """
         Split the interval at the provided `t` time moment and
         get the 2 new time intervals as a result (as a tuple).
@@ -1753,6 +1851,135 @@ class TimeIntervalCutter:
             )
         )
     
+# TODO: Mix this class with the cutter and make single
+# methods able to extend or cut based on if the variation
+# is positive or negative
+class TimeIntervalExtender:
+    """
+    Class to wrap the functionality related to extending
+    """
+
+    @staticmethod
+    @parameter_to_new_time_interval('time_interval')
+    def extend_end(
+        time_interval: 'NewTimeInterval',
+        t_variation: Number
+    ):
+        """
+        Extend the end of the given `time_interval` the `t_variation`
+        amount of seconds provided.
+        """
+        ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
+
+        return TimeIntervalExtender.extend_end_to(
+            time_interval = time_interval,
+            t = time_interval.end + t_variation
+        )
+    
+    @staticmethod
+    @parameter_to_new_time_interval('time_interval')
+    def extend_end_to(
+        time_interval: 'NewTimeInterval',
+        t: Number
+    ):
+        """
+        Extend the end of the given `time_interval` the to the `t`
+        time moment provided.
+        """
+        _validate_new_time_interval_original_limits(time_interval, t)
+        
+        if t < time_interval.end:
+            raise Exception('The "t" parameter provided is lower than the current time interval `end` and this method is to extend it.')
+        
+        return NewTimeInterval(
+            start = time_interval.start,
+            end = t,
+            fps = time_interval.fps
+        )
+    
+    @staticmethod
+    @parameter_to_new_time_interval('time_interval')
+    def extend_start(
+        time_interval: 'NewTimeInterval',
+        t_variation: Number
+    ):
+        """
+        Extend the start of the given `time_interval` the `t_variation`
+        amount of seconds provided if the new `start` is greater than
+        the `limit` provided and than the original (and min) `start`
+        value of the time interval.
+        """
+        ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
+
+        return TimeIntervalExtender.extend_start_to(
+            time_interval = time_interval,
+            t = time_interval.start - t_variation
+        )
+    
+    @staticmethod
+    @parameter_to_new_time_interval('time_interval')
+    def extend_start_to(
+        time_interval: 'NewTimeInterval',
+        t: Number
+    ):
+        """
+        Extend the start of the given `time_interval` the to the `t`
+        time moment provided.
+        """
+        _validate_new_time_interval_original_limits(time_interval, t)
+        
+        if t > time_interval.start:
+            raise Exception('The "t" parameter provided is greater than the current time interval `start` and this method is to extend it.')
+        
+        return NewTimeInterval(
+            start = t,
+            end = time_interval.end,
+            fps = time_interval.fps
+        )
+    
+def _validate_new_time_interval_original_limits(
+    time_interval: NewTimeInterval,
+    t: Number
+) -> None:
+    """
+    *For internal use only*
+
+    This method will raise an exception if the `t` time moment
+    parameter value provided is out of the `time_interval` 
+    original limits.
+
+    TODO: How and where to put this (?)
+    """
+    if (
+        t < time_interval.original_start or
+        t > time_interval.original_end
+    ):
+        raise Exception(f'The "t" parameter value provided ({str(float(t))}) is out of the time interval original limits (max and min) [{str(float(time_interval.original_start))}, {str(float(time_interval.original_end))}].')
+                        
+def _validate_new_time_interval_current_limits(
+    time_interval: NewTimeInterval,
+    t: Number
+) -> None:
+    """
+    *For internal use only*
+
+    This method will raise an exception if the `t` time moment
+    parameter value provided is out of the `time_interval` 
+    current limits (current `start` and `end`).
+
+    This method is useful when we are cutting or splitting the
+    time interval so the parameter value must be always within
+    the current time range.
+
+    TODO: How and where to put this (?)
+    """
+    if (
+        t < time_interval.start or
+        t > time_interval.end
+    ):
+        raise Exception(f'The "t" parameter value provided ({str(float(t))}) is out of the time interval current limits [{str(float(time_interval.start))}, {str(float(time_interval.end))}].')
+    
+    
 # TODO: Maybe add some 'extend' functionality
         
 # # TODO: This method is interesting if we don't want only to

{yta_video_frame_time-0.0.16.dist-info → yta_video_frame_time-0.0.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yta-video-frame-time
-Version: 0.0.16
+Version: 0.0.17
 Summary: Youtube Autonomous Video Frame Time Module
 License-File: LICENSE
 Author: danialcala94

yta_video_frame_time-0.0.17.dist-info/RECORD

@@ -0,0 +1,8 @@
+yta_video_frame_time/__init__.py,sha256=-YOa7lOKdiA3FwDEHHU1tHobnmhjFpTaVLfJQLZqoMI,22252
+yta_video_frame_time/decorators.py,sha256=tPFaDP7Iu9SXVg6raJ26QfHJ-81uzgFZv88SvBZ5RnE,2848
+yta_video_frame_time/interval.py,sha256=LWJtUycyu8LZ3SfzC4XjgAU3teP3rQGl679kBbaDB0c,69643
+yta_video_frame_time/t_fraction.py,sha256=YBOnH-Shs2YKSKFvm84EbFfvzXmg4AyNnyKd_hzF3Uk,29216
+yta_video_frame_time-0.0.17.dist-info/licenses/LICENSE,sha256=6kbiFSfobTZ7beWiKnHpN902HgBx-Jzgcme0SvKqhKY,1091
+yta_video_frame_time-0.0.17.dist-info/METADATA,sha256=I0yY3Havxt5unlEmTlSDdu3ztlqd3TfzTqzapUQTHxM,538
+yta_video_frame_time-0.0.17.dist-info/WHEEL,sha256=M5asmiAlL6HEcOq52Yi5mmk9KmTVjY2RDPtO4p9DMrc,88
+yta_video_frame_time-0.0.17.dist-info/RECORD,,

yta_video_frame_time-0.0.16.dist-info/RECORD

@@ -1,8 +0,0 @@
-yta_video_frame_time/__init__.py,sha256=-YOa7lOKdiA3FwDEHHU1tHobnmhjFpTaVLfJQLZqoMI,22252
-yta_video_frame_time/decorators.py,sha256=tPFaDP7Iu9SXVg6raJ26QfHJ-81uzgFZv88SvBZ5RnE,2848
-yta_video_frame_time/interval.py,sha256=2Ru5QMT1Une3TPMyX1h-PnZduTYe76PqlF_nisfENqU,62489
-yta_video_frame_time/t_fraction.py,sha256=YBOnH-Shs2YKSKFvm84EbFfvzXmg4AyNnyKd_hzF3Uk,29216
-yta_video_frame_time-0.0.16.dist-info/licenses/LICENSE,sha256=6kbiFSfobTZ7beWiKnHpN902HgBx-Jzgcme0SvKqhKY,1091
-yta_video_frame_time-0.0.16.dist-info/METADATA,sha256=b4WIjTN2oziXRwUt4bakBqClD_rCoEZJ9fUDlyMKPqs,538
-yta_video_frame_time-0.0.16.dist-info/WHEEL,sha256=M5asmiAlL6HEcOq52Yi5mmk9KmTVjY2RDPtO4p9DMrc,88
-yta_video_frame_time-0.0.16.dist-info/RECORD,,