onecache

library0.8.1pypypi✓ verified 22d ago

onecache is a Python library providing in-memory caching for both synchronous and asynchronous code. It implements an LRU (Least Recently Used) algorithm and supports time-to-live (TTL) expiration for cache entries. The library is currently at version 0.8.1, with its latest update on February 20, 2026, indicating active maintenance though releases might be infrequent.

database

pip install onecache

package ↗

INSTALL

IMPORT

SIG · ONECACHE

onecache

databasepythonv0.8.1

Install

1.6s avg

Import

25ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.026s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.024s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CacheDecorator

✓ from onecache import CacheDecorator

AsyncCacheDecorator

✓ from onecache import AsyncCacheDecorator

This example demonstrates basic usage of `CacheDecorator` for synchronous functions and `AsyncCacheDecorator` for asynchronous functions. It shows how to apply the decorators with `maxsize` and `ttl` parameters, and how cache hits and misses affect the underlying function's execution count. For the async example, `asyncio.run()` is used to execute the main coroutine.

import asyncio from onecache import CacheDecorator, AsyncCacheDecorator # Synchronous Cache Example counter_sync = {'count': 0} @CacheDecorator(maxsize=2, ttl=1000) # max 2 items, TTL 1000ms def get_sync_data(key): counter_sync['count'] += 1 print(f"Fetching sync data for {key}. Call count: {counter_sync['count']}") return f"sync_value_{key}_{counter_sync['count']}" print("--- Sync Cache ---") print(get_sync_data('A')) # Fetch, count=1 print(get_sync_data('A')) # Cached, count=1 print(get_sync_data('B')) # Fetch, count=2 print(get_sync_data('C')) # Fetch, count=3, 'A' might be evicted (LRU) print(get_sync_data('A')) # Re-fetch if evicted, count=4 (or cached if B evicted) # Asynchronous Cache Example counter_async = {'count': 0} @AsyncCacheDecorator(maxsize=2, ttl=1000) async def get_async_data(key): counter_async['count'] += 1 print(f"Fetching async data for {key}. Call count: {counter_async['count']}") await asyncio.sleep(0.01) # Simulate async work return f"async_value_{key}_{counter_async['count']}" async def main(): print("\n--- Async Cache ---") print(await get_async_data('X')) # Fetch, count=1 print(await get_async_data('X')) # Cached, count=1 print(await get_async_data('Y')) # Fetch, count=2 print(await get_async_data('Z')) # Fetch, count=3, 'X' might be evicted (LRU) print(await get_async_data('X')) # Re-fetch if evicted, count=4 (or cached if Y evicted) if __name__ == '__main__': asyncio.run(main())

Debug

Known issues

gotchaThe `max_mem_size` parameter in `CacheDecorator` is ignored when running on PyPy. On CPython, it enforces a memory limit for cached values, but this functionality is bypassed in PyPy environments due to its JIT compilation and object size characteristics.

fix

Avoid relying on `max_mem_size` for memory control when deploying to PyPy. Implement external memory monitoring or alternative eviction strategies if strict memory limits are required in PyPy.

affects: >=0.8.0

gotchaBy default, `CacheDecorator` and `AsyncCacheDecorator` are not thread-safe (`thread_safe=False`). In multi-threaded synchronous applications, or when sharing an async cache across multiple event loop tasks that modify the cache concurrently, race conditions can occur.

fix

For thread-safe operation in concurrent environments, explicitly set `thread_safe=True` in the decorator arguments: `@CacheDecorator(thread_safe=True)` or `@AsyncCacheDecorator(thread_safe=True)`. This will use a lock to protect cache access.

affects: All versions

gotchaThe `ttl` (time-to-live) for a cache entry is not automatically refreshed on access by default. If an item is accessed frequently but its initial TTL has passed, it will be evicted despite recent use.

fix

If you want the TTL to be reset (refreshed) whenever a cached item is accessed, set the `refresh_ttl` parameter to `True` in the decorator: `@CacheDecorator(ttl=60000, refresh_ttl=True)`.

affects: All versions

gotcha`onecache` is purely an in-memory cache. It does not provide any persistence mechanism out-of-the-box, meaning all cached data will be lost when the application restarts or the process terminates.

fix

For persistent caching across application restarts, integrate `onecache` with a separate persistent storage layer (e.g., Redis, database, file system) or choose a different caching library designed for persistence (e.g., `requests-cache` for HTTP, `anycache` for general object persistence).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'onecache'

The `onecache` library has not been installed in the current Python environment.

fix

pip install onecache

ImportError: cannot import name 'cache' from 'onecache.cache'

The `cache` decorator is directly available from the top-level `onecache` package, not from a non-existent submodule like `onecache.cache`.

fix

from onecache import cache

TypeError: '<' not supported between instances of 'str' and 'int'

The `ttl` (time-to-live) or `maxsize` arguments for the `@cache` decorator were provided with an incorrect data type, such as a string instead of an integer.

fix

from onecache import cache

@cache(ttl=60, maxsize=100)
def my_func():
    return 'cached data'

TypeError: 'str' object is not callable

The `key_builder` argument expects a callable (a function) to generate custom cache keys, but a non-callable object (like a string or number) was provided.

fix

from onecache import cache

@cache(key_builder=lambda *args, **kwargs: f'custom_key_{args[0]}')
def my_func(arg1, arg2='default'):
    return arg1 + arg2

Upgrade

Version history

0.8.1latest on PyPI · released Feb 20, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/onecache/ ↗