Xsync

A set of tools to create hybrid sync/async interfaces.

CPython versions 3.7 through 3.11-dev and PyPy versions 3.7 through 3.9 are officially supported.

Windows, MacOS, and Linux are all supported.

What does Xsync do?

Xsync allows developers to create dynamic interfaces which can be run in sync or async contexts.

In simple terms, it makes this possible:

result = my_function()
result = await my_function()

How neat is that?!

Usage

The above behaviour can be achieved with the as_hybrid decorator:

@xsync.as_hybrid()
def my_function():
    ...

This sets my_function up as a "hybrid callable", which is capable of being run both synchronously and asynchronously. However, we also need to set an async implementation for my_function for it to work. We can do this using the set_async_impl decorator:

@xsync.set_async_impl(my_function)
async def my_async_function():
    ...

Doing this tells Xsync to run this function instead of my_function when awaiting:

my_function()        # runs as normal
await my_function()  # calls `my_async_function` instead

Don't worry, my_async_function can still be run directly, as you'd expect.

It also works on methods, class methods, and static methods:

class MyClass:
    @xsync.as_hybrid()
    def my_method(self):
        ...

    @xsync.set_async_impl(my_method)
    async def my_async_method(self):
        ...

    @classmethod
    @xsync.as_hybrid()
    def my_class_method(cls):
        ...

    @classmethod
    @xsync.set_async_impl(my_class_method)
    async def my_async_class_method(cls):
        ...

    @staticmethod
    @xsync.as_hybrid()
    def my_static_method(cls):
        ...

    @staticmethod
    @xsync.set_async_impl(my_static_method)
    async def my_async_static_method(cls):
        ...

The above is the newer (and better) of two available implementations.

@xsync.maybe_async()
def my_function():
    ...

async def _async_my_function():
    ...

my_function()        # runs as normal
await my_function()  # calls `_async_my_function` instead

class MyClass:
    @xsync.maybe_async()
    def my_method(self):
        ...

    async def _async_my_method(self):
        ...

    @classmethod
    @xsync.maybe_async()
    def my_class_method(cls):
        ...

    @classmethod
    async def _async_my_class_method(cls):
        ...

Contributing

Contributions are very much welcome! To get started:

• Familiarise yourself with the code of conduct
• Have a look at the contributing guide

License

The Xsync module for Python is licensed under the BSD 3-Clause License.