cacheprop 0.1.0__py3-none-any.whl

cacheprop/__init__.py

@@ -0,0 +1,73 @@
+import inspect
+from typing import Callable, Any
+
+
+class cacheprop[T]:
+    """
+    Decorator that converts a method with a single self argument into a
+    property cached on the instance.
+
+    A cacheprop can be made out of an existing method:
+    (e.g. ``url = cacheprop(get_absolute_url)``).
+
+    Also provided generic type so that we can accomodate for type checking
+    for properties that return different types, ie general types
+
+    Works with both sync and async methods.
+    """
+
+    name = None
+
+    @staticmethod
+    def func(instance):
+        raise TypeError(
+            "Cannot use cacheprop instance without calling " "__set_name__() on it."
+        )
+
+    def __init__(self, func: Callable[[Any], T]):
+        self.real_func = func
+        self._is_async = inspect.iscoroutinefunction(func)
+        self.__doc__ = getattr(func, "__doc__")
+        self.__annotations__ = getattr(func, "__annotations__", {})
+
+    def __set_name__(self, owner, name):
+        if self.name is None:
+            self.name = name
+            self.func = self.real_func  # type: ignore[method-assign]
+        elif name != self.name:
+            raise TypeError(
+                "Cannot assign the same cacheprop to two different names "
+                "(%r and %r)." % (self.name, name)
+            )
+
+    def __get__(self, instance, cls=None) -> T:
+        """
+        Call the function and put the return value in instance.__dict__ so that
+        subsequent attribute access on the instance returns the cached value
+        instead of calling cacheprop.__get__().
+        """
+        if instance is None:
+            return self  # type: ignore[return-value]
+        cache_key = f"_cached_{self.name}"
+        if self.name is not None and cache_key in instance.__dict__:
+            if self._is_async:
+
+                async def _cache_and_return():
+                    return instance.__dict__[cache_key]  # type: ignore[index]
+
+                return _cache_and_return()
+            return instance.__dict__[cache_key]
+        res = self.func(instance)
+        if self._is_async:
+
+            async def _cache_and_return():
+                result = await res
+                instance.__dict__[cache_key] = result  # type: ignore[index]
+                return result
+
+            return _cache_and_return()  # type: ignore[return-value]
+        instance.__dict__[self.name] = res
+        return res
+
+
+__all__ = ["cacheprop"]

cacheprop-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: cacheprop
+Version: 0.1.0
+Summary: Typed cached property decorator with async support
+Author-email: "Nikola T." <git@nikola.aleeas.com>
+License-Expression: 0BSD
+Project-URL: Homepage, https://gitlab.com/elrik/cacheprop
+Project-URL: Repository, https://gitlab.com/elrik/cacheprop.git
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cacheprop
+
+[![PyPI](https://img.shields.io/pypi/v/cacheprop.svg)](https://pypi.python.org/pypi/cacheprop)
+
+A typed cached property decorator with async support.
+
+## Why?
+
+- Makes caching of time or computation-expensive properties quick and easy.
+- Provides proper type checking via PEP 695 generic syntax (`class cacheprop[T]`).
+- Works with both sync and async methods — the return value is automatically awaited for async functions.
+- Preserves `__doc__` and `__annotations__` from the wrapped function.
+
+## Installation
+
+```bash
+pip install cacheprop
+```
+
+Requires **Python 3.12+** (uses PEP 695 type parameter syntax).
+
+## Usage
+
+### Sync methods
+
+```python
+from cacheprop import cacheprop
+
+
+class MyClass:
+    @cacheprop
+    def expensive(self) -> str:
+        return heavy_computation()
+
+
+obj = MyClass()
+print(obj.expensive)  # calls heavy_computation(), caches result
+print(obj.expensive)  # returns cached value, no call
+```
+
+### Async methods
+
+```python
+class MyAsyncClass:
+    @cacheprop
+    async def fetch_data(self) -> dict:
+        return await http_get("https://example.com/api")
+
+
+async def main():
+    obj = MyAsyncClass()
+    data1 = await obj.fetch_data  # awaits and caches
+    data2 = await obj.fetch_data  # returns cached value, no await needed
+```
+
+### Reusing an existing function
+
+```python
+def get_absolute_url(self):
+    return f"/items/{self.id}"
+
+
+class Item:
+    url = cacheprop(get_absolute_url)
+```
+
+## Type checking
+
+The generic parameter `T` lets type checkers infer the return type:
+
+```python
+@cacheprop
+def size(self) -> int:
+    return len(self.data)
+
+reveal_type(obj.size)  # int (not object or Any)
+```
+
+## License
+
+0BSD

cacheprop-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cacheprop/__init__.py,sha256=lnElEP_9XBvn6ghe2F2mrAqkV4voEPzl8KO4Z9zyAgQ,2423
+cacheprop-0.1.0.dist-info/licenses/LICENSE,sha256=Sc9mCostqbVaA-dHC_EzdbLanw7O4r4z4v52w5t1M64,654
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_cacheprop.py,sha256=aqfxavb86RpkXmBFY1yj7gD2XjX1KmfK3k66fbj4WRQ,7510
+cacheprop-0.1.0.dist-info/METADATA,sha256=R-bB-zMatFUFX8tnPVqwFqgCu76QNTBAgVfWq9XvvyI,2182
+cacheprop-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cacheprop-0.1.0.dist-info/top_level.txt,sha256=VlJJ-wFg2nMClFd-JhKJdC7e7xK7l4lcYzTiC2eUipw,16
+cacheprop-0.1.0.dist-info/RECORD,,

cacheprop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cacheprop-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,10 @@
+Copyright (C) by the authors of this software
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without
+fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

cacheprop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+cacheprop
+tests

tests/test_cacheprop.py

@@ -0,0 +1,290 @@
+import asyncio
+
+import pytest
+
+from ..cacheprop import cacheprop
+
+
+class TestCacheprop:
+    def test_unassigned_raises_type_error(self):
+        """
+        Using cacheprop without assigning to a class should raise TypeError
+        """
+        call_count = 0
+
+        def my_func(self):
+            nonlocal call_count
+            call_count += 1
+            return 42
+
+        prop = cacheprop(my_func)
+        with pytest.raises(TypeError) as excinfo:
+            prop.__get__(object())
+        assert (
+            str(excinfo.value) == "Cannot use cacheprop instance without calling "
+            "__set_name__() on it."
+        )
+
+    def test_reassign_same_cacheprop_raises(self):
+        """
+        Assigning the same cacheprop to two different class names raises TypeError
+        """
+        call_count = 0
+
+        def my_func(self):
+            nonlocal call_count
+            call_count += 1
+            return 42
+
+        prop = cacheprop(my_func)
+
+        class A:
+            attr_a = prop
+
+        with pytest.raises(TypeError) as excinfo:
+
+            class B:
+                attr_b = prop
+
+        assert (
+            str(excinfo.value)
+            == "Cannot assign the same cacheprop to two different names "
+            "('attr_a' and 'attr_b')."
+        )
+
+    def test_class_access_returns_descriptor(self):
+        """
+        Accessing cacheprop from the class (not instance) returns self
+        """
+
+        class MyClass:
+            @cacheprop
+            def my_prop(self):
+                return 42
+
+        assert isinstance(MyClass.my_prop, cacheprop)
+
+    def test_basic_caching_behavior(self):
+        """
+        cacheprop should cache the result on the instance
+        """
+        call_count = 0
+
+        class MyClass:
+            @cacheprop
+            def my_prop(self):
+                nonlocal call_count
+                call_count += 1
+                return 42
+
+        instance = MyClass()
+        assert instance.my_prop == 42
+        assert instance.my_prop == 42
+        assert call_count == 1
+
+    def test_docstring_preserved(self):
+        """
+        cacheprop should copy __doc__ from the wrapped function
+        """
+
+        def my_func(self):
+            """My docstring"""
+            return 42
+
+        prop = cacheprop(my_func)
+        assert prop.__doc__ == "My docstring"
+
+    def test_annotations_preserved(self):
+        """
+        cacheprop should copy __annotations__ from the wrapped function
+        """
+
+        def my_func(self) -> int:
+            return 42
+
+        prop = cacheprop(my_func)
+        assert prop.__annotations__ == {"return": int}
+
+    def test_different_instances_independent(self):
+        """
+        Each instance should have its own cached value
+        """
+        call_counts = {"a": 0, "b": 0}
+
+        class MyClass:
+            @cacheprop
+            def my_prop(self):
+                label = "a" if self.label == "a" else "b"
+                call_counts[label] += 1
+                return 42
+
+        a = MyClass()
+        a.label = "a"
+        b = MyClass()
+        b.label = "b"
+
+        assert a.my_prop == 42
+        assert b.my_prop == 42
+        assert call_counts["a"] == 1
+        assert call_counts["b"] == 1
+
+    def test_cached_in_instance_dict(self):
+        """
+        The cached value should be stored in the instance's __dict__
+        """
+
+        class MyClass:
+            @cacheprop
+            def my_prop(self):
+                return 42
+
+        instance = MyClass()
+        assert "my_prop" not in instance.__dict__
+        _ = instance.my_prop
+        assert "my_prop" in instance.__dict__
+        assert instance.__dict__["my_prop"] == 42
+
+    @pytest.mark.asyncio
+    async def test_async_method_returns_coroutine(self):
+        """
+        Using cacheprop on an async method should return a coroutine
+        """
+
+        class MyClass:
+            @cacheprop
+            async def my_async_prop(self):
+                return 42
+
+        instance = MyClass()
+        result = instance.my_async_prop
+        assert asyncio.iscoroutine(result)
+        assert 42 == await result
+        result.close()
+
+    def test_cached_value_returned_from_dict(self):
+        """
+        Once cached, the value should be returned directly from __dict__
+        """
+
+        class MyClass:
+            @cacheprop
+            def my_prop(self):
+                return 42
+
+        instance = MyClass()
+        instance.__dict__["my_prop"] = 99
+        assert instance.my_prop == 99
+
+    @pytest.mark.asyncio
+    async def test_async_method_caches_result(self):
+        """
+        Async cacheprop should only call the function once
+        """
+        call_count = 0
+
+        class MyClass:
+            @cacheprop
+            async def my_async_prop(self):
+                nonlocal call_count
+                call_count += 1
+                return 42
+
+        instance = MyClass()
+        r1 = await instance.my_async_prop
+        r2 = await instance.my_async_prop
+        assert r1 == 42
+        assert r2 == 42
+        assert call_count == 1
+
+    def test_async_method_docstring_preserved(self):
+        """
+        cacheprop should copy __doc__ from async function
+        """
+
+        async def my_async_func(self):
+            """Async docstring"""
+            return 42
+
+        prop = cacheprop(my_async_func)
+        assert prop.__doc__ == "Async docstring"
+
+    def test_async_method_annotations_preserved(self):
+        """
+        cacheprop should copy __annotations__ from async function
+        """
+
+        async def my_async_func(self) -> int:
+            return 42
+
+        prop = cacheprop(my_async_func)
+        assert prop.__annotations__ == {"return": int}
+
+    @pytest.mark.asyncio
+    async def test_async_method_different_instances_independent(self):
+        """
+        Each instance should have its own cached async value
+        """
+        call_counts = {"a": 0, "b": 0}
+
+        class MyClass:
+            @cacheprop
+            async def my_async_prop(self):
+                label = "a" if self.label == "a" else "b"
+                call_counts[label] += 1
+                return 42
+
+        a = MyClass()
+        a.label = "a"
+        b = MyClass()
+        b.label = "b"
+
+        r1 = await a.my_async_prop
+        r2 = await b.my_async_prop
+        assert r1 == 42
+        assert r2 == 42
+        assert call_counts["a"] == 1
+        assert call_counts["b"] == 1
+
+    @pytest.mark.asyncio
+    async def test_async_method_cached_in_instance_dict(self):
+        """
+        The cached async value should be stored in the instance's __dict__
+        """
+
+        class MyClass:
+            @cacheprop
+            async def my_async_prop(self):
+                return 42
+
+        instance = MyClass()
+        assert "my_async_prop" not in instance.__dict__
+        await instance.my_async_prop
+        assert "_cached_my_async_prop" in instance.__dict__
+        assert instance.__dict__["_cached_my_async_prop"] == 42
+
+    def test_returns(self):
+        class A:
+            _a = 0
+
+            @cacheprop
+            def val(self):
+                self._a += 1
+                return self._a
+
+        a: A = A()
+        assert a.val == 1
+        assert a.val == 1
+
+    @pytest.mark.asyncio
+    async def test_async_returns(self):
+        class A:
+            _a = 0
+
+            @cacheprop
+            async def val(self):
+                self._a += 1
+                return self._a
+
+        a: A = A()
+        assert await a.val == 1
+        assert await a.val == 1