zyncio 0.1.0__py3-none-any.whl

zyncio/__init__.py

@@ -0,0 +1,243 @@
+"""Write dual sync/async interfaces with minimal duplication."""
+
+from collections.abc import Callable, Coroutine
+from enum import Enum
+from typing import Any, Concatenate, Final, Generic, ParamSpec, TypeVar, overload
+from typing_extensions import Self
+
+
+__all__ = [
+    'Mode',
+    'SYNC',
+    'ASYNC',
+    'zfunc',
+    'zmethod',
+    'zclassmethod',
+    'zproperty',
+    'SyncMixin',
+    'AsyncMixin',
+]
+
+
+class Mode(Enum):
+    """`zyncio` execution mode."""
+
+    SYNC = 'sync'
+    ASYNC = 'async'
+
+
+SYNC: Final = Mode.SYNC
+ASYNC: Final = Mode.ASYNC
+
+
+P = ParamSpec('P')
+ReturnT = TypeVar('ReturnT')
+SelfT = TypeVar('SelfT')
+
+
+Zyncable = Callable[Concatenate[Mode, P], Coroutine[Any, Any, ReturnT]]
+ZyncableMethod = Callable[Concatenate[SelfT, Mode, P], Coroutine[Any, Any, ReturnT]]
+
+
+def _run_sync_coroutine(coro: Coroutine[Any, Any, ReturnT]) -> ReturnT:
+    try:
+        coro.send(None)
+    except StopIteration as e:
+        return e.value
+    else:
+        raise RuntimeError('zyncio functions must only await pure coroutines in sync mode')
+
+
+class zfunc(Generic[P, ReturnT]):
+    """Wrap a function to run in both sync and async modes."""
+
+    def __init__(self, func: Zyncable[P, ReturnT]) -> None:
+        """..
+
+        :param func: The function to wrap.
+        """
+        self.func: Final[Zyncable[P, ReturnT]] = func
+        self.__name__: str = func.__name__
+        self.__qualname__: str = getattr(func, '__qualname__', func.__name__)
+        self.__doc__: str | None = getattr(func, '__doc__', None)
+
+    def __repr__(self) -> str:
+        return f'<{self.__module__}.{type(self).__name__} {self.__qualname__}>'
+
+    def run_sync(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT:
+        """Run the function in sync mode."""
+        return _run_sync_coroutine(self.func(SYNC, *args, **kwargs))
+
+    async def run_async(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT:
+        """Run the function in async mode."""
+        return await self.func(ASYNC, *args, **kwargs)
+
+
+class SyncMixin:
+    """Mixin that makes `zyncio.zmethod`s into sync callables."""
+
+
+class AsyncMixin:
+    """Mixin that makes `zyncio.zmethod`s into async callables."""
+
+
+class zmethod(Generic[SelfT, P, ReturnT]):
+    """Wrap a method to run in both sync and async modes."""
+
+    def __init__(self, func: ZyncableMethod[SelfT, P, ReturnT]) -> None:
+        """..
+
+        :param func: The method to wrap.
+        """
+        self.func: Final[ZyncableMethod[SelfT, P, ReturnT]] = func
+        self.__name__: str = func.__name__
+        self.__qualname__: str = getattr(func, '__qualname__', func.__name__)
+        self.__doc__: str | None = getattr(func, '__doc__', None)
+
+    def __repr__(self) -> str:
+        return f'<{self.__module__}.{type(self).__name__} {self.__qualname__}>'
+
+    @overload
+    def __get__(self, instance: None, owner: type[SelfT]) -> Self: ...
+    @overload
+    def __get__(self, instance: SelfT, owner: type[SelfT] | None) -> 'BoundZyncMethod[SelfT, P, ReturnT]': ...
+    def __get__(self, instance: SelfT | None, owner: type[SelfT] | None) -> 'Self | BoundZyncMethod[SelfT, P, ReturnT]':
+        if instance is None:
+            return self
+        return BoundZyncMethod(self.func, instance)
+
+
+class zclassmethod(Generic[SelfT, P, ReturnT]):
+    """Wrap a method to run in both sync and async modes."""
+
+    def __init__(self, func: ZyncableMethod[type[SelfT], P, ReturnT]) -> None:
+        """..
+
+        :param func: The method to wrap.
+        """
+        self.func: Final[ZyncableMethod[type[SelfT], P, ReturnT]] = func.__func__ if isinstance(func, classmethod) else func
+        self.__name__: str = func.__name__
+        self.__qualname__: str = getattr(func, '__qualname__', func.__name__)
+        self.__doc__: str | None = getattr(func, '__doc__', None)
+
+    def __repr__(self) -> str:
+        return f'<{self.__module__}.{type(self).__name__} {self.__qualname__}>'
+
+    def __get__(self, instance: SelfT | None, owner: type[SelfT]) -> 'BoundZyncClassMethod[SelfT, P, ReturnT]':
+        return BoundZyncClassMethod(self.func, owner)
+
+
+SyncSelfT = TypeVar('SyncSelfT', bound=SyncMixin)
+AsyncSelfT = TypeVar('AsyncSelfT', bound=AsyncMixin)
+
+
+class BoundZyncMethod(Generic[SelfT, P, ReturnT]):
+    """A bound `zyncio.zmethod`."""
+
+    def __init__(self, func: ZyncableMethod[SelfT, P, ReturnT], instance: SelfT) -> None:
+        """..
+
+        :param func: The method to wrap.
+        :param instance: The instance to bind the method to.
+        """
+        self.func: Final[ZyncableMethod[SelfT, P, ReturnT]] = func
+        self.instance: Final[SelfT] = instance
+
+    def __repr__(self) -> str:
+        return f'<{self.__module__}.{type(self).__name__} {self.func.__qualname__} of {self.instance!r}>'
+
+    def run_zync(self, mode: Mode, *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, ReturnT]:
+        """Run the method in the given mode."""
+        return self.func(self.instance, mode, *args, **kwargs)
+
+    def run_sync(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT:
+        """Run the method in sync mode."""
+        return _run_sync_coroutine(self.func(self.instance, SYNC, *args, **kwargs))
+
+    async def run_async(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT:
+        """Run the method in async mode."""
+        return await self.func(self.instance, ASYNC, *args, **kwargs)
+
+    @overload
+    def __call__(self: 'BoundZyncMethod[SyncSelfT, P, ReturnT]', *args: P.args, **kwargs: P.kwargs) -> ReturnT: ...
+    @overload
+    def __call__(self: 'BoundZyncMethod[AsyncSelfT, P, ReturnT]', *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, ReturnT]: ...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT | Coroutine[Any, Any, ReturnT]:  # noqa: D102
+        if isinstance(self.instance, SyncMixin):
+            return self.run_sync(*args, **kwargs)
+        elif isinstance(self.instance, AsyncMixin):
+            return self.run_async(*args, **kwargs)
+        else:
+            raise TypeError(f'{type(self).__name__} is only callable when bound to instances of SyncMixin or AsyncMixin')
+
+
+class BoundZyncClassMethod(Generic[SelfT, P, ReturnT]):
+    """A bound `zyncio.zclassmethod`."""
+
+    def __init__(self, func: ZyncableMethod[type[SelfT], P, ReturnT], cls: type[SelfT]) -> None:
+        """..
+
+        :param func: The method to wrap.
+        :param cls: The class to bind the method to.
+        """
+        self.func: Final[ZyncableMethod[type[SelfT], P, ReturnT]] = func
+        self.cls: Final[type[SelfT]] = cls
+
+    def __repr__(self) -> str:
+        return f'<{self.__module__}.{type(self).__name__} {self.func.__qualname__} of {self.cls!r}>'
+
+    def run_zync(self, mode: Mode, *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, ReturnT]:
+        """Run the method in the given mode."""
+        return self.func(self.cls, mode, *args, **kwargs)
+
+    def run_sync(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT:
+        """Run the method in sync mode."""
+        return _run_sync_coroutine(self.func(self.cls, SYNC, *args, **kwargs))
+
+    async def run_async(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT:
+        """Run the method in async mode."""
+        return await self.func(self.cls, ASYNC, *args, **kwargs)
+
+    @overload
+    def __call__(self: 'BoundZyncClassMethod[SyncSelfT, P, ReturnT]', *args: P.args, **kwargs: P.kwargs) -> ReturnT: ...
+    @overload
+    def __call__(self: 'BoundZyncClassMethod[AsyncSelfT, P, ReturnT]', *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, ReturnT]: ...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> ReturnT | Coroutine[Any, Any, ReturnT]:  # noqa: D102
+        if issubclass(self.cls, SyncMixin):
+            return self.run_sync(*args, **kwargs)
+        elif issubclass(self.cls, AsyncMixin):
+            return self.run_async(*args, **kwargs)
+        else:
+            raise TypeError(f'{type(self).__name__} is only callable when bound to subclasses of SyncMixin or AsyncMixin')
+
+
+class zproperty(Generic[SelfT, ReturnT]):
+    """Wrap a method to act as a property in sync mode, and as a coroutine in async mode."""
+
+    def __init__(self, func: ZyncableMethod[SelfT, [], ReturnT]) -> None:
+        """..
+
+        :param func: The method to wrap.
+        """
+        self.func: Final[ZyncableMethod[SelfT, [], ReturnT]] = func
+        self.__name__: str = func.__name__
+        self.__qualname__: str = getattr(func, '__qualname__', func.__name__)
+        self.__doc__: str | None = getattr(func, '__doc__', None)
+
+    def __repr__(self) -> str:
+        return f'<{self.__module__}.{type(self).__name__} {self.__qualname__}>'
+
+    @overload
+    def __get__(self, instance: None, owner: type[SelfT]) -> Self: ...
+    @overload
+    def __get__(self: 'zproperty[SyncSelfT, ReturnT]', instance: SelfT, owner: type[SelfT] | None) -> ReturnT: ...
+    @overload
+    def __get__(self: 'zproperty[AsyncSelfT, ReturnT]', instance: SelfT, owner: type[SelfT] | None) -> 'BoundZyncMethod[SelfT, [], ReturnT]': ...
+    def __get__(self, instance: SelfT | None, owner: type[SelfT] | None) -> 'Self | ReturnT | BoundZyncMethod[SelfT, [], ReturnT]':
+        if instance is None:
+            return self
+        elif isinstance(instance, SyncMixin):
+            return BoundZyncMethod(self.func, instance).run_sync()
+        elif isinstance(instance, AsyncMixin):
+            return BoundZyncMethod(self.func, instance)
+        raise TypeError(f'{type(self).__name__} can only be accessed on instances of SyncMixin or AsyncMixin')

zyncio-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: zyncio
+Version: 0.1.0
+Summary: Write dual sync/async interfaces with minimal duplication.
+Project-URL: Documentation, https://github.com/BenjyWiener/zyncio#readme
+Project-URL: Issues, https://github.com/BenjyWiener/zyncio/issues
+Project-URL: Source, https://github.com/BenjyWiener/zyncio
+Author-email: Benjy Wiener <benjywiener@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions~=4.0
+Provides-Extra: dev
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# `zyncio`
+
+## Write dual sync/async interfaces with minimal duplication.
+
+> If I had a nickel for every almost identical interface I had to write,
+> I'd have two nickels... which isn't a lot, but it's weird that I had to
+> write it twice.
+>
+> – Dr. Doofenshmirtz, before discovering zyncio.
+
+# What is `zyncio`?
+
+`zyncio` allows you to write interfaces that can be used synchronously and asynchronously,
+while avoiding the code duplication this usually entails.
+
+# How does it work?
+
+`zyncio` works due to the fact that in Python you can actually run a coroutine **without an event loop**,
+as long as your chain of `await`s consists exclusively of other coroutines (i.e. no `Future`s or `Task`s):
+
+> The behavior of `await coroutine` is effectively the same as invoking a regular, synchronous Python function.
+>
+> – [A Conceptual Overview of `asyncio`](https://docs.python.org/3/howto/a-conceptual-overview-of-asyncio.html#await)
+
+To run such a coroutine, we simply call `send(None)`, catch the `StopIteration`, and extract its `value`:
+
+```python
+coro = pure_coroutine_func()
+try:
+    coro.send(None)
+except StopIteration as e:
+    ret = e.value
+```
+
+This means that a single `async def` function can be made to run in both synchronous and asynchronous
+contexts, as long as we have a way to determine which mode we're currently using:
+
+```python
+async def zync_sleep(zync_mode: zyncio.Mode, secs: float) -> None:
+    if zync_mode is zyncio.SYNC:
+        time.sleep(secs)
+    else:
+        await asyncio.sleep(secs)
+```
+
+But this isn't very convenient; you need to pass an additional parameter, and running in
+sync mode is pretty clunky. That's where `zyncio.zfunc` comes in:
+
+```python
+@zyncio.zfunc
+async def zync_sleep(zync_mode: zyncio.Mode, secs: float) -> None:
+    ...
+
+zync_sleep.run_sync(3)
+asyncio.run(zync_sleep.run_async(3))
+
+@zyncio.zfunc
+async def sleep_3(zync_mode: zyncio.Mode) -> None:
+    await zync_sleep.run_zync(zync_mode, 3)
+```
+
+## The real magic: `SyncMixin`/`AsyncMixin`, `zyncio.zmethod`, and `zyncio.zproperty`
+
+The real power of `zyncio` comes out when implementing client interfaces:
+
+1. Implement a single base client, using the `zyncio.zmethod` and `zyncio.zproperty`
+   decorators.
+
+2. Create two subclasses a sync client and an async client, adding the `zyncio.SyncMixin`
+   and `zyncio.AsyncMixin` mixins respectively.
+
+3. All of your `zyncio.zmethod`s magically become sync methods on the sync client and async
+   methods on the async client.
+
+   All of the `zyncio.zproperty`s magically become properties on the sync client, and async
+   methods on the async client.
+
+```python
+class BaseClient:
+    def __init__(self, sock: socket.socket) -> None:
+        self.sock: socket.socket = sock
+
+    @zyncio.zmethod
+    async def send_msg(self, zync_mode: zyncio.Mode, data: bytes) -> None:
+        if zync_mode is zyncio.SYNC:
+            self.sock.sendall(data)
+        else:
+            loop = asyncio.get_running_loop()
+            await loop.sock_sendall(self.sock, data)
+
+    @zyncio.zmethod
+    async def recv_msg(self, zync_mode: zyncio.Mode, n: int) -> bytes:
+        buf = b''
+        if zync_mode is zyncio.SYNC:
+            while len(buf) < n:
+                buf += self.sock.recv(n)
+        else:
+            loop = asyncio.get_running_loop()
+            while len(buf) < n:
+                buf += await loop.sock_recv(self.sock, n)
+        return buf
+
+    @zyncio.zmethod
+    async def do_handshake(self, zync_mode: zyncio.Mode) -> None:
+        await self.send_msg.run_zync(zync_mode, HANDSHAKE_REQ)
+        response = await self.recv_msg.run_zync(zync_mode, len(HANDSHAKE_RESP))
+        if response != HANDSHAKE_RESP:
+            raise RuntimeError('Handshake failed')
+
+    @zyncio.zproperty
+    async def status(self, zync_mode: zyncio.Mode) -> str:
+        await self.send_msg.run_zync(zync_mode, STATUS_REQ)
+        return (await self.recv_msg.run_zync(zync_mode, STATUS_RESP_LEN)).decode()
+
+
+class SyncClient(BaseClient, zyncio.SyncMixin):
+    pass
+
+
+class AsyncClient(BaseClient, zyncio.AsyncMixin):
+    def __init__(self, sock: socket.socket) -> None:
+        super().__init__(sock)
+        self.sock.setblocking(False)
+
+
+sync_client = SyncClient(sock)
+sync_client.do_handshake()  # Magically sync!
+print('Status:', sync_client.status)  # Sync property
+
+
+async def use_async_client():
+    async_client = AsyncClient(sock)
+    await async_client.do_handshake()  # Magically async!
+    print('Status:', await sync_client.status())  # Async func
+
+asyncio.run(use_async_client())
+```
+
+# Typing
+
+`zyncio` is fully typed, and built specifically for typed projects. If you're getting
+unexepcted type checking errors, please [open an issue](https://github.com/BenjyWiener/zyncio/issues).

zyncio-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+zyncio/__init__.py,sha256=8n_oe7_cJxOQq8NF9JRakK8bw51yQkj0Pv1QSPIqddU,9504
+zyncio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zyncio-0.1.0.dist-info/METADATA,sha256=vVVl-g1XGniPrsI5qYqEVvvvdgjPqSvwtdUMg2MytO0,5877
+zyncio-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+zyncio-0.1.0.dist-info/licenses/LICENSE,sha256=ZQlZ_loQOM5bqucZC4VC-ha3VmWsx39qjxnGF9yY9JU,1069
+zyncio-0.1.0.dist-info/RECORD,,

zyncio-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zyncio-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjy Wiener
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.