Class-Based API

The class-based API is the core of ZyncIO.

Decorators and Wrappers

class zmethod[T_co, **P, ReturnT_co](func)

Wrap a method to be callable in both sync and async mode.

Decorated methods act like sync methods on SyncObjects and like async methods on AsyncObjects.

Accessing on an instance returns a BoundZyncMethod.

Example
class BaseClient:
    @zyncio.zmethod
    async def sleep(self, duration: float) -> None:
        if zyncio.is_sync(self):
            time.sleep(duration)
        else:
            await asyncio.sleep(duration)

class SyncClient(BaseClient, zyncio.SyncMixin): pass
class AsyncClient(BaseClient, zyncio.AsyncMixin): pass

SyncClient().sleep(1.0)

await AsyncClient().sleep(1.0)
Parameters:

func (async (T_co, *P.args, **P.kwargs) -> ReturnT_co) – The function to wrap.

class zclassmethod[T_co, **P, ReturnT_co](func)

Wrap a class method to be callable in both sync and async mode.

Decorated methods act like sync classmethods on subclasses of SyncMixin and like async classmethods on subclasses of AsyncMixin.

Accessing returns a BoundZyncClassMethod.

Example
class BaseClient:
    @zyncio.zclassmethod
    @classmethod
    async def sleep(cls, duration: float) -> None:
        if zyncio.is_sync_class(self):
            time.sleep(duration)
        else:
            await asyncio.sleep(duration)

class SyncClient(BaseClient, zyncio.SyncMixin): pass
class AsyncClient(BaseClient, zyncio.AsyncMixin): pass

SyncClient.sleep(1.0)

await AsyncClient.sleep(1.0)

Note

This decorator does not work with ZyncDelegator.

Parameters:

func (async (type[T_co], *P.args, **P.kwargs) -> ReturnT_co) – The function to wrap.

class zproperty[T_co, ReturnT_co](getter)

Wrap a method to act as a property in sync mode, and as a coroutine in async mode.

Decorated methods act like sync propertys on SyncObjects and like async methods on AsyncObjects.

Accessing on an instance of AsyncObject returns a BoundZyncMethod.

When accessed via the owning class, instances of zproperty are callable, calling through to the wrapped (unbound) getter.

Example
class BaseClient:
    ...

    @zyncio.zproperty
    async def status(self) -> str:
        return await self.get_status.z()

class SyncClient(BaseClient, zyncio.SyncMixin): pass
class AsyncClient(BaseClient, zyncio.AsyncMixin): pass

print(SyncClient().status)

print(await AsyncClient().status())
Parameters:

getter (async (T_co) -> ReturnT_co) – The getter for this property.

setter(setter)

Return a new ZyncSettableProperty with the given setter.

Example
class BaseClient:
    ...

    @zyncio.zproperty
    async def status(self) -> str:
        return await self.get_status.z()

    @status.setter
    async def status(self, value: str) -> None:
        await self.set_status.z(value)

class SyncClient(BaseClient, zyncio.SyncMixin): pass
class AsyncClient(BaseClient, zyncio.AsyncMixin): pass

SyncClient().status = 'RUNNING'

await AsyncClient().status.set('RUNNING')

Warning

Some type checkers may complain if you use the same name for the getter and setter.

Return type:

ZyncSettableProperty[T_co, ReturnT_co]

class ZyncSettableProperty[T, ReturnT](getter, setter)

A zyncio.zproperty with a setter.

See zyncio.zproperty.setter.

Accessing on an instance of AsyncObject returns a BoundZyncSettableProperty.

Parameters:

  • getter (async (T) -> ReturnT) – The getter for this property.

  • setter (async (T, ReturnT) -> None) – The setter for this property.

class zgeneratormethod[T_co, **P, ReturnT_co, SendT_contra](func)

Wrap a generator method to be callable in both sync and async mode.

Decorated methods return sync generators when called on SyncObjects and async generators when called on AsyncObjects.

Accessing on an instance returns a BoundZyncGeneratorMethod.

Example
class BaseClient:
    @zyncio.zgeneratormethod
    async def countdown(start: int) -> AsyncGenerator[int]:
        for i in range(start, 0, -1):
            if zyncio.is_sync(self):
                time.sleep(1.0)
            else:
                await asyncio.sleep(1.0)
            yield i


class SyncClient(BaseClient, zyncio.SyncMixin): pass
class AsyncClient(BaseClient, zyncio.AsyncMixin): pass

for n in SyncClient().countdown(5):
    print(n)

async for n in AsyncClient().countdown(5):
    print(n)
Parameters:

func ((T_co, *P.args, **P.kwargs) -> AsyncGenerator[ReturnT_co, SendT_contra]) – The generator method to wrap.

class zcontextmanagermethod[T_co, **P, ReturnT_co](func)

Similar to @contextlib.contextmanager, but callable in both sync and async modes.

Decorated methods return sync context managers when called on SyncObjects and async context managers when called on AsyncObjects.

Accessing on an instance returns a BoundZyncContextManagerMethod.

Example
class BaseClient:
    @zyncio.zcontextmanagermethod
    async def run_process(command: str) -> AsyncGenerator[int]:
        if zync_mode is zyncio.SYNC:
            process = subprocess.Popen(command, shell=True)
        else:
            process = await asyncio.create_subprocess_shell(command)

        try:
            yield process.pid
        finally:
            process.terminate()

class SyncClient(BaseClient, zyncio.SyncMixin): pass
class AsyncClient(BaseClient, zyncio.AsyncMixin): pass

with SyncClient().run_process('some command') as pid:
    print(pid)

async with AsyncClient().run_process('some command') as pid:
    print(pid)
Parameters:

func ((T_co, *P.args, **P.kwargs) -> AsyncGenerator[ReturnT_co, None]) – The generator method to wrap.

Mixins and Protocols

class SyncMixin

Mixin that makes bindable ZyncIO constructs use SYNC mode.

See the documentation for each construct for details on how they interact with this mixin.

class AsyncMixin

Mixin that makes bindable ZyncIO constructs use ASYNC mode.

See the documentation for each construct for details on how they interact with this mixin.

protocol ZyncDelegator

Protocol for delegating ZyncIO Mode to another object.

This protocol should be used for objects that wrap another ZyncIO-compatible object, and perform all operations via that “delegate” object.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod __zync_delegate__()

Return an object to which calls to zyncio.get_mode should be delegated.

The returned object must either be an instance of zyncio.SyncMixin or zyncio.AsyncMixin, or implement this protocol itself.

Return type:

T_co | ZyncDelegator[T_co]

Bound Methods

class BoundZyncMethod[T_co, **P, ReturnT_co](func, instance)

A bound zyncio.zmethod.

Acts like a sync method when bound to a SyncObject and like an async method when bound to an AsyncObject.

Parameters:
await call_zync(*args, **kwargs)

Run the method as a coroutine regardless of mode.

Parameters:

  • args (P.args) – Positional arguments to forward to the wrapped function.

  • kwargs (P.kwargs) – Keyword arguments to forward to the wrapped function.

Return type:

ReturnT_co

await z(*args, **kwargs)

Alias for call_zync.

class BoundZyncClassMethod[T, **P, ReturnT_co](func, cls)

A bound zyncio.zclassmethod.

Acts like a sync classmethod when bound to a subclass of SyncMixin and like an async classmethod when bound to a subclass of AsyncMixin.

Parameters:
await call_zync(*args, **kwargs)

Run the method as a coroutine regardless of mode.

Parameters:

  • args (P.args) – Positional arguments to forward to the wrapped function.

  • kwargs (P.kwargs) – Keyword arguments to forward to the wrapped function.

Return type:

ReturnT_co

await z(*args, **kwargs)

Alias for call_zync.

class BoundZyncSettableProperty[T, ReturnT](getter, setter, instance)

A bound zyncio.ZyncSettableProperty.

This class provides the set functionality for ZyncSettableProperty when accessed on an instance of AsyncObject.

Parameters:

  • func – The method to wrap.

  • instance (T) – The instance to bind the method to.

await set(value)

Set the value of the property.

class BoundZyncGeneratorMethod[T, **P, ReturnT_co, SendT_contra](func, instance)

A bound zyncio.zgeneratormethod.

Returns a sync generator when bound to a SyncObject and an async generator when bound to an AsyncObject.

Parameters:
call_zync(*args, **kwargs)

Run the generator function in the given mode.

Return type:

AsyncGenerator[ReturnT_co, SendT_contra]

z(*args, **kwargs)

Alias for call_zync.

class BoundZyncContextManagerMethod[T, **P, ReturnT_co](func, instance)

A bound zyncio.zcontextmanagermethod.

Returns a sync context manager when bound to a SyncObject and an async context manager when bound to an AsyncObject.

Parameters:
call_zync(*args, **kwargs)

Enter the context manager as an async context manager regardless of mode.

Return type:

AbstractAsyncContextManager[ReturnT_co]

z(*args, **kwargs)

Alias for call_zync.