jetpytools 1.7.4__py3-none-any.whl → 2.0.0__py3-none-any.whl

jetpytools/types/utils.py

@@ -4,28 +4,28 @@ import sys
 from contextlib import suppress
 from functools import wraps
 from inspect import Signature
-from inspect import _empty as empty_param
 from typing import (
     TYPE_CHECKING,
     Any,
     Callable,
     ClassVar,
     Concatenate,
-    Generator,
     Generic,
     Iterable,
     Iterator,
     Mapping,
     NoReturn,
+    ParamSpec,
     Protocol,
+    Self,
     Sequence,
     cast,
     overload,
 )
 
-from typing_extensions import Self, TypeVar, deprecated
+from typing_extensions import TypeVar, deprecated
 
-from .builtins import F0, F1, P0, P1, R0, T0, KwargsT, P, R, R0_co, R1_co, R_co, T, T0_co, T1_co, T_co
+from .builtins import KwargsT
 
 __all__ = [
     "KwargsNotNone",
@@ -38,12 +38,11 @@ __all__ = [
     "get_subclasses",
     "inject_kwargs_params",
     "inject_self",
-    "to_singleton",
 ]
 # ruff: noqa: N801
 
 
-def copy_signature(target: F0, /) -> Callable[[Callable[..., Any]], F0]:
+def copy_signature[F: Callable[..., Any]](target: F, /) -> Callable[[Callable[..., Any]], F]:
     """
     Utility function to copy the signature of one function to another one.
 
@@ -71,292 +70,433 @@ def copy_signature(target: F0, /) -> Callable[[Callable[..., Any]], F0]:
                # another thing
     """
 
-    def decorator(wrapped: Callable[..., Any]) -> F0:
-        return cast(F0, wrapped)
+    def decorator(wrapped: Callable[..., Any]) -> F:
+        return cast(F, wrapped)
 
     return decorator
 
 
-class injected_self_func(Protocol[T_co, P, R_co]):
-    @overload
-    @staticmethod
-    def __call__(*args: P.args, **kwargs: P.kwargs) -> R_co: ...
+type _InnerInjectSelfType = dict[_InjectSelfMeta, dict[_InjectSelfMeta, _InnerInjectSelfType]]
+_inject_self_cls: _InnerInjectSelfType = {}
 
-    @overload
-    @staticmethod
-    def __call__(self: T_co, *args: P.args, **kwargs: P.kwargs) -> R_co:  # type: ignore[misc]
-        ...
 
-    @overload
-    @staticmethod
-    def __call__(cls: type[T_co], *args: P.args, **kwargs: P.kwargs) -> R_co: ...
+class _InjectSelfMeta(type):
+    """
+    Metaclass used to manage subclass relationships and type flattening for the `inject_self` hierarchy.
+    """
+
+    _subclasses: frozenset[_InjectSelfMeta]
+    """All descendant metaclasses of a given `inject_self` subclass."""
 
+    def __new__[MetaSelf: _InjectSelfMeta](
+        mcls: type[MetaSelf], name: str, bases: tuple[type, ...], namespace: dict[str, Any], /, **kwargs: Any
+    ) -> MetaSelf:
+        cls = super().__new__(mcls, name, bases, namespace, **kwargs)
 
-self_objects_cache = dict[Any, Any]()
+        clsd = _inject_self_cls.setdefault(cls, {})
 
+        for k, v in _inject_self_cls.items():
+            if k in namespace.values():
+                clsd[k] = v
 
-class inject_self_base(Generic[T_co, P, R_co]):
-    cache: bool | None
-    signature: Signature | None
-    init_kwargs: list[str] | None
-    first_key: str | None
+        cls._subclasses = frozenset(cls._flatten_cls())
 
-    def __init__(self, function: Callable[Concatenate[T_co, P], R_co], /, *, cache: bool = False) -> None:
+        return cls
+
+    def _flatten_cls(cls, d: _InnerInjectSelfType | None = None) -> Iterator[_InjectSelfMeta]:
         """
-        Wrap ``function`` to always have a self provided to it.
+        Recursively flatten and yield all nested inject_self metaclass relationships.
 
-        :param function:    Method to wrap.
-        :param cache:       Whether to cache the self object.
+        :param d:   Optional inner dictionary representing the hierarchy level.
+        :yield:     Each `_InjectSelfMeta` subclass found in the hierarchy.
         """
+        if d is None:
+            d = _inject_self_cls[cls]
 
-        self.cache = self.init_kwargs = None
+        for k, v in d.items():
+            yield k
+            yield from cls._flatten_cls(v)
 
-        if isinstance(self, inject_self.cached):
-            self.cache = True
+    def __instancecheck__(cls, instance: Any) -> bool:
+        """Allow isinstance() checks to succeed for any flattened subclass."""
+        return any(type.__instancecheck__(t, instance) for t in cls._subclasses)
 
-        self.function = function
+    def __subclasscheck__(cls, subclass: type) -> bool:
+        """Allow issubclass() checks to succeed for any flattened subclass."""
+        return any(type.__subclasscheck__(t, subclass) for t in cls._subclasses)
 
-        self.signature = self.first_key = self.init_kwargs = None
 
-        self.args = tuple[Any]()
-        self.kwargs = dict[str, Any]()
+_T = TypeVar("_T")
+_T0 = TypeVar("_T0")
 
-        self.clean_kwargs = False
+_T_co = TypeVar("_T_co", covariant=True)
+_T0_co = TypeVar("_T0_co", covariant=True)
+_T1_co = TypeVar("_T1_co", covariant=True)
 
-    def __get__(
-        self,
-        class_obj: type[T] | T | None,
-        class_type: type[T | type[T]] | Any,  # type: ignore[valid-type]
-    ) -> injected_self_func[T_co, P, R_co]:
-        if not self.signature or not self.first_key:
-            self.signature = Signature.from_callable(self.function, eval_str=True)
-            self.first_key = next(iter(list(self.signature.parameters.keys())), None)
-
-            if isinstance(self, inject_self.init_kwargs):
-                from ..exceptions import CustomValueError
+_R_co = TypeVar("_R_co", covariant=True)
+_R0_co = TypeVar("_R0_co", covariant=True)
+_R1_co = TypeVar("_R1_co", covariant=True)
 
-                if 4 not in {x.kind for x in self.signature.parameters.values()}:
-                    raise CustomValueError(
-                        "This function hasn't got any kwargs!", "inject_self.init_kwargs", self.function
-                    )
-
-                self.init_kwargs = list[str](k for k, x in self.signature.parameters.items() if x.kind != 4)
-
-        @wraps(self.function)
-        def _wrapper(*args: Any, **kwargs: Any) -> Any:
-            first_arg = (args[0] if args else None) or (kwargs.get(self.first_key, None) if self.first_key else None)
-
-            if first_arg and (
-                (is_obj := isinstance(first_arg, class_type))
-                or isinstance(first_arg, type(class_type))
-                or first_arg is class_type
-            ):
-                obj = first_arg if is_obj else first_arg()
-                if args:
-                    args = args[1:]
-                elif kwargs and self.first_key:
-                    kwargs.pop(self.first_key)
-            elif class_obj is None:
-                if self.cache:
-                    if class_type not in self_objects_cache:
-                        obj = self_objects_cache[class_type] = class_type(*self.args, **self.kwargs)
-                    else:
-                        obj = self_objects_cache[class_type]
-                elif self.init_kwargs:
-                    obj = class_type(
-                        *self.args, **(self.kwargs | {k: v for k, v in kwargs.items() if k not in self.init_kwargs})
-                    )
-                    if self.clean_kwargs:
-                        kwargs = {k: v for k, v in kwargs.items() if k in self.init_kwargs}
-                else:
-                    obj = class_type(*self.args, **self.kwargs)
+_T_Any = TypeVar("_T_Any", default=Any)
+_T0_Any = TypeVar("_T0_Any", default=Any)
+
+_P = ParamSpec("_P")
+_P0 = ParamSpec("_P0")
+_P1 = ParamSpec("_P1")
+
+
+class _InjectedSelfFunc(Protocol[_T_co, _P, _R_co]):
+    """
+    Protocol defining the callable interface for wrapped functions under `inject_self`.
+
+    This allows the injected function to be called in any of the following forms:
+    - As a normal function: `f(*args, **kwargs)`
+    - As a bound method: `f(self, *args, **kwargs)`
+    - As a class method: `f(cls, *args, **kwargs)`
+    """
+
+    @overload
+    def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> _R_co: ...
+    @overload
+    def __call__(_self, self: _T_co, /, *args: _P.args, **kwargs: _P.kwargs) -> _R_co: ...  # type: ignore[misc]  # noqa: N805
+    @overload
+    def __call__(self, cls: type[_T_co], /, *args: _P.args, **kwargs: _P.kwargs) -> _R_co: ...  # pyright: ignore[reportGeneralTypeIssues]
+
+
+_self_objects_cache = dict[type[Any], Any]()
+
+
+class _InjectSelfBase(Generic[_T_co, _P, _R_co]):
+    """
+    Base descriptor implementation for `inject_self`.
+    """
+
+    __isabstractmethod__ = False
+    __slots__ = ("_function", "_init_signature", "_signature", "args", "kwargs")
+
+    _signature: Signature | None
+    _init_signature: Signature | None
+
+    def __init__(self, function: Callable[Concatenate[_T_co, _P], _R_co], /, *args: Any, **kwargs: Any) -> None:
+        """
+        Initialize the inject_self descriptor.
+
+        :param function:    The function or method to wrap.
+        :param *args:       Positional arguments to pass when instantiating the target class.
+        :param **kwargs:    Keyword arguments to pass when instantiating the target class.
+        """
+        self._function = function
+
+        self._signature = self._init_signature = None
+
+        self.args = args
+        self.kwargs = kwargs
+
+    def __get__[T](self, instance: T | None, owner: type[T]) -> _InjectedSelfFunc[T, _P, _R_co]:  # pyright: ignore[reportGeneralTypeIssues]
+        """
+        Return a wrapped callable that automatically injects an instance as the first argument when called.
+        """
+
+        @wraps(self._function)
+        def _wrapper(*args: Any, **kwargs: Any) -> _R_co:
+            """
+            Call wrapper that performs the actual injection of `self`.
+            """
+            if args and isinstance((first_arg := args[0]), (owner, type(owner))):
+                # Instance or class explicitly provided as first argument
+                obj = first_arg if isinstance(first_arg, owner) else first_arg()  # type: ignore[operator]
+                args = args[1:]
+            elif instance is None:
+                # Accessed via class
+                obj, kwargs = self._handle_class_access(owner, kwargs)
             else:
-                obj = class_obj
+                # Accessed via instance
+                obj = instance
 
-            return self.function(obj, *args, **kwargs)  # type: ignore
+            return self._function(obj, *args, **kwargs)  # type: ignore[arg-type]
 
         return _wrapper
 
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R_co:
-        return self.__get__(None, self)(*args, **kwargs)
+    def _handle_class_access[T](self, owner: type[T], kwargs: dict[str, Any]) -> tuple[T, dict[str, Any]]:
+        """
+        Handle logic when the descriptor is accessed from the class level.
+
+        :param owner:   The class object owning the descriptor.
+        :param kwargs:  Keyword arguments passed to the wrapped function.
+        :return:        A tuple of `(self_object, updated_kwargs)`.
+        """
+        if isinstance(self, inject_self.cached):
+            # Cached instance creation
+            try:
+                return _self_objects_cache[owner], kwargs
+            except KeyError:
+                return _self_objects_cache.setdefault(owner, owner()), kwargs
+
+        if isinstance(self, (inject_self.init_kwargs, inject_self.init_kwargs.clean)):
+            # Constructor accepts forwarded kwargs
+            has_kwargs = any(
+                param.kind in (param.VAR_KEYWORD, param.KEYWORD_ONLY)
+                for param in self.__signature__.parameters.values()
+            )
+
+            if not has_kwargs:
+                from ..exceptions import CustomValueError
+
+                raise CustomValueError(
+                    f"Function {self._function.__name__} doesn't accept keyword arguments.",
+                    "inject_self.init_kwargs",
+                    self._function,
+                )
+
+            if not self._init_signature:
+                self._init_signature = Signature.from_callable(owner)
+
+            init_kwargs = self.kwargs | {k: kwargs[k] for k in kwargs.keys() & self._init_signature.parameters.keys()}
+
+            obj = owner(*self.args, **init_kwargs)
+
+            if isinstance(self, inject_self.init_kwargs.clean):
+                # Clean up forwarded kwargs
+                kwargs = {k: v for k, v in kwargs.items() if k not in self._init_signature.parameters}
+
+            return obj, kwargs
+
+        return owner(*self.args, **self.kwargs), kwargs
+
+    @property
+    def __func__(self) -> Callable[Concatenate[_T_co, _P], _R_co]:
+        """Return the original wrapped function."""
+        return self._function
 
     @property
     def __signature__(self) -> Signature:
-        return Signature.from_callable(self.function)
+        """Return (and cache) the signature of the wrapped function."""
+        if not self._signature:
+            self._signature = Signature.from_callable(self._function)
+        return self._signature
 
     @classmethod
-    def with_args(
+    def with_args[T0, **P0, R0](
         cls, *args: Any, **kwargs: Any
-    ) -> Callable[[Callable[Concatenate[T0_co, P0], R0_co]], inject_self[T0_co, P0, R0_co]]:
-        """Provide custom args to instantiate the ``self`` object with."""
+    ) -> Callable[[Callable[Concatenate[T0, P0], R0]], inject_self[T0, P0, R0]]:
+        """
+        Decorator factory to construct an `inject_self` or subclass (`cached`, `init_kwargs`, etc.)
+        with specific instantiation arguments.
+        """
 
+        # TODO: The precise subclass type cannot be expressed yet when the class is itself generic.
         def _wrapper(function: Callable[Concatenate[T0, P0], R0]) -> inject_self[T0, P0, R0]:
-            inj = cls(function)  # type: ignore
-            inj.args = args
-            inj.kwargs = kwargs
-            return inj  # type: ignore
+            return cls(function, *args, **kwargs)  # type: ignore[return-value, arg-type]
 
         return _wrapper
 
 
-class inject_self(inject_self_base[T_co, P, R_co]):
-    """Wrap a method so it always has a constructed ``self`` provided to it."""
+class inject_self(_InjectSelfBase[_T_co, _P, _R_co], metaclass=_InjectSelfMeta):
+    """
+    Descriptor that ensures the wrapped function always has a constructed `self`.
+
+    When accessed via a class, it will automatically instantiate an object before calling the function.
+    When accessed via an instance, it simply binds.
+
+    Subclasses such as `cached`, `init_kwargs`, and `init_kwargs.clean`
+    define variations in how the injected object is created or reused.
+    """
+
+    __slots__ = ()
 
-    class cached(inject_self_base[T0_co, P0, R0_co]):
+    class cached(_InjectSelfBase[_T0_co, _P0, _R0_co], metaclass=_InjectSelfMeta):
         """
-        Wrap a method so it always has a constructed ``self`` provided to it.
-        Once ``self`` is constructed, it will be reused.
+        Variant of `inject_self` that caches the constructed instance.
+
+        The first time the method is accessed via the class, a `self` object is created and stored.
+        Subsequent calls reuse it.
         """
 
-        class property(Generic[T1_co, R1_co]):
-            def __init__(self, function: Callable[[T1_co], R1_co]) -> None:
-                self.function = inject_self(function)
+        __slots__ = ()
+
+        class property(Generic[_T1_co, _P1, _R1_co], metaclass=_InjectSelfMeta):
+            """Property variant of `inject_self.cached` that auto-calls the wrapped method."""
 
-            def __get__(self, class_obj: type[T1_co] | T1_co | None, class_type: type[T1_co] | T1_co) -> R1_co:
-                return self.function.__get__(class_obj, class_type)()
+            __slots__ = ("__func__",)
 
-    class init_kwargs(inject_self_base[T0_co, P0, R0_co]):
+            def __init__(self, function: Callable[[_T1_co], _R1_co], /) -> None:
+                self.__func__ = inject_self.cached(function)
+
+            def __get__(self, instance: _T1_co | None, owner: type[_T1_co]) -> _R1_co:  # pyright: ignore[reportGeneralTypeIssues]
+                """Return the result of calling the cached method without arguments."""
+                return self.__func__.__get__(instance, owner)()
+
+    class init_kwargs(_InjectSelfBase[_T0_co, _P0, _R0_co], metaclass=_InjectSelfMeta):
         """
-        Wrap a method so it always has a constructed ``self`` provided to it.
-        When constructed, kwargs to the function will be passed to the constructor.
+        Variant of `inject_self` that forwards function keyword arguments to the class constructor
+        when instantiating `self`.
         """
 
-        @classmethod
-        def clean(cls, function: Callable[Concatenate[T1_co, P1], R1_co]) -> inject_self[T1_co, P1, R1_co]:
-            """Wrap a method, pass kwargs to the constructor and remove them from actual **kwargs."""
-            inj = cls(function)  # type: ignore
-            inj.clean_kwargs = True
-            return inj  # type: ignore
+        __slots__ = ()
 
-    class property(Generic[T0_co, R0_co]):
-        def __init__(self, function: Callable[[T0_co], R0_co]) -> None:
-            self.function = inject_self(function)
+        class clean(_InjectSelfBase[_T1_co, _P1, _R1_co], metaclass=_InjectSelfMeta):
+            """
+            Variant of `inject_self.init_kwargs` that removes any forwarded kwargs from the final function call
+            after using them for construction.
+            """
 
-        def __get__(self, class_obj: type[T0_co] | T0_co | None, class_type: type[T0_co] | T0_co) -> R0_co:
-            return self.function.__get__(class_obj, class_type)()
+            __slots__ = ()
 
+    class property(Generic[_T0_co, _R0_co], metaclass=_InjectSelfMeta):
+        """Property variant of `inject_self` that auto-calls the wrapped method."""
 
-class inject_kwargs_params_base_func(Generic[T_co, P, R_co]):
-    def __call__(self: T_co, *args: P.args, **kwargs: P.kwargs) -> R_co:
-        raise NotImplementedError
+        __slots__ = ("__func__",)
 
+        def __init__(self, function: Callable[[_T0_co], _R0_co], /) -> None:
+            self.__func__ = inject_self(function)
 
-class inject_kwargs_params_base(Generic[T_co, P, R_co]):
-    signature: Signature | None
+        def __get__(self, instance: _T0_co | None, owner: type[_T0_co]) -> _R0_co:  # pyright: ignore[reportGeneralTypeIssues]
+            """Return the result of calling the injected method without arguments."""
+            return self.__func__.__get__(instance, owner)()
 
-    _kwargs_name = "kwargs"
 
-    def __init__(self, function: Callable[Concatenate[T_co, P], R_co]) -> None:
-        self.function = function
+class _InjectKwargsParamsBase(Generic[_T_co, _P, _R_co]):
+    """
+    Base descriptor implementation for `inject_kwargs_params`.
+    """
 
-        self.signature = None
+    __isabstractmethod__ = False
+    __slots__ = ("_function", "_signature")
 
-    def __get__(self, class_obj: T, class_type: type[T]) -> inject_kwargs_params_base_func[T_co, P, R_co]:
-        if not self.signature:
-            self.signature = Signature.from_callable(self.function, eval_str=True)
+    _kwargs_name = "kwargs"
+    _signature: Signature | None
 
-            if (
-                isinstance(self, inject_kwargs_params.add_to_kwargs)  # type: ignore[arg-type]
-                and (4 not in {x.kind for x in self.signature.parameters.values()})
-            ):
-                from ..exceptions import CustomValueError
+    def __init__(self, func: Callable[Concatenate[_T_co, _P], _R_co], /) -> None:
+        """
+        Initialize the inject_kwargs_params descriptor.
 
-                raise CustomValueError(
-                    "This function hasn't got any kwargs!", "inject_kwargs_params.add_to_kwargs", self.function
-                )
+        :param function:    The target function or method whose parameters will be injected
+                            from the instance's `self.kwargs` mapping.
+        """
+        self._function = func
+        self._signature = None
 
-        this = self
+    @overload
+    def __get__(self, instance: None, owner: type[Any]) -> Self: ...
+    @overload
+    def __get__(self, instance: Any, owner: type[Any]) -> Callable[_P, _R_co]: ...
+    def __get__(self, instance: Any | None, owner: type[Any]) -> Self | Callable[_P, _R_co]:
+        """
+        Descriptor binding logic.
 
-        @wraps(self.function)
-        def _wrapper(self: Any, *_args: Any, **kwargs: Any) -> R_co:
-            assert this.signature
+        When accessed via an instance, returns a wrapped function that injects values from `instance.<_kwargs_name>`
+        into matching function parameters.
 
-            if class_obj and not isinstance(self, class_type):
-                _args = (self, *_args)
-                self = class_obj
+        When accessed via the class, returns the descriptor itself.
+        """
+        if instance is None:
+            return self
 
-            if not hasattr(self, this._kwargs_name):
-                from ..exceptions import CustomRuntimeError
+        if not hasattr(instance, self._kwargs_name):
+            from ..exceptions import CustomRuntimeError
 
-                raise CustomRuntimeError(
-                    f'This class doesn\'t have any "{this._kwargs_name}" attribute!', reason=self.__class__
-                )
+            raise CustomRuntimeError(
+                f'Missing attribute "{self._kwargs_name}" on {type(instance).__name__}.', owner, self.__class__
+            )
 
-            this_kwargs = self.kwargs.copy()
-            args, n_args = list(_args), len(_args)
+        @wraps(self._function)
+        def wrapper(*args: Any, **kwargs: Any) -> _R_co:
+            """
+            Wrapper that performs parameter injection before calling the wrapped function.
+            """
+            injectable_kwargs = dict(getattr(instance, self._kwargs_name))
 
-            for i, (key, value) in enumerate(this.signature.parameters.items()):
-                if key not in this_kwargs:
-                    continue
+            if not injectable_kwargs:
+                return self._function(instance, *args, **kwargs)
 
-                kw_value = this_kwargs.pop(key)
+            args_list = [instance, *args]
+            kwargs = kwargs.copy()
 
-                if value.default is empty_param:
+            for i, (name, param) in enumerate(self.__signature__.parameters.items()):
+                if name not in injectable_kwargs:
                     continue
 
-                if i < n_args:
-                    if args[i] != value.default:
-                        continue
+                value_from_kwargs = injectable_kwargs.pop(name)
 
-                    args[i] = kw_value
+                if i < len(args_list):
+                    # Positional arg case
+                    if args_list[i] == param.default:
+                        args_list[i] = value_from_kwargs
                 else:
-                    if key in kwargs and kwargs[key] != value.default:
-                        continue
+                    # Keyword arg case
+                    if kwargs.get(name, param.default) == param.default:
+                        kwargs[name] = value_from_kwargs
 
-                    kwargs[key] = kw_value
+            # Merge leftover kwargs if subclass allows
+            if isinstance(self, inject_kwargs_params.add_to_kwargs):
+                kwargs |= injectable_kwargs
 
-            if isinstance(this, inject_kwargs_params.add_to_kwargs):  # type: ignore[arg-type]
-                kwargs |= this_kwargs
+            return self._function(*tuple(args_list), **kwargs)
 
-            return this.function(self, *args, **kwargs)
+        return wrapper
 
-        return _wrapper  # type: ignore
-
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R_co:
-        return self.__get__(None, self)(*args, **kwargs)  # type: ignore
+    @property
+    def __func__(self) -> Callable[Concatenate[_T_co, _P], _R_co]:
+        """Return the original wrapped function."""
+        return self._function
 
     @property
     def __signature__(self) -> Signature:
-        return Signature.from_callable(self.function)
+        """Return (and cache) the signature of the wrapped function."""
+        if not self._signature:
+            self._signature = Signature.from_callable(self._function)
+        return self._signature
 
     @classmethod
-    def with_name(cls, kwargs_name: str) -> type[inject_kwargs_params]:  # type: ignore
-        class _inner(inject_kwargs_params):  # type: ignore
-            _kwargs_name = kwargs_name
+    def with_name[T0, **P0, R0](
+        cls, kwargs_name: str = "kwargs"
+    ) -> Callable[[Callable[Concatenate[T0, P0], R0]], inject_kwargs_params[T0, P0, R0]]:
+        """
+        Decorator factory that creates a subclass of `inject_kwargs_params` with a custom name
+        for the keyword argument store.
+        """
+        ns = cls.__dict__.copy()
+        ns["_kwargs_name"] = kwargs_name
 
-        return _inner
+        custom_cls = type(cls.__name__, cls.__bases__, ns)
 
+        # TODO: The precise subclass type cannot be expressed yet when the class is itself generic.
+        def _wrapper(function: Callable[Concatenate[T0, P0], R0]) -> inject_kwargs_params[T0, P0, R0]:
+            return custom_cls(function)  # pyright: ignore[reportReturnType, reportArgumentType]
 
-if TYPE_CHECKING:  # love you mypy...
+        return _wrapper
 
-    class _add_to_kwargs:
-        def __call__(self, func: F1) -> F1: ...
 
-    class _inject_kwargs_params:
-        def __call__(self, func: F0) -> F0: ...
+class inject_kwargs_params[T, **P, R](_InjectKwargsParamsBase[T, P, R]):
+    """
+    Descriptor that injects parameters into functions based on an instance's keyword mapping.
 
-        add_to_kwargs = _add_to_kwargs()
+    When a method wrapped with `@inject_kwargs_params` is called, the descriptor inspects the function's signature
+    and replaces any arguments matching keys in `self.kwargs` (or another mapping defined by `_kwargs_name`)
+    if their values equal the parameter's default.
+    """
 
-    inject_kwargs_params = _inject_kwargs_params()
-else:
+    __slots__ = ()
 
-    class inject_kwargs_params(Generic[T, P, R], inject_kwargs_params_base[T, P, R]):
-        class add_to_kwargs(Generic[T0, P0, R0], inject_kwargs_params_base[T0, P0, R0]): ...
+    class add_to_kwargs[T0, **P0, R0](_InjectKwargsParamsBase[T0, P0, R0]):
+        """
+        Variant of `inject_kwargs_params` that merges unused entries from `self.kwargs` into the keyword arguments
+        passed to the target function.
 
+        This allows additional context or configuration values to be forwarded without requiring explicit parameters.
+        """
 
-class complex_hash(Generic[T]):
-    """
-    Decorator for classes to add a ``__hash__`` method to them.
+        __slots__ = ()
 
-    Especially useful for NamedTuples.
-    """
 
-    def __new__(cls, class_type: T) -> T:  # type: ignore
-        class inner_class_type(class_type):  # type: ignore
-            def __hash__(self) -> int:
-                return complex_hash.hash(self.__class__.__name__, *(getattr(self, key) for key in self.__annotations__))
+class _ComplexHash[**P, R]:
+    __slots__ = "func"
 
-        return inner_class_type  # type: ignore
+    def __init__(self, func: Callable[P, R]) -> None:
+        self.func = func
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        return self.func(*args, **kwargs)
 
     @staticmethod
     def hash(*args: Any) -> int:
@@ -380,7 +520,24 @@ class complex_hash(Generic[T]):
         return hash("_".join(values))
 
 
-def get_subclasses(family: type[T], exclude: Sequence[type[T]] = []) -> list[type[T]]:
+@_ComplexHash
+def complex_hash[T](cls: type[T]) -> type[T]:
+    """
+    Decorator for classes to add a ``__hash__`` method to them.
+
+    Especially useful for NamedTuples.
+    """
+
+    def __hash__(self: T) -> int:  # noqa: N807
+        return complex_hash.hash(self.__class__.__name__, *(getattr(self, key) for key in self.__annotations__))
+
+    ns = cls.__dict__.copy()
+    ns["__hash__"] = __hash__
+
+    return type(cls.__name__, (cls,), ns)  # pyright: ignore[reportReturnType]
+
+
+def get_subclasses[T](family: type[T], exclude: Sequence[type[T]] = []) -> list[type[T]]:
     """
     Get all subclasses of a given type.
 
@@ -391,7 +548,7 @@ def get_subclasses(family: type[T], exclude: Sequence[type[T]] = []) -> list[typ
     :return:        List of all subclasses of "family".
     """
 
-    def _subclasses(cls: type[T]) -> Generator[type[T], None, None]:
+    def _subclasses(cls: type[T]) -> Iterator[type[T]]:
         for subclass in cls.__subclasses__():
             yield from _subclasses(subclass)
             if subclass in exclude:
@@ -401,24 +558,20 @@ def get_subclasses(family: type[T], exclude: Sequence[type[T]] = []) -> list[typ
     return list(set(_subclasses(family)))
 
 
-_T_Any = TypeVar("_T_Any", default=Any)
-_T0_Any = TypeVar("_T0_Any", default=Any)
-
-
-class classproperty_base(Generic[T, R_co, _T_Any]):
+class classproperty_base(Generic[_T, _R_co, _T_Any]):
     __isabstractmethod__: bool = False
 
-    fget: Callable[[type[T]], R_co]
-    fset: Callable[Concatenate[type[T], _T_Any, ...], None] | None
-    fdel: Callable[[type[T]], None] | None
+    fget: Callable[[type[_T]], _R_co]
+    fset: Callable[Concatenate[type[_T], _T_Any, ...], None] | None
+    fdel: Callable[[type[_T]], None] | None
 
     def __init__(
         self,
-        fget: Callable[[type[T]], R_co] | classmethod[T, ..., R_co],
-        fset: Callable[Concatenate[type[T], _T_Any, ...], None]
-        | classmethod[T, Concatenate[_T_Any, ...], None]
+        fget: Callable[[type[_T]], _R_co] | classmethod[_T, ..., _R_co],
+        fset: Callable[Concatenate[type[_T], _T_Any, ...], None]
+        | classmethod[_T, Concatenate[_T_Any, ...], None]
         | None = None,
-        fdel: Callable[[type[T]], None] | classmethod[T, ..., None] | None = None,
+        fdel: Callable[[type[_T]], None] | classmethod[_T, ..., None] | None = None,
         doc: str | None = None,
     ) -> None:
         self.fget = fget.__func__ if isinstance(fget, classmethod) else fget
@@ -431,7 +584,7 @@ class classproperty_base(Generic[T, R_co, _T_Any]):
     def __set_name__(self, owner: object, name: str) -> None:
         self.__name__ = name
 
-    def _get_cache(self, type_: type[T]) -> dict[str, Any]:
+    def _get_cache(self, type_: type[_T]) -> dict[str, Any]:
         cache_key = getattr(self, "cache_key")
 
         if not hasattr(type_, cache_key):
@@ -439,7 +592,7 @@ class classproperty_base(Generic[T, R_co, _T_Any]):
 
         return getattr(type_, cache_key)
 
-    def __get__(self, obj: T | None, type_: type[T] | None = None) -> R_co:
+    def __get__(self, obj: _T | None, type_: type[_T] | None = None) -> _R_co:
         if type_ is None and obj is not None:
             type_ = type(obj)
         elif type_ is None:
@@ -455,7 +608,7 @@ class classproperty_base(Generic[T, R_co, _T_Any]):
         cache[self.__name__] = value
         return value
 
-    def __set__(self, obj: T, value: _T_Any) -> None:
+    def __set__(self, obj: _T, value: _T_Any) -> None:
         if not self.fset:
             raise AttributeError(
                 f'classproperty with getter "{self.__name__}" of "{obj.__class__.__name__}" object has no setter.'
@@ -471,7 +624,7 @@ class classproperty_base(Generic[T, R_co, _T_Any]):
 
         self.fset(type_, value)
 
-    def __delete__(self, obj: T) -> None:
+    def __delete__(self, obj: _T) -> None:
         if not self.fdel:
             raise AttributeError(
                 f'classproperty with getter "{self.__name__}" of "{obj.__class__.__name__}" object has no deleter.'
@@ -488,12 +641,12 @@ class classproperty_base(Generic[T, R_co, _T_Any]):
         self.fdel(type_)
 
 
-class classproperty(classproperty_base[T, R_co, _T_Any]):
+class classproperty(classproperty_base[_T, _R_co, _T_Any]):
     """
     A combination of `classmethod` and `property`.
     """
 
-    class cached(classproperty_base[T0, R0_co, _T0_Any]):
+    class cached(classproperty_base[_T0, _R0_co, _T0_Any]):
         """
         A combination of `classmethod` and `property`.
 
@@ -526,7 +679,7 @@ class classproperty(classproperty_base[T, R_co, _T_Any]):
                     del cache[name]
 
 
-class cachedproperty(property, Generic[R_co, _T_Any]):
+class cachedproperty(property, Generic[_R_co, _T_Any]):
     """
     Wrapper for a one-time get property, that will be cached.
 
@@ -547,17 +700,17 @@ class cachedproperty(property, Generic[R_co, _T_Any]):
 
         def __init__(
             self,
-            fget: Callable[[Any], R_co],
+            fget: Callable[[Any], _R_co],
             fset: Callable[[Any, _T_Any], None] | None = None,
             fdel: Callable[[Any], None] | None = None,
             doc: str | None = None,
         ) -> None: ...
 
-        def getter(self, fget: Callable[..., R_co]) -> cachedproperty[R_co, _T_Any]: ...
+        def getter(self, fget: Callable[..., _R_co]) -> cachedproperty[_R_co, _T_Any]: ...
 
-        def setter(self, fset: Callable[[Any, _T_Any], None]) -> cachedproperty[R_co, _T_Any]: ...
+        def setter(self, fset: Callable[[Any, _T_Any], None]) -> cachedproperty[_R_co, _T_Any]: ...
 
-        def deleter(self, fdel: Callable[..., None]) -> cachedproperty[R_co, _T_Any]: ...
+        def deleter(self, fdel: Callable[..., None]) -> cachedproperty[_R_co, _T_Any]: ...
 
     if sys.version_info < (3, 13):
 
@@ -569,7 +722,7 @@ class cachedproperty(property, Generic[R_co, _T_Any]):
     def __get__(self, instance: None, owner: type | None = None) -> Self: ...
 
     @overload
-    def __get__(self, instance: Any, owner: type | None = None) -> R_co: ...
+    def __get__(self, instance: Any, owner: type | None = None) -> _R_co: ...
 
     def __get__(self, instance: Any, owner: type | None = None) -> Any:
         if instance is None:
@@ -629,18 +782,20 @@ class cachedproperty(property, Generic[R_co, _T_Any]):
 class KwargsNotNone(KwargsT):
     """Remove all None objects from this kwargs dict."""
 
-    if not TYPE_CHECKING:
-
-        def __new__(cls, *args: Any, **kwargs: Any) -> Self:
-            return KwargsT(**{key: value for key, value in KwargsT(*args, **kwargs).items() if value is not None})
+    @copy_signature(KwargsT.__init__)
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__({key: value for key, value in dict(*args, **kwargs).items() if value is not None})
 
 
 class SingletonMeta(type):
     _instances: ClassVar[dict[type[Any], Any]] = {}
     _singleton_init: bool
 
-    def __new__(cls, name: str, bases: tuple[type, ...], namespace: dict[str, Any], **kwargs: Any) -> SingletonMeta:
-        return type.__new__(cls, name, bases, namespace | {"_singleton_init": kwargs.pop("init", False)})
+    def __new__[MetaSelf: SingletonMeta](
+        mcls: type[MetaSelf], name: str, bases: tuple[type, ...], namespace: dict[str, Any], **kwargs: Any
+    ) -> MetaSelf:
+        namespace["_singleton_init"] = kwargs.pop("init", False)
+        return super().__new__(mcls, name, bases, namespace, **kwargs)
 
     def __call__(cls, *args: Any, **kwargs: Any) -> SingletonMeta:
         if cls not in cls._instances:
@@ -654,34 +809,7 @@ class SingletonMeta(type):
 class Singleton(metaclass=SingletonMeta):
     """Handy class to inherit to have the SingletonMeta metaclass."""
 
-
-class to_singleton_impl:
-    _ts_args = tuple[str, ...]()
-    _ts_kwargs: Mapping[str, Any] = {}
-    _add_classes = tuple[type, ...]()
-
-    def __new__(_cls, cls: type[T]) -> T:  # type: ignore
-        if _cls._add_classes:
-
-            class rcls(cls, *_cls._add_classes):  # type: ignore
-                ...
-        else:
-            rcls = cls  # type: ignore
-
-        return rcls(*_cls._ts_args, **_cls._ts_kwargs)
-
-    @classmethod
-    def with_args(cls, *args: Any, **kwargs: Any) -> type[to_singleton]:
-        class _inner_singl(cls):  # type: ignore
-            _ts_args = args
-            _ts_kwargs = kwargs
-
-        return _inner_singl
-
-
-class to_singleton(to_singleton_impl):
-    class as_property(to_singleton_impl):
-        _add_classes = (property,)
+    __slots__ = ()
 
 
 class LinearRangeLut(Mapping[int, int]):
@@ -706,13 +834,14 @@ class LinearRangeLut(Mapping[int, int]):
             if self._misses_n > 2:
                 self._ranges_idx_lut = self._ranges_idx_lut[missed_hit:] + self._ranges_idx_lut[:missed_hit]
 
-        return idx
+        return idx  # pyright: ignore[reportPossiblyUnboundVariable]
 
     def __len__(self) -> int:
         return len(self.ranges)
 
     def __iter__(self) -> Iterator[int]:
-        return iter(range(len(self)))
+        for i in range(len(self)):
+            yield i
 
     def __setitem__(self, n: int, _range: range) -> NoReturn:
         raise NotImplementedError