Memoize (Class-Based Memoization)

Per-instance memoization for class methods with full type hint and docstring preservation.

Overview

gri-memoize provides a MemoizedClass base class and a @memoize decorator for caching method results within class instances. Unlike functools.lru_cache, which stores results in a global cache tied to the function object, gri-memoize keeps cached results on each instance -- so garbage collection, per-instance invalidation, and IDE tooling all work as expected.

Requires Python 3.12+.

Documentation

The wheel ships its documentation inside the package, in gri_memoize/docs/, so it is available wherever the package is installed:

• overview.md -- usage, cache invalidation, and gotchas
• api_summary.md -- every public name and signature (generated)

Print the directory with python -c "import gri_memoize, pathlib; print(pathlib.Path(gri_memoize.__file__).parent / 'docs')". Every example in those files is run by the test suite.

Installation

pip install gri-memoize

For development:

git clone https://gitlab.com/geosol-foss/python/gri-memoize.git
cd gri-memoize
uv sync

Quick Start

from gri_memoize import MemoizedClass, memoize


class Geometry(MemoizedClass):
    def __init__(self, radius: float):
        self._radius = radius

    @memoize
    def area(self) -> float:
        """Circle area (cached after first call)."""
        return 3.14159 * self._radius ** 2

    @memoize
    def circumference(self) -> float:
        """Circle circumference (cached after first call)."""
        return 2 * 3.14159 * self._radius


g = Geometry(5.0)
g.area()           # Computed
g.area()           # Returned from cache
g.clear_memoized_results()  # Invalidate all cached results
g.area()           # Recomputed

Why Not functools.lru_cache?

Usage

1. Inherit from MemoizedClass
2. Decorate methods with @memoize
3. Call clear_memoized_results() if the underlying data changes

from gri_memoize import MemoizedClass, memoize


class Sensor(MemoizedClass):
    def __init__(self, readings: list[float]):
        self._readings = readings

    @memoize
    def mean(self) -> float:
        return sum(self._readings) / len(self._readings)

    @memoize
    def variance(self) -> float:
        m = self.mean()
        return sum((x - m) ** 2 for x in self._readings) / len(self._readings)

    def update(self, readings: list[float]) -> None:
        self._readings = readings
        self.clear_memoized_results()  # Invalidate stale cache

Methods with arguments are cached per unique argument combination:

class Matrix(MemoizedClass):
    @memoize
    def power(self, n: int) -> float:
        return self._value ** n

m = Matrix()
m.power(2)  # Cached for n=2
m.power(3)  # Cached separately for n=3

How It Works

Each MemoizedClass instance carries a memoized_results dictionary, initialized in __new__ to support multiple inheritance. The @memoize decorator builds a key from the function's qualified name, positional args, and sorted keyword args; the args must be hashable. On cache hit, the stored result is returned without calling the function.

Dependencies

None. gri-memoize has no external dependencies.

Other Projects

Current list of other GRI FOSS Projects we are building and maintaining.

License

MIT License. See LICENSE for details.