btrcache 0.1.0__py3-none-any.whl

btrcache/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (C) 2026 Lucas Dias
+
+"""Caching tools, collections and decorators.
+
+This package provides in-memory cache implementations and memoizing
+decorators for synchronous and asynchronous callables, cache collections
+implementing multiple algorithms and other utilities for working with
+caches.
+"""

btrcache/__version__.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

btrcache/asyncio/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (C) 2026 Lucas Dias
+
+"""Asyncio-based caching package.
+
+Provides decorators for caching coroutines.
+"""
+
+import typing
+
+from src.btrcache.asyncio.decorators import async_cached, async_cachedmethod
+
+__all__: typing.Final = ("async_cached", "async_cachedmethod")

btrcache/asyncio/cache.py

@@ -0,0 +1,18 @@
+# Copyright (C) 2026 Lucas Dias
+
+"""Type aliases for asynchronous cache implementations.
+
+This module defines generic cache aliases used by the asynchronous
+decorators.
+"""
+
+import asyncio
+import typing
+
+from src.btrcache.cache import Cache
+
+__all__: typing.Final = ("AsyncCache",)
+
+# Each asynchronous cache entry stores the executing `Task`
+# together with the shared `Future` returned
+type AsyncCache[R] = Cache[tuple[asyncio.Task[R], asyncio.Future[R]]]

btrcache/asyncio/decorators.py

@@ -0,0 +1,395 @@
+# Copyright (C) 2026 Lucas Dias
+#
+# Portions Copyright (C) 2026 James Ward
+# Source: https://github.com/imnotjames/cachetools-async/blob/53d453441dac736b16ec549ee4dd50453c9669c9/src/cachetools_async/decorators.py
+# License: MIT (See LICENSE file for details)
+
+"""Asynchronous caching utilities for coroutines and methods.
+
+This module provides async-compatible decorator patterns similar to
+`cachetools`, designed to store and reuse `Future` instances to prevent
+duplicate in-flight executions (cache stampede) and cache completed
+results.
+"""
+
+import asyncio
+import contextlib
+import functools
+import inspect
+import typing
+
+from src.btrcache.keys import HashedKey, KeyHashStrategy, KeyHashStrategyProtocol
+
+if typing.TYPE_CHECKING:
+    import collections.abc
+
+    from src.btrcache.asyncio.cache import AsyncCache
+
+__all__: typing.Final = ("async_cached", "async_cachedmethod")
+
+
+def __async_cache_get[R](
+    *,
+    cache: AsyncCache[R],
+    key: HashedKey,
+    call_fn: collections.abc.Callable[[], collections.abc.Coroutine[typing.Any, typing.Any, R]],
+    result_predicate: collections.abc.Callable[[typing.Any], bool] = lambda _: True,
+    exception_predicate: collections.abc.Callable[[BaseException], bool] = lambda _: True,
+) -> tuple[asyncio.Task[R], asyncio.Future[R]]:
+    with contextlib.suppress(KeyError):
+        # If alrady exists a cached version, return it
+        return cache[key]
+
+    # Creates a new task for this call
+    loop = asyncio.get_event_loop()
+    task = loop.create_task(call_fn())
+    future: asyncio.Future[R] = loop.create_future()
+
+    # `done` callback for when future is concluded
+    def done(t: asyncio.Task[R]) -> None:
+        # Removes cancelled tasks from the cache
+        if t.cancelled():
+            cache.pop(key, None)
+            future.cancel()
+            return
+
+        # Treats thrown exceptions inside executed task
+        exception = t.exception()
+        if exception is not None:
+            # Validates if the thrown exception should invalidate caching
+            if not exception_predicate(exception):
+                cache.pop(key, None)
+
+            # Propagates the exception
+            future.set_exception(exception)
+            return
+
+        # Successful result
+        result = t.result()
+
+        # Validates if the result should invalidate caching
+        if not result_predicate(result):
+            cache.pop(key, None)
+
+        # Stores the successful result in the shared future
+        future.set_result(result)
+
+    # Adds `done` callback of future to task
+    task.add_done_callback(done)
+
+    # Returns the cached value
+    with contextlib.suppress(ValueError):
+        cache[key] = (task, future)
+
+    return task, future
+
+
+class __AsyncCachedFunctionWrapperProtocol[**P, R](typing.Protocol):
+    """Protocol for cached asynchronous function wrappers."""
+
+    cache: AsyncCache[R] | None
+    cache_key: KeyHashStrategyProtocol
+    cache_lock: contextlib.AbstractContextManager[typing.Any] | None
+    cache_info: bool | None
+    cache_clear: collections.abc.Callable[[], None]
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> collections.abc.Awaitable[R]:
+        raise NotImplementedError
+
+
+class __AsyncCachedMethodWrapperProtocol[**P, R](typing.Protocol):
+    """Protocol for cached asynchronous method wrappers."""
+
+    cache: collections.abc.Callable[[typing.Any], AsyncCache[R] | None]
+    cache_key: KeyHashStrategyProtocol
+    cache_lock: contextlib.AbstractContextManager[typing.Any] | None
+    cache_info: bool | None
+    cache_clear: collections.abc.Callable[[typing.Any], None]
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> collections.abc.Awaitable[R]:
+        raise NotImplementedError
+
+    def __get__(
+        self,
+        # IGNORE: Type `Any` was used as it must The descriptor
+        # is accessed from an instance of the class containing
+        # the decorated method which must be any arbitrary
+        # user-defined type.
+        instance: typing.Any,  # noqa: ANN401
+        owner: type | None,
+    ) -> __AsyncCachedMethodWrapperProtocol[P, R]:
+        if instance is None:
+            return self
+
+        # Binds the method to the instance at runtime
+        bound = typing.cast(
+            "__AsyncCachedMethodWrapperProtocol[P, R]",
+            functools.partial(self.__call__, instance),
+        )
+
+        # Mirrors the cache attributes to the bound wrapper
+        bound.cache = self.cache
+        bound.cache_key = self.cache_key
+        bound.cache_lock = self.cache_lock
+        bound.cache_info = self.cache_info
+        bound.cache_clear = self.cache_clear
+
+        return bound
+
+
+class __AsyncFunctionDecoratorProtocol(typing.Protocol):
+    """Protocol representing a decorator that wraps an async function."""
+
+    def __call__[**P, R](
+        self,
+        fn: collections.abc.Callable[P, collections.abc.Awaitable[R]],
+    ) -> __AsyncCachedFunctionWrapperProtocol[P, R]:
+        raise NotImplementedError
+
+
+class __AsyncMethodDecoratorProtocol(typing.Protocol):
+    """Protocol representing a decorator that wraps an async instance method."""
+
+    def __call__[SelfT, **P, R](
+        self,
+        fn: collections.abc.Callable[typing.Concatenate[SelfT, P], collections.abc.Awaitable[R]],
+    ) -> __AsyncCachedMethodWrapperProtocol[P, R]:
+        raise NotImplementedError
+
+
+# IGNORE: Function defines a public interface
+# that necessitates many arguments
+def async_cached(  # noqa: PLR0913
+    cache: AsyncCache[typing.Any] | None,
+    *,
+    key_hash_strategy: KeyHashStrategyProtocol = KeyHashStrategy,
+    lock: contextlib.AbstractContextManager[typing.Any] | None = None,
+    info: bool = False,
+    result_predicate: collections.abc.Callable[[typing.Any], bool] = lambda _: True,
+    exception_predicate: collections.abc.Callable[[BaseException], bool] = lambda _: True,
+) -> __AsyncFunctionDecoratorProtocol:
+    """Decorate caching async function results using asyncio `Future`.
+
+    This decorator stores `Future` objects in a shared mapping keyed by
+    deterministic `HashedKey` objects generated from the supplied
+    `key_hash_strategy`. It ensures that concurrent callers awaiting the
+    same computation will reuse the same in-progress `Future`, preventing
+    duplicate execution (cache stampede protection).
+
+    Args:
+        cache (AsyncCache[Any] | None):
+            Cache used to store tasks and futures. If None, caching is disabled.
+
+        key_hash_strategy (KeyHashStrategyProtocol):
+            Strategy used to compute deterministic cache keys from the
+            positional and keyword arguments. Defaults to `KeyHashStrategy`.
+
+        lock (AbstractContextManager[Any] | None):
+            Optional lock context manager. Not supported in this implementation.
+
+        info (bool):
+            If True, raises NotImplementedError (not supported).
+
+        result_predicate (Callable[[Any], bool]):
+            A custom callable that receives the completed result of the
+            coroutine and returns True if it should remain cached. If it
+            returns False, the result is evicted from the cache immediately
+            upon completion. Defaults to a lambda that always returns True.
+
+        exception_predicate (Callable[[BaseException], bool]):
+            A custom callable that receives the raised exception if the
+            coroutine fails, returning True if the exception should be cached.
+            If it returns False, the failed future is evicted, allowing
+            subsequent calls to retry execution. Defaults to a lambda that
+            always returns True.
+
+    Returns:
+        __AsyncFunctionDecoratorProtocol:
+            A decorator that wraps an async function with caching behavior.
+
+    Raises:
+        NotImplementedError:
+            If `info` or `lock` are provided.
+
+    """
+    if info:
+        msg = "`info` is not supported"
+        raise NotImplementedError(msg)
+
+    if lock is not None:
+        msg = "`lock` is not supported"
+        raise NotImplementedError(msg)
+
+    def decorator[**P, R](
+        fn: collections.abc.Callable[P, collections.abc.Awaitable[R]],
+    ) -> __AsyncCachedFunctionWrapperProtocol[P, R]:
+        if not inspect.iscoroutinefunction(fn):
+            msg = f"Expected 'Coroutine' function, got {fn}"
+            raise TypeError(msg)
+
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            if cache is None:
+                return await fn(*args, **kwargs)
+
+            # Generates key
+            generated_key = HashedKey(args, kwargs, hash_strategy=key_hash_strategy)
+
+            task, future = __async_cache_get(
+                cache=cache,
+                key=generated_key,
+                call_fn=lambda: fn(*args, **kwargs),
+                result_predicate=result_predicate,
+                exception_predicate=exception_predicate,
+            )
+
+            try:
+                return await future
+            except asyncio.CancelledError:
+                # If an awaiting caller is cancelled, the corresponding cache entry is
+                # removed and the underlying task is cancelled when appropriate
+
+                # Evicts from cache instantly
+                cache.pop(generated_key, None)
+
+                # Directly terminates the underlying task loop execution
+                if not task.done():
+                    task.cancel()
+
+                raise
+
+        wrapped = typing.cast(
+            "__AsyncCachedFunctionWrapperProtocol[P, R]",
+            functools.update_wrapper(wrapper, fn),
+        )
+
+        wrapped.cache = cache
+        wrapped.cache_key = key_hash_strategy
+        wrapped.cache_lock = None
+        wrapped.cache_info = None
+        wrapped.cache_clear = lambda: cache.clear() if cache is not None else None
+
+        return wrapped
+
+    return decorator
+
+
+# IGNORE: Function defines a public interface
+# that necessitates many arguments
+def async_cachedmethod(  # noqa: PLR0913
+    cache: collections.abc.Callable[[typing.Any], AsyncCache[typing.Any] | None],
+    *,
+    key_hash_strategy: KeyHashStrategyProtocol = KeyHashStrategy,
+    lock: collections.abc.Callable[[typing.Any], contextlib.AbstractContextManager[typing.Any]]
+    | None = None,
+    info: bool = False,
+    result_predicate: collections.abc.Callable[[typing.Any], bool] = lambda _: True,
+    exception_predicate: collections.abc.Callable[[BaseException], bool] = lambda _: True,
+) -> __AsyncMethodDecoratorProtocol:
+    """Decorate caching async instance/class methods.
+
+    This is similar to `cached`, but the cache is resolved dynamically
+    per instance (or class) via the provided cache function.
+
+    It is primarily used for memoizing async methods where cache storage
+    is attached to `self` or another runtime context.
+
+    Args:
+        cache (Callable[[Any], AsyncCache[Any] | None]):
+            Callable that returns an `AsyncCache` for the given instance,
+            or None to disable caching for that instance.
+
+        key_hash_strategy (KeyHashStrategyProtocol):
+            Strategy used to compute deterministic cache keys from the
+            positional and keyword arguments. Defaults to `KeyHashStrategy`.
+
+        lock (Callable[[Any], AbstractContextManager[Any]] | None):
+            Optional lock context manager factory. Not supported.
+
+        info (bool):
+            If True, raises NotImplementedError (not supported).
+
+        result_predicate (Callable[[Any], bool]):
+            A custom callable that receives the completed result of the
+            coroutine and returns True if it should remain cached. If it
+            returns False, the result is evicted from the cache immediately
+            upon completion. Defaults to a lambda that always returns True.
+
+        exception_predicate (Callable[[BaseException], bool]):
+            A custom callable that receives the raised exception if the
+            coroutine fails, returning True if the exception should be cached.
+            If it returns False, the failed future is evicted, allowing
+            subsequent calls to retry execution. Defaults to a lambda that
+            always returns True.
+
+    Returns:
+        __AsyncMethodDecoratorProtocol:
+            A decorator that wraps an async method with caching behavior.
+
+    Raises:
+        NotImplementedError:
+            If `info` or `lock` are provided.
+
+    """
+    if info:
+        msg = "`info` is not supported"
+        raise NotImplementedError(msg)
+
+    if lock is not None:
+        msg = "`lock` is not supported"
+        raise NotImplementedError(msg)
+
+    def decorator[SelfT, **P, R](
+        fn: collections.abc.Callable[typing.Concatenate[SelfT, P], collections.abc.Awaitable[R]],
+    ) -> __AsyncCachedMethodWrapperProtocol[P, R]:
+        if not inspect.iscoroutinefunction(fn):
+            msg = f"Expected 'Coroutine' function, got {fn}"
+            raise TypeError(msg)
+
+        async def wrapper(self_obj: SelfT, *args: P.args, **kwargs: P.kwargs) -> R:
+            self_cache = cache(self_obj)
+
+            if self_cache is None:
+                return await fn(self_obj, *args, **kwargs)
+
+            # Generates key
+            generated_key = HashedKey(args, kwargs, hash_strategy=key_hash_strategy)
+
+            task, future = __async_cache_get(
+                cache=self_cache,
+                key=generated_key,
+                call_fn=lambda: fn(self_obj, *args, **kwargs),
+                result_predicate=result_predicate,
+                exception_predicate=exception_predicate,
+            )
+
+            try:
+                return await future
+            except asyncio.CancelledError:
+                # If an awaiting caller is cancelled, the corresponding cache entry is
+                # removed and the underlying task is cancelled when appropriate
+
+                # Evicts from cache instantly
+                self_cache.pop(generated_key, None)
+
+                # Directly terminates the underlying task loop execution
+                if not task.done():
+                    task.cancel()
+
+                raise
+
+        wrapped = typing.cast(
+            "__AsyncCachedMethodWrapperProtocol[P, R]",
+            functools.update_wrapper(wrapper, fn),
+        )
+
+        wrapped.cache = cache
+        wrapped.cache_key = key_hash_strategy
+        wrapped.cache_lock = None
+        wrapped.cache_info = None
+        wrapped.cache_clear = lambda self_obj: (
+            self_cache.clear() if (self_cache := cache(self_obj)) is not None else None
+        )
+
+        return wrapped
+
+    return decorator

btrcache/cache.py

@@ -0,0 +1,21 @@
+# Copyright (C) 2026 Lucas Dias
+
+"""Cache collections and related abstractions.
+
+This module provides shared cache collection interfaces, generic type
+aliases, and cache implementations.
+"""
+
+import typing
+
+from src.btrcache.keys import HashedKey
+
+if typing.TYPE_CHECKING:
+    import collections.abc
+
+__all__: typing.Final = ("Cache",)
+
+type Cache[R] = collections.abc.MutableMapping[
+    HashedKey,
+    R,
+]

btrcache/keys.py

@@ -0,0 +1,213 @@
+# Copyright (C) 2026 Lucas Dias
+#
+# Portions Copyright (C) 2026 Thomas Kemmer
+# Source: https://github.com/tkem/cachetools/blob/48284d73d0a8834c9c50f8d41bb99e6f93b2dfed/src/cachetools/keys.py
+# License: MIT (See LICENSE file for details)
+
+"""Utilities for constructing deterministic, hashable cache keys.
+
+This module provides strategies for converting positional and keyword
+arguments into immutable tuple representations suitable for hashing and
+cache lookups, along with a lightweight wrapper that lazily caches the
+computed hash value.
+"""
+
+import typing
+
+__all__: typing.Final = (
+    "HashedKey",
+    "KeyHashStrategy",
+    "KeyHashStrategyProtocol",
+    "KeyHashTypedStrategy",
+)
+
+# Immutable tuple representation used internally for cache keys.
+type RawCacheKey = tuple[typing.Any, ...]
+
+
+class KeyHashStrategyProtocol(typing.Protocol):
+    """Protocol implemented by cache key generation strategies."""
+
+    @staticmethod
+    def hashkey(args: tuple[object, ...], kwargs: dict[str, object]) -> RawCacheKey:
+        """Convert function arguments into a hashable cache key.
+
+        Args:
+            args (tuple[object, ...]):
+                Positional arguments.
+
+            kwargs (dict[str, object]):
+                Keyword arguments.
+
+        Returns:
+            RawCacheKey:
+                Immutable tuple representing the cache key.
+
+        """
+        raise NotImplementedError
+
+
+class KeyHashStrategy:
+    """Generate cache keys using only argument values."""
+
+    @staticmethod
+    def hashkey(args: tuple[object, ...], kwargs: dict[str, object]) -> RawCacheKey:
+        """Construct a deterministic cache key.
+
+        Positional arguments are stored first. Keyword arguments are
+        sorted by name and appended after a sentinel marker to ensure
+        deterministic ordering and avoid ambiguity with positional
+        arguments.
+
+        Args:
+            args (tuple[object, ...]):
+                Positional arguments.
+
+            kwargs (dict[str, object]):
+                Keyword arguments.
+
+        Returns:
+            RawCacheKey:
+                Immutable tuple representing the cache key.
+
+        """
+        # No keyword arguments are present
+        if not kwargs:
+            return tuple(args)
+
+        # Appends a marker followed by sorted keyword argument pairs to ensure
+        # deterministic ordering and distinguish them from positional arguments
+        return args + HashedKey.KWARGS_MARKER + tuple(sorted(kwargs.items()))
+
+
+class KeyHashTypedStrategy:
+    """Generate cache keys that also encode argument types."""
+
+    @staticmethod
+    def hashkey(args: tuple[object, ...], kwargs: dict[str, object]) -> RawCacheKey:
+        """Construct a type-aware cache key.
+
+        In addition to argument values, the runtime type of each argument
+        is appended to distinguish values that compare equal but have
+        different types.
+
+        Args:
+            args (tuple[object, ...]):
+                Positional arguments.
+
+            kwargs (dict[str, object]):
+                Keyword arguments.
+
+        Returns:
+            RawCacheKey:
+                Immutable tuple representing the cache key.
+
+        """
+        # Starts with the positional argument values and appends
+        # every value type to distinguish between them in the final
+        # hash
+        key = args + tuple(type(v) for v in args)
+
+        if kwargs:
+            # Sorts keyword arguments to produce a deterministic key
+            sorted_kwargs = tuple(sorted(kwargs.items()))
+
+            # Appends the sentinel marker and the keyword argument values
+            key += HashedKey.KWARGS_MARKER + sorted_kwargs
+
+            # Append the type of each keyword argument value
+            key += tuple(type(v) for _, v in sorted_kwargs)
+
+        return key
+
+
+class HashedKey:
+    """Immutable tuple-like object that caches its computed hash value.
+
+    The hash is computed lazily on first use and cached for subsequent
+    calls to avoid repeated tuple hashing overhead in cache key generation.
+    """
+
+    # Sentinel marker used to separate positional arguments from keyword arguments
+    # when building cache keys.
+    #
+    # This prevents ambiguity between calls like:
+    #     f(1, ("x", 2))        -> positional tuple argument
+    #     f(1, x=2)             -> keyword argument form
+    #
+    # Without a separator, both could normalize to the same tuple representation,
+    # causing cache key collisions.
+    #
+    # The value is a class object because it is guaranteed unique, immutable and hashable.
+    KWARGS_MARKER: typing.ClassVar[tuple[type]] = (tuple,)
+
+    def __init__(
+        self,
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        *,
+        hash_strategy: KeyHashStrategyProtocol = KeyHashStrategy,
+    ) -> None:
+        """Initialize a hashable cache key from function arguments.
+
+        This converts positional and keyword arguments into a single immutable
+        tuple representation used for hashing and equality comparisons.
+
+        Args:
+            args (tuple[object, ...]):
+                Positional arguments.
+
+            kwargs (dict[str, object]):
+                Keyword arguments.
+
+            hash_strategy (KeyHashStrategyProtocol):
+                Strategy used to normalize the arguments into an immutable cache
+                key representation.
+
+        """
+        self.__hashvalue: int
+        self.__tuple: RawCacheKey = hash_strategy.hashkey(args, kwargs)
+
+    @typing.override
+    def __eq__(self, value: object, /) -> bool:
+        # Keys must share the same class
+        if not isinstance(value, HashedKey):
+            return NotImplemented
+
+        # If they share the same hash, must be the same key
+        return self.__hash__() == value.__hash__()
+
+    @typing.override
+    def __hash__(self) -> int:
+        # Try-except is used instead of `is None` for
+        # performance issues
+        try:
+            return self.__hashvalue
+        except AttributeError:
+            # It will raise error if tuple has unhashable element
+            self.__hashvalue = self.__tuple.__hash__()
+            return self.__hashvalue
+
+    @typing.override
+    def __getstate__(self) -> object:
+        # Only keeps the given arguments in pickle
+        # (keeping hash stored is not safe)
+        return self.__tuple
+
+    def __setstate__(self, state: RawCacheKey) -> None:
+        """Restore the object state during unpickling.
+
+        This method reconstructs the internal immutable tuple representation
+        from the serialized state. Any cached hash value is intentionally
+        not restored, ensuring that the hash is recomputed lazily after
+        unpickling if needed.
+
+        Args:
+            state (RawCacheKey):
+                The previously serialized tuple representing the cache key.
+                This contains only the semantic argument structure and does
+                not include any runtime-cached values such as the hash.
+
+        """
+        # Restores internal tuple only
+        self.__tuple = state

btrcache-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: btrcache
+Version: 0.1.0
+Summary: High-performance caching tools, memoization decorators, and cache collections for Python.
+Project-URL: Homepage, https://github.com/lucas-azdias/btrcache?tab=readme-ov-file
+Project-URL: Source, https://github.com/lucas-azdias/btrcache
+Project-URL: Issues, https://github.com/lucas-azdias/btrcache/issues
+Author-email: Lucas Dias <lucas@azdias.com.br>
+Maintainer-email: Lucas Dias <lucas@azdias.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# `btrcache`
+
+[![License](https://img.shields.io/github/license/lucas-azdias/btrcache)](https://raw.github.com/lucas-azdias/btrcache/master/LICENSE)
+
+[![Coverage](https://img.shields.io/codecov/c/github/lucas-azdias/btrcache/main.svg)](https://codecov.io/gh/lucas-azdias/btrcache)
+
+High-performance caching tools, memoization decorators, and cache collections for Python.
+
+---
+
+## Overview
+
+**`btrcache`** is a Python library that provides a flexible set of in-memory caching primitives, decorators, and cache collections designed for both synchronous and asynchronous workloads.
+
+## Installation
+
+```bash
+pip install btrcache
+```
+
+<!--
+## Quick Start
+
+### Simple function memoization
+
+```python
+from btrcache import cached
+
+@cached()
+def fib(n: int) -> int:
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+```
+
+### Custom cache size
+
+```python
+from btrcache import cached, LRUCache
+
+@cached(cache_factory=lambda: LRUCache(maxsize=1024))
+def compute(x):
+    return x * x
+```
+-->
+
+## Roadmap
+
+* [X] Key generators
+* [X] Asynchronous decorators
+* [ ] Create tests
+* [ ] Release in PyPi
+* [ ] Synchronous decorators
+* [ ] Cache collections
+* [ ] Optimizations
+
+## Contributing
+
+Contributions are welcome. Please ensure:
+
+* Code is type-annotated;
+* Tests cover edge cases.
+
+## Acknowledgements
+
+This project builds upon ideas and implementations from the following open-source projects:
+
+- [`cachetools`](https://github.com/tkem/cachetools/) - An extensible set of memoizing collections and decorators for Python. Developed and maintained by [Thomas Kemmer](https://github.com/tkem/).
+- [`cachetools-async`](https://github.com/imnotjames/cachetools-async/) - Python library that extends `cachetools` with async decorators. Created by [James Ward](https://github.com/imnotjames/).
+
+## License
+
+Copyright (C) 2026 Lucas Dias.
+
+Licensed under the [MIT License](LICENSE).

btrcache-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+btrcache/__init__.py,sha256=xV1uBiQrCqH7JOahvX3eUUwzfwMGf4vCjiIIb4uVy50,303
+btrcache/__version__.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+btrcache/cache.py,sha256=-mTu0MFgI-SuYpNlKdKsk_B1sDj7WC7FxvlIPjGbmBY,409
+btrcache/keys.py,sha256=T5jEYt9p7Dp8c10kmmQmOiifehg8k4mg33zsM7spMEU,7058
+btrcache/asyncio/__init__.py,sha256=fErA-0szqAW0vAcEBuTbPyWSwTtMKXnVk3tSpKmT2xQ,273
+btrcache/asyncio/cache.py,sha256=jzrsl5wWkB2FFxbBXlTYm3N5QNXpJK5qejBjxzCT6gQ,458
+btrcache/asyncio/decorators.py,sha256=3T4zzQGq3SNxlXBeVwwuh-RW_IZRV5TvZZ45xrdOtII,14517
+btrcache-0.1.0.dist-info/METADATA,sha256=d7HmKyT9uGd0qqExzoPKnIna_5IG6yXGu9IO16A3NEI,2811
+btrcache-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+btrcache-0.1.0.dist-info/licenses/LICENSE,sha256=MdnrHR7Fd0qpOZbLajTEsB7ifgteTCTTiCcha0ASkWA,1067
+btrcache-0.1.0.dist-info/RECORD,,

btrcache-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

btrcache-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Dias
+
+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.