lazyval 0.2.0

A lazy evaluation wrapper for Python with JSON/YAML serialization support

lazyval

A lazy evaluation wrapper for Python that defers function execution until the value is actually needed.

Installation

pip install lazyval

With optional dependencies:

pip install lazyval[yaml]    # YAML serialization support
pip install lazyval[jinja]   # Jinja2 template support

Quick Start

from lazyval import Lazy

def expensive_query():
    print("Executing query...")
    return {"name": "Alice", "score": 95}

# Wrap the function - nothing executes yet
data = Lazy(expensive_query)

# Function executes only when value is accessed
print(data["name"])  # Prints "Executing query..." then "Alice"
print(data["score"]) # Just prints "95" (cached)

Features

Deferred Evaluation

The wrapped function only executes when you actually use the value:

lazy_val = Lazy(lambda: 42)
# Nothing has executed yet

if lazy_val > 10:  # Function executes here
    print("Large value")

Function Arguments

Pass arguments and keyword arguments to be used when the function is evaluated:

def fetch_user(user_id, include_details=False):
    return database.get_user(user_id, include_details)

# Arguments are stored and passed when evaluated
lazy_user = Lazy(fetch_user, 123, include_details=True)

# Function executes with args when first accessed
print(lazy_user["name"])

Automatic Caching

Once evaluated, the result is cached:

lazy_val = Lazy(expensive_function)
x = lazy_val + 1  # Executes function
y = lazy_val + 2  # Uses cached value

Works with JSON

import json
from lazyval import Lazy, dumps, LazyJSONEncoder

data = {"value": Lazy(lambda: 42)}

# Option 1: Use convenience function
json_str = dumps(data)

# Option 2: Use encoder class
json_str = json.dumps(data, cls=LazyJSONEncoder)

Works with YAML

import yaml
from lazyval import Lazy

data = {"value": Lazy(lambda: 42)}
yaml_str = yaml.dump(data)  # Outputs: value: 42

Works with Jinja2 Templates

from jinja2 import Template
from lazyval import Lazy

template = Template("Hello, {{ name }}!")
lazy_name = Lazy(lambda: "World")
result = template.render(name=lazy_name)  # "Hello, World!"

Full Operator Support

lazy_val = Lazy(lambda: 10)

# Arithmetic
lazy_val + 5   # 15
lazy_val * 2   # 20
10 - lazy_val  # 0

# Comparisons
lazy_val > 5   # True
lazy_val == 10 # True

# Container operations
lazy_list = Lazy(lambda: [1, 2, 3])
lazy_list[0]        # 1
len(lazy_list)      # 3
2 in lazy_list      # True
list(lazy_list)     # [1, 2, 3]

# Attribute access
lazy_str = Lazy(lambda: "hello")
lazy_str.upper()    # "HELLO"

Decorator Syntax

from lazyval import lazy

@lazy
def config():
    return load_config_from_file()

# Use like a regular value
if config["debug"]:
    print("Debug mode")

lazy() with Arguments

from lazyval import lazy

def fetch_data(url, timeout=30):
    return requests.get(url, timeout=timeout).json()

# Create a lazy value with arguments
lazy_data = lazy(fetch_data, "https://api.example.com", timeout=10)

# Function executes with args when first accessed
print(lazy_data["result"])

API Reference

Lazy(func, *args, **kwargs)

Create a lazy wrapper around a callable.

• func: A callable that returns the value
• *args: Positional arguments to pass to the function when evaluated
• **kwargs: Keyword arguments to pass to the function when evaluated

# Without arguments
Lazy(lambda: 42)

# With arguments
Lazy(fetch_data, user_id, limit=10)

Properties and Methods

• lazy_val.is_evaluated - Check if the value has been computed
• lazy_val.force() - Force evaluation and return the value

JSON Functions

• dumps(obj, **kwargs) - JSON dumps with Lazy support
• loads(s, **kwargs) - JSON loads (convenience wrapper)
• LazyJSONEncoder - Custom JSON encoder class
• lazy_json_default(obj) - Default function for json.dumps()

Requirements

• Python 3.10+

License

MIT