theine-core

library2.1.0pypypi✓ verified 82d ago

Theine is a high-performance, in-memory cache library for Python with support for TTL, LRU, LFU, and windowed TinyLFU eviction policies. Current version 2.1.0 requires Python >=3.10 and is actively maintained.

database

pip install theine-core

package ↗

INSTALL

IMPORT

SIG · THEINE-CORE

theine-core

databasepythonv2.1.0

Install

1.6s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cache

✓ from theine_core import TlfuCore

✗ from theine import Cache

BloomFilter

✓ from theine_core import BloomFilter

spread

✓ from theine_core import spread

Basic LRU cache with TTL and a context manager example.

from theine import Cache cache = Cache("lru", maxsize=100, ttl=60) cache.set("key", "value") print(cache.get("key")) # 'value' # Context manager with Cache("tinylfu", maxsize=1000) as c: c.set("a", 1) print(c.get("a")) # 1

Debug

Known issues

gotchaThe package name is 'theine-core' on PyPI, but the import module is 'theine'. Many users mistakenly import from 'theine_core' or 'theine.core'.

fix

Use 'from theine import Cache' (not theine-core, not theine_core).

affects: all

breakingIn version 2.x, the API changed: The Cache class no longer accepts 'policy' as a string like 'lru' directly? Verify: Actually it does. But the 'maxsize' parameter was renamed from 'max_size' in v1.x.

fix

Use 'maxsize' instead of 'max_size'. Also, the 'ttl' parameter now expects seconds as an integer, not a timedelta.

affects: >=2.0.0

gotchaTheine's thread-safety is limited: concurrent writes from multiple threads may cause race conditions. The documentation notes that Cache is not thread-safe for writes.

fix

Use external locking if you need concurrent writes, or consider a thread-safe cache like cachetools.

affects: all

gotchaWhen using 'tinylfu' policy, the 'maxsize' must be a power of two for optimal performance; otherwise it may degrade.

fix

Set maxsize to a power of two (e.g., 1024, 2048) when using 'tinylfu' or 'windowed_tinylfu'.

affects: all

Upgrade

Version history

2.1.0latest on PyPI · released Oct 27, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/theine-core/ ↗