proxystore.proxy

proxystore/proxy.py

Proxy implementation and helpers.

Proxy

Proxy(factory: FactoryType[T])

Bases: Proxy, Generic[T]

Lazy Object Proxy.

An extension of the Proxy from lazy-object-proxy with modified pickling behavior.

An object proxy acts as a thin wrapper around a Python object, i.e. the proxy behaves identically to the underlying object. The proxy is initialized with a callable factory object. The factory returns the underlying object when called, i.e. 'resolves' the proxy. The does just-in-time resolution, i.e., the proxy does not call the factory until the first access to the proxy (hence, the lazy aspect of the proxy).

The factory contains the mechanisms to appropriately resolve the object, e.g., which in the case for ProxyStore means requesting the correct object from the backend store.

x = np.array([1, 2, 3])
f = ps.factory.SimpleFactory(x)
p = ps.proxy.Proxy(f)
assert isinstance(p, np.ndarray)
assert np.array_equal(p, [1, 2, 3])

Note

The factory, by default, is only ever called once during the lifetime of a proxy instance.

Note

When a proxy instance is pickled, only the factory is pickled, not the wrapped object. Thus, proxy instances can be pickled and passed around cheaply, and once the proxy is unpickled and used, the factory will be called again to resolve the object.

Warning

A proxy of a singleton type (e.g., True, False, and None) will not behave exactly as a singleton type would. This is because the proxy itself is not a singleton.

>>> from proxystore.proxy import Proxy
>>> p = Proxy(lambda: True)
>>> p == True
True
>>> p is True
False

Warning

Python bindings to other languages (e.g., C, C++) may throw type errors when receiving a Proxy instance. Casting the proxy or extracting the target object may be needed.

>>> import io
>>> from proxystore.proxy import Proxy
>>> s = 'mystring'
>>> p = Proxy(lambda: s)
>>> io.StringIO(p)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: initial_value must be str or None, not Proxy
>>> io.StringIO(str(p))  # succeeds

Parameters:

• factory (FactoryType[T]) –

  Callable object that returns the underlying object when called.

Raises:

• TypeError –

  If factory is not callable.

Source code in proxystore/proxy.py

def __init__(self, factory: FactoryType[T]) -> None:
    if not callable(factory):
        raise TypeError('factory must be callable')
    super().__init__(factory)

ProxyLocker

ProxyLocker(proxy: Proxy[T])

Bases: Generic[T]

Proxy locker that prevents resolution of wrapped proxies.

The class prevents unintended access to a wrapped proxy to ensure a proxy is not resolved. The wrapped proxy can be retrieved with proxy = ProxyLocker(proxy).unlock().

Parameters:

• proxy (Proxy[T]) –

  Proxy to lock.

Source code in proxystore/proxy.py

def __init__(self, proxy: Proxy[T]) -> None:
    self._proxy = proxy

unlock()

unlock() -> Proxy[T]

Retrieve the locked proxy.

Returns:

• Proxy[T] –

  Proxy object.

Source code in proxystore/proxy.py

def unlock(self) -> Proxy[T]:
    """Retrieve the locked proxy.

    Returns:
        Proxy object.
    """
    return super().__getattribute__('_proxy')

extract()

extract(proxy: proxystore.proxy.Proxy[T]) -> T

Return object wrapped by proxy.

If the proxy has not been resolved yet, this will force the proxy to be resolved prior.

Parameters:

• proxy (Proxy[T]) –

  Proxy instance to extract from.

Returns:

• T –

  Object wrapped by proxy.

Source code in proxystore/proxy.py

def extract(proxy: proxystore.proxy.Proxy[T]) -> T:
    """Return object wrapped by proxy.

    If the proxy has not been resolved yet, this will force
    the proxy to be resolved prior.

    Args:
        proxy: Proxy instance to extract from.

    Returns:
        Object wrapped by proxy.
    """
    return proxy.__wrapped__

is_resolved()

is_resolved(proxy: proxystore.proxy.Proxy[T]) -> bool

Check if a proxy is resolved.

Parameters:

• proxy (Proxy[T]) –

  Proxy instance to check.

Returns:

• bool –

  True if proxy is resolved (i.e., the factory has been called) and False otherwise.

Source code in proxystore/proxy.py

def is_resolved(proxy: proxystore.proxy.Proxy[T]) -> bool:
    """Check if a proxy is resolved.

    Args:
        proxy: Proxy instance to check.

    Returns:
        `True` if `proxy` is resolved (i.e., the `factory` has been called) \
        and `False` otherwise.
    """
    return proxy.__resolved__

resolve()

resolve(proxy: proxystore.proxy.Proxy[T]) -> None

Force a proxy to resolve itself.

Parameters:

• proxy (Proxy[T]) –

  Proxy instance to force resolve.

Source code in proxystore/proxy.py

def resolve(proxy: proxystore.proxy.Proxy[T]) -> None:
    """Force a proxy to resolve itself.

    Args:
        proxy: Proxy instance to force resolve.
    """
    proxy.__wrapped__  # noqa: B018