pytest-antilru

Caching expensive function calls with functools.lru_cache is simple and great performance optimization. It works so well that it'll even speed up your unit test runs! Too bad it violated test isolation and caches the wrong values under test conditions, introducing test pollution (persisted state between test runs). This package will bust the lru_cache between test runs, avoiding test pollution and helping you keep your sanity.

Imagine you mock a network call out and your application ends up caching these mocked results:

def expensive_network_call() -> int:
    # Pretend this is an expensive network call.
    # You want to cache this for performance but you want to run tests with different responses as well.
    return 1


@lru_cache()
def cache_me() -> int:
    return expensive_network_call()

Now you have test pollution:

def test_a_run_first() -> None:
    assert cache_me() == 1


def test_b_run_second() -> None:
    # We want to mock the network call for this test case
    with mock.patch.object(sys.modules[__name__], 'expensive_network_call', return_value=2) as mock_network_call:
        assert cache_me() == 2
        assert mock_network_call.called

On your next test run, it doesn't matter what you mock, the results are already cached. Now trying running those two test out-of-order sequence and tell me how it goes.

What gets busted

The plugin replaces functools.lru_cache with a wrapper while pytest collects your tests. The wrapper caches exactly as lru_cache does, and additionally records every cache it creates. After each test, every recorded cache is cleared.

Collection is when pytest imports your test modules, and therefore when it imports the application code those tests import. A @lru_cache applied at module level is applied during that import, so it is recorded.

@functools.cache is covered the same way: it delegates to functools.lru_cache internally, so replacing that attribute also changes what functools.cache uses.

That is the normal case, and it needs no configuration:

@lru_cache
def cache_me() -> int:
    return expensive_network_call()

What is not covered

A cache that is not created during collection is not recorded, and is never cleared. Two ways that happens.

A module first imported while a test is running. Application code that imports inside a function body, rather than at the top of the module, is not imported during collection:

def handle(key):
    from app import registry  # circular-import workaround
    return registry.lookup(key)

app.registry is imported the first time handle runs, which is during a test. Its @lru_cache decorators are never recorded. PEP 8 asks for imports at the top of the module, and code that follows that is covered normally.

lru_cache applied at runtime instead of as a decorator. The call happens when the object is built, which is usually during a test rather than during collection:

class Client:
    def __init__(self, conn):
        self._lookup = functools.lru_cache(self._lookup_uncached)

In both cases the cache keeps its values across tests and nothing is reported. If you are debugging test pollution with this plugin installed, check for these two patterns first.

docs/architecture.md explains the mechanism in full: a cache is recorded if and only if it is created while the plugin's patch is actively recording, from the moment it installs (before any test or application module is imported) through the end of collection.

Dependencies

Since this is a pytest plugin, you need to be using pytest to run your tests.

Compatibility

Current releases (>=2.0) support Python >=3.9. If you need Python <3.9, use an older pytest-antilru release line instead.

The supported pytest bands for current releases are:

• Python 3.9: pytest >=3,<9
• Python 3.10+: pytest >=3,<10

Pytest 9 is tested only on Python 3.10+.

The tox matrix in [tox.ini] and CI exercise these compatibility bands, including Python 3.14 coverage.

While we aim to support a wide range of Python and pytest combinations, pytest only allows its latest releases to support new interpreters: they do not patch older releases to work with newer Python versions. See [tox.ini] for the full envlist of what is being tested, and see the existing allowlist docs in the lru_cache_disabled section for compatibility-related configuration guidance.

If you experience issues, please check for compatibility between your python and pytest target versions. Open an issue once these are verified.

Installation

Simply install this in the same python environment that pytest uses and the rest is magic.

pip install pytest-antilru

Development setup

The runtime support for this package is Python >=3.9. For local contributor workflows, we recommend Python >=3.13 with uv.

Recommended setup after cloning:

make setup

This does two things for contributors:

• installs the project dev environment with uv sync
• installs git hooks with pre-commit install --install-hooks

If you prefer the raw commands:

uv sync
uv run pre-commit install --install-hooks

If you only want the project dev environment without git hook installation:

make venv

Poetry remains supported for legacy workflows, but is deprecated in favor of uv. When dependencies change, make lock runs both uv and poetry lock commands.

Legacy Poetry commands:

poetry lock
poetry sync

Configuration

Add this where ever your pytest configurations live.

lru_cache_disabled

lru_cache_disabled is an allowlist of module paths to disable lru_cache for. This allows you to target disable caching for specific modules that are causing test pollution.

The default behaviour of pytest-antilru is to disable lru_cache everywhere. However, this can interfere with other dependencies that are reliant on lru_cache behaviour to behave correctly within the same test run.

[tool.pytest.ini_options]
lru_cache_disabled = '''
    my_module.util
    my_module.client_lib.database
    '''

In this example, any usage of lru_cache in a file inside my_module.util or my_module.client_lib.database will be disabled. All other instances will continue to be cached within a test run.

Matching is on module-path boundaries: an entry matches a module with exactly that path, or any module beneath it. my_module.util matches my_module.util and my_module.util.helpers, but does not match my_module.utilities.

How to test the software

make test

This validates the pre-commit checks with pre-commit run --all-files, but it does not install git hooks for you. Run make setup once on a new clone so local commits are checked before push.

Credits and references

This project was a re-engineering of a similar project a colleague of mine wrote. That project was not intended to be open-source and rather than go though all the hoops and hurdles to sanitize it, I've written it from the ground up such that it's kosher to open-source (given that it's such as small project).