FloriaKit 0.0.5__py3-none-any.whl

FloriaKit/hints/__init__.py

@@ -0,0 +1,14 @@
+import typing as t
+
+from . import (
+    common,
+    color,
+    size,
+    position,
+    vector,
+    exception,
+)
+
+from .common import *
+from .quaternion import *
+from .matrix import *

FloriaKit/hints/color.py

@@ -0,0 +1,36 @@
+import typing as t
+
+from .common import number
+
+
+type rgb = tuple[number, number, number]
+type rgba = tuple[number, number, number, number]
+
+type color = t.Union[
+    rgb,
+    rgba,
+]
+
+
+def get_rgba(value: color) -> rgba:
+    match len(value):
+        case 3:
+            return (*value, 255)  # pyright: ignore[reportReturnType]
+
+        case 4:
+            return value  # pyright: ignore[reportReturnType]
+
+        case _:
+            raise
+
+
+def get_rgb(value: color) -> rgb:
+    match len(value):
+        case 3:
+            return value  # pyright: ignore[reportReturnType]
+
+        case 4:
+            return value[:3]
+
+        case _:
+            raise

FloriaKit/hints/common.py

@@ -0,0 +1,44 @@
+import typing as t
+
+
+type number = int | float
+
+# vec2
+
+type vec2 = tuple[number, number]
+type pos2 = vec2
+type size2 = vec2
+type scale2 = vec2
+
+type vec2i = tuple[int, int]
+type pos2i = vec2i
+type size2i = vec2i
+type scale2i = vec2i
+
+type vec2f = tuple[float, float]
+type pos2f = vec2f
+type size2f = vec2f
+type scale2f = vec2f
+
+# vec3
+
+type vec3 = tuple[number, number]
+type pos3 = vec3
+type size3 = vec3
+type scale3 = vec3
+
+type vec3i = tuple[int, int, int]
+type pos3i = vec3i
+type size3i = vec3i
+type scale3i = vec3i
+
+type vec3f = tuple[float, float, float]
+type pos3f = vec3f
+type size3f = vec3f
+type scale3f = vec3f
+
+# vec4
+
+type vec4 = tuple[number, number, number, number]
+type vec4i = tuple[int, int, int, int]
+type vec4f = tuple[float, float, float, float]

FloriaKit/hints/exception.py

@@ -0,0 +1,19 @@
+import typing as t
+
+
+type ex = Exception | str
+
+
+if t.TYPE_CHECKING:
+
+    @t.overload
+    def get_exception(ex_: ex) -> Exception: ...
+
+    @t.overload
+    def get_exception(ex_: ex | None) -> Exception | None: ...
+
+
+def get_exception(ex_: ex | None):
+    if ex_ is None:
+        return None
+    return ex_ if isinstance(ex_, Exception) else Exception(ex_)

FloriaKit/hints/matrix.py

@@ -0,0 +1,8 @@
+import typing as t
+
+from .common import vec2, vec3, vec4
+
+
+type mat2x2 = tuple[vec2, vec2]
+type mat3x3 = tuple[vec3, vec3, vec3]
+type mat4x4 = tuple[vec4, vec4, vec4, vec4]

FloriaKit/hints/quaternion.py

@@ -0,0 +1,5 @@
+import typing as t
+
+from .common import number
+
+type quaternion = tuple[number, number, number, number]

FloriaKit/protocols/__init__.py

@@ -0,0 +1,3 @@
+from . import (
+    functions,
+)

FloriaKit/protocols/functions.py

@@ -0,0 +1,15 @@
+import typing as t
+
+
+class SyncFunction[**P = [], R = t.Any](t.Protocol):
+    def __call__(self, *args: P.args, **kwds: P.kwargs) -> R: ...
+
+
+class AsyncFunction[**P = [], R = t.Any](t.Protocol):
+    async def __call__(self, *args: P.args, **kwds: P.kwargs) -> R: ...
+
+
+type AnyFunction[**P = [], R = t.Any] = t.Union[
+    SyncFunction[P, R],
+    AsyncFunction[P, R],
+]

FloriaKit/utils/__init__.py

@@ -0,0 +1,120 @@
+import typing as t
+import asyncio
+
+from .calculated_value import CalculatedValue, gcv
+from .calculated_fields import CalculatedFields
+from .interpolation_field import InterpolationField
+from .stopwatch import Stopwatch, stopwatch
+from .avg import Avg
+from .flag import Flag
+
+from .. import hints
+
+from . import (
+    context,
+    logging,
+    quaternion,
+    matrix,
+    vector,
+)
+
+
+if t.TYPE_CHECKING:
+
+    @t.overload
+    def coalapse[T](
+        *items: T | None,
+        exception: hints.exception.ex | None = None,
+    ) -> T: ...
+
+    @t.overload
+    def coalapse[T, TD](
+        *items: T | None,
+        default: TD,
+    ) -> T | TD: ...
+
+
+def coalapse(
+    *items: t.Any | None,
+    **kw: t.Any,
+) -> t.Any:
+    for item in items:
+        if item is not None:
+            return item
+
+    if 'default' in kw:
+        return kw['default']
+
+    if (ex := hints.exception.get_exception(kw.get('exception'))) is not None:
+        raise ex
+
+    raise ValueError()
+
+
+if t.TYPE_CHECKING:
+
+    @t.overload
+    def coalapse_lazy[T](
+        *items: CalculatedValue[T | None] | T | None,
+        exception: hints.exception.ex | None = None,
+    ) -> T: ...
+
+    @t.overload
+    def coalapse_lazy[T, TD](
+        *items: CalculatedValue[T | None] | T | None,
+        default: TD,
+    ) -> T | TD: ...
+
+
+def coalapse_lazy(
+    *items: CalculatedValue[t.Any] | t.Any | None,
+    **kw: t.Any,
+) -> t.Any:
+    for item in items:
+        if (value := gcv(item)) is not None:
+            return value
+
+    if 'default' in kw:
+        return kw['default']
+
+    if (ex := hints.exception.get_exception(kw.get('exception'))) is not None:
+        raise ex
+
+    raise ValueError()
+
+
+async def invoke[**P, R](
+    func: t.Callable[P, R | t.Coroutine[R, t.Any, t.Any]],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> R:
+    if asyncio.iscoroutine(result := func(*args, **kwargs)):
+        return await result
+    return result
+
+
+def partition[T](
+    predicate: t.Callable[[T], bool] | None,
+    iterable: t.Iterable[T],
+) -> tuple[list[T], list[T]]:
+    '''
+    return: trues, falses
+    '''
+
+    trues: list[T] = []
+    falses: list[T] = []
+
+    for item in iterable:
+        if item is not None if predicate is None else predicate(item):
+            trues.append(item)
+        else:
+            falses.append(item)
+
+    return trues, falses
+
+
+def ensure_iterable[T](value: T | t.Iterable[T]) -> t.Iterable[T]:
+    if isinstance(value, t.Iterable) and not isinstance(value, (str, bytes)):
+        return value
+    else:
+        return [value]

FloriaKit/utils/avg.py

@@ -0,0 +1,74 @@
+import typing as t
+
+
+class Avg:
+    """Accumulator for incremental average calculation.
+
+    Efficiently computes arithmetic mean without storing all values.
+    Suitable for real-time metrics tracking.
+
+    For example::
+
+        avg = Avg()
+
+        avg.add(60)
+        avg.add(30)
+
+        avg.value  # 45
+    """
+
+    __slots__ = ('_sum', '_count')
+
+    def __init__(self) -> None:
+        """Initialize Avg instance"""
+        super().__init__()
+
+        self._sum: float = 0
+        self._count: int = 0
+
+    def add(self, value: float):
+        """Add new value to the accumulator.
+
+        Args:
+            value: Numeric value to include in average calculation
+        """
+        self._sum += value
+        self._count += 1
+
+    def extend(self, values: t.Iterable[float]):
+        """Add multiple values efficiently.
+
+        Args:
+            values: Iterable of numeric values
+        """
+        for value in values:
+            self.add(value)
+
+    def clear(self):
+        """Reset accumulator state."""
+        self._sum = self._count = 0
+
+    @property
+    def count(self) -> int:
+        """Current number of accumulated values."""
+        return self._count
+
+    @property
+    def total(self) -> float:
+        """Current accumulated sum of values."""
+        return self._sum
+
+    @property
+    def value(self) -> float:
+        """Current arithmetic mean.
+
+        Returns 0.0 when no values accumulated to avoid division errors.
+        """
+        return self._sum / self._count if self._count > 0 else 0
+
+    def __len__(self) -> int:
+        return self._count
+
+    def __iadd__(self, value: float) -> 'Avg':
+        self.add(value)
+        return self

FloriaKit/utils/calculated_fields.py

@@ -0,0 +1,62 @@
+import typing as t
+
+from .interpolation_field import InterpolationField
+from .calculated_value import CalculatedValue, gcv
+
+
+class CalculatedFields[TK: str = str, **P = []]:
+    __slots__ = (
+        '_map',
+        '_process_func',
+        '__weakref__',
+    )
+
+    @staticmethod
+    def default_process(value: t.Any) -> t.Any:
+        if isinstance(value, InterpolationField):
+            return t.cast(InterpolationField[t.Any], value).get_value()
+
+        elif isinstance(value, CalculatedValue):
+            return gcv(t.cast(CalculatedValue[t.Any], value))
+
+        return value
+
+    def __init__(
+        self,
+        map: t.Mapping[TK | str, CalculatedValue[t.Any, P] | t.Any] | None = None,
+        process_func: t.Callable[[t.Any], t.Any] | None = None,
+    ):
+        self._map: dict[TK | str, CalculatedValue[t.Any, P] | t.Any] = (
+            {}
+            if map is None
+            else t.cast(dict[TK | str, CalculatedValue[t.Any, P] | t.Any], map)
+        )
+        self._process_func: t.Callable[[t.Any], t.Any] | None = process_func
+
+    def update(
+        self, map: t.Mapping[TK | str, CalculatedValue[t.Any, P] | t.Any]
+    ) -> t.Self:
+        self._map.update(map)
+        return self
+
+    def get[TD: t.Any | None = None](
+        self,
+        name: TK | str,
+        *args: P.args,
+        __default__: TD = None,
+        **kwargs: P.kwargs,
+    ) -> t.Any | TD:
+        if (func := self._map.get(name)) is None:
+            return __default__
+
+        value = gcv(func, *args, **kwargs)
+
+        return (
+            value
+            if (process_func := self._process_func) is None
+            else process_func(value)
+        )
+
+    @property
+    def names(self) -> list[TK | str]:
+        return list(self._map.keys())

FloriaKit/utils/calculated_value.py

@@ -0,0 +1,16 @@
+import typing as t
+
+
+@t.runtime_checkable
+class CalculatedValue[R, **P = []](t.Protocol):
+    def __call__(self, *args: P.args, **kwds: P.kwargs) -> R: ...
+
+
+def gcv[T, **P = []](
+    value: CalculatedValue[T, P] | T,
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> T:
+    if isinstance(value, CalculatedValue):
+        return value(*args, **kwargs)  # pyright: ignore[reportUnknownVariableType]
+    return value

FloriaKit/utils/context.py

@@ -0,0 +1,16 @@
+import contextlib
+import typing as t
+
+
+@contextlib.contextmanager
+def empty[TD: t.Any | None](
+    default: TD = None,
+) -> t.Generator[TD, t.Any, None]:
+    yield default
+
+
+@contextlib.asynccontextmanager
+async def async_empty[TD: t.Any | None](
+    default: TD = None,
+) -> t.AsyncGenerator[TD, t.Any]:
+    yield default

FloriaKit/utils/flag.py

@@ -0,0 +1,50 @@
+import typing as t
+
+
+class Flag:
+    __slots__ = ('_depth',)
+
+    """
+    Управляемый флаг с поддержкой контекстного менеджера.
+
+    Предоставляет механизм временного установления флага с
+    автоматическим сбросом при выходе из контекста.
+
+    Пример:
+
+    ```python
+
+        flag = Flag()
+
+        ...
+
+        with flag:
+            # Флаг установлен в True
+            ...
+
+        # Флаг автоматически сброшен в False
+
+        ...
+
+        if flag:
+            raise Exception(...)
+    ```
+    """
+
+    def __init__(self):
+        self._depth: int = 0
+
+    def __enter__(self, *args: t.Any, **kwargs: t.Any):
+        self._depth += 1
+
+    def __exit__(self, *args: t.Any, **kwargs: t.Any):
+        self._depth -= 1
+
+    @property
+    def value(self) -> bool:
+        """Текущее состояние флага"""
+        return self._depth > 0
+
+    def __bool__(self) -> bool:
+        """Возвращает текущее состояние флага для использования в условиях"""
+        return self.value

FloriaKit/utils/interpolation_field.py

@@ -0,0 +1,80 @@
+import typing as t
+import time
+
+from .calculated_value import CalculatedValue, gcv
+
+
+class InterpolationField[T = t.Any]:
+    __slots__ = (
+        '_interpolation_func',
+        '_delay',
+        '_value',
+        '_next',
+        '__weakref__',
+    )
+
+    def __init__(
+        self,
+        interpolation_func: t.Callable[[T, T, float], T],
+        delay: CalculatedValue[float] | float,
+        default: T = None,
+    ):
+        self._interpolation_func = interpolation_func
+        self._delay = delay
+
+        self._value: T = default
+        self._next: tuple[T, float] | None = None
+        '''next_value, next_time'''
+
+    def get_value(self) -> T:
+        if self._next is None:
+            return self._value
+
+        next_value, next_time = self._next
+
+        if time.perf_counter() >= next_time:
+            self._value = next_value
+            self._next = None
+            return self._value
+
+        return self._interpolation_func(
+            self._value,
+            next_value,
+            self.progress,
+        )
+
+    def set_value(self, value: T, flash: bool = False) -> t.Self:
+        if flash:
+            self._next = None
+            self._value = value
+
+        else:
+            if self._next is not None:
+                self._value = self._next[0]
+
+            self._next = (
+                value,
+                time.perf_counter() + self.delay,
+            )
+
+        return self
+
+    @property
+    def progress(self) -> float:
+        if self._next is None:
+            return 1
+
+        _, next_time = self._next
+
+        if (cur_time := time.perf_counter()) >= next_time:
+            return 1
+
+        return min(1, max(0, 1 - (next_time - cur_time) / self.delay))
+
+    @property
+    def delay(self):
+        return gcv(self._delay)
+
+    @property
+    def is_interpolated(self):
+        return self._next is not None

FloriaKit/utils/logging.py

@@ -0,0 +1,42 @@
+import typing as t
+import logging
+
+
+_logger_level_ann = t.Literal[
+    'debug',
+    'info',
+    'warning',
+    'error',
+    'critical',
+]
+
+_logger_level_map: dict[_logger_level_ann, int] = {
+    'debug': logging.DEBUG,
+    'info': logging.INFO,
+    'warning': logging.WARNING,
+    'error': logging.ERROR,
+    'critical': logging.CRITICAL,
+}
+
+
+def create(
+    name: str,
+    level: int | _logger_level_ann,
+    terminal_format: logging.Formatter | str | None = None,
+) -> logging.Logger:
+    level_ = _logger_level_map[level] if isinstance(level, str) else level
+
+    logger = logging.Logger(name, level_)
+
+    terminal_handler = logging.StreamHandler()
+    terminal_handler.setLevel(level_)
+    if terminal_format is not None:
+        terminal_handler.setFormatter(
+            terminal_format
+            if isinstance(terminal_format, logging.Formatter)
+            else logging.Formatter(terminal_format)
+        )
+
+    logger.addHandler(terminal_handler)
+
+    return logger

FloriaKit/utils/matrix.py

@@ -0,0 +1,70 @@
+import typing as t
+from pyglm import glm
+
+if t.TYPE_CHECKING:
+    from .. import hints
+
+
+def model_matrix(
+    position: 'hints.pos3f',
+    angle: 'hints.quaternion',
+    scale: 'hints.scale3f',
+) -> 'hints.mat4x4':
+    return (
+        glm.translate(
+            glm.mat4(1),
+            glm.vec3(*position),
+        )
+        * glm.mat4_cast(
+            angle,
+        )
+        * glm.scale(
+            glm.mat4(1.0),
+            glm.vec3(*scale),
+        )
+    ).to_tuple()  # pyright: ignore[reportReturnType]
+
+
+def view_matrix(
+    position: 'hints.pos3f',
+    angle: 'hints.quaternion',
+) -> 'hints.mat4x4':
+    return glm.lookAt(
+        position,
+        glm.vec3(*position) + (rotation_glm := glm.quat(*angle)) * (0.0, 0.0, -1.0),
+        rotation_glm * (0.0, 1.0, 0.0),
+    ).to_tuple()
+
+
+def ortho_projection_matrix(
+    size: 'hints.size2f',
+    near_far: tuple[float, float],
+    zoom: float = 1,
+) -> 'hints.mat4x4':
+    width, height = size
+
+    left = -width / 2 / zoom
+    right = width / 2 / zoom
+    bottom = -height / 2 / zoom
+    top = height / 2 / zoom
+
+    return glm.ortho(
+        left,
+        right,
+        bottom,
+        top,
+        *near_far,
+    ).to_tuple()
+
+
+def perspecrive_projection_matrix(
+    fov: float,
+    aspect: float,
+    near_far: tuple[float, float],
+    zoom: float = 1,
+) -> 'hints.mat4x4':
+    return glm.perspective(
+        glm.radians(fov / zoom),
+        aspect,
+        *near_far,
+    ).to_tuple()