veritas-mem 0.1.1

Veritas is a minimal Python microframework that enables safe usage of shared mutable default arguments in functions.

Veritas

Veritas is a minimal Python microframework that enables safe usage of shared mutable default arguments in functions. Designed with both async and sync contexts in mind, Veritas flips the conventional wisdom around "mutable defaults are bad" into a powerful feature for building lightweight stateful systems, in-memory caches, and inter-task communication channels.

Core Philosophy

Mutable defaults, when used intentionally and safely, can act as implicit state carriers. Veritas enforces safety by requiring that shared mutable defaults be explicitly defined using thread-safe or async-safe structures. It validates their usage at function definition time and ensures consistent behavior across sync and async contexts.

Features

• ThreadSafeDict / AsyncSafeDict: Built-in safe dictionaries for concurrent access.
• Safe by Default: Disallows unsafe usage unless explicitly opted-in.
• Support for asyncio and threading: Works seamlessly with both paradigms.
• Introspective Design: Automatically extracts and validates the shared object.
• Direct Access to Internal State: Use .state on wrapped functions to inspect or manipulate shared memory.

Installation

pip install veritas-mem

Usage

from veritas import veritas
from veritas.datastructs import ThreadSafeDict

shared = ThreadSafeDict()
shared.set("count", 0)

@veritas
def increment(shared=shared):
    val = shared.get("count")
    shared.set("count", val + 1)
    print(f"Count is now {val + 1}")

for _ in range(10):
    increment()

# Access shared state directly
print("Final count:", increment.state.get("count"))

Caching Features

Veritas also includes a powerful @cache decorator that provides in-memory caching with the following features:

• maxsize: Limits the cache to a maximum number of entries.
• LRU Eviction: Uses a Least Recently Used (LRU) policy to evict entries when the cache is full.
• ttl: Sets a Time-to-Live (TTL) for cached items, causing them to expire after a specified duration.
• Probabilistic Eviction: When both maxsize and ttl are set, the cache uses a probabilistic eviction strategy to efficiently remove expired items.

Caching Example

from veritas.cache import cache
import time

@cache(maxsize=10, ttl=5)
def my_cached_function(x):
    print(f"Computing for {x}...")
    return x * x

# First call, this will be a miss
my_cached_function(5)

# Second call, this will be a hit
my_cached_function(5)

# Wait for the TTL to expire
time.sleep(6)

# Third call, this will be a miss again
my_cached_function(5)

Example

See the examples directory for a multi-threaded shared status writer-reader.

Why Not ContextVars?

Veritas is not a replacement for contextvars. Instead, it offers a different kind of shared memory: persistent, introspectable, and defined at function scope rather than dynamic execution context.

Contributing

Feature requests, bug reports, and PRs are welcome. See the TODO list in the issues for roadmap.

---

Veritas — because shared memory doesn’t have to be dangerous.