onecache 0.8.1__tar.gz → 0.9.0__tar.gz

onecache-0.9.0/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.0] 2026-10-12
+### Added
+- Cython implementation of the cache core, used automatically on CPython; pure Python fallback for PyPy and platforms without a prebuilt wheel
+- `onecache.COMPILED` flag and `ONECACHE_NO_EXTENSIONS` environment variable to force the pure Python implementation
+- Prebuilt wheels for Linux (manylinux/musllinux), macOS and Windows on x86_64 and ARM64, built with cibuildwheel
+- Decorated functions keep the wrapped function metadata (`__name__`, `__doc__`, `__wrapped__`)
+- `ExpirableCache.clear()` to drop every entry
+- `onecache.monotonic()`, the clock used for `CacheValue.expire_at`
+- Decorated functions support weak references and pickle by reference with both implementations
+
+### Changed
+- `LRUCache` now evicts the least recently used entry (previously the least frequently accessed)
+- Expiration checks are O(1) amortized instead of scanning the whole cache on every access, and eviction no longer sorts the cache
+- `thread_safe=True` now guards every cache operation, not only writes, with a reentrant lock
+- `max_mem_size` evicts entries until the new value fits, instead of always keeping at least one previous entry; a value bigger than `max_mem_size` is not cached
+- Setting an existing key again moves it to the newest position in the eviction order
+- `ExpirableCache.cache` is a read-only view; use `expire()` or `clear()` to remove entries. Its iteration order is not the eviction order
+- `timeout`, `max_mem_size`, `current_size` and `thread_safe` are read-only attributes; the `lock` attribute was removed
+- `CacheValue.expire_at` is a timestamp in seconds from `onecache.monotonic()` (`float("inf")` when it does not expire) instead of a `datetime`; that clock is not always `time.monotonic()`
+- `CacheValue.size` is only computed when `max_mem_size` is set (0 otherwise)
+- A `timeout` of 0 or lower means entries do not expire
+- A cache size (`maxsize`) lower than 1 raises `ValueError`
+- Eviction is no longer customizable by overriding `_pop_one()`
+- Cache instances (`ExpirableCache`, `LRUCache`) can't be pickled or copied; `CacheValue` entries pickle only their own data
+- On CPython, decorated functions are `CachedFunction` objects instead of plain functions (`inspect.isfunction()` is False), and compiled cache instances don't accept arbitrary attributes or weak references
+- Build backend switched from poetry-core to setuptools + Cython
+
+### Removed
+- `CacheValue.set_expired()`, `CacheValue.refresh_ttl()`, `CacheValue.increment()` and the `fetch_value` argument of `ExpirableCache.get()`
+- `onecache.IS_PYPY` and `onecache.utcnow` re-exports (still available in `onecache.utils`)
+
+## [0.8.1] 2026-02-20
+### Changed
+- Removed the maximum Python version constraint from runtime requirements (`python = ">=3.8"`)
+- Updated Python classifiers and refreshed CI/docs for newer Python versions
+
+## [0.8.0] 2025-11-12
+### Removed
+- Dropped the unused `packaging` dependency from runtime requirements
+
+## [0.7.2] 2025-10-30
+### Added
+* python 3.14 compatibility
+
+## [0.7.1] 2025-01-26
+### Added
+* python 3.13 compatibility
+
+
+## [0.7.0] 2024-08-01
+### Added
+* poetry for project management
+* utcnow() function utility for newer python versions
+
+## [0.6.0] 2023-08-11
+### Added
+- Compatibility and tests for python versions 3.10 and 3.11
+
+### Removed
+- Removed all cython stuff
+
+## [0.5.1] 2023-06-28
+### Fixed
+- Prevent access to attribute if cache_value is None
+
+## [0.5.0] 2023-03-27
+### Fixed
+- Pypy onecache works
+
+## [0.4.1] 2022-02-04
+### Fixed
+- Counting values size at decreasing
+
+## [0.4.0] 2022-01-30
+### Added
+- C extension for cache value with cython
+
+## [0.3.2] 2022-01-26
+### Added
+- Flag for thread safety
+
+## [0.3.1] 2021-07-20
+### Changed
+- Better pop when doing set, and reaching max size
+
+## [0.3.0] 2021-07-19
+### Changed
+- access map removed in favor of using cache map + CacheValue access attribute
+
+## [0.2.0] 2021-07-19
+### Added
+- CacheValue class as data container
+- refresh_ttl argument, for refresh ttl per key access
+
+## [0.1.0] 2021-07-18
+### Fixed
+- Better serialize keys with sort
+
+## [0.0.4] 2021-07-16
+### Fixed
+- TTL and LRU usage combination works as expected
+
+## [0.0.3] 2021-07-16
+### Added
+- LRUCache, using it by default for decorators
+
+## [0.0.2] 2021-07-16
+### Fix
+- Readme for pypi
+
+## [0.0.1] 2021-07-16
+### Added
+- Cache class
+- Sync and Async decorators
+
+[Unreleased]: https://github.com/sonic182/onecache/compare/0.9.0..HEAD
+[0.9.0]: https://github.com/sonic182/onecache/compare/0.8.1..0.9.0
+[0.8.1]: https://github.com/sonic182/onecache/compare/0.8.0..0.8.1
+[0.8.0]: https://github.com/sonic182/onecache/compare/0.7.2..0.8.0
+[0.7.2]: https://github.com/sonic182/onecache/compare/0.7.1..0.7.2
+[0.7.1]: https://github.com/sonic182/onecache/compare/0.7.0..0.7.1
+[0.7.0]: https://github.com/sonic182/onecache/compare/0.6.0..0.7.0
+[0.6.0]: https://github.com/sonic182/onecache/compare/0.5.1..0.6.0
+[0.5.1]: https://github.com/sonic182/onecache/compare/0.5.0..0.5.1
+[0.5.0]: https://github.com/sonic182/onecache/compare/0.4.1..0.5.0
+[0.4.1]: https://github.com/sonic182/onecache/compare/0.4.0..0.4.1
+[0.4.0]: https://github.com/sonic182/onecache/compare/0.3.2..0.4.0
+[0.3.2]: https://github.com/sonic182/onecache/compare/0.3.1..0.3.2
+[0.3.1]: https://github.com/sonic182/onecache/compare/0.3.0..0.3.1
+[0.3.0]: https://github.com/sonic182/onecache/compare/0.2.0..0.3.0
+[0.2.0]: https://github.com/sonic182/onecache/compare/0.1.0..0.2.0
+[0.1.0]: https://github.com/sonic182/onecache/compare/0.0.4..0.1.0
+[0.0.4]: https://github.com/sonic182/onecache/compare/0.0.3..0.0.4
+[0.0.3]: https://github.com/sonic182/onecache/compare/0.0.2..0.0.3
+[0.0.2]: https://github.com/sonic182/onecache/compare/0.0.1..0.0.2
+[0.0.1]: https://github.com/sonic182/onecache/compare/814065637987644cc56a09028df955e001a2163b..0.0.1

onecache-0.9.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include CHANGELOG.md
+include pytest.ini
+include onecache/*.pyx
+recursive-include tests *.py
+exclude onecache/*.c
+global-exclude *.so *.pyd *.py[cod]

{onecache-0.8.1 → onecache-0.9.0}/PKG-INFO

@@ -1,16 +1,14 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: onecache
-Version: 0.8.1
+Version: 0.9.0
 Summary: Python cache for sync and async code
+Author-email: Johanderson Mogollon <johander1822@gmail.com>
 License: MIT
-Author: Johanderson Mogollon
-Author-email: johander1822@gmail.com
-Requires-Python: >=3.8
+Project-URL: Homepage, https://github.com/sonic182/onecache
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Cython
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -18,8 +16,11 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+Dynamic: license
 
 
 [![Coverage Status](https://coveralls.io/repos/github/sonic182/onecache/badge.svg?branch=master)](https://coveralls.io/github/sonic182/onecache?branch=master)
@@ -30,7 +31,9 @@ Python cache for sync and async code.
 
 Cache uses an LRU algorithm and can optionally set TTLs per entry.
 
-Tested automatically on CPython 3.8–3.14 and PyPy 3.9 across Linux, macOS, and Windows (see the workflow badge). Earlier versions may work but are not part of the supported matrix.
+On CPython the cache core is a compiled Cython extension (prebuilt wheels for Linux, macOS and Windows on x86_64 and ARM64). On PyPy, or on platforms without a prebuilt wheel, it falls back to an equivalent pure Python implementation. `onecache.COMPILED` tells which one is in use.
+
+Tested automatically on CPython 3.10 and 3.14 and PyPy 3.11 across Linux, macOS, and Windows on x86_64 and ARM64 (see the workflow badge). Python 3.8 and 3.9 are still installable and get prebuilt wheels, but are no longer part of the test matrix.
 
 # Usage
 
@@ -79,9 +82,15 @@ Decorator classes supports the following arguments
 * **cache_class (class)**: Class to use for cache instance. default: LRUCache
 * **refresh_ttl (bool)**: if cache with ttl, This flag makes key expiration timestamp to be refresh per access. default: False
 * **thread_safe (bool)**: tell decorator to use thread safe lock. default=False
-* **max_mem_size (int)**: max mem size in bytes. Ceil for sum of cache values sizes. default=None which means no limit. For pypy this value is ignored as the objects can change by the JIT compilation.
+* **max_mem_size (int)**: max mem size in bytes, as the sum of `sys.getsizeof(key) + sys.getsizeof(value)` of every entry (shallow sizes). default=None which means no limit. For pypy this value is ignored as the objects can change by the JIT compilation.
+
+If num of records exceds maxsize, it drops the least recently used one. With `max_mem_size`, a value bigger than the limit is not cached.
 
-If num of records exceds maxsize, it drops the oldest.
+Use `thread_safe=True` when the decorated function is called from several threads.
+
+The decorated function exposes its cache as `.cache`: `.cache.expire(*args, **kwargs)` drops one entry, `.cache.clear()` drops all of them, and `.cache.cache` is a read-only view of the entries.
+
+Set `ONECACHE_NO_EXTENSIONS` to any non-empty value to force the pure Python implementation. If the extension failed to build when installing from source (e.g. no compiler), pip may keep reusing that pure Python build from its cache; reinstall with `pip install --no-cache-dir --force-reinstall onecache` after installing a compiler.
 
 
 # Development
@@ -91,11 +100,23 @@ Install dependencies with Poetry (includes dev + test groups):
 poetry install --with test,dev
 ```
 
-Run the test suite and coverage locally:
+Build the Cython extension in place (needed after any change to `onecache/_ccore.pyx`):
 ```bash
-poetry run pytest --cov
+make build_ext
 ```
 
+Run the test suite against the compiled and the pure Python implementations:
+```bash
+poetry run pytest
+ONECACHE_NO_EXTENSIONS=1 poetry run pytest
+```
+
+`onecache/_ccore.pyx` and `onecache/_core.py` implement the same API and must be kept in sync.
+
+# Releasing
+
+Pull requests only build cp310 and cp314 wheels, so first run the `Wheels` workflow by hand on `master` (Actions → Wheels → Run workflow) to build and test every Python version. Then bump `version` in `pyproject.toml` and push a tag with the same value (e.g. `0.9.0`). The `Wheels` workflow builds the wheels with cibuildwheel, the sdist and a pure Python fallback wheel, and publishes them to PyPI through trusted publishing. That needs a `pypi` environment in the GitHub repository settings and a trusted publisher on PyPI for this repository, workflow `wheels.yml` and environment `pypi`.
+
 Lint and format checks:
 ```bash
 poetry run flake8
@@ -109,4 +130,3 @@ poetry run autopep8 --in-place --recursive onecache tests
 3. commit - push - pull request
 
 Thanks :)
-

onecache-0.9.0/README.md

@@ -0,0 +1,108 @@
+
+[![Coverage Status](https://coveralls.io/repos/github/sonic182/onecache/badge.svg?branch=master)](https://coveralls.io/github/sonic182/onecache?branch=master)
+![github status](https://github.com/sonic182/onecache/actions/workflows/python.yml/badge.svg)
+# OneCache
+
+Python cache for sync and async code.
+
+Cache uses an LRU algorithm and can optionally set TTLs per entry.
+
+On CPython the cache core is a compiled Cython extension (prebuilt wheels for Linux, macOS and Windows on x86_64 and ARM64). On PyPy, or on platforms without a prebuilt wheel, it falls back to an equivalent pure Python implementation. `onecache.COMPILED` tells which one is in use.
+
+Tested automatically on CPython 3.10 and 3.14 and PyPy 3.11 across Linux, macOS, and Windows on x86_64 and ARM64 (see the workflow badge). Python 3.8 and 3.9 are still installable and get prebuilt wheels, but are no longer part of the test matrix.
+
+# Usage
+
+```python
+from onecache import CacheDecorator
+from onecache import AsyncCacheDecorator
+
+
+class Counter:
+    def __init__(self, count=0):
+        self.count = count
+
+
+@pytest.mark.asyncio
+async def test_async_cache_counter():
+    """Test async cache, counter case."""
+    counter = Counter()
+
+    @AsyncCacheDecorator()
+    async def mycoro(counter: Counter):
+        counter.count += 1
+        return counter.count
+
+    assert 1 == (await mycoro(counter))
+    assert 1 == (await mycoro(counter))
+
+
+def test_cache_counter():
+    """Test async cache, counter case."""
+    counter = Counter()
+
+    @CacheDecorator()
+    def sample(counter: Counter):
+        counter.count += 1
+        return counter.count
+
+    assert 1 == (sample(counter))
+    assert 1 == (sample(counter))
+```
+
+Decorator classes supports the following arguments
+
+* **maxsize (int)**: Maximun number of items to be cached. default: 512
+* **ttl (int)**: time to expire in milliseconds, if None, it does not expire. default: None
+* **skip_args (bool)**: apply cache as the function doesn't have any arguments, default: False
+* **cache_class (class)**: Class to use for cache instance. default: LRUCache
+* **refresh_ttl (bool)**: if cache with ttl, This flag makes key expiration timestamp to be refresh per access. default: False
+* **thread_safe (bool)**: tell decorator to use thread safe lock. default=False
+* **max_mem_size (int)**: max mem size in bytes, as the sum of `sys.getsizeof(key) + sys.getsizeof(value)` of every entry (shallow sizes). default=None which means no limit. For pypy this value is ignored as the objects can change by the JIT compilation.
+
+If num of records exceds maxsize, it drops the least recently used one. With `max_mem_size`, a value bigger than the limit is not cached.
+
+Use `thread_safe=True` when the decorated function is called from several threads.
+
+The decorated function exposes its cache as `.cache`: `.cache.expire(*args, **kwargs)` drops one entry, `.cache.clear()` drops all of them, and `.cache.cache` is a read-only view of the entries.
+
+Set `ONECACHE_NO_EXTENSIONS` to any non-empty value to force the pure Python implementation. If the extension failed to build when installing from source (e.g. no compiler), pip may keep reusing that pure Python build from its cache; reinstall with `pip install --no-cache-dir --force-reinstall onecache` after installing a compiler.
+
+
+# Development
+
+Install dependencies with Poetry (includes dev + test groups):
+```bash
+poetry install --with test,dev
+```
+
+Build the Cython extension in place (needed after any change to `onecache/_ccore.pyx`):
+```bash
+make build_ext
+```
+
+Run the test suite against the compiled and the pure Python implementations:
+```bash
+poetry run pytest
+ONECACHE_NO_EXTENSIONS=1 poetry run pytest
+```
+
+`onecache/_ccore.pyx` and `onecache/_core.py` implement the same API and must be kept in sync.
+
+# Releasing
+
+Pull requests only build cp310 and cp314 wheels, so first run the `Wheels` workflow by hand on `master` (Actions → Wheels → Run workflow) to build and test every Python version. Then bump `version` in `pyproject.toml` and push a tag with the same value (e.g. `0.9.0`). The `Wheels` workflow builds the wheels with cibuildwheel, the sdist and a pure Python fallback wheel, and publishes them to PyPI through trusted publishing. That needs a `pypi` environment in the GitHub repository settings and a trusted publisher on PyPI for this repository, workflow `wheels.yml` and environment `pypi`.
+
+Lint and format checks:
+```bash
+poetry run flake8
+poetry run autopep8 --in-place --recursive onecache tests
+```
+
+# Contribute
+
+1. Fork
+2. create a branch `feature/your_feature`
+3. commit - push - pull request
+
+Thanks :)

onecache-0.9.0/onecache/__init__.py

@@ -0,0 +1,122 @@
+"""Onecache main module."""
+
+import os
+from functools import update_wrapper
+from typing import Optional
+
+if os.environ.get("ONECACHE_NO_EXTENSIONS"):
+    from onecache._core import CacheValue, ExpirableCache, LRUCache, monotonic
+
+    COMPILED = False
+else:
+    try:
+        from onecache._ccore import CacheValue, ExpirableCache, LRUCache, monotonic
+
+        COMPILED = True
+    except ImportError:
+        from onecache._core import CacheValue, ExpirableCache, LRUCache, monotonic
+
+        COMPILED = False
+
+__all__ = [
+    "AsyncCacheDecorator",
+    "CacheDecorator",
+    "CacheValue",
+    "COMPILED",
+    "ExpirableCache",
+    "LRUCache",
+    "monotonic",
+]
+
+_MISSING = object()
+
+
+class CacheDecorator:
+    """Decorator for ExpirableCache"""
+
+    def __init__(
+        self,
+        maxsize=512,
+        ttl: Optional[int] = None,
+        skip_args: bool = False,
+        cache_class=LRUCache,
+        refresh_ttl: Optional[bool] = False,
+        thread_safe: Optional[bool] = False,
+        max_mem_size: Optional[int] = None,
+    ):
+        """
+        Args:
+            * **maxsize (int)**: Maximun number of items to be cached. default: 512
+            * **ttl (int)**: time to expire in milliseconds, if None, it does not expire. default: None
+            * **skip_args (bool)**: apply cache as the function doesn't have any arguments, default: False
+            * **cache_class (class)**: Class to use for cache instance. default: LRUCache
+            * **refresh_ttl (bool)**: if cache with ttl, This flag makes key expiration timestamp to be
+                refresh per access. default: False
+            * **thread_safe (bool)**: tell decorator to use thread safe lock. default=False
+            * **max_mem_size (int)**: max mem size inside cache structure. default=None which means no limit.
+                For pypy this value is ignored as the objects can change by the JIT compilation.
+        """
+        self.cache = cache_class(
+            maxsize,
+            ttl,
+            refresh_ttl=refresh_ttl,
+            thread_safe=thread_safe,
+            max_mem_size=max_mem_size,
+        )
+        self.maxsize = maxsize
+        self.skip_args = skip_args
+        self._fast = type(self.cache) in (ExpirableCache, LRUCache)
+
+    def __call__(self, func):
+        cache = self.cache
+        skip_args = self.skip_args
+
+        if self._fast:
+            return update_wrapper(cache._wrap(func, skip_args), func, updated=())
+
+        def wrapper(*args, **kwargs):
+            key = "any" if skip_args else cache.get_key(*args, **kwargs)
+            if key not in cache:
+                resp = func(*args, **kwargs)
+                cache.set(key, resp)
+                return resp
+            return cache.get(key)
+
+        wrapper.cache = cache
+
+        return update_wrapper(wrapper, func, updated=())
+
+
+class AsyncCacheDecorator(CacheDecorator):
+    """Async Decorator for ExpirableCache"""
+
+    def __call__(self, func):
+        cache = self.cache
+        skip_args = self.skip_args
+
+        if self._fast:
+            make_key = cache._make_key
+            lookup = cache._lookup
+            set_value = cache.set
+
+            async def async_wrapper(*args, **kwargs):
+                key = "any" if skip_args else make_key(args, kwargs)
+                value = lookup(key, _MISSING)
+                if value is _MISSING:
+                    value = await func(*args, **kwargs)
+                    set_value(key, value)
+                return value
+
+        else:
+
+            async def async_wrapper(*args, **kwargs):
+                key = "any" if skip_args else cache.get_key(*args, **kwargs)
+                if key not in cache:
+                    resp = await func(*args, **kwargs)
+                    cache.set(key, resp)
+                    return resp
+                return cache.get(key)
+
+        async_wrapper.cache = cache
+
+        return update_wrapper(async_wrapper, func, updated=())