cachebox 6.1.2__tar.gz → 6.2.1__tar.gz

{cachebox-6.1.2 → cachebox-6.2.1}/.github/workflows/CI.yml

@@ -57,7 +57,6 @@ jobs:
           args: --release --out dist --interpreter ${{ matrix.platform.interpreter }}
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
           manylinux: auto
-          rust-toolchain: nightly
 
       - uses: actions/upload-artifact@v7.0.1
         with:
@@ -101,7 +100,6 @@ jobs:
           args: --release --out dist --interpreter ${{ matrix.platform.interpreter }}
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
           manylinux: musllinux_1_2
-          rust-toolchain: nightly
 
       - uses: actions/upload-artifact@v7.0.1
         with:
@@ -117,7 +115,10 @@ jobs:
               target: x64,
               interpreter: "3.10 3.11 3.12 3.13 3.14 3.14t 3.15 3.15t pypy3.11",
             }
-          - { target: x86, interpreter: "3.10 3.11 3.12 3.13 3.14 3.14t 3.15 3.15t" }
+          - {
+              target: x86,
+              interpreter: "3.10 3.11 3.12 3.13 3.14 3.14t 3.15 3.15t",
+            }
 
     steps:
       - uses: actions/checkout@v6.0.2
@@ -134,7 +135,6 @@ jobs:
           target: ${{ matrix.platform.target }}
           args: --release --out dist --interpreter ${{ matrix.platform.interpreter }}
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
-          rust-toolchain: nightly
 
       - uses: actions/upload-artifact@v7.0.1
         with:
@@ -169,7 +169,6 @@ jobs:
           target: ${{ matrix.platform.target }}
           args: --release --out dist --interpreter ${{ matrix.platform.interpreter }}
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
-          rust-toolchain: nightly
 
       - uses: actions/upload-artifact@v7.0.1
         with:
@@ -188,7 +187,6 @@ jobs:
         with:
           command: sdist
           args: --out dist
-          rust-toolchain: nightly
 
       - name: Upload sdist
         uses: actions/upload-artifact@v7.0.1

{cachebox-6.1.2 → cachebox-6.2.1}/.github/workflows/python-test.yml

@@ -16,7 +16,7 @@ env:
 
 jobs:
   test-python:
-    name: test ${{ matrix.python-version }}
+    name: ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     continue-on-error: ${{ endsWith(matrix.python-version, 't') }}
     strategy:
@@ -36,22 +36,24 @@ jobs:
     steps:
       - uses: actions/checkout@v6.0.2
 
-      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/rust-toolchain@stable
 
       - uses: actions/setup-python@v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
 
-      - run: pip install virtualenv pytest pytest-asyncio hypothesis maturin
+      - run: pip install virtualenv
+      - run: pip install -r requirements-dev.txt
       - run: virtualenv --no-vcs-ignore .venv
+
       - run: maturin develop --features use-small-offset
-      - run: pytest -v
+      - run: pytest -v -n auto
         env:
           HYPOTHESIS_PROFILE: slow
 
   test-os:
-    name: test on ${{ matrix.os }}
+    name: ${{ matrix.os }}
     runs-on: ${{ matrix.os }}-latest
     strategy:
       fail-fast: false
@@ -61,16 +63,17 @@ jobs:
     steps:
       - uses: actions/checkout@v6.0.2
 
-      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/rust-toolchain@stable
 
       - uses: actions/setup-python@v6.2.0
         with:
           python-version: "3.13"
-          allow-prereleases: true
 
-      - run: pip install virtualenv pytest pytest-asyncio hypothesis maturin
+      - run: pip install virtualenv
+      - run: pip install -r requirements-dev.txt
       - run: virtualenv --no-vcs-ignore .venv
+
       - run: maturin develop --features use-small-offset
-      - run: pytest -v
+      - run: pytest -v -n auto
         env:
           HYPOTHESIS_PROFILE: slow

{cachebox-6.1.2 → cachebox-6.2.1}/Cargo.lock

@@ -2,6 +2,12 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "allocator-api2"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c880a97d28a3681c0267bd29cff89621202715b065127cd445fa0f0fe0aa2880"
+
 [[package]]
 name = "android_system_properties"
 version = "0.1.5"
@@ -31,8 +37,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "cachebox"
-version = "6.1.2"
+version = "6.2.1"
 dependencies = [
+ "allocator-api2",
  "cfg-if",
  "chrono",
  "fastrand",

{cachebox-6.1.2 → cachebox-6.2.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachebox"
-version = "6.1.2"
+version = "6.2.1"
 edition = "2021"
 description = "The fastest memoizing and caching Python library written in Rust"
 readme = "README.md"
@@ -22,12 +22,12 @@ panic = "abort"
 strip = true
 
 [dependencies]
+allocator-api2 = "0.4.0"
 cfg-if = "1.0.4"
 chrono = "0.4.44"
 fastrand = "2.4.1"
 parking_lot = {version="0.12.5", default-features=false}
 pyo3 = {version="0.29", default-features=false, features=["macros", "chrono"]}
-# tokio = {version="1.52.3", default-features=false, features=["sync"]}
 
 [build-dependencies]
 pyo3-build-config = {version="0.29", default-features=false, features=["resolve-config"]}

{cachebox-6.1.2 → cachebox-6.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachebox
-Version: 6.1.2
+Version: 6.2.1
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Programming Language :: Python :: 3
@@ -161,7 +161,7 @@ assert cache.get("key") == "value"
 ```
 
 ## Learn more
-Read the documentation for full information and learn more: [**Documentation**](https://awolverp.github.com/cachebox)
+Read the documentation for full information and learn more: [**Documentation**](https://awolverp.github.io/cachebox/)
 
 ## License
 This repository is licensed under the [MIT License](LICENSE)

{cachebox-6.1.2 → cachebox-6.2.1}/README.md

@@ -130,7 +130,7 @@ assert cache.get("key") == "value"
 ```
 
 ## Learn more
-Read the documentation for full information and learn more: [**Documentation**](https://awolverp.github.com/cachebox)
+Read the documentation for full information and learn more: [**Documentation**](https://awolverp.github.io/cachebox/)
 
 ## License
 This repository is licensed under the [MIT License](LICENSE)

{cachebox-6.1.2 → cachebox-6.2.1}/cachebox/_core.pyi

@@ -157,7 +157,9 @@ class BaseCacheImpl(typing.Generic[KT, VT]):
         *args: typing.Any,
         **kwargs: typing.Any,
     ) -> None: ...
-    def get(self, key: KT, default: typing.Optional[DT] = None) -> typing.Union[VT, DT]: ...
+    def get(
+        self, key: KT, default: typing.Optional[DT] = None
+    ) -> typing.Union[VT, DT]: ...
     def __getitem__(self, key: KT) -> VT: ...
     def setdefault(
         self,
@@ -166,6 +168,13 @@ class BaseCacheImpl(typing.Generic[KT, VT]):
         *args: typing.Any,
         **kwargs: typing.Any,
     ) -> typing.Optional[VT | DT]: ...
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+        *args: typing.Any,
+        **kwargs: typing.Any,
+    ) -> VT | DT: ...
     def pop(self, key: KT, default: DT = ...) -> typing.Union[VT, DT]:
         """
         Removes the specified key and returns the corresponding value.
@@ -352,15 +361,40 @@ class Cache(BaseCacheImpl[KT, VT]):
         default: typing.Optional[DT] = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
+        """
+        ...
+
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 
@@ -508,15 +542,40 @@ class FIFOCache(BaseCacheImpl[KT, VT]):
         default: typing.Optional[DT] = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
+        """
+        ...
+
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 
@@ -697,15 +756,40 @@ class RRCache(BaseCacheImpl[KT, VT]):
         default: typing.Optional[DT] = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
+        """
+        ...
+
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 
@@ -879,15 +963,40 @@ class LRUCache(BaseCacheImpl[KT, VT]):
         default: typing.Optional[DT] = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
+        """
+        ...
+
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 
@@ -1102,15 +1211,40 @@ class LFUCache(BaseCacheImpl[KT, VT]):
         default: typing.Optional[DT] = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
+        """
+        ...
+
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 
@@ -1284,15 +1418,40 @@ class TTLCache(BaseCacheImpl[KT, VT]):
         default: typing.Optional[DT] = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
+        """
+        ...
+
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 
@@ -1524,16 +1683,43 @@ class VTTLCache(BaseCacheImpl[KT, VT]):
         ttl: float | timedelta | datetime | None = None,
     ) -> typing.Optional[VT | DT]:
         """
-        Inserts ``key`` with ``default`` as its value if the key is absent.
+        Get `key`s value, or atomatically insert `default` and return it.
+        If `key` exists, its current value is returned and `default` is ignored.
+        Otherwise `default` is inserted for `key` and returned.
+
+        Note:
+            Use `setdefault_with`, if computing the value is expensive or has side
+            effectes.
 
         Args:
             key: The key to look up or insert.
             default: The value to insert if ``key`` is not in the cache.
                 Defaults to ``None``.
-            ttl: An optional time-to-live duration for items.
+            ttl: An optional time-to-live duration for item.
+        """
+        ...
 
-        Returns:
-            The existing value if ``key`` is present, otherwise ``default``.
+    def setdefault_with(
+        self,
+        key: KT,
+        factory: typing.Callable[[], DT],
+        ttl: float | timedelta | datetime | None = None,
+    ) -> VT | DT:
+        """
+        Get `key`s value, or atomatically create and insert one via `factory`.
+        If `key` exists, its current value is returned and `factory` is not called.
+        Otherwise `factory` is called exactly once under an internal lock, its
+        result is inserted and returned.
+
+        Args:
+            key: The key to look up or insert.
+            factory: The factory to call and get default value from if ``key`` is not in the cache.
+            ttl: An optional time-to-live duration for item.
+
+        Warning:
+            `factory` must not call back into this cache (deadlock risk) or block
+            for long. If `factory` raises, nothing is inserted and the exception
+            propagates.
         """
         ...
 

{cachebox-6.1.2 → cachebox-6.2.1}/cachebox/_wrappers.py

@@ -3,7 +3,7 @@ import typing
 from collections import namedtuple
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
-from cachebox import BaseCacheImpl
+from cachebox._core import BaseCacheImpl, Cache
 
 _PostProcess: typing.TypeAlias = typing.Callable[[typing.Any], typing.Any]
 _Callback: typing.TypeAlias = typing.Callable[[int, typing.Any, typing.Any], typing.Any]
@@ -71,7 +71,9 @@ def _cached_wrapper_without_lock(
 
     # Per-instance caches receive `self` as args[0]; exclude it from the ke
     _make_key = (
-        (lambda a, k: key_maker(*a[1:], **k)) if cache_is_fn else (lambda a, k: key_maker(*a, **k))
+        (lambda a, k: key_maker(*a[1:], **k))
+        if cache_is_fn
+        else (lambda a, k: key_maker(*a, **k))
     )
 
     hits = 0
@@ -143,7 +145,9 @@ def _async_cached_wrapper_without_lock(
 
     # Per-instance caches receive `self` as args[0]; exclude it from the ke
     _make_key = (
-        (lambda a, k: key_maker(*a[1:], **k)) if cache_is_fn else (lambda a, k: key_maker(*a, **k))
+        (lambda a, k: key_maker(*a[1:], **k))
+        if cache_is_fn
+        else (lambda a, k: key_maker(*a, **k))
     )
 
     hits = 0
@@ -205,13 +209,15 @@ def _cached_wrapper(
 
     # Per-instance caches receive `self` as args[0]; exclude it from the key
     _make_key = (
-        (lambda a, k: key_maker(*a[1:], **k)) if cache_is_fn else (lambda a, k: key_maker(*a, **k))
+        (lambda a, k: key_maker(*a[1:], **k))
+        if cache_is_fn
+        else (lambda a, k: key_maker(*a, **k))
     )
 
     hits = 0
     misses = 0
 
-    locks: dict[typing.Hashable, _Lock] = {}
+    locks: Cache[typing.Hashable, _Lock] = Cache(0)
     pending_errors: dict[typing.Hashable, BaseException] = {}
 
     def _wrapped(*args, **kwds):
@@ -237,9 +243,7 @@ def _cached_wrapper(
         except KeyError:
             pass
 
-        lock = locks.get(key)
-        if lock is None:
-            locks[key] = lock = _Lock(lock_type())
+        lock = locks.setdefault_with(key, lambda: _Lock(lock_type()))
 
         # Acquire the per-key lock so that only one task computes the value
         # while the rest wait.
@@ -307,12 +311,37 @@ def _async_cached_wrapper(
 ):
     cache_is_fn = callable(cache)
     _make_key = (
-        (lambda a, k: key_maker(*a[1:], **k)) if cache_is_fn else (lambda a, k: key_maker(*a, **k))
+        (lambda a, k: key_maker(*a[1:], **k))
+        if cache_is_fn
+        else (lambda a, k: key_maker(*a, **k))
     )
 
     hits = 0
     misses = 0
-    locks: dict[typing.Hashable, _AsyncLock] = {}
+
+    # See _cached_wrapper
+    locks: Cache[typing.Hashable, _AsyncLock] = Cache(0)
+
+    # if lock_type is asyncio.Lock:
+
+    #     async def _get_lock(key: typing.Hashable):
+    #         return locks.setdefault(key, _AsyncLock(lock_type()))
+
+    # else:
+    #     _lock_creation_guard = asyncio.Lock()
+
+    #     async def _get_lock(key: typing.Hashable):
+    #         lock = locks.get(key)
+    #         if lock is not None:
+    #             return lock
+
+    #         async with _lock_creation_guard:
+    #             lock = locks.get(key)
+    #             if lock is None:
+    #                 locks[key] = lock = _AsyncLock(lock_type())
+
+    #         return lock
+
     pending_errors: dict[typing.Hashable, BaseException] = {}
 
     async def _wrapped(*args, **kwds):
@@ -335,9 +364,7 @@ def _async_cached_wrapper(
         except KeyError:
             pass
 
-        lock = locks.get(key)
-        if lock is None:
-            locks[key] = lock = _AsyncLock(lock_type())
+        lock = locks.setdefault_with(key, lambda: _AsyncLock(lock_type()))
 
         async with lock:
             err = pending_errors.get(key)