{"id":22459,"library":"theine-core","title":"Theine Cache","description":"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.","status":"active","version":"2.1.0","language":"python","source_language":"en","source_url":"https://github.com/kayembi/theine","tags":["cache","lru","lfu","tinylfu","in-memory"],"install":[{"cmd":"pip install theine-core","lang":"bash","label":"install from PyPI"}],"dependencies":[],"imports":[{"note":"The package is installed as theine-core but the import is from 'theine'.","wrong":"from theine_core import Cache","symbol":"Cache","correct":"from theine import Cache"},{"note":"","wrong":"","symbol":"TieredCache","correct":"from theine import TieredCache"}],"quickstart":{"code":"from theine import Cache\n\ncache = Cache(\"lru\", maxsize=100, ttl=60)\ncache.set(\"key\", \"value\")\nprint(cache.get(\"key\"))  # 'value'\n\n# Context manager\nwith Cache(\"tinylfu\", maxsize=1000) as c:\n    c.set(\"a\", 1)\n    print(c.get(\"a\"))  # 1","lang":"python","description":"Basic LRU cache with TTL and a context manager example."},"warnings":[{"fix":"Use 'from theine import Cache' (not theine-core, not theine_core).","message":"The package name is 'theine-core' on PyPI, but the import module is 'theine'. Many users mistakenly import from 'theine_core' or 'theine.core'.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'maxsize' instead of 'max_size'. Also, the 'ttl' parameter now expects seconds as an integer, not a timedelta.","message":"In 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use external locking if you need concurrent writes, or consider a thread-safe cache like cachetools.","message":"Theine'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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set maxsize to a power of two (e.g., 1024, 2048) when using 'tinylfu' or 'windowed_tinylfu'.","message":"When using 'tinylfu' policy, the 'maxsize' must be a power of two for optimal performance; otherwise it may degrade.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run: pip install theine-core\nThen import: from theine import Cache","cause":"Installed the package 'theine-core' but tried to import 'theine_core' or misspelled the import.","error":"ModuleNotFoundError: No module named 'theine'"},{"fix":"Use 'maxsize' instead of 'max_size'. Example: Cache('lru', maxsize=100)","cause":"In version 2.x, the parameter was renamed from 'max_size' to 'maxsize'.","error":"TypeError: __init__() got an unexpected keyword argument 'max_size'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}