Memoria
A Python package for efficient function result caching with type safety and flexible storage options. Memoria helps you cache function results to avoid redundant computations, with built-in type checking and flexible storage options.
Installation
pip install memoria
Quick Start
The most basic usage of Memoria involves setting up a cache directory and using the @cache decorator on your functions. Here's a simple example:
from memoria import cache
# Set up the cache directory (required before using the cache)
cache.set_dir("./my_cache")
# Basic usage with the @cache decorator
@cache()
def expensive_computation(x, y):
# Your expensive computation here
return x + y
# The result will be cached and reused for the same inputs
result = expensive_computation(5, 3) # Computes and caches
result = expensive_computation(5, 3) # Returns cached result
Features
Type Safety
Memoria can enforce type checking on your cached results. This is useful when you want to ensure that your function always returns data of a specific type. If the function returns a value of a different type, a TypeError will be raised:
# Using actual type objects for type checking
@cache(output_type=list) # Note: using list, not List
def get_numbers():
return [1, 2, 3]
# This will raise a TypeError if the function returns something other than a list
# For example:
@cache(output_type=str)
def get_string():
return "hello" # This is fine
# return 42 # This would raise TypeError: result is not of type str
Custom Cache Directory Structure
You can organize your cached results in subdirectories by specifying a directory name in the cache decorator. This helps keep your cache organized, especially when dealing with multiple functions:
@cache(dir="my_subdirectory")
def my_function():
pass
The results will be stored in ./my_cache/my_subdirectory/ instead of directly in the cache root.
Custom Cache File Naming
By default, Memoria uses a hash of the function arguments to name cache files. You can customize this using the pattern parameter, which supports Python's string formatting:
@cache(pattern="{param1}_{param2}")
def my_function(param1, param2):
pass
This will create cache files named like param1_value_param2_value.pkl instead of using a hash.
Cache Management
Memoria provides several tools to manage your cached results:
# Check if a result is cached
@cache()
def my_function(x):
return x * 2
my_function.is_cached(x=5) # Returns True if cached
# Clear specific cache
my_function.clear(x=5) # Clears cache for x=5
# Clear all caches for a function
my_function.clear_all()
# Enable/disable verbose logging
cache.verbose_on() # Shows cache hits/misses
cache.verbose_off() # Hides cache hits/misses
The verbose mode is particularly useful during development as it shows you when results are being retrieved from cache versus being computed.
Global Cache Management
In addition to per-function cache management, Memoria provides global cache management functions:
# Get current cache directory
current_dir = cache.get_dir()
# Clear all caches
cache.clear()
# Unset cache directory
cache.unset_dir()
These functions help you manage the cache at a global level, useful for cleanup operations or changing cache locations.
Advanced Usage
Complex Data Types
Memoria works well with custom data types. When using custom classes, make sure to pass the actual class as the output_type:
from dataclasses import dataclass
@dataclass
class Result:
value: int
description: str
@cache(output_type=Result) # Using the actual Result class
def process_data(x: int) -> Result:
return Result(value=x*2, description=f"Processed {x}")
The type checking ensures that your function returns an instance of the specified class.
License
This project is licensed under the Conditional Freedom License (CFL-1.0) - see the LICENSE file for details.
1 maintainer
Metadata
1 maintainer
Release files for memoria 2025.4.27.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| memoria-2025.4.27.4.tar.gz | 8.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| memoria-2025.4.27.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.9 kB
Release files / memoria-2025.4.27.4.tar.gz
| Download URL | memoria-2025.4.27.4.tar.gz |
|---|---|
| Size | 8.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ed7ae4ed6116894bdd0aec3c7ca9aeb4483abd2ac5f502339b42a89fa066b2b9
|
|
BLAKE2b-256 checksum How to use checksums |
ce9dcca8b359553a95bc5cf92d985ca63f7d80ae86fdf406e09012a1b4a7e5eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.16
|
Release files / memoria-2025.4.27.4-py3-none-any.whl
| Download URL | memoria-2025.4.27.4-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
49c171294a3e2c54b6123240de72438720745db33a552a36b4ec3bfc578a399e
|
|
BLAKE2b-256 checksum How to use checksums |
6e07548885e81341f5739060f040d6085e485e6572e8582837046157ff8e3831
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.16
|
