best-simple-caching 1.0.0__tar.gz

best_simple_caching-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gorshipisk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

best_simple_caching-1.0.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: best-simple-caching
+Version: 1.0.0
+Summary: Asynchronous caching library with per-key locking, TTL, LRU and decorators
+Author-email: Gorshipisk <bestdevelopment.work@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Gorshipiskp/best-simple-cache
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+### Short Description
+
+A lightweight, asynchronous caching library for Python with per‑key locking, TTL, LRU eviction, and convenient decorators. Built with `asyncio` and Pydantic.
+
+---
+
+# Best Simple Cache
+
+**Best Simple Cache** is an asynchronous caching library designed for modern Python applications that use `asyncio` and Pydantic models. It provides:
+
+- **Per‑key locking** for thread‑safe concurrent access.
+- **Time‑to‑live (TTL)** and **LRU eviction**.
+- **Decorator‑based integration** – add caching to any async/sync function with minimal boilerplate.
+- **Invalidation hooks** and **automatic cache refresh**.
+- **Flexible primary key generation** – define your own key structure.
+
+## Features
+
+- ✅ **Async‑first** – built on `asyncio` with per‑key locks to avoid race conditions.
+- ✅ **TTL & LRU** – automatically evict stale or least‑recently used entries.
+- ✅ **Decoupled storage** – implement your own cache backend by subclassing `EntityCache`.
+- ✅ **Decorator suite** – `@cache`, `@invalidate_after`, and `@refresh_after_by` for common patterns.
+- ✅ **Mixed sync/async support** – works with both synchronous and asynchronous functions.
+- ✅ **Type hints** – fully typed for better IDE support.
+
+## Installation
+
+```bash
+pip install best_simple_caching
+```
+
+**Requirements:** Python 3.10+, Pydantic (v2).
+
+## Quick Start
+
+```python
+import asyncio
+from pydantic import BaseModel
+from best_simple_cache import EntityCache, CacheDecorator, CachingConfig
+
+# 1. Define your Pydantic model
+class User(BaseModel):
+    id: int
+    name: str
+
+# 2. Define the primary key (must be hashable)
+class UserPK:
+    def __init__(self, user_id: int):
+        self.user_id = user_id
+
+    def __hash__(self):
+        return hash(self.user_id)
+
+    def __eq__(self, other):
+        return isinstance(other, UserPK) and self.user_id == other.user_id
+
+# 3. Implement your cache class
+class UserCache(EntityCache[User, UserPK]):
+    def make_pk(self, user_id: int, **_kwargs) -> UserPK:
+        return UserPK(user_id)
+
+# 4. Create a decorator instance
+user_cache = CacheDecorator(
+    entity_cache=UserCache(
+        entity_name="user",
+        model=User,
+        config=CachingConfig(ttl=60, max_size=1000)
+    )
+)
+
+# 5. Decorate your function
+@user_cache.cache
+async def get_user(*, user_id: int) -> User:
+    # Simulate an expensive API call
+    await asyncio.sleep(1)
+    return User(id=user_id, name="Alice")
+
+async def main():
+    # First call – runs the function, stores result
+    user = await get_user(user_id=42)
+    print(user)
+
+    # Second call – returns from cache
+    user = await get_user(user_id=42)
+    print(user)  # Instant
+
+asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Invalidation
+
+```python
+@user_cache.invalidate_after
+async def update_user(*, user_id: int) -> User:
+    # This function updates the user and then invalidates the cache
+    updated_user = ...  # some update logic
+    return updated_user
+```
+
+### Refresh After Write
+
+```python
+@user_cache.refresh_after_by(get_user)  # get_user is a cached function
+async def update_user(*, user_id: int) -> None:
+    # Perform update, then the cache will be invalidated and refreshed
+    ...
+```
+
+### Custom Key Generation
+
+The `make_pk` method receives the same keyword arguments as the decorated function. Use it to build a hashable key.
+
+```python
+class MyCache(EntityCache[MyModel, MyPK]):
+    def make_pk(self, id: int, region: str = "default", **_kwargs) -> MyPK:
+        return MyPK(id, region)
+```
+
+## API Reference
+
+### `EntityCache(ABC, Generic[T, PK])`
+
+Abstract base class for a cache backend.
+
+- `__init__(entity_name: str, model: type[T], config: CachingConfig | None)`
+- `async set(entity: T, **kwargs) -> None` – store an entity.
+- `async get(**kwargs) -> T | None` – retrieve an entity by keyword arguments.
+- `async get_by_pk(pk: PK) -> T | None` – retrieve directly by primary key.
+- `async invalidate(entity_pk: PK | None = None, **kwargs) -> None` – remove an entry.
+- `abstractmethod make_pk(**kwargs) -> PK` – build a primary key from arguments.
+
+### `CacheDecorator(Generic[T, PK])`
+
+Creates decorators bound to a specific `EntityCache`.
+
+- `cache` – decorator that caches the function result.
+- `invalidate_after` – decorator that invalidates the cache after the function runs.
+- `refresh_after_by(refresh_func)` – decorator that invalidates and then calls `refresh_func` to repopulate the cache.
+
+### `CachingConfig`
+
+Configuration for a cache.
+
+- `ttl: float | None` – seconds after which an entry is considered stale (default `None` = never expires).
+- `max_size: int` – maximum number of entries; `0` means unlimited (default `0`).
+- `disabled: bool` – if `True`, caching is disabled (default `False`).
+
+## Limitations
+
+- **Keyword arguments only** – the decorated function must use only keyword arguments (or at least those used in `make_pk` must be named). Positional arguments are not supported.
+- **Pydantic models** – the library assumes cached entities are subclasses of `BaseModel`. You can extend it to work with other types by overriding type checks.
+- **In‑memory only** – the default implementation stores data in an `OrderedDict`. For distributed caching, implement your own backend.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+MIT

best_simple_caching-1.0.0/README.md

@@ -0,0 +1,162 @@
+### Short Description
+
+A lightweight, asynchronous caching library for Python with per‑key locking, TTL, LRU eviction, and convenient decorators. Built with `asyncio` and Pydantic.
+
+---
+
+# Best Simple Cache
+
+**Best Simple Cache** is an asynchronous caching library designed for modern Python applications that use `asyncio` and Pydantic models. It provides:
+
+- **Per‑key locking** for thread‑safe concurrent access.
+- **Time‑to‑live (TTL)** and **LRU eviction**.
+- **Decorator‑based integration** – add caching to any async/sync function with minimal boilerplate.
+- **Invalidation hooks** and **automatic cache refresh**.
+- **Flexible primary key generation** – define your own key structure.
+
+## Features
+
+- ✅ **Async‑first** – built on `asyncio` with per‑key locks to avoid race conditions.
+- ✅ **TTL & LRU** – automatically evict stale or least‑recently used entries.
+- ✅ **Decoupled storage** – implement your own cache backend by subclassing `EntityCache`.
+- ✅ **Decorator suite** – `@cache`, `@invalidate_after`, and `@refresh_after_by` for common patterns.
+- ✅ **Mixed sync/async support** – works with both synchronous and asynchronous functions.
+- ✅ **Type hints** – fully typed for better IDE support.
+
+## Installation
+
+```bash
+pip install best_simple_caching
+```
+
+**Requirements:** Python 3.10+, Pydantic (v2).
+
+## Quick Start
+
+```python
+import asyncio
+from pydantic import BaseModel
+from best_simple_cache import EntityCache, CacheDecorator, CachingConfig
+
+# 1. Define your Pydantic model
+class User(BaseModel):
+    id: int
+    name: str
+
+# 2. Define the primary key (must be hashable)
+class UserPK:
+    def __init__(self, user_id: int):
+        self.user_id = user_id
+
+    def __hash__(self):
+        return hash(self.user_id)
+
+    def __eq__(self, other):
+        return isinstance(other, UserPK) and self.user_id == other.user_id
+
+# 3. Implement your cache class
+class UserCache(EntityCache[User, UserPK]):
+    def make_pk(self, user_id: int, **_kwargs) -> UserPK:
+        return UserPK(user_id)
+
+# 4. Create a decorator instance
+user_cache = CacheDecorator(
+    entity_cache=UserCache(
+        entity_name="user",
+        model=User,
+        config=CachingConfig(ttl=60, max_size=1000)
+    )
+)
+
+# 5. Decorate your function
+@user_cache.cache
+async def get_user(*, user_id: int) -> User:
+    # Simulate an expensive API call
+    await asyncio.sleep(1)
+    return User(id=user_id, name="Alice")
+
+async def main():
+    # First call – runs the function, stores result
+    user = await get_user(user_id=42)
+    print(user)
+
+    # Second call – returns from cache
+    user = await get_user(user_id=42)
+    print(user)  # Instant
+
+asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Invalidation
+
+```python
+@user_cache.invalidate_after
+async def update_user(*, user_id: int) -> User:
+    # This function updates the user and then invalidates the cache
+    updated_user = ...  # some update logic
+    return updated_user
+```
+
+### Refresh After Write
+
+```python
+@user_cache.refresh_after_by(get_user)  # get_user is a cached function
+async def update_user(*, user_id: int) -> None:
+    # Perform update, then the cache will be invalidated and refreshed
+    ...
+```
+
+### Custom Key Generation
+
+The `make_pk` method receives the same keyword arguments as the decorated function. Use it to build a hashable key.
+
+```python
+class MyCache(EntityCache[MyModel, MyPK]):
+    def make_pk(self, id: int, region: str = "default", **_kwargs) -> MyPK:
+        return MyPK(id, region)
+```
+
+## API Reference
+
+### `EntityCache(ABC, Generic[T, PK])`
+
+Abstract base class for a cache backend.
+
+- `__init__(entity_name: str, model: type[T], config: CachingConfig | None)`
+- `async set(entity: T, **kwargs) -> None` – store an entity.
+- `async get(**kwargs) -> T | None` – retrieve an entity by keyword arguments.
+- `async get_by_pk(pk: PK) -> T | None` – retrieve directly by primary key.
+- `async invalidate(entity_pk: PK | None = None, **kwargs) -> None` – remove an entry.
+- `abstractmethod make_pk(**kwargs) -> PK` – build a primary key from arguments.
+
+### `CacheDecorator(Generic[T, PK])`
+
+Creates decorators bound to a specific `EntityCache`.
+
+- `cache` – decorator that caches the function result.
+- `invalidate_after` – decorator that invalidates the cache after the function runs.
+- `refresh_after_by(refresh_func)` – decorator that invalidates and then calls `refresh_func` to repopulate the cache.
+
+### `CachingConfig`
+
+Configuration for a cache.
+
+- `ttl: float | None` – seconds after which an entry is considered stale (default `None` = never expires).
+- `max_size: int` – maximum number of entries; `0` means unlimited (default `0`).
+- `disabled: bool` – if `True`, caching is disabled (default `False`).
+
+## Limitations
+
+- **Keyword arguments only** – the decorated function must use only keyword arguments (or at least those used in `make_pk` must be named). Positional arguments are not supported.
+- **Pydantic models** – the library assumes cached entities are subclasses of `BaseModel`. You can extend it to work with other types by overriding type checks.
+- **In‑memory only** – the default implementation stores data in an `OrderedDict`. For distributed caching, implement your own backend.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+MIT

best_simple_caching-1.0.0/best_simple_cache/__init__.py

@@ -0,0 +1,6 @@
+from .caching import CacheDecorator
+from .entity_cache import EntityCache, CachingConfig, CacheInfo
+
+__all__ = ["EntityCache", "CacheInfo", "CachingConfig", "CacheDecorator"]
+__version__ = "1.0.0"
+__author__ = "Gorshipisk"

best_simple_caching-1.0.0/best_simple_cache/__main__.py

@@ -0,0 +1,7 @@
+import asyncio
+
+from .example import main
+
+if "__main__" == __name__:
+    # Runs examples
+    asyncio.run(main())

best_simple_caching-1.0.0/best_simple_cache/caching.py

@@ -0,0 +1,79 @@
+import functools
+from typing import Generic, Any, Callable, Awaitable, Coroutine, ParamSpec
+
+from . import EntityCache
+from .entity_cache import PK, T
+from .misc import handle_maybe_async
+
+P = ParamSpec("P")
+
+
+class CacheDecorator(Generic[T, PK]):
+    def __init__(self, entity_cache: EntityCache[T, PK]) -> None:
+        self._entity_cache: EntityCache[T, PK] = entity_cache
+
+        self.cache = self.__cache()
+        self.invalidate_after = self.__invalidate_after()
+
+    def __cache(self) -> Callable[
+        [Callable[P, T | Awaitable[T] | Coroutine[Any, Any, T]]],
+        Callable[P, Coroutine[Any, Any, T]]
+    ]:
+        def decorator(
+                func: Callable[P, T | Awaitable[T] | Coroutine[Any, Any, T]]
+        ) -> Callable[P, Coroutine[Any, Any, T]]:
+            func.is_cached = True
+
+            @functools.wraps(func)
+            async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                from_cache: T | None = await self._entity_cache.get(**kwargs)
+
+                if from_cache is not None:
+                    return from_cache
+
+                result: T = await handle_maybe_async(func, *args, **kwargs)
+
+                await self._entity_cache.set(entity=result, **kwargs)
+
+                return result
+
+            return wrapper
+
+        return decorator
+
+    def __invalidate_after(self):
+        def decorator(
+                func: Callable[P, T | Awaitable[T] | Coroutine[Any, Any, T]]
+        ) -> Callable[P, Coroutine[Any, Any, T]]:
+            @functools.wraps(func)
+            async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                result: T = await handle_maybe_async(func, *args, **kwargs)
+
+                await self._entity_cache.invalidate(**kwargs)
+
+                return result
+
+            return wrapper
+
+        return decorator
+
+    def refresh_after_by(
+            self,
+            refresh_func: Callable[..., T | Awaitable[T] | Coroutine[Any, Any, T]]
+    ) -> Callable[[Callable[P, T | Awaitable[T]]], Callable[P, Coroutine[Any, Any, T]]]:
+        def decorator(func: Callable[P, T | Awaitable[T]]) -> Callable[P, Coroutine[Any, Any, T]]:
+            @functools.wraps(func)
+            async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                result: T = await handle_maybe_async(func, *args, **kwargs)
+
+                await self._entity_cache.invalidate(**kwargs)
+
+                refresh_res: T = await handle_maybe_async(refresh_func, *args, **kwargs)
+                if getattr(func, "is_cached", False):
+                    await self._entity_cache.set(entity=refresh_res, **kwargs)
+
+                return result
+
+            return wrapper
+
+        return decorator

best_simple_caching-1.0.0/best_simple_cache/entity_cache.py

@@ -0,0 +1,124 @@
+import time
+from abc import ABC, abstractmethod
+from asyncio import Lock
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar, Hashable
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+PK = TypeVar("PK", bound=Hashable)
+
+
+@dataclass(frozen=True, kw_only=True)
+class CacheInfo(Generic[T]):
+    entity: T
+    created_at: float
+
+
+class CachingConfig:
+    def __init__(
+            self,
+            ttl: float | None = None,
+            max_size: int = 0,
+            disabled: bool = False,
+    ):
+        self.ttl: float | None = ttl
+        self.max_size: int = max_size
+        self.disabled: bool = disabled
+
+    def __repr__(self):
+        return f"CachingConfig(ttl={self.ttl}; max_size={self.max_size}; disabled={self.disabled})"
+
+
+class EntityCache(ABC, Generic[T, PK]):
+    def __init__(
+            self,
+            entity_name: str,
+            model: type[T],
+            config: CachingConfig | None = None,
+    ):
+        self.entity_name: str = entity_name
+        self.model: type[T] = model
+
+        self._config: CachingConfig = config or CachingConfig()
+        self._pool: OrderedDict[PK, CacheInfo[T]] = OrderedDict()
+        self._pool_locks: dict[PK, Lock] = {}
+
+    def __repr__(self) -> str:
+        return (f"{self.__class__.__name__}(name=\"{self.entity_name}\"; "
+                f"pool_len={len(self._pool)}; config={self._config})")
+
+    async def set(self, entity: T, **kwargs: Any) -> None:
+        if self._config.disabled:
+            return
+
+        if not isinstance(entity, self.model):
+            raise TypeError(f"Expected {self.model}, got {type(entity)}")
+
+        entity_pk: PK = self.make_pk(**kwargs)
+
+        async with self._pool_locks.setdefault(entity_pk, Lock()):
+            now: float = time.monotonic()
+
+            self._pool[entity_pk] = CacheInfo(entity=entity, created_at=now)
+
+            self._pool.move_to_end(entity_pk)
+
+            self._evict_if_needed()
+
+    async def get_by_pk(self, pk: PK) -> T | None:
+        return await self._get(pk)
+
+    async def get(self, **kwargs: Any) -> T | None:
+        return await self._get(self.make_pk(**kwargs))
+
+    async def _get(self, entity_pk: PK) -> T | None:
+        if self._config.disabled:
+            return None
+
+        async with self._pool_locks.setdefault(entity_pk, Lock()):
+            info: CacheInfo[T] = self._pool.get(entity_pk)
+
+            if info is None:
+                return None
+
+            if self._is_expired(info):
+                self._pool.pop(entity_pk, None)
+                self._pool_locks.pop(entity_pk, None)
+                return None
+
+            self._pool.move_to_end(entity_pk)
+
+            return info.entity
+
+    async def invalidate(self, entity_pk: PK | None = None, **kwargs: Any) -> None:
+        if entity_pk is None:
+            entity_pk = self.make_pk(**kwargs)
+
+        async with self._pool_locks.setdefault(entity_pk, Lock()):
+            self._pool.pop(entity_pk, None)
+            self._pool_locks.pop(entity_pk, None)
+
+    def _evict_if_needed(self) -> None:
+        max_size: int = self._config.max_size
+
+        if max_size <= 0:
+            return
+
+        while len(self._pool) > max_size:
+            entity_pk: PK = self._pool.popitem(last=False)
+            self._pool_locks.pop(entity_pk, None)
+
+    def _is_expired(self, info: CacheInfo[T]) -> bool:
+        ttl: float | None = self._config.ttl
+
+        if ttl is None:
+            return False
+
+        return (time.monotonic() - info.created_at) > ttl
+
+    @abstractmethod
+    def make_pk(self, **kwargs: Any) -> PK:
+        ...

best_simple_caching-1.0.0/best_simple_cache/example.py

@@ -0,0 +1,131 @@
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+from . import EntityCache
+from .caching import CacheDecorator
+from .entity_cache import CachingConfig
+
+
+async def main():
+    print(f"\n{' Example caching and TTL ':=^70}\n")
+
+    # Some kind of pydantic classes of API response (strict hashable)
+    class Group(BaseModel):
+        group_id: int
+        name: str
+        scope: str
+
+        model_config = {"frozen": True}
+
+    # Set `Group` entity's cache
+
+    # Primary key of group
+    @dataclass(frozen=True, kw_only=True)
+    class GroupPK:
+        group_id: int
+
+    # Overload necessary methods
+    class GroupCache(EntityCache):
+        def make_pk(self, group_id: int, **_kwargs: Any) -> GroupPK:
+            # We need `_kwargs` for backward compatibility
+            return GroupPK(
+                group_id=group_id
+            )
+
+    groups_cache: CacheDecorator[Group, GroupPK] = CacheDecorator(
+        entity_cache=GroupCache(
+            entity_name="group",
+            model=Group,
+            config=CachingConfig(
+                ttl=3
+            )
+        )
+    )
+
+    # Arbitrary API-contract (adding caching)
+    @groups_cache.cache
+    async def get_group_contract(*, group_id: int) -> Group:
+        # Warning: function with `.cache` decorator must include the same kwargs, that was set in PK
+
+        # Some API and requests thing
+        ...
+
+        await asyncio.sleep(1)
+
+        # Got the result
+        return Group(
+            group_id=group_id,
+            name="PMiK-16",
+            scope="GLOBAL"
+        )
+
+    start: float = time.perf_counter()
+    await get_group_contract(group_id=1)
+    end: float = time.perf_counter()
+
+    print(f"Before caching: {end - start:.6f}")
+
+    start: float = time.perf_counter()
+    await get_group_contract(group_id=1)
+    end: float = time.perf_counter()
+
+    print(f"After caching: {end - start:.6f}")
+
+    await asyncio.sleep(3.1)
+
+    start: float = time.perf_counter()
+    await get_group_contract(group_id=1)
+    end: float = time.perf_counter()
+
+    print(f"After ttl expire: {end - start:.6f}")
+
+    print(f"\n{' Invalidation hook example ':=^70}\n")
+
+    # New model and contract (invalidation hook with auto-refresh)
+    class GroupSettings(BaseModel):
+        group_id: int
+        new_members: bool
+
+        model_config = {"frozen": True}
+
+    class GroupSettingsPK(GroupPK):
+        ...
+
+    class GroupSettingsCache(EntityCache):
+        def make_pk(self, group_id: int, **_kwargs: Any) -> GroupPK:
+            return GroupSettingsPK(
+                group_id=group_id
+            )
+
+    groups_settings_cache: CacheDecorator[GroupSettings, GroupSettingsPK] = CacheDecorator(
+        entity_cache=GroupSettingsCache(
+            entity_name="group_settings",
+            model=GroupSettings
+        )
+    )
+
+    @groups_settings_cache.cache
+    async def get_group_settings(*, group_id: int) -> GroupSettings:
+        # Some API and requests thing
+        ...
+
+        print("Got group's settings")
+        # Got the result
+        return GroupSettings(
+            group_id=group_id,
+            new_members=True
+        )
+
+    @groups_settings_cache.refresh_after_by(get_group_settings)
+    async def update_group_settings(*, group_id: int) -> None:
+        # Some API and requests thing
+        ...
+
+        print(f"Group settings ({group_id=}) updated")
+
+    await get_group_settings(group_id=1)
+    await update_group_settings(group_id=1)

best_simple_caching-1.0.0/best_simple_cache/misc.py

@@ -0,0 +1,37 @@
+import inspect
+from typing import TypeVar, Callable, Awaitable, Coroutine
+
+T = TypeVar("T")
+
+
+async def handle_maybe_async(func: Coroutine[..., ..., T] | Callable[..., T | Awaitable[T]] | T, *args, **kwargs) -> T:
+    """
+    Execute a value that may be synchronous, asynchronous, or already a result,
+    and return its resolved value
+
+    This utility normalizes mixed sync/async inputs into a single awaited result,
+    simplifying code that needs to transparently handle both execution models
+
+    Args:
+        func: A coroutine function, coroutine object, callable returning a value or awaitable,
+              or a direct value
+        *args: Positional arguments passed to the callable, if applicable
+        **kwargs: Keyword arguments passed to the callable, if applicable
+
+    Returns:
+        The resolved value of type `T` after executing or awaiting as necessary
+    """
+
+    if inspect.iscoroutinefunction(func):
+        return await func(*args, **kwargs)
+    if inspect.iscoroutine(func):
+        return await func
+    if not inspect.isfunction(func):
+        return func
+
+    result: T = func(*args, **kwargs)
+
+    if inspect.isawaitable(result):
+        return await result
+
+    return result

best_simple_caching-1.0.0/best_simple_caching.egg-info/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: best-simple-caching
+Version: 1.0.0
+Summary: Asynchronous caching library with per-key locking, TTL, LRU and decorators
+Author-email: Gorshipisk <bestdevelopment.work@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Gorshipiskp/best-simple-cache
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+### Short Description
+
+A lightweight, asynchronous caching library for Python with per‑key locking, TTL, LRU eviction, and convenient decorators. Built with `asyncio` and Pydantic.
+
+---
+
+# Best Simple Cache
+
+**Best Simple Cache** is an asynchronous caching library designed for modern Python applications that use `asyncio` and Pydantic models. It provides:
+
+- **Per‑key locking** for thread‑safe concurrent access.
+- **Time‑to‑live (TTL)** and **LRU eviction**.
+- **Decorator‑based integration** – add caching to any async/sync function with minimal boilerplate.
+- **Invalidation hooks** and **automatic cache refresh**.
+- **Flexible primary key generation** – define your own key structure.
+
+## Features
+
+- ✅ **Async‑first** – built on `asyncio` with per‑key locks to avoid race conditions.
+- ✅ **TTL & LRU** – automatically evict stale or least‑recently used entries.
+- ✅ **Decoupled storage** – implement your own cache backend by subclassing `EntityCache`.
+- ✅ **Decorator suite** – `@cache`, `@invalidate_after`, and `@refresh_after_by` for common patterns.
+- ✅ **Mixed sync/async support** – works with both synchronous and asynchronous functions.
+- ✅ **Type hints** – fully typed for better IDE support.
+
+## Installation
+
+```bash
+pip install best_simple_caching
+```
+
+**Requirements:** Python 3.10+, Pydantic (v2).
+
+## Quick Start
+
+```python
+import asyncio
+from pydantic import BaseModel
+from best_simple_cache import EntityCache, CacheDecorator, CachingConfig
+
+# 1. Define your Pydantic model
+class User(BaseModel):
+    id: int
+    name: str
+
+# 2. Define the primary key (must be hashable)
+class UserPK:
+    def __init__(self, user_id: int):
+        self.user_id = user_id
+
+    def __hash__(self):
+        return hash(self.user_id)
+
+    def __eq__(self, other):
+        return isinstance(other, UserPK) and self.user_id == other.user_id
+
+# 3. Implement your cache class
+class UserCache(EntityCache[User, UserPK]):
+    def make_pk(self, user_id: int, **_kwargs) -> UserPK:
+        return UserPK(user_id)
+
+# 4. Create a decorator instance
+user_cache = CacheDecorator(
+    entity_cache=UserCache(
+        entity_name="user",
+        model=User,
+        config=CachingConfig(ttl=60, max_size=1000)
+    )
+)
+
+# 5. Decorate your function
+@user_cache.cache
+async def get_user(*, user_id: int) -> User:
+    # Simulate an expensive API call
+    await asyncio.sleep(1)
+    return User(id=user_id, name="Alice")
+
+async def main():
+    # First call – runs the function, stores result
+    user = await get_user(user_id=42)
+    print(user)
+
+    # Second call – returns from cache
+    user = await get_user(user_id=42)
+    print(user)  # Instant
+
+asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Invalidation
+
+```python
+@user_cache.invalidate_after
+async def update_user(*, user_id: int) -> User:
+    # This function updates the user and then invalidates the cache
+    updated_user = ...  # some update logic
+    return updated_user
+```
+
+### Refresh After Write
+
+```python
+@user_cache.refresh_after_by(get_user)  # get_user is a cached function
+async def update_user(*, user_id: int) -> None:
+    # Perform update, then the cache will be invalidated and refreshed
+    ...
+```
+
+### Custom Key Generation
+
+The `make_pk` method receives the same keyword arguments as the decorated function. Use it to build a hashable key.
+
+```python
+class MyCache(EntityCache[MyModel, MyPK]):
+    def make_pk(self, id: int, region: str = "default", **_kwargs) -> MyPK:
+        return MyPK(id, region)
+```
+
+## API Reference
+
+### `EntityCache(ABC, Generic[T, PK])`
+
+Abstract base class for a cache backend.
+
+- `__init__(entity_name: str, model: type[T], config: CachingConfig | None)`
+- `async set(entity: T, **kwargs) -> None` – store an entity.
+- `async get(**kwargs) -> T | None` – retrieve an entity by keyword arguments.
+- `async get_by_pk(pk: PK) -> T | None` – retrieve directly by primary key.
+- `async invalidate(entity_pk: PK | None = None, **kwargs) -> None` – remove an entry.
+- `abstractmethod make_pk(**kwargs) -> PK` – build a primary key from arguments.
+
+### `CacheDecorator(Generic[T, PK])`
+
+Creates decorators bound to a specific `EntityCache`.
+
+- `cache` – decorator that caches the function result.
+- `invalidate_after` – decorator that invalidates the cache after the function runs.
+- `refresh_after_by(refresh_func)` – decorator that invalidates and then calls `refresh_func` to repopulate the cache.
+
+### `CachingConfig`
+
+Configuration for a cache.
+
+- `ttl: float | None` – seconds after which an entry is considered stale (default `None` = never expires).
+- `max_size: int` – maximum number of entries; `0` means unlimited (default `0`).
+- `disabled: bool` – if `True`, caching is disabled (default `False`).
+
+## Limitations
+
+- **Keyword arguments only** – the decorated function must use only keyword arguments (or at least those used in `make_pk` must be named). Positional arguments are not supported.
+- **Pydantic models** – the library assumes cached entities are subclasses of `BaseModel`. You can extend it to work with other types by overriding type checks.
+- **In‑memory only** – the default implementation stores data in an `OrderedDict`. For distributed caching, implement your own backend.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+MIT

best_simple_caching-1.0.0/best_simple_caching.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+best_simple_cache/__init__.py
+best_simple_cache/__main__.py
+best_simple_cache/caching.py
+best_simple_cache/entity_cache.py
+best_simple_cache/example.py
+best_simple_cache/misc.py
+best_simple_caching.egg-info/PKG-INFO
+best_simple_caching.egg-info/SOURCES.txt
+best_simple_caching.egg-info/dependency_links.txt
+best_simple_caching.egg-info/requires.txt
+best_simple_caching.egg-info/top_level.txt

best_simple_caching-1.0.0/best_simple_caching.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

best_simple_caching-1.0.0/best_simple_caching.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=2.0

best_simple_caching-1.0.0/best_simple_caching.egg-info/top_level.txt

@@ -0,0 +1 @@
+best_simple_cache

best_simple_caching-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "best-simple-caching"
+version = "1.0.0"
+description = "Asynchronous caching library with per-key locking, TTL, LRU and decorators"
+readme = "README.md"
+authors = [
+    { name = "Gorshipisk", email = "bestdevelopment.work@gmail.com" },
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Gorshipiskp/best-simple-cache"

best_simple_caching-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+