Documentation Index
Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
Use this file to discover all available pages before exploring further.
This guide covers the @session.function() decorator for running Python functions in sandboxes.
Overview
The function decorator API lets you execute Python functions in isolated sandbox containers:
import cwsandbox
from cwsandbox import SandboxDefaults
with cwsandbox.Session(SandboxDefaults(container_image="python:3.11")) as session:
@session.function()
def compute(x: int, y: int) -> int:
return x + y
# Execute in sandbox
result = compute.remote(2, 3).result()
print(result) # 5
Basic usage
Defining functions
Decorate functions with @session.function():
@session.function()
def process_data(data: dict) -> dict:
# Code runs inside the sandbox
import pandas as pd
df = pd.DataFrame(data)
return {"mean": df["value"].mean()}
Calling functions
Call .remote() on the decorated function to execute in the sandbox:
# Returns OperationRef immediately
ref = compute.remote(2, 3)
# Block for result
result = ref.result()
# One-liner
result = compute.remote(2, 3).result()
Execution methods
map() - parallel execution
Execute across multiple inputs:
@session.function()
def square(x: int) -> int:
return x * x
# Execute for each input
refs = square.map((x,) for x in range(10))
# Collect all results
from cwsandbox import results
all_results = results(refs) # [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
@session.function()
def add(x: int, y: int) -> int:
return x + y
# Each tuple is unpacked as arguments
refs = add.map([(1, 2), (3, 4), (5, 6)])
all_results = results(refs) # [3, 7, 11]
local() - local execution
Run locally without a sandbox (useful for testing):
# No sandbox created - runs in current process
result = compute.local(2, 3)
print(result) # 5
Serialization modes
JSON (default)
Safe and human-readable, but limited to JSON-serializable types:
from cwsandbox import Serialization
@session.function(serialization=Serialization.JSON)
def process(data: dict) -> dict:
return {"result": data["value"] * 2}
Pickle
Supports complex Python objects:
import numpy as np
@session.function(serialization=Serialization.PICKLE)
def compute_numpy(arr: np.ndarray) -> np.ndarray:
return arr * 2
arr = np.array([1, 2, 3])
result = compute_numpy.remote(arr).result() # array([2, 4, 6])
- NumPy arrays
- Pandas DataFrames
- Custom class instances
- Complex nested objects
Closures and globals
Closure variables
Functions can capture variables from their enclosing scope:
multiplier = 10
@session.function()
def multiply(x: int) -> int:
return x * multiplier # Captures 'multiplier'
result = multiply.remote(5).result() # 50
Global variables
Referenced globals are serialized with the function:
CONFIG = {"threshold": 0.5}
@session.function()
def check_value(x: float) -> bool:
return x > CONFIG["threshold"]
result = check_value.remote(0.7).result() # True
Container image
Override the container image for specific functions:
@session.function(container_image="pytorch/pytorch:latest")
def train_model(data: dict) -> dict:
import torch
# GPU training code
return {"loss": 0.01}
Error handling
Function exceptions propagate to the caller:
@session.function()
def failing_function() -> None:
raise ValueError("Something went wrong")
try:
failing_function.remote().result()
except Exception as e:
print(f"Function failed: {e}")
When to use functions vs. sandboxes
| Use case | Recommended API |
|---|
| Simple Python computation | Function decorator |
| Map/reduce over data | Function decorator |
| Interactive workflow, multiple commands | Sandbox |
| Streaming output | Sandbox |
| File manipulation | Sandbox |
| Long-running processes | Sandbox |
Limitations
The function API is intentionally simple. For complex workflows:
- Retries/backoff: Implement in calling code
- Task dependencies/DAGs: Use Airflow, Prefect, etc.
- Complex scheduling: Use the sandbox API directly
Complete example
import cwsandbox
from cwsandbox import SandboxDefaults, Serialization, results
import numpy as np
defaults = SandboxDefaults(
container_image="python:3.11",
tags=("remote-functions-demo",),
)
with cwsandbox.Session(defaults=defaults) as session:
# JSON serialization for simple types
@session.function()
def square(x: int) -> int:
return x * x
# Pickle for complex types
@session.function(serialization=Serialization.PICKLE)
def process_array(arr: np.ndarray) -> float:
return float(arr.mean())
# Single execution
result = square.remote(7).result()
print(f"7 squared: {result}")
# Parallel execution
refs = square.map((x,) for x in range(5))
all_results = results(refs)
print(f"Squares: {all_results}")
# NumPy example
arr = np.array([1, 2, 3, 4, 5])
mean = process_array.remote(arr).result()
print(f"Array mean: {mean}")
