jetpytools 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

jetpytools/functions/normalize.py

@@ -1,31 +1,32 @@
 from __future__ import annotations
 
+import sys
 from fractions import Fraction
 from typing import Any, Callable, Iterable, Iterator, Sequence, overload
 
+from ..exceptions import CustomOverflowError
 from ..types import SoftRange, SoftRangeN, SoftRangesN, StrictRange, SupportsString, T, is_soft_range_n
 
 __all__ = [
-    'normalize_seq',
-    'to_arr',
-    'flatten',
-    'normalize_list_to_ranges',
-    'normalize_ranges_to_list',
-    'normalize_range',
-    'normalize_ranges',
-    'invert_ranges',
-    'norm_func_name', 'norm_display_name'
+    "flatten",
+    "invert_ranges",
+    "norm_display_name",
+    "norm_func_name",
+    "normalize_list_to_ranges",
+    "normalize_range",
+    "normalize_ranges",
+    "normalize_ranges_to_list",
+    "normalize_seq",
+    "to_arr",
 ]
 
 
 @overload
-def normalize_seq(val: T | Sequence[T], length: int) -> list[T]:
-    ...
+def normalize_seq(val: T | Sequence[T], length: int) -> list[T]: ...
 
 
 @overload
-def normalize_seq(val: Any, length: int) -> list[Any]:
-    ...
+def normalize_seq(val: Any, length: int) -> list[Any]: ...
 
 
 def normalize_seq(val: T | Sequence[T], length: int) -> list[T]:
@@ -48,13 +49,11 @@ def normalize_seq(val: T | Sequence[T], length: int) -> list[T]:
 
 
 @overload
-def to_arr(val: T | Iterable[T]) -> list[T]:
-    ...
+def to_arr(val: T | Iterable[T]) -> list[T]: ...
 
 
 @overload
-def to_arr(val: Any) -> list[Any]:
-    ...
+def to_arr(val: Any) -> list[Any]: ...
 
 
 def to_arr(val: Any, *, sub: Any = []) -> list[Any]:
@@ -64,19 +63,18 @@ def to_arr(val: Any, *, sub: Any = []) -> list[Any]:
     """
     if sub:
         import warnings
+
         warnings.warn("sub is deprecated.", DeprecationWarning)
 
     return list(val) if (isinstance(val, Iterable) and not isinstance(val, (str, bytes))) else [val]
 
 
 @overload
-def flatten(items: Iterable[Iterable[T]]) -> Iterator[T]:
-    ...
+def flatten(items: Iterable[Iterable[T]]) -> Iterator[T]: ...
 
 
 @overload
-def flatten(items: Iterable[Any]) -> Iterator[Any]:
-    ...
+def flatten(items: Iterable[Any]) -> Iterator[Any]: ...
 
 
 def flatten(items: Any) -> Iterator[Any]:
@@ -93,11 +91,13 @@ def flatten(items: Any) -> Iterator[Any]:
             yield val
 
 
-def normalize_range(ranges: SoftRange, /) -> Iterable[int]:
+def normalize_range(ranges: SoftRange, /, exclusive: bool = False) -> Sequence[int]:
     """
     Normalize ranges represented by a tuple to an iterable of frame numbers.
 
     :param ranges:      Ranges to normalize.
+    :param exclusive:   Whether to use exclusive (Python-style) ranges.
+                        Defaults to False.
 
     :return:            List of positive frame ranges.
     """
@@ -109,22 +109,21 @@ def normalize_range(ranges: SoftRange, /) -> Iterable[int]:
         start, stop = ranges
         step = -1 if stop < start else 1
 
-        return range(start, stop + step, step)
+        return range(start, stop + (not exclusive * step), step)
 
     return ranges
 
 
-def normalize_list_to_ranges(flist: Iterable[int], min_length: int = 0) -> list[StrictRange]:
+def normalize_list_to_ranges(flist: Iterable[int], min_length: int = 0, exclusive: bool = False) -> list[StrictRange]:
     flist2 = list[list[int]]()
     flist3 = list[int]()
 
     prev_n = -1
 
     for n in sorted(set(flist)):
-        if prev_n + 1 != n:
-            if flist3:
-                flist2.append(flist3)
-                flist3 = []
+        if prev_n + 1 != n and flist3:
+            flist2.append(flist3)
+            flist3.clear()
         flist3.append(n)
         prev_n = n
 
@@ -133,22 +132,21 @@ def normalize_list_to_ranges(flist: Iterable[int], min_length: int = 0) -> list[
 
     flist4 = [i for i in flist2 if len(i) > min_length]
 
-    return list(zip(
-        [i[0] for i in flist4],
-        [i[-1] for j, i in enumerate(flist4)]
-    ))
+    return list(zip([i[0] for i in flist4], [i[-1] + exclusive for i in flist4]))
 
 
-def normalize_ranges_to_list(ranges: Iterable[SoftRange]) -> list[int]:
+def normalize_ranges_to_list(ranges: Iterable[SoftRange], exclusive: bool = False) -> list[int]:
     out = list[int]()
 
     for srange in ranges:
-        out.extend(normalize_range(srange))
+        out.extend(normalize_range(srange, exclusive))
 
     return out
 
 
-def normalize_ranges(ranges: SoftRangeN | SoftRangesN, end: int) -> list[StrictRange]:
+def normalize_ranges(
+    ranges: SoftRangeN | SoftRangesN, length: int, exclusive: bool = False, *, strict: bool = True
+) -> list[StrictRange]:
     """
     Normalize ranges to a list of positive ranges.
 
@@ -160,57 +158,105 @@ def normalize_ranges(ranges: SoftRangeN | SoftRangesN, end: int) -> list[StrictR
 
     .. code-block:: python
 
-        >>> normalize_ranges((None, None), end=1000)
+        >>> normalize_ranges((None, None), length=1000)
         [(0, 999)]
-        >>> normalize_ranges((24, -24), end=1000)
+        >>> normalize_ranges((24, -24), length=1000)
         [(24, 975)]
-        >>> normalize_ranges([(24, 100), (80, 150)], end=1000)
+        >>> normalize_ranges([(24, 100), (80, 150)], length=1000)
         [(24, 150)]
 
 
-    :param franges:     Frame range or list of frame ranges.
-    :param end:         End number.
+    :param ranges:      Frame range or list of frame ranges.
+    :param length:      Number of frames.
+    :param exclusive:   Whether to use exclusive (Python-style) ranges.
+                        Defaults to False.
+    :param strict:      Whether to enforce strict checking for out-of-range values.
 
     :return:            List of positive frame ranges.
     """
+    from ..utils import clamp
 
     ranges = [ranges] if is_soft_range_n(ranges) else ranges
 
-    out = []
+    out = list[tuple[int, int]]()
+    exceptions = list[Exception]()
 
     for r in ranges:
         if r is None:
             r = (None, None)
 
         if isinstance(r, tuple):
-            start, endd = r
+            start, end = r
             if start is None:
                 start = 0
-            if endd is None:
-                endd = end - 1
+            if end is None:
+                end = length - (not exclusive)
         else:
             start = r
-            endd = r
+            end = r + exclusive
 
         if start < 0:
-            start = end - 1 + start
+            start = length + start
+
+        if end < 0:
+            end = length + end - (not exclusive)
+
+        # Always throws an error if start and end are negative
+        # or higher than length
+        # or start is higher than end (likely mismatched)
+        if any(
+            [
+                start < 0 and end < 0,
+                start >= length and end - (not exclusive) > length,
+                start >= end + (not exclusive),
+            ]
+        ):
+            exception = CustomOverflowError(
+                f"Range `{r}` with length `{length}` could not be normalized!", normalize_ranges
+            )
+            exceptions.append(exception)
+            continue
+
+        if strict:
+            if start < 0:
+                exception = CustomOverflowError(
+                    f"Start frame `{start}` in range `{r}` with length `{length}` could not be normalized!",
+                    normalize_ranges,
+                )
+                exceptions.append(exception)
+                continue
+            if end - (not exclusive) > length:
+                exception = CustomOverflowError(
+                    f"End frame `{end}` in range `{r}` with length `{length}` could not be normalized!",
+                    normalize_ranges,
+                )
+                exceptions.append(exception)
+                continue
+        else:
+            start = clamp(start, 0, length - 1)
+            end = clamp(end, int(exclusive), length - (not exclusive))
+
+        out.append((start, end))
 
-        if endd < 0:
-            endd = end - 1 + endd
+    if exceptions:
+        if sys.version_info >= (3, 11):
+            raise ExceptionGroup("Multiple exceptions occurred!", exceptions)  # noqa: F821
 
-        out.append((start, endd))
+        raise Exception(exceptions)
 
-    return normalize_list_to_ranges([
-        x for start, endd in out for x in range(start, endd + 1)
-    ])
+    return normalize_list_to_ranges(
+        [x for start, end in out for x in range(start, end + (not exclusive))], exclusive=exclusive
+    )
 
 
-def invert_ranges(ranges: SoftRangeN | SoftRangesN, enda: int, endb: int | None) -> list[StrictRange]:
-    norm_ranges = normalize_ranges(ranges, enda if endb is None else endb)
+def invert_ranges(
+    ranges: SoftRangeN | SoftRangesN, lengtha: int, lengthb: int | None, exclusive: bool = False
+) -> list[StrictRange]:
+    norm_ranges = normalize_ranges(ranges, lengtha if lengthb is None else lengthb, exclusive)
 
-    b_frames = {*normalize_ranges_to_list(norm_ranges)}
+    b_frames = {*normalize_ranges_to_list(norm_ranges, exclusive)}
 
-    return normalize_list_to_ranges({*range(enda)} - b_frames)
+    return normalize_list_to_ranges({*range(lengtha)} - b_frames, exclusive=exclusive)
 
 
 def norm_func_name(func_name: SupportsString | Callable[..., Any]) -> str:
@@ -224,15 +270,14 @@ def norm_func_name(func_name: SupportsString | Callable[..., Any]) -> str:
 
     func = func_name
 
-    if hasattr(func_name, '__name__'):
+    if hasattr(func_name, "__name__"):
         func_name = func.__name__
-    elif hasattr(func_name, '__qualname__'):
+    elif hasattr(func_name, "__qualname__"):
         func_name = func.__qualname__
 
-    if callable(func):
-        if hasattr(func, '__self__'):
-            func = func.__self__ if isinstance(func.__self__, type) else func.__self__.__class__
-            func_name = f'{func.__name__}.{func_name}'
+    if callable(func) and hasattr(func, "__self__"):
+        func = func.__self__ if isinstance(func.__self__, type) else func.__self__.__class__
+        func_name = f"{func.__name__}.{func_name}"
 
     return str(func_name).strip()
 
@@ -241,12 +286,12 @@ def norm_display_name(obj: object) -> str:
     """Get a fancy name from any object."""
 
     if isinstance(obj, Iterator):
-        return ', '.join(norm_display_name(v) for v in obj).strip()
+        return ", ".join(norm_display_name(v) for v in obj).strip()
 
     if isinstance(obj, Fraction):
-        return f'{obj.numerator}/{obj.denominator}'
+        return f"{obj.numerator}/{obj.denominator}"
 
     if isinstance(obj, dict):
-        return '(' + ', '.join(f'{k}={v}' for k, v in obj.items()) + ')'
+        return "(" + ", ".join(f"{k}={v}" for k, v in obj.items()) + ")"
 
     return norm_func_name(obj)

jetpytools/functions/other.py

@@ -2,9 +2,7 @@ from __future__ import annotations
 
 from typing import Any
 
-__all__ = [
-    'deepmerge'
-]
+__all__ = ["deepmerge"]
 
 
 def deepmerge(source: dict[Any, Any], destination: dict[Any, Any]) -> dict[Any, Any]:

jetpytools/types/__init__.py

@@ -1,7 +1,7 @@
-from .builtins import *  # noqa: F401, F403
-from .check import *  # noqa: F401, F403
-from .file import *  # noqa: F401, F403
-from .funcs import *  # noqa: F401, F403
-from .generic import *  # noqa: F401, F403
-from .supports import *  # noqa: F401, F403
-from .utils import *  # noqa: F401, F403
+from .builtins import *
+from .check import *
+from .file import *
+from .funcs import *
+from .generic import *
+from .supports import *
+from .utils import *

jetpytools/types/builtins.py

@@ -3,58 +3,77 @@ from __future__ import annotations
 from typing import Any, Callable, ParamSpec, Sequence, SupportsFloat, SupportsIndex, TypeAlias, TypeVar, Union
 
 __all__ = [
-    'T', 'T0', 'T1', 'T2', 'T_co', 'T0_co', 'T1_co', 'T_contra',
-
-    'F', 'F0', 'F1', 'F2',
-
-    'P', 'P0', 'P1', 'P2',
-    'R', 'R0', 'R1', 'R2', 'R_co', 'R0_co', 'R1_co', 'R_contra',
-
-    'Nb',
-
-    'StrictRange', 'SoftRange', 'SoftRangeN', 'SoftRangesN',
-
-    'SingleOrArr', 'SingleOrArrOpt',
-    'SingleOrSeq', 'SingleOrSeqOpt',
-
-    'SimpleByteData', 'SimpleByteDataArray',
-    'ByteData',
-
-    'KwargsT'
+    "F0",
+    "F1",
+    "F2",
+    "P0",
+    "P1",
+    "P2",
+    "R0",
+    "R1",
+    "R2",
+    "T0",
+    "T1",
+    "T2",
+    "ByteData",
+    "F",
+    "KwargsT",
+    "Nb",
+    "P",
+    "R",
+    "R0_co",
+    "R1_co",
+    "R_co",
+    "R_contra",
+    "SimpleByteData",
+    "SimpleByteDataArray",
+    "SingleOrArr",
+    "SingleOrArrOpt",
+    "SingleOrSeq",
+    "SingleOrSeqOpt",
+    "SoftRange",
+    "SoftRangeN",
+    "SoftRangesN",
+    "StrictRange",
+    "T",
+    "T0_co",
+    "T1_co",
+    "T_co",
+    "T_contra",
 ]
 
-Nb = TypeVar('Nb', float, int)
+Nb = TypeVar("Nb", float, int)
 
-T = TypeVar('T')
-T0 = TypeVar('T0')
-T1 = TypeVar('T1')
-T2 = TypeVar('T2')
+T = TypeVar("T")
+T0 = TypeVar("T0")
+T1 = TypeVar("T1")
+T2 = TypeVar("T2")
 
-F = TypeVar('F', bound=Callable[..., Any])
-F0 = TypeVar('F0', bound=Callable[..., Any])
-F1 = TypeVar('F1', bound=Callable[..., Any])
-F2 = TypeVar('F2', bound=Callable[..., Any])
+F = TypeVar("F", bound=Callable[..., Any])
+F0 = TypeVar("F0", bound=Callable[..., Any])
+F1 = TypeVar("F1", bound=Callable[..., Any])
+F2 = TypeVar("F2", bound=Callable[..., Any])
 
-P = ParamSpec('P')
-P0 = ParamSpec('P0')
-P1 = ParamSpec('P1')
-P2 = ParamSpec('P2')
+P = ParamSpec("P")
+P0 = ParamSpec("P0")
+P1 = ParamSpec("P1")
+P2 = ParamSpec("P2")
 
-R = TypeVar('R')
-R0 = TypeVar('R0')
-R1 = TypeVar('R1')
-R2 = TypeVar('R2')
+R = TypeVar("R")
+R0 = TypeVar("R0")
+R1 = TypeVar("R1")
+R2 = TypeVar("R2")
 
-T_co = TypeVar('T_co', covariant=True)
-T0_co = TypeVar('T0_co', covariant=True)
-T1_co = TypeVar('T1_co', covariant=True)
+T_co = TypeVar("T_co", covariant=True)
+T0_co = TypeVar("T0_co", covariant=True)
+T1_co = TypeVar("T1_co", covariant=True)
 
-R_co = TypeVar('R_co', covariant=True)
-R0_co = TypeVar('R0_co', covariant=True)
-R1_co = TypeVar('R1_co', covariant=True)
+R_co = TypeVar("R_co", covariant=True)
+R0_co = TypeVar("R0_co", covariant=True)
+R1_co = TypeVar("R1_co", covariant=True)
 
-T_contra = TypeVar('T_contra', contravariant=True)
-R_contra = TypeVar('R_contra', contravariant=True)
+T_contra = TypeVar("T_contra", contravariant=True)
+R_contra = TypeVar("R_contra", contravariant=True)
 
 StrictRange: TypeAlias = tuple[int, int]
 SoftRange: TypeAlias = int | StrictRange | Sequence[int]

jetpytools/types/check.py

@@ -4,9 +4,7 @@ from typing_extensions import TypeIs
 
 from .builtins import SoftRange, SoftRangeN, SoftRangesN, StrictRange
 
-__all__ = [
-    "is_strict_range", "is_soft_range", "is_soft_range_n", "is_soft_ranges_n"
-]
+__all__ = ["is_soft_range", "is_soft_range_n", "is_soft_ranges_n", "is_strict_range"]
 
 
 def is_strict_range(val: Any) -> TypeIs[StrictRange]:
@@ -14,8 +12,10 @@ def is_strict_range(val: Any) -> TypeIs[StrictRange]:
 
 
 def is_soft_range(val: Any) -> TypeIs[SoftRange]:
-    return isinstance(val, int) or is_strict_range(val) or (
-        isinstance(val, Sequence) and all(isinstance(x, int) for x in val)
+    return (
+        isinstance(val, int)
+        or is_strict_range(val)
+        or (isinstance(val, Sequence) and all(isinstance(x, int) for x in val))
     )
 
 
@@ -28,7 +28,4 @@ def is_soft_range_n(val: Any) -> TypeIs[SoftRangeN]:
 
 
 def is_soft_ranges_n(val: Any) -> TypeIs[SoftRangesN]:
-    return (
-        isinstance(val, Sequence)
-        and all(is_soft_range_n(x) for x in val)
-    )
+    return isinstance(val, Sequence) and all(is_soft_range_n(x) for x in val)