jetpytools 1.2.3__py3-none-any.whl

jetpytools/__init__.py

@@ -0,0 +1,5 @@
+from .enums import *  # noqa: F401, F403
+from .exceptions import *  # noqa: F401, F403
+from .functions import *  # noqa: F401, F403
+from .types import *  # noqa: F401, F403
+from .utils import *  # noqa: F401, F403

jetpytools/_metadata.py

@@ -0,0 +1,12 @@
+"""Collection of stuff that's useful in general python programming"""
+
+__version__ = '1.2.3'
+
+__author_name__, __author_email__ = 'Jaded Encoding Thaumaturgy', 'jaded.encoding.thaumaturgy@gmail.com'
+__maintainer_name__, __maintainer_email__ = __author_name__, __author_email__
+
+__author__ = f'{__author_name__} <{__author_email__}>'
+__maintainer__ = __author__
+
+if __name__ == '__github__':
+    print(__version__)

jetpytools/enums/__init__.py

@@ -0,0 +1,2 @@
+from .base import *  # noqa: F401, F403
+from .other import *  # noqa: F401, F403

jetpytools/enums/base.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, TypeVar
+
+from ..exceptions import CustomValueError, NotFoundEnumValue
+from ..types import FuncExceptT
+
+__all__ = [
+    'SelfEnum',
+    'CustomEnum', 'CustomIntEnum', 'CustomStrEnum'
+]
+
+
+class CustomEnum(Enum):
+    """Base class for custom enums."""
+
+    @classmethod
+    def _missing_(cls: type[SelfEnum], value: Any) -> SelfEnum | None:
+        return cls.from_param(value)
+
+    @classmethod
+    def from_param(cls: type[SelfEnum], value: Any, func_except: FuncExceptT | None = None) -> SelfEnum | None:
+        """
+        Return the enum value from a parameter.
+
+        :param value:               Value to instantiate the enum class.
+        :param func_except:         Exception function.
+
+        :return:                    Enum value.
+
+        :raises NotFoundEnumValue:   Variable not found in the given enum.
+        """
+
+        if value is None:
+            return None
+
+        if func_except is None:
+            func_except = cls.from_param
+
+        if isinstance(value, cls):
+            return value
+
+        if value is cls:
+            raise CustomValueError('You must select a member, not pass the enum!', func_except)
+
+        try:
+            return cls(value)
+        except Exception:
+            pass
+
+        if isinstance(func_except, tuple):
+            func_name, var_name = func_except
+        else:
+            func_name, var_name = func_except, str(cls)
+
+        raise NotFoundEnumValue(
+            'The given value for "{var_name}" argument must be a valid {enum_name}, not "{value}"!\n'
+            'Valid values are: [{readable_enum}].', func_name,
+            var_name=var_name, enum_name=cls, value=value,
+            readable_enum=iter([f'{x.name} ({x.value})' for x in cls]),
+            reason=value
+        )
+
+
+class CustomIntEnum(int, CustomEnum):
+    """Base class for custom int enums."""
+
+    value: int
+
+
+class CustomStrEnum(str, CustomEnum):
+    """Base class for custom str enums."""
+
+    value: str
+
+
+SelfEnum = TypeVar('SelfEnum', bound=CustomEnum)

jetpytools/enums/other.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import TypeVar, overload
+
+__all__ = [
+    'Coordinate',
+    'Position',
+    'Size'
+]
+
+
+class Coordinate:
+    """
+    Positive set of (x, y) coordinates.
+
+    :raises ValueError:     Negative values were passed.
+    """
+
+    x: int
+    """Horizontal coordinate."""
+
+    y: int
+    """Vertical coordinate."""
+
+    @overload
+    def __init__(self: SelfCoord, other: tuple[int, int] | SelfCoord, /) -> None:
+        ...
+
+    @overload
+    def __init__(self: SelfCoord, x: int, y: int, /) -> None:
+        ...
+
+    def __init__(self: SelfCoord, x_or_self: int | tuple[int, int] | SelfCoord, y: int | None = None, /) -> None:
+        from ..exceptions import CustomValueError
+
+        if isinstance(x_or_self, int):
+            x = x_or_self
+        else:
+            x, y = x_or_self if isinstance(x_or_self, tuple) else (x_or_self.x, x_or_self.y)
+
+        if y is None:
+            raise CustomValueError("y coordinate must be defined!", self.__class__)
+
+        if x < 0 or y < 0:
+            raise CustomValueError("Values can't be negative!", self.__class__)
+
+        self.x = x
+        self.y = y
+
+
+SelfCoord = TypeVar('SelfCoord', bound=Coordinate)
+
+
+class Position(Coordinate):
+    """Positive set of an (x,y) offset relative to the top left corner of an area."""
+
+
+class Size(Coordinate):
+    """Positive set of an (x,y), (horizontal,vertical), size of an area."""

jetpytools/exceptions/__init__.py

@@ -0,0 +1,5 @@
+from .base import *  # noqa: F401, F403
+from .enum import *  # noqa: F401, F403
+from .file import *  # noqa: F401, F403
+from .generic import *  # noqa: F401, F403
+from .module import *  # noqa: F401, F403

jetpytools/exceptions/base.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import sys
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ..types import MISSING, FuncExceptT, SupportsString
+
+__all__ = [
+    'CustomError',
+
+    'CustomValueError',
+    'CustomIndexError',
+    'CustomOverflowError',
+    'CustomKeyError',
+    'CustomTypeError',
+    'CustomRuntimeError',
+    'CustomNotImplementedError',
+    'CustomPermissionError'
+]
+
+
+if TYPE_CHECKING:
+    class ExceptionT(Exception):
+        __name__: str
+        __qualname__: str
+        ...
+else:
+    ExceptionT = Exception
+
+
+class CustomErrorMeta(type):
+    """Custom base exception meta class."""
+
+    def __new__(cls: type[SelfCErrorMeta], *args: Any) -> SelfCErrorMeta:
+        return CustomErrorMeta.setup_exception(type.__new__(cls, *args))  # type: ignore
+
+    @staticmethod
+    def setup_exception(exception: SelfCErrorMeta, override: str | ExceptionT | None = None) -> SelfCErrorMeta:
+        """
+        Setup an exception for later use in CustomError.
+
+        :param exception:   Exception to update.
+        :param override:    Optional name or exception from which get the override values.
+
+        :return:            Set up exception.
+        """
+
+        if override:
+            if isinstance(override, str):
+                over_name = over_qual = override
+            else:
+                over_name, over_qual = override.__name__, override.__qualname__
+
+            if over_name.startswith('Custom'):
+                exception.__name__ = over_name
+            else:
+                exception.__name__ = f'Custom{over_name}'
+
+            exception.__qualname__ = over_qual
+
+        if exception.__qualname__.startswith('Custom'):
+            exception.__qualname__ = exception.__qualname__[6:]
+
+        if sys.stdout and sys.stdout.isatty():
+            exception.__qualname__ = f'\033[0;31;1m{exception.__qualname__}\033[0m'
+
+        exception.__module__ = Exception.__module__
+
+        return exception
+
+    if TYPE_CHECKING:
+        def __getitem__(self, exception: type[Exception]) -> CustomError:
+            ...
+
+
+SelfCErrorMeta = TypeVar('SelfCErrorMeta', bound=CustomErrorMeta)
+
+
+class CustomError(ExceptionT, metaclass=CustomErrorMeta):
+    """Custom base exception class."""
+
+    def __init__(
+        self, message: SupportsString | None = None, func: FuncExceptT | None = None, reason: Any = None, **kwargs: Any
+    ) -> None:
+        """
+        Instantiate a new exception with pretty printing and more.
+
+        :param message: Message of the error.
+        :param func:    Function this exception was raised from.
+        :param reason:  Reason of the exception. For example, an optional parameter.
+        """
+
+        self.message = message
+        self.func = func
+        self.reason = reason
+        self.kwargs = kwargs
+
+        super().__init__(message)
+
+    def __class_getitem__(cls, exception: str | type[ExceptionT] | ExceptionT) -> CustomError:
+        if isinstance(exception, str):
+            class inner_exception(cls):  # type: ignore
+                ...
+        else:
+            if not issubclass(exception, type):  # type: ignore
+                exception = exception.__class__  # type: ignore
+
+            class inner_exception(cls, exception):  # type: ignore
+                ...
+
+        return CustomErrorMeta.setup_exception(inner_exception, exception)  # type: ignore
+
+    def __call__(
+        self: SelfError, message: SupportsString | None = MISSING,
+        func: FuncExceptT | None = MISSING, reason: SupportsString | FuncExceptT | None = MISSING,  # type: ignore
+        **kwargs: Any
+    ) -> SelfError:
+        """
+        Copy an existing exception with defaults and instantiate a new one.
+
+        :param message: Message of the error.
+        :param func:    Function this exception was raised from.
+        :param reason:  Reason of the exception. For example, an optional parameter.
+        """
+
+        err = deepcopy(self)
+
+        if message is not MISSING:
+            err.message = message
+
+        if func is not MISSING:  # type: ignore[comparison-overlap]
+            err.func = func
+
+        if reason is not MISSING:
+            err.reason = reason
+
+        err.kwargs |= kwargs
+
+        return err
+
+    def __str__(self) -> str:
+        from ..functions import norm_display_name, norm_func_name
+
+        message = self.message
+
+        if not message:
+            message = 'An error occurred!'
+
+        if self.func:
+            func_header = norm_func_name(self.func).strip()
+
+            if sys.stdout and sys.stdout.isatty():
+                func_header = f'\033[0;36m{func_header}\033[0m'
+
+            func_header = f'({func_header}) '
+        else:
+            func_header = ''
+
+        if self.kwargs:
+            self.kwargs = {
+                key: norm_display_name(value) for key, value in self.kwargs.items()
+            }
+
+        if self.reason:
+            reason = self.reason = norm_display_name(self.reason)
+
+            if reason:
+                if not isinstance(self.reason, dict):
+                    reason = f'({reason})'
+
+                if sys.stdout and sys.stdout.isatty():
+                    reason = f'\033[0;33m{reason}\033[0m'
+                reason = f' {reason}'
+        else:
+            reason = ''
+
+        return f'{func_header}{self.message!s}{reason}'.format(**self.kwargs).strip()
+
+
+SelfError = TypeVar('SelfError', bound=CustomError)
+
+
+class CustomValueError(CustomError, ValueError):
+    """Thrown when a specified value is invalid."""
+
+
+class CustomIndexError(CustomError, IndexError):
+    """Thrown when an index or generic numeric value is out of bound."""
+
+
+class CustomOverflowError(CustomError, OverflowError):
+    """Thrown when a value is out of range. e.g. temporal radius too big."""
+
+
+class CustomKeyError(CustomError, KeyError):
+    """Thrown when trying to access an non-existent key."""
+
+
+class CustomTypeError(CustomError, TypeError):
+    """Thrown when a passed argument is of wrong type."""
+
+
+class CustomRuntimeError(CustomError, RuntimeError):
+    """Thrown when a runtime error occurs."""
+
+
+class CustomNotImplementedError(CustomError, NotImplementedError):
+    """Thrown when you encounter a yet not implemented branch of code."""
+
+
+class CustomPermissionError(CustomError, PermissionError):
+    """Thrown when the user can't perform an action."""

jetpytools/exceptions/enum.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .base import CustomKeyError
+
+__all__ = [
+    'NotFoundEnumValue'
+]
+
+
+class NotFoundEnumValue(CustomKeyError):
+    """Raised when you try to instantiate an Enum with unknown value"""

jetpytools/exceptions/file.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from .base import CustomError, CustomPermissionError
+
+
+__all__ = [
+    'FileNotExistsError',
+    'FileWasNotFoundError',
+    'FilePermissionError',
+    'FileTypeMismatchError',
+    'FileIsADirectoryError',
+
+    'PathIsNotADirectoryError',
+]
+
+
+class FileNotExistsError(CustomError, FileExistsError):
+    """Raised when a file doesn't exists"""
+
+
+class FileWasNotFoundError(CustomError, FileNotFoundError):
+    """Raised when a file wasn't found but the path is correct, e.g. parent directory exists"""
+
+
+class FilePermissionError(CustomPermissionError):
+    """Raised when you try to access a file but haven't got permissions to do so"""
+
+
+class FileTypeMismatchError(CustomError, OSError):
+    """Raised when you try to access a file with a FileType != AUTO and it's another file type"""
+
+
+class FileIsADirectoryError(CustomError, IsADirectoryError):
+    """Raised when you try to access a file but it's a directory instead"""
+
+
+class PathIsNotADirectoryError(CustomError, NotADirectoryError):
+    """Raised when you try to access a directory but it's not a directory"""

jetpytools/exceptions/generic.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from ..types import FuncExceptT, SupportsString, T
+from .base import CustomValueError
+
+__all__ = [
+    'MismatchError', 'MismatchRefError'
+]
+
+
+class MismatchError(CustomValueError):
+    """Raised when there's a mismatch between two or more values."""
+
+    @classmethod
+    def _item_to_name(cls, item: Any) -> str:
+        return str(item)
+
+    @classmethod
+    def _reduce(cls, items: Iterable[Any]) -> tuple[str]:
+        return tuple[str](dict.fromkeys(map(cls._item_to_name, items)).keys())  # type: ignore
+
+    def __init__(
+        self, func: FuncExceptT, items: Iterable[Any], message: SupportsString = 'All items must be equal!',
+        reason: Any = '{reduced_items}', **kwargs: Any
+    ) -> None:
+        super().__init__(message, func, reason, **kwargs, reduced_items=iter(self._reduce(items)))
+
+    @classmethod
+    def check(cls, func: FuncExceptT, *items: Any, **kwargs: Any) -> None:
+        if len(cls._reduce(items)) != 1:
+            raise cls(func, items, **kwargs)
+
+
+class MismatchRefError(MismatchError):
+    def __init__(
+        self, func: FuncExceptT, base: T, ref: T, message: SupportsString = 'All items must be equal!', **kwargs: Any
+    ) -> None:
+        super().__init__(func, [base, ref], message, **kwargs)
+
+    @classmethod
+    def check(cls, func: FuncExceptT, *items: Any, **kwargs: Any) -> None:
+        if len(cls._reduce(items)) != 1:
+            raise cls(func, *items, **kwargs)

jetpytools/exceptions/module.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import FuncExceptT, SupportsString
+from .base import CustomError
+
+__all__ = [
+    'CustomImportError',
+    'DependencyNotFoundError'
+]
+
+
+class CustomImportError(CustomError, ImportError):
+    """Raised when there's a general import error."""
+
+    def __init__(
+        self, func: FuncExceptT, package: str | ImportError,
+        message: SupportsString = "Import failed for package '{package}'!",
+        **kwargs: Any
+    ) -> None:
+        """
+        :param func:        Function this error was raised from.
+        :param package:     Either the raised error or the name of the missing package.
+        :param message:     Custom error message.
+        """
+
+        super().__init__(message, func, package=package if isinstance(package, str) else package.name, **kwargs)
+
+
+class DependencyNotFoundError(CustomImportError):
+    """Raised when there's a missing optional dependency."""
+
+    def __init__(
+        self, func: FuncExceptT, package: str | ImportError,
+        message: SupportsString = "Missing dependency '{package}'!",
+        **kwargs: Any
+    ) -> None:
+        super().__init__(func, package, message, **kwargs)

jetpytools/functions/__init__.py

@@ -0,0 +1,3 @@
+from .funcs import *  # noqa: F401, F403
+from .normalize import *  # noqa: F401, F403
+from .other import *  # noqa: F401, F403

jetpytools/functions/funcs.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Concatenate, overload
+
+from ..exceptions import CustomRuntimeError
+from ..types import MISSING, KwargsT, MissingT, P, R, T
+
+__all__ = [
+    'iterate', 'fallback', 'kwargs_fallback'
+]
+
+
+def iterate(
+    base: T, function: Callable[Concatenate[T | R, P], R],
+    count: int, *args: P.args, **kwargs: P.kwargs
+) -> T | R:
+    """
+    Execute a given function over the base value multiple times.
+
+    Different from regular iteration functions is that you do not need to pass a partial object.
+    This function accepts *args and **kwargs. These will be passed on to the given function.
+
+    Examples:
+
+    >>> iterate(5, lambda x: x * 2, 2)
+        20
+
+    :param base:        Base value, etc. to iterate over.
+    :param function:    Function to iterate over the base.
+    :param count:       Number of times to execute function.
+    :param *args:       Positional arguments to pass to the given function.
+    :param **kwargs:    Keyword arguments to pass to the given function.
+
+    :return:            Value, etc. with the given function run over it
+                        *n* amount of times based on the given count.
+    """
+
+    if count <= 0:
+        return base
+
+    result: T | R = base
+
+    for _ in range(count):
+        result = function(result, *args, **kwargs)
+
+    return result
+
+
+fallback_missing = object()
+
+
+@overload
+def fallback(value: T | None, fallback: T, /) -> T:
+    ...
+
+
+@overload
+def fallback(value: T | None, fallback0: T | None, default: T, /) -> T:
+    ...
+
+
+@overload
+def fallback(value: T | None, fallback0: T | None, fallback1: T | None, default: T, /) -> T:
+    ...
+
+
+@overload
+def fallback(value: T | None, *fallbacks: T | None) -> T | MissingT:
+    ...
+
+
+@overload
+def fallback(value: T | None, *fallbacks: T | None, default: T) -> T:
+    ...
+
+
+def fallback(value: T | None, *fallbacks: T | None, default: Any | T = fallback_missing) -> T | MissingT:
+    """
+    Utility function that returns a value or a fallback if the value is None.
+
+    Example:
+
+    .. code-block:: python
+
+        >>> fallback(5, 6)
+        5
+        >>> fallback(None, 6)
+        6
+
+    :param value:               Input value to evaluate. Can be None.
+    :param fallback_value:      Value to return if the input value is None.
+
+    :return:                    Input value or fallback value if input value is None.
+    """
+
+    if value is not None:
+        return value
+
+    for fallback in fallbacks:
+        if fallback is not None:
+            return fallback
+
+    if default is not fallback_missing:
+        return default
+    elif len(fallbacks) > 3:
+        return MISSING
+
+    raise CustomRuntimeError('You need to specify a default/fallback value!')
+
+
+@overload
+def kwargs_fallback(
+    input_value: T | None, kwargs: tuple[KwargsT, str], fallback: T
+) -> T:
+    ...
+
+
+@overload
+def kwargs_fallback(
+    input_value: T | None, kwargs: tuple[KwargsT, str], fallback0: T | None, default: T
+) -> T:
+    ...
+
+
+@overload
+def kwargs_fallback(
+    input_value: T | None, kwargs: tuple[KwargsT, str], fallback0: T | None, fallback1: T | None,
+    default: T
+) -> T:
+    ...
+
+
+@overload
+def kwargs_fallback(
+    input_value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None
+) -> T | MissingT:
+    ...
+
+
+@overload
+def kwargs_fallback(
+    input_value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None, default: T
+) -> T:
+    ...
+
+
+def kwargs_fallback(  # type: ignore
+    value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None, default: T = fallback_missing  # type: ignore
+) -> T | MissingT:
+    """Utility function to return a fallback value from kwargs if value was not found or is None."""
+
+    return fallback(value, kwargs[0].get(kwargs[1], None), *fallbacks, default=default)