Eviction callback

[uncle-lv]

An optional callback when the cache entry was deleted.

[uncle-lv]

Usage

set on_delete callback.

cache = Cache(on_delete=on_delete)

on_delete is a callable object.

Callable[[key: Hashable, value: Any, cause: EvictedCause],  None]

First parameter is the key of cache entry has been deleted.

Second is the value.

Third is the cause of cache entry eviction.

EvictedCause is an enum.

class EvictedCause(Enum):
    EXPLICIT = auto()
    REPLACED = auto()
    EXPIRED = auto()
    SIZE = auto()

• EXPLICIT: indicates that the cache entry was deleted explicitly.

• REPLACED: indicates that the entry was replaced with a new value.

• EXPIRED: indicates that the cache entry was removed because it expired.

• SIZE: indicates that the cache entry was removed because cache has reached the maximum size limit.

Trigger

The table shows methods will trigger on_delete.

cause	trigger
EXPLICIT	The cache entry was removed explicitly by delete() or delete_many()
REPLACED	The cache entry was replaced by set() or set_many()
EXPIRED	Implicit. When the cache entry was removed because it expired
SIZE	Implicit. The cache entry was removed because cache has reached the maximum size limit

⚠ clear() never triggers on_delete.

[coveralls]

coverage: 100.0%. remained the same when pulling db9d136 on uncle-lv:eviction-callback into 11ba7fd on dgilland:master.

[uncle-lv]

This pr is for #30 .

[uncle-lv]

This pr includes the commits of last pr. I tried to solve it, but failed. So does anyone know the right way to do it?

[uncle-lv]

Sorry, I was not able to solve this problem finally. So I used force push to make commits clean.

[dgilland]

Looks good overall! A few minor tweaks and some discussion around which eviction cause to use when popitem() called.

[dgilland]

Suggested change

	An enum to represent the cause for the evication of a cache entry.
	An enum to represent the cause for the eviction of a cache entry.

[dgilland]

Suggested change

	class EvictedCause(Enum):
	class EvictionCause(Enum):

[dgilland]

I wonder if _popitem() might need the eviction cause as an argument since it could potentially be called for different reasons. It's either called from evict() which would be SIZE but when called from popitem() it could be considered EXPLICIT since it's similar to a direct call to delete() except the key isn't being supplied. Seems like SIZE might not fit so well if the caller is the one making the popitem() call (so really the cache might not be full, it's just being intentionally pruned based on the cache policy).

Just brainstorming here, but another option might be to have POLICY replace SIZE which would encompass deleting the key because either the cache was full or because the key was removed via popitem(). But maybe wanting to differentiate between cache-full and an explicit call to remove a key would be preferable.

Thoughts?

[uncle-lv]

I will add an EvictionCause argument for _popitem().
It will be committed soon.

[uncle-lv]

After careful consideration, I don't agree popitem() should be considered EXPLICIT, because the user don't know which entry will be deleted explicitly. But I have no idea about it now. Maybe a new EvictionCause value called POPITEM? Any suggestions?

[dgilland]

If going the route of something like EvictionCause.POPITEM, then could potentially align with the method names where the eviction is happening.

E.g.

• EXPLICIT -> DELETE
• REPLACE -> SET
• SIZE -> FULL
• EXPIRED (leave as-is)
• POPITEM (new)

Might be a little clearer that way, although, it is a little more implementation specific (but maybe that's fine).

[uncle-lv]

Good idea! I'll do it.

[uncle-lv]

Updated usage.

Usage

set on_delete callback.

cache = Cache(on_delete=on_delete)

on_delete is a callable object.

Callable[[key: Hashable, value: Any, cause: RemovalCause],  None]

First parameter is the key of cache entry has been deleted.

Second is the value.

Third is the cause of cache entry removal.

RemovalCause is an enum.

class RemovalCause(Enum):
    DELETE = auto()
    SET = auto()
    EXPIRED = auto()
    FULL = auto()
    POPITEM = auto()

• DELETE: indicates that the cache entry was deleted by delete() or delete_many() explicitly.
• SET: indicates that the cache entry was replaced with a new value by set() or set_many().
• EXPIRED: indicates that the cache entry was removed because it expired.
• FULL: indicates that the cache entry was removed because cache has been full (reached the maximum size limit).
• POPITEM: indicates that the cache entry was deleted by popitem().

Trigger

The table shows methods will trigger on_delete.

cause	trigger
DELETE	The cache entry was removed explicitly by delete() or delete_many()
SET	The cache entry was replaced by set() or set_many()
POPITEM	The cache entry was deleted by popitem()
EXPIRED	Implicit. When the cache entry was removed because it expired
FULL	Implicit. The cache entry was removed because cache has reached the maximum size limit

⚠ clear() never triggers on_delete.

[dgilland]

Nice work! Thanks for taking the time to add this! 👍

[arossert]

When are you planing to make an official release with this change?

[dgilland]

@arossert

Released in v0.15.0: https://pypi.org/project/cacheout/0.15.0/