Python Build a Least-Recently-Used Cache

Create an LRU cache that evicts the least recently used item.

What You Will Learn

OrderedDict.move_to_end() marks reads as recent and popitem(last=False) evicts the oldest entry. functools.lru_cache is usually preferable when you only want memoization of a pure function.

This teaching example is not thread-safe and does not implement TTL expiration.

Caching uses extra memory and can return stale results when a function relies on changing state outside its arguments.

Step-by-Step Example

The example below makes the behavior visible with small input values that you can change safely.

from collections import OrderedDict
cache = OrderedDict()
def put(key, value):
    if key in cache:
        cache.move_to_end(key)
    cache[key] = value
    if len(cache) > 2:
        cache.popitem(last=False)
put('A', 1)
put('B', 2)
cache.move_to_end('A')
put('C', 3)
print(list(cache.items()))

How the Example Works

The imports provide the standard-library tools used in the demonstration: collections.
The function put defines reusable behavior; its body executes when it is called, not when it is declared.
The variable cache holds the result of OrderedDict(). Later lines use that value or inspect how it changes.
The print() calls make the return values or state visible so you can compare them with the explanation and check your prediction.

For the chosen input, the expression list(cache.items()) prints [('A', 1), ('C', 3)]. Compare that result with the rule above before you change the argument.

Expected output from the example:

[('A', 1), ('C', 3)]

When You Would Use This

These tools are useful when composing small reusable functions, adapting callbacks, or eliminating repeated work. Pay attention to whether the operation returns a new object, updates state, or produces lazy results. Test a small success case and a boundary case before integrating it into an application.

Practice: Modify the Code

Wrap the cache in get() and put() functions and test eviction under repeated access.

Verify the changed output against the behavior described above, including the relevant invalid or boundary case.

For complete parameters and version details, consult the official Python documentation.

Common Beginner Mistakes

Forgetting to update recency on reads, leading to eviction of recently accessed values.
Assuming the operation has the same behavior for missing values, empty inputs and regular inputs.

Key Takeaways

Create an LRU cache that evicts the least recently used item.
OrderedDict.move_to_end() marks reads as recent and popitem(last=False) evicts the oldest entry. functools.lru_cache is usually preferable when you only want memoization of a pure function.
This teaching example is not thread-safe and does not implement TTL expiration.