upd8

upd8 - Track updates to Python objects

upd8._field

Field descriptor for Versioned classes.

field Objects

class field(Generic[T])

Declarative versioned field with a default value.

Example:

class Counter(Versioned):

• count - int = field(0)
• name - str = field(“default”)

upd8._versioned

Base class for objects with versioning and thread-safe access.

Versioned Objects

class Versioned()

Base class for objects whose state changes should be trackable via a version number. Includes a reentrant lock for thread safety when modifying or accessing state.

__init__

def __init__()

Initializes version to 0 and creates a reentrant lock.

version

@property
def version() -> int

Returns the current version number of this object.

__hash__

def __hash__() -> int

Makes Versioned objects hashable based on identity and current version. Useful for caching mechanisms that depend on object state.

__eq__

def __eq__(other: Any) -> bool

Equality check based on identity and version. Two Versioned objects are equal if they are the same object instance and have the same version number.

upd8._decorator

Decorators for Versioned objects.

changes

def changes(method)

Decorate state mutating methods with this. Works with both synchronous and asynchronous methods. Automatically uses the change context manager.

If a method raises AbortChange, the exception is caught and the method returns the return value passed to the exception.

waits

def waits(method)

Decorate state awaiting methods with this. Works with both synchronous and asynchronous methods. Automatically acquires the lock for thread-safe access.

upd8._change

Helper for applying changes in a context manager or the update method

_Change Objects

class _Change()

Helper class that provides both method call and context manager functionality for version tracking. Supports both synchronous and asynchronous contexts.

__call__

def __call__()

Called when used as a method

__enter__

def __enter__()

Called when used as a synchronous context manager

__exit__

def __exit__(exc_type, exc_val, exc_tb)

Called when exiting the synchronous context

__aenter__

async def __aenter__()

Called when used as an asynchronous context manager

__aexit__

async def __aexit__(exc_type, exc_val, exc_tb)

Called when exiting the asynchronous context

upd8._exception

Exception classes for the upd8 package.

AbortChange Objects

class AbortChange(Exception)

Raise this exception to exit a @changes decorated method without incrementing the version.

Can optionally include a return value.