jetpytools 1.6.5__tar.gz → 1.7.1__tar.gz

{jetpytools-1.6.5 → jetpytools-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetpytools
-Version: 1.6.5
+Version: 1.7.1
 Summary: Collection of stuff that's useful in general python programming
 Project-URL: Source Code, https://github.com/Jaded-Encoding-Thaumaturgy/jetpytools
 Project-URL: Contact, https://discord.gg/XTpc6Fa9eB

{jetpytools-1.6.5 → jetpytools-1.7.1}/jetpytools/_metadata.py

@@ -1,6 +1,6 @@
 """Collection of stuff that's useful in general python programming"""
 
-__version__ = "1.6.5"
+__version__ = "1.7.1"
 
 __author_name__, __author_email__ = "Jaded Encoding Thaumaturgy", "jaded.encoding.thaumaturgy@gmail.com"
 __maintainer_name__, __maintainer_email__ = __author_name__, __author_email__

{jetpytools-1.6.5 → jetpytools-1.7.1}/jetpytools/types/utils.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from functools import partial, wraps
+import sys
+from contextlib import suppress
+from functools import wraps
 from inspect import Signature
 from inspect import _empty as empty_param
 from typing import (
@@ -21,9 +23,9 @@ from typing import (
     overload,
 )
 
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
-from .builtins import F0, F1, P0, P1, R0, R1, T0, T1, T2, KwargsT, P, R, R0_co, R1_co, R_co, T, T0_co, T1_co, T_co
+from .builtins import F0, F1, P0, P1, R0, R1, T0, KwargsT, P, R, R0_co, R1_co, R_co, T, T0_co, T1_co, T_co
 
 __all__ = [
     "KwargsNotNone",
@@ -400,17 +402,15 @@ def get_subclasses(family: type[T], exclude: Sequence[type[T]] = []) -> list[typ
     return list(set(_subclasses(family)))
 
 
-class classproperty(Generic[T, R]):
-    """
-    Make a class property. A combination between classmethod and property.
-    """
-
+class classproperty_base(Generic[T, R_co]):
     __isabstractmethod__: bool = False
 
     def __init__(
         self,
-        fget: Callable[[type[T]], R] | classmethod[T, ..., R],
-        fset: Callable[[type[T], R], None] | classmethod[T, Concatenate[R, ...], None] | None = None,
+        fget: Callable[[type[T]], R_co] | classmethod[T, ..., R_co],
+        fset: Callable[Concatenate[type[T], Any, ...], None]
+        | classmethod[T, Concatenate[Any, ...], None]
+        | None = None,
         fdel: Callable[[type[T]], None] | classmethod[T, ..., None] | None = None,
         doc: str | None = None,
     ) -> None:
@@ -419,6 +419,7 @@ class classproperty(Generic[T, R]):
         self.fdel = self._wrap(fdel) if fdel is not None else fdel
 
         self.__doc__ = doc
+        self.__name__ = self.fget.__name__
 
     def _wrap(self, func: Callable[..., R1] | classmethod[T, P1, R1]) -> classmethod[T, P1, R1]:
         if not isinstance(func, classmethod):
@@ -426,11 +427,30 @@ class classproperty(Generic[T, R]):
 
         return func
 
-    def __get__(self, obj: T | None, type_: type | None = None) -> R:
+    def __set_name__(self, owner: object, name: str) -> None:
+        self.__name__ = name
+
+    def _get_cache(self, type_: type) -> dict[str, Any]:
+        cache_key = getattr(self, "cache_key")
+
+        if not hasattr(type_, cache_key):
+            setattr(type_, cache_key, {})
+
+        return getattr(type_, cache_key)
+
+    def __get__(self, obj: T | None, type_: type | None = None) -> R_co:
         if type_ is None:
             type_ = type(obj)
 
-        return self.fget.__get__(obj, type_)()
+        if not isinstance(self, classproperty.cached):
+            return self.fget.__get__(obj, type_)()
+
+        if self.__name__ in (cache := self._get_cache(type_)):
+            return cache[self.__name__]
+
+        value = self.fget.__get__(obj, type_)()
+        cache[self.__name__] = value
+        return value
 
     def __set__(self, obj: T, value: Any) -> None:
         if not self.fset:
@@ -438,7 +458,12 @@ class classproperty(Generic[T, R]):
                 f'classproperty with getter "{self.__name__}" of "{obj.__class__.__name__}" object has no setter.'
             )
 
-        self.fset.__get__(None, type(obj))(value)
+        type_ = type(obj)
+
+        if self.__name__ in (cache := self._get_cache(type_)):
+            del cache[self.__name__]
+
+        self.fset.__get__(None, type_)(value)
 
     def __delete__(self, obj: T) -> None:
         if not self.fdel:
@@ -446,88 +471,139 @@ class classproperty(Generic[T, R]):
                 f'classproperty with getter "{self.__name__}" of "{obj.__class__.__name__}" object has no deleter.'
             )
 
-        self.fdel.__get__(None, type(obj))()
+        type_ = type(obj)
 
-    @property
-    def __name__(self) -> str:
-        return self.fget.__name__
+        if self.__name__ in (cache := self._get_cache(type_)):
+            del cache[self.__name__]
+
+        self.fdel.__get__(None, type_)()
 
 
-class cachedproperty(property, Generic[P, R_co, T, T0, P0]):
+class classproperty(classproperty_base[T, R_co]):
     """
-    Wrapper for a one-time get property, that will be cached.
+    A combination of `classmethod` and `property`.
+    """
+
+    class cached(classproperty_base[T0, R0_co]):
+        """
+        A combination of `classmethod` and `property`.
+
+        The value is computed once and then cached in a dictionary (under `cache_key`)
+        attached to the class type. If a setter or deleter is defined and invoked,
+        the cache is cleared.
+        """
+
+        cache_key = "_jetpt_classproperty_cached"
+
+        @classmethod
+        def clear_cache(cls, type_: type, names: str | Iterable[str] | None = None) -> None:
+            """
+            Clear cached properties of an type instance.
 
-    Keep in mind two things:
+            :param type_:   The type whose cache should be cleared.
+            :param names:   Specific property names to clear. If None, all cached properties are cleared.
+            """
+            if names is None:
+                with suppress(AttributeError):
+                    getattr(type_, cls.cache_key).clear()
+                return None
 
-     * The cache is per-object. Don't hold a reference to itself or it will never get garbage collected.
-     * Your class has to either manually set __dict__[cachedproperty.cache_key]
-       or inherit from cachedproperty.baseclass.
+            from ..functions import to_arr
+
+            cache = getattr(type_, cls.cache_key, {})
+
+            for name in to_arr(names):
+                with suppress(KeyError):
+                    del cache[name]
+
+
+class cachedproperty(property, Generic[R_co]):
+    """
+    Wrapper for a one-time get property, that will be cached.
+
+    You shouldn't hold a reference to itself or it will never get garbage collected.
     """
 
     __isabstractmethod__: bool = False
 
     cache_key = "_jetpt_cachedproperty_cache"
 
+    @deprecated(
+        "The cache dict is now set automatically. You no longer need to inherit from it", category=DeprecationWarning
+    )
     class baseclass:
         """Inherit from this class to automatically set the cache dict."""
 
-        if not TYPE_CHECKING:
-
-            def __new__(cls, *args: Any, **kwargs: Any) -> None:
-                try:
-                    self = super().__new__(cls, *args, **kwargs)
-                except TypeError:
-                    self = super().__new__(cls)
-                self.__dict__.__setitem__(cachedproperty.cache_key, dict[str, Any]())
-                return self
-
     if TYPE_CHECKING:
 
         def __init__(
             self,
-            fget: Callable[P, R_co],
-            fset: Callable[[T, T0], None] | None = None,
-            fdel: Callable[P0, None] | None = None,
+            fget: Callable[[Any], R_co],
+            fset: Callable[[Any, Any], None] | None = None,
+            fdel: Callable[[Any], None] | None = None,
             doc: str | None = None,
         ) -> None: ...
 
-        def getter(self, fget: Callable[P1, R0_co]) -> cachedproperty[P1, R0_co, T, T0, P0]: ...
+        def getter(self, fget: Callable[..., R_co]) -> cachedproperty[R_co]: ...
+
+        def setter(self, fset: Callable[[Any, Any], None]) -> cachedproperty[R_co]: ...
+
+        def deleter(self, fdel: Callable[..., None]) -> cachedproperty[R_co]: ...
 
-        def setter(self, fset: Callable[[T1, T2], None]) -> cachedproperty[P, R_co, T1, T2, P0]: ...
+    if sys.version_info < (3, 13):
 
-        def deleter(self, fdel: Callable[P1, None]) -> cachedproperty[P, R_co, T, T0, P1]: ...
+        def __init__(self, fget: Any, fset: Any | None = None, fdel: Any | None = None, doc: str | None = None) -> None:
+            self.__name__ = fget.__name__
+            super().__init__(fget, fset, fdel, doc)
 
     @overload
-    def __get__(self, obj: None, type_: type | None = None) -> Self: ...
+    def __get__(self, instance: None, owner: type | None = None) -> Self: ...
 
     @overload
-    def __get__(self, obj: object, type_: type | None = None) -> R_co: ...
+    def __get__(self, instance: Any, owner: type | None = None) -> R_co: ...
 
-    def __get__(self, obj: Any, type_: type | None = None) -> Any:
-        if isinstance(self.fget, classproperty):
-            function = partial(self.fget.__get__, obj, type_)  # type: ignore
-            obj = type_
+    def __get__(self, instance: Any, owner: type | None = None) -> Any:
+        if instance is None:
+            return self
 
-            if not hasattr(obj, cachedproperty.cache_key):
-                setattr(obj, cachedproperty.cache_key, dict[str, Any]())
+        if self.__name__ in (cache := instance.__dict__.setdefault(self.cache_key, {})):
+            return cache[self.__name__]
 
-            cache = getattr(obj, cachedproperty.cache_key)
-            name = self.fget.__name__
-        else:
-            assert self.fget
-            function = self.fget.__get__(obj, type_)
-            cache = obj.__dict__.get(cachedproperty.cache_key)
-            name = function.__name__
+        value = super().__get__(instance, owner)
+        cache[self.__name__] = value
+        return value
 
-        if name not in cache:
-            cache[name] = function()
+    def __set__(self, instance: Any, value: Any) -> None:
+        if self.__name__ in (cache := instance.__dict__.setdefault(self.cache_key, {})):
+            del cache[self.__name__]
 
-        return cache[name]
+        return super().__set__(instance, value)
 
-    if TYPE_CHECKING:
+    def __delete__(self, instance: Any) -> None:
+        if self.__name__ in (cache := instance.__dict__.setdefault(self.cache_key, {})):
+            del cache[self.__name__]
+
+        return super().__delete__(instance)
+
+    @classmethod
+    def clear_cache(cls, obj: object, names: str | Iterable[str] | None = None) -> None:
+        """
+        Clear cached properties of an object instance.
+
+        :param obj:   The object whose cache should be cleared.
+        :param names: Specific property names to clear. If None, all cached properties are cleared.
+        """
+        if names is None:
+            obj.__dict__.get(cls.cache_key, {}).clear()
+            return None
+
+        from ..functions import to_arr
+
+        cache = obj.__dict__.get(cls.cache_key, {})
 
-        def __set__(self, obj: Any, value: R_co, /) -> None:  # type: ignore[misc]
-            ...
+        for name in to_arr(names):
+            with suppress(KeyError):
+                del cache[name]
 
 
 class KwargsNotNone(KwargsT):