feat: on-get callback #38
Conversation
src/cacheout/cache.py
Outdated
| on_get: Callback which will be executed when a cache entry is got. | ||
| on_delete: Callback which will be executed when a cache entry is removed. |
There was a problem hiding this comment.
Would be good to include the excepted method signatures for on_get and on_delete in terms of what the positional arguments are since just the types don't give enough context.
There was a problem hiding this comment.
| on_get: Callback which will be executed when a cache entry is got. | |
| on_delete: Callback which will be executed when a cache entry is removed. | |
| on_get: Callback that will be executed when a cache entry is retrieved. It is called with arguments ``(key, value, exists)`` where `key` is the cache key, `value` is the value retrieved (could be the default), and `exists` is whether the cache key exists or not. | |
| on_delete: Callback that will be executed when a cache entry is removed. It is called with arguments ``(key, value, cause)`` where `key` is the cache key, `value` is the cached value at the time of deletion, and `cause` is the reason the key was removed (see :class:`RemovalCause` for enumerated causes). |
src/cacheout/cache.py
Outdated
| @@ -74,6 +74,7 @@ class Cache: | |||
| default: Default value or function to use in :meth:`get` when key is not found. If callable, | |||
| it will be passed a single argument, ``key``, and its return value will be set for that | |||
| cache key. | |||
| on_get: Callback which will be executed when a cache entry is got. | |||
There was a problem hiding this comment.
Instead of is got, maybe is retrieved.
src/cacheout/cache.py
Outdated
| if self.on_get: | ||
| self.on_get(key, value, True) | ||
| except KeyError: |
There was a problem hiding this comment.
There's an edge-case here where if self.on_get() throws a KeyError, then we end up calling it twice. Maybe we should defer calling self.on_get until after the try/except block. That way we'd only have a single place where it's called and if it happens to raise a KeyError, we won't mistakenly catch it.
src/cacheout/cache.py
Outdated
| F = t.TypeVar("F", bound=t.Callable[..., t.Any]) | ||
| T_DECORATOR = t.Callable[[F], F] | ||
| T_TTL = t.Union[int, float] | ||
| T_FILTER = t.Union[str, t.List[t.Hashable], t.Pattern, t.Callable] | ||
|
|
||
| UNSET = object() |
There was a problem hiding this comment.
These should stay at the top right below the imports.
src/cacheout/cache.py
Outdated
| T_DECORATOR = t.Callable[[F], F] | ||
| T_TTL = t.Union[int, float] | ||
| T_FILTER = t.Union[str, t.List[t.Hashable], t.Pattern, t.Callable] | ||
| ON_GET_CALLBACK = t.Optional[t.Callable[[t.Hashable, t.Any, bool], None]] |
src/cacheout/cache.py
Outdated
| """ | ||
| Callback that will be executed when a cache entry is retrieved. | ||
|
|
||
| It is called with arguments ``(key, value, exists)`` where `key` is the cache key, | ||
| `value` is the value retrieved (could be the default), | ||
| and `exists` is whether the cache key exists or not. | ||
| """ |
There was a problem hiding this comment.
Convert these to #: * prefixed comments above the variable declaration like:
#: Callback that will be executed when a cache entry is retrieved. It is called with arguments
#: ``(key, value, exists)`` where `key` is the cache key, `value` is the value retrieved (could be
#: the default), and `exists` is whether the cache key exists or not.
T_ON_DELETE_CALLBACK = ...
src/cacheout/cache.py
Outdated
| on_get: Callback which will be executed when a cache entry is retrieved. | ||
| on_delete: Callback which will be executed when a cache entry is removed. |
There was a problem hiding this comment.
My thinking of putting the variable descriptions here was so that it would be prominent when viewing the class documentation. Does any of the details from the constant docstrings show up here in the generated docs?
There was a problem hiding this comment.
I guess we could add a class reference so that there's at least a link to the variable docs using something like:
See :class:`T_ON_DELETE_CALLBACK`.
There was a problem hiding this comment.
My thinking of putting the variable descriptions here was so that it would be prominent when viewing the class documentation. Does any of the details from the constant docstrings show up here in the generated docs?
Yes, it works.
| #: Callback that will be executed when a cache entry is retrieved. | ||
|
|
||
| #: It is called with arguments ``(key, value, exists)`` where `key` is the cache key, | ||
| #: `value` is the value retrieved (could be the default), | ||
| #: and `exists` is whether the cache key exists or not. | ||
| T_ON_GET_CALLBACK = t.Optional[t.Callable[[t.Hashable, t.Any, bool], None]] | ||
|
|
||
| #: Callback that will be executed when a cache entry is removed. | ||
|
|
||
| #: It is called with arguments ``(key, value, cause)`` where `key` is the cache key, | ||
| #: `value` is the cached value at the time of deletion, | ||
| #: and `cause` is the reason the key was removed (see :class:`RemovalCause` for enumerated causes). | ||
| T_ON_DELETE_CALLBACK = t.Optional[t.Callable[[t.Hashable, t.Any, RemovalCause], None]] |
There was a problem hiding this comment.
nit: Constants should all be at the top after the imports. Class definitions next and then function definitions.
There was a problem hiding this comment.
T_ON_DELETE_CALLBACK must be after RemovalCause because it depends on RemovalCause.
Usage
set
on_getcallback.on_getis a callable object.keyis the key of cache entry has been got.valueis the real value when the key has existed. Otherwise, it's the default value.exsitedindicates whether the key has existed.