jetpytools 1.2.3__py3-none-any.whl

jetpytools/functions/normalize.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+from fractions import Fraction
+from typing import Any, Iterable, Iterator, Sequence, overload
+
+from ..types import F, SupportsString, T, SoftRange, SoftRangeN, SoftRangesN, StrictRange
+
+__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'
+]
+
+
+@overload
+def normalize_seq(val: Sequence[T], length: int) -> list[T]:
+    ...
+
+
+@overload
+def normalize_seq(val: T | Sequence[T], length: int) -> list[T]:
+    ...
+
+
+def normalize_seq(val: T | Sequence[T], length: int) -> list[T]:
+    """
+    Normalize a sequence of values.
+
+    :param val:     Input value.
+    :param length:  Amount of items in the output.
+                    If original sequence length is less that this,
+                    the last item will be repeated.
+
+    :return:        List of normalized values with a set amount of items.
+    """
+
+    val = to_arr(val)
+
+    val += [val[-1]] * (length - len(val))
+
+    return val[:length]
+
+
+_iterables_t = (list, tuple, range, zip, set, map, enumerate)
+
+
+@overload
+def to_arr(val: list[T], *, sub: bool = False) -> list[T]:
+    ...
+
+
+@overload
+def to_arr(val: T | Sequence[T], *, sub: bool = False) -> list[T]:
+    ...
+
+
+def to_arr(val: T | Sequence[T], *, sub: bool = False) -> list[T]:
+    """Normalize any value into an iterable."""
+
+    if sub:
+        return list(val) if any(isinstance(val, x) for x in _iterables_t) else [val]  # type: ignore
+
+    return list(val) if type(val) in _iterables_t else [val]  # type: ignore
+
+
+@overload
+def flatten(items: T | Iterable[T | Iterable[T | Iterable[T]]]) -> Iterable[T]:
+    ...
+
+
+@overload
+def flatten(items: T | Iterable[T | Iterable[T]]) -> Iterable[T]:  # type: ignore
+    ...
+
+
+@overload
+def flatten(items: T | Iterable[T]) -> Iterable[T]:  # type: ignore
+    ...
+
+
+def flatten(items: Any) -> Any:
+    """Flatten an array of values."""
+
+    for val in items:
+        if isinstance(val, Iterable) and not isinstance(val, (str, bytes)):
+            for sub_x in flatten(val):
+                yield sub_x
+        else:
+            yield val
+
+
+def normalize_range(ranges: SoftRange, /) -> Iterable[int]:
+    """
+    Normalize ranges represented by a tuple to an iterable of frame numbers.
+
+    :param ranges:      Ranges to normalize.
+
+    :return:            List of positive frame ranges.
+    """
+
+    if isinstance(ranges, int):
+        return [ranges]
+
+    if isinstance(ranges, tuple):
+        start, stop = ranges
+        step = -1 if stop < start else 1
+
+        return range(start, stop + step, step)
+
+    return ranges
+
+
+def normalize_list_to_ranges(flist: Iterable[int], min_length: int = 0) -> 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 = []
+        flist3.append(n)
+        prev_n = n
+
+    if flist3:
+        flist2.append(flist3)
+
+    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)]
+    ))
+
+
+def normalize_ranges_to_list(ranges: Iterable[SoftRange]) -> list[int]:
+    out = list[int]()
+
+    for srange in ranges:
+        out.extend(normalize_range(srange))
+
+    return out
+
+
+def normalize_ranges(ranges: SoftRangeN | SoftRangesN, end: int) -> list[StrictRange]:
+    """
+    Normalize ranges to a list of positive ranges.
+
+    Frame ranges can include None and negative values.
+    None will be converted to either 0 if it's the first value in a SoftRange, or the end if it's the second item.
+    Negative values will be subtracted from the end.
+
+    Examples:
+
+    .. code-block:: python
+
+        >>> normalize_ranges((None, None), end=1000)
+        [(0, 999)]
+        >>> normalize_ranges((24, -24), end=1000)
+        [(24, 975)]
+        >>> normalize_ranges([(24, 100), (80, 150)], end=1000)
+        [(24, 150)]
+
+
+    :param clip:        Input clip.
+    :param franges:     Frame range or list of frame ranges.
+
+    :return:            List of positive frame ranges.
+    """
+
+    ranges = ranges if isinstance(ranges, list) else [ranges]  # type:ignore
+
+    out = []
+
+    for r in ranges:
+        if r is None:
+            r = (None, None)
+
+        if isinstance(r, tuple):
+            start, endd = r
+            if start is None:
+                start = 0
+            if endd is None:
+                endd = end - 1
+        else:
+            start = r
+            endd = r
+
+        if start < 0:
+            start = end - 1 + start
+
+        if endd < 0:
+            endd = end - 1 + endd
+
+        out.append((start, endd))
+
+    return normalize_list_to_ranges([
+        x for start, endd in out for x in range(start, endd + 1)
+    ])
+
+
+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)
+
+    b_frames = {*normalize_ranges_to_list(norm_ranges)}
+
+    return normalize_list_to_ranges({*range(enda)} - b_frames)
+
+
+def norm_func_name(func_name: SupportsString | F) -> str:
+    """Normalize a class, function, or other object to obtain its name"""
+
+    if isinstance(func_name, str):
+        return func_name.strip()
+
+    if not isinstance(func_name, type) and not callable(func_name):
+        return str(func_name).strip()
+
+    func = func_name
+
+    if hasattr(func_name, '__name__'):
+        func_name = func.__name__
+    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}'
+
+    return str(func_name).strip()
+
+
+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()
+
+    if isinstance(obj, Fraction):
+        return f'{obj.numerator}/{obj.denominator}'
+
+    if isinstance(obj, dict):
+        return '(' + ', '.join(f'{k}={v}' for k, v in obj.items()) + ')'
+
+    return norm_func_name(obj)

jetpytools/functions/other.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    'deepmerge'
+]
+
+
+def deepmerge(source: dict[Any, Any], destination: dict[Any, Any]) -> dict[Any, Any]:
+    for key, value in source.items():
+        if isinstance(value, dict):
+            node = destination.setdefault(key, {})
+            deepmerge(value, node)
+        else:
+            destination[key] = value
+
+    return destination

jetpytools/types/__init__.py

@@ -0,0 +1,6 @@
+from .builtins 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

jetpytools/types/builtins.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING, Any, Callable, ParamSpec, Sequence, SupportsFloat, SupportsIndex, TypeAlias, TypeVar, Union
+)
+
+__all__ = [
+    'T', 'T0', 'T1', 'T2', 'T_contra',
+
+    'F', 'F0', 'F1', 'F2',
+
+    'P', 'P0', 'P1', 'P2',
+    'R', 'R0', 'R1', 'R2', 'R_contra',
+
+    'Nb',
+
+    'StrictRange', 'SoftRange', 'SoftRangeN', 'SoftRangesN',
+
+    'Self',
+
+    'SingleOrArr', 'SingleOrArrOpt',
+    'SingleOrSeq', 'SingleOrSeqOpt',
+
+    'SimpleByteData', 'SimpleByteDataArray',
+    'ByteData',
+
+    'KwargsT'
+]
+
+Nb = TypeVar('Nb', float, int)
+
+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])
+
+P = ParamSpec('P')
+P0 = ParamSpec('P0')
+P1 = ParamSpec('P1')
+P2 = ParamSpec('P2')
+
+R = TypeVar('R')
+R0 = TypeVar('R0')
+R1 = TypeVar('R1')
+R2 = TypeVar('R2')
+
+T_contra = TypeVar('T_contra', contravariant=True)
+R_contra = TypeVar('R_contra', contravariant=True)
+
+Self = TypeVar('Self')
+
+StrictRange: TypeAlias = tuple[int, int]
+SoftRange: TypeAlias = int | StrictRange | Sequence[int]
+
+SoftRangeN: TypeAlias = int | tuple[int | None, int | None] | None
+
+if TYPE_CHECKING:
+    SoftRangesN: TypeAlias = Sequence[SoftRangeN]
+else:
+    SoftRangesN: TypeAlias = list[SoftRangeN]
+
+SingleOrArr = Union[T, list[T]]
+SingleOrSeq = Union[T, Sequence[T]]
+SingleOrArrOpt = Union[SingleOrArr[T], None]
+SingleOrSeqOpt = Union[SingleOrSeq[T], None]
+
+SimpleByteData: TypeAlias = str | bytes | bytearray
+SimpleByteDataArray = Union[SimpleByteData, Sequence[SimpleByteData]]
+
+ByteData: TypeAlias = SupportsFloat | SupportsIndex | SimpleByteData | memoryview
+
+KwargsT = dict[str, Any]

jetpytools/types/file.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import fnmatch
+import shutil
+from os import PathLike, listdir, path, walk
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Literal, TypeAlias, Union
+
+__all__ = [
+    'FilePathType', 'FileDescriptor',
+    'FileOpener',
+
+    'OpenTextModeUpdating',
+    'OpenTextModeWriting',
+    'OpenTextModeReading',
+
+    'OpenBinaryModeUpdating',
+    'OpenBinaryModeWriting',
+    'OpenBinaryModeReading',
+
+    'OpenTextMode',
+    'OpenBinaryMode',
+
+    'SPath', 'SPathLike'
+]
+
+FileDescriptor: TypeAlias = int
+
+FilePathType: TypeAlias = str | bytes | PathLike[str] | PathLike[bytes]
+
+FileOpener: TypeAlias = Callable[[str, int], int]
+
+OpenTextModeUpdating: TypeAlias = Literal[
+    'r+', '+r', 'rt+', 'r+t', '+rt', 'tr+', 't+r', '+tr', 'w+', '+w', 'wt+', 'w+t', '+wt', 'tw+', 't+w', '+tw',
+    'a+', '+a', 'at+', 'a+t', '+at', 'ta+', 't+a', '+ta', 'x+', '+x', 'xt+', 'x+t', '+xt', 'tx+', 't+x', '+tx',
+]
+OpenTextModeWriting: TypeAlias = Literal[
+    'w', 'wt', 'tw', 'a', 'at', 'ta', 'x', 'xt', 'tx'
+]
+OpenTextModeReading: TypeAlias = Literal[
+    'r', 'rt', 'tr', 'U', 'rU', 'Ur', 'rtU', 'rUt', 'Urt', 'trU', 'tUr', 'Utr'
+]
+
+OpenBinaryModeUpdating: TypeAlias = Literal[
+    'rb+', 'r+b', '+rb', 'br+', 'b+r', '+br', 'wb+', 'w+b', '+wb', 'bw+', 'b+w', '+bw',
+    'ab+', 'a+b', '+ab', 'ba+', 'b+a', '+ba', 'xb+', 'x+b', '+xb', 'bx+', 'b+x', '+bx'
+]
+OpenBinaryModeWriting: TypeAlias = Literal[
+    'wb', 'bw', 'ab', 'ba', 'xb', 'bx'
+]
+OpenBinaryModeReading: TypeAlias = Literal[
+    'rb', 'br', 'rbU', 'rUb', 'Urb', 'brU', 'bUr', 'Ubr'
+]
+
+OpenTextMode: TypeAlias = OpenTextModeUpdating | OpenTextModeWriting | OpenTextModeReading
+OpenBinaryMode: TypeAlias = OpenBinaryModeUpdating | OpenBinaryModeReading | OpenBinaryModeWriting
+
+
+class SPath(Path):
+    """Modified version of pathlib.Path"""
+
+    if TYPE_CHECKING:
+        def __new__(cls, *args: SPathLike, **kwargs: Any) -> SPath:
+            ...
+
+    def format(self, *args: Any, **kwargs: Any) -> SPath:
+        """Format the path with the given arguments."""
+
+        return SPath(self.to_str().format(*args, **kwargs))
+
+    def to_str(self) -> str:
+        """Cast the path to a string."""
+
+        return str(self)
+
+    def get_folder(self) -> SPath:
+        """Get the folder of the path."""
+
+        folder_path = self.resolve()
+
+        if folder_path.is_dir():
+            return folder_path
+
+        return SPath(path.dirname(folder_path))
+
+    def mkdirp(self, mode: int = 0o777) -> None:
+        """Make the dir path with its parents."""
+
+        return self.get_folder().mkdir(mode, True, True)
+
+    def rmdirs(self, missing_ok: bool = False, ignore_errors: bool = True) -> None:
+        """Remove the dir path with its contents."""
+
+        try:
+            return shutil.rmtree(str(self.get_folder()), ignore_errors)
+        except FileNotFoundError:
+            if not missing_ok:
+                raise
+
+    def read_lines(
+        self, encoding: str | None = None, errors: str | None = None, keepends: bool = False
+    ) -> list[str]:
+        """Read the file and return its lines."""
+
+        return super().read_text(encoding, errors).splitlines(keepends)
+
+    def write_lines(
+        self, data: Iterable[str], encoding: str | None = None,
+        errors: str | None = None, newline: str | None = None
+    ) -> int:
+        """Open the file and write the given lines."""
+
+        return super().write_text('\n'.join(data), encoding, errors, newline)
+
+    def append_to_stem(self, suffixes: str | Iterable[str], sep: str = '_') -> SPath:
+        """Append a suffix to the stem of the path"""
+
+        from ..functions import to_arr
+
+        return self.with_stem(sep.join([self.stem, *to_arr(suffixes)]))  # type:ignore[list-item]
+
+    def is_empty_dir(self) -> bool:
+        """Check if the directory is empty."""
+
+        return self.is_dir() and not any(self.iterdir())
+
+    def move_dir(self, dst: SPath, *, mode: int = 0o777) -> None:
+        """Move the directory to the specified destination."""
+
+        dst.mkdir(mode, True, True)
+
+        for file in listdir(self):
+            src_file = self / file
+            dst_file = dst / file
+
+            if dst_file.exists():
+                src_file.unlink()
+            else:
+                src_file.rename(dst_file)
+
+        self.rmdir()
+
+    def copy_dir(self, dst: SPath) -> SPath:
+        """Copy the directory to the specified destination."""
+
+        if not self.is_dir():
+            from ..exceptions import PathIsNotADirectoryError
+            raise PathIsNotADirectoryError('The given path, \"{self}\" is not a directory!', self.copy_dir)
+
+        dst.mkdirp()
+        shutil.copytree(self, dst, dirs_exist_ok=True)
+
+        return SPath(dst)
+
+    def lglob(self, pattern: str = '*') -> list[SPath]:
+        """Glob the path and return the list of paths."""
+
+        return list(map(SPath, self.glob(pattern)))
+
+    def fglob(self, pattern: str = '*') -> SPath | None:
+        """Glob the path and return the first match."""
+
+        for root, dirs, files in walk(self):
+            for name in dirs + files:
+                if fnmatch.fnmatch(name, pattern):
+                    return SPath(path.join(root, name))
+
+        return None
+
+    def find_newest_file(self, pattern: str = '*') -> SPath | None:
+        """Find the most recently modified file matching the given pattern in the directory."""
+
+        matching_files = self.get_folder().glob(pattern)
+
+        if not matching_files:
+            return None
+
+        return max(matching_files, key=lambda p: p.stat().st_mtime, default=None)  # type:ignore
+
+    def get_size(self) -> int:
+        """Get the size of the file or directory in bytes."""
+
+        if not self.exists():
+            from ..exceptions import FileNotExistsError
+            raise FileNotExistsError('The given path, \"{self}\" is not a file or directory!', self.get_size)
+
+        if self.is_file():
+            return self.stat().st_size
+
+        return sum(f.stat().st_size for f in self.rglob('*') if f.is_file())
+
+
+SPathLike = Union[str, Path, SPath]

jetpytools/types/funcs.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+from functools import wraps
+
+from typing import TYPE_CHECKING, Any, Callable, Iterable, List, SupportsIndex, TypeAlias, TypeVar, overload
+
+from .builtins import T, P
+from .supports import SupportsString
+
+__all__ = [
+    'StrList',
+    'Sentinel'
+]
+
+
+class StrList(List[SupportsString]):
+    """Custom class for representing a recursively "stringable" list."""
+
+    if TYPE_CHECKING:
+        @overload
+        def __init__(self, __iterable: Iterable[SupportsString | None] = []) -> None:
+            ...
+
+        @overload
+        def __init__(self, __iterable: Iterable[Iterable[SupportsString | None] | None] = []) -> None:
+            ...
+
+        def __init__(self, __iterable: Any = []) -> None:
+            ...
+
+    @property
+    def string(self) -> str:
+        return self.to_str()
+
+    def to_str(self) -> str:
+        return str(self)
+
+    def __str__(self) -> str:
+        from ..functions import flatten
+
+        return ' '.join(
+            filter(
+                None,
+                (str(x).strip() for x in flatten(self) if x is not None)  # type: ignore[var-annotated,arg-type]
+            )
+        )
+
+    def __add__(self, __x: list[SupportsString]) -> StrList:  # type: ignore[override]
+        return StrList(super().__add__(__x))
+
+    def __mul__(self, __n: SupportsIndex) -> StrList:
+        return StrList(super().__mul__(__n))
+
+    def __rmul__(self, __n: SupportsIndex) -> StrList:
+        return StrList(super().__rmul__(__n))
+
+    @property
+    def mlength(self) -> int:
+        return len(self) - 1
+
+    def append(self, *__object: SupportsString) -> None:
+        for __obj in __object:
+            super().append(__obj)
+
+
+class SentinelDispatcher:
+    def check(self, ret_value: T, cond: bool) -> T | SentinelDispatcher:
+        return ret_value if cond else self
+
+    def check_cb(self, callback: Callable[P, tuple[T, bool]]) -> Callable[P, T | SentinelDispatcher]:
+        @wraps(callback)
+        def _wrap(*args: P.args, **kwargs: P.kwargs) -> T | SentinelDispatcher:
+            return self.check(*callback(*args, **kwargs))
+
+        return _wrap
+
+    def filter(self: SelfSentinel, items: Iterable[T | SelfSentinel]) -> Iterable[T]:
+        for item in items:
+            if item is self:
+                continue
+
+            yield item  # type: ignore
+
+    @classmethod
+    def filter_multi(cls, items: Iterable[T | SelfSentinel], *sentinels: SelfSentinel) -> Iterable[T]:
+        for item in items:
+            if item in sentinels:
+                continue
+
+            yield item  # type: ignore
+
+    def __getattr__(self, name: str) -> SentinelDispatcher:
+        if name not in _sentinels:
+            _sentinels[name] = SentinelDispatcher()
+        return _sentinels[name]
+
+    def __setattr__(self, __name: str, __value: Any) -> None:
+        raise NameError
+
+    def __call__(self) -> SentinelDispatcher:
+        return SentinelDispatcher()
+
+    Type: TypeAlias = 'SentinelDispatcher'
+
+
+Sentinel = SentinelDispatcher()
+
+_sentinels = dict[str, SentinelDispatcher]()
+
+SelfSentinel = TypeVar('SelfSentinel', bound=SentinelDispatcher)