Skip to main content

Simple and fast Python in-memory caching library

Project description

poche

Build Status Codecov Checked with mypy Code style: black

Simple and fast Python in-memory caching.

Meant to speed up using dictionaries as cache backend for simple usecases.

No external dependencies, 100% code coverage and static type checked.

Installation

Requires Python 3.6+.

pip install poche

Roadmap

v1:

  • [x] K/V cache system
  • [x] Basic TTL
  • [x] TTL methods (get, bump, remove, etc)
  • [ ] Memoizing decorator
  • [ ] (Lower required Python version)

v2:

  • [ ] Optional per cache stats

Usage

Instantiate a Poche cache object:

>>> import poche
>>> c = poche.Cache()
# or you can set a default TTL
>>> c = poche.Cache(default_ttl=5)

Warning: When using TTLs, The only call removing a value with expired TTL is get()!

Basic operations

Set a value in cache:

def set(key: Hashable, value: Any, Optional: Optional[Union[int, datetime]] = None) -> None

Get a value in cache:

def get(key: Hashable) -> Any

Get or set a value in cache if not present:

def gos(key: Hashable, value: Any, ttl: Optional[int] = None) -> Any

Delete a value in cache:

def delete(key: Hashable) -> None

Flush all cache content:

def flush() -> None

Examples:

>>> c.set("un", 1)
>>> c.get("un")
1
>>> c.delete("un")

>>> c.get("deux")
KeyError
>>> c.gos("deux", 2) 
2
>>> c.gos("deux", 3)
2
>>> c.get("deux")
2
>>> c.flush()

TTLs

Set the TTL of a cache item:

def set_ttl(key: Hashable, ttl: Optional[Union[int, datetime]],) -> None

Get the TTL of a cache item:

def get_ttl(key: Hashable) -> Optional[datetime]

Add seconds to the current TTL:

def bump(key: str, ttl: int) -> None:

Examples:

>>> c.set("un", 1, ttl=2)
>>> c.get("un")
1
>>> time.sleep(3)
>>> c.get("un")
KeyError

>>> c.set("deux", 2, ttl=datetime(2025, 20, 1)) 
>>> c.get_ttl("deux")
datetime(2025, 20, 1)
>>> c.set_ttl("deux", 2)
>>> time.sleep(3)
>>> c.get("deux")
KeyError

>>> c.set("trois", 3, ttl=2)
>>> c.set_ttl(None)
>>> time.sleep(3)
>>> c.get("trois")
3

# The only call removing a value with expired TTL is `get()`!
>>> c.set("quatre", 4, ttl=2)
>>> time.sleep(3)
>>> "quatre" in c.keys()
True
>>> c.get("quatre")
KeyError
>>> "quatre" in c.keys()
False

Dictionary like methods

Get the cache keys:

def keys() -> KeysView[Hashable]

Get de cache values:

def values() -> ValuesView[Any]

Get the cache values:

def items() -> ItemsView[Hashable, Cacheitem]

Examples:

>>> c.set("un", 1)
>>> c.set("deux", 2)
>>> c.keys()
["un", "deux"]
>>> c.values()
[1, 2]
>>> for item in c.items():
...     print(f"{item[0]} -> {item[1].value}")
"1 -> un"
"2 -> deux"

Access raw objects

Examples:

>>> c.set("un", 1)
>>> c["un"]
Cacheitem(expiration=None, value=1)
>>> c["un"] == 1
True
>>> 1 in c
True
>>> c["un"] < 2
True
>>> c["deux"] = 2
TypeError
>>> c["deux"] = Cacheitem(expiration=None, value=2)
>>> len(c)
2
>>> c["un"] < c["deux"]
True
>>> del c["deux"]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for poche, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size poche-0.3.0-py3-none-any.whl (16.2 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size poche-0.3.0.tar.gz (16.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page