zyncio 0.1.0__tar.gz

zyncio-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Make release
+
+on:
+  push:
+    tags:
+      - "*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build source distribution and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+      - name: Install Python 3.x
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Install build
+        run: pip install build
+      - name: Build sdist & wheel
+        run: python -m build
+      - name: Save sdist & wheel
+        uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: |
+            dist/*.tar.gz
+            dist/*.whl
+
+  upload:
+    name: Upload
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    # Don't release when running the workflow manually from GitHub's UI.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    permissions:
+      id-token: write
+      attestations: write
+      contents: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: dist
+          merge-multiple: true
+          path: dist
+      - name: Attest provenance
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: dist/*
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

zyncio-0.1.0/.github/workflows/static-analyses.yml

@@ -0,0 +1,43 @@
+name: Run static analyses
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: Lint source with Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+      - name: Run ruff check
+        uses: astral-sh/ruff-action@v3
+        with:
+          version: latest
+      - name: Run ruff format
+        run: ruff format --diff
+
+  type-check:
+    name: Type-check with Pyright
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e .[dev]
+      - name: Run Pyright
+        uses: jakebailey/pyright-action@v1

zyncio-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,75 @@
+name: Run tests
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e .[dev]
+      - name: Run tests
+        run: pytest --cov --cov-report=
+        env:
+          COVERAGE_FILE: coverage/coverage-${{ matrix.python-version }}
+      - name: Upload coverage files
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage
+
+  coverage-merge:
+    needs: [test]
+    runs-on: ubuntu-latest
+    permissions:
+      statuses: write
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install coverage
+      - name: Get coverage files
+        uses: actions/download-artifact@v6
+        with:
+          pattern: coverage-*
+          path: coverage
+          merge-multiple: true
+      - run: coverage combine coverage/*
+      - name: Create coverage status
+        run: |
+          coverage="$(coverage report --format=total)"
+          state="$([[ "$coverage" = "100.00" ]] && echo "success" || echo "failure")"
+
+          curl -sS --fail-with-body -X POST \
+            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+            -H "Accept: application/vnd.github+json" \
+            https://api.github.com/repos/${{ github.repository }}/statuses/${{ github.sha }} \
+            -d @- <<EOF
+          {
+            "state": "${state}",
+            "context": "coverage",
+            "description": "Coverage ${coverage}%",
+            "target_url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          }
+          EOF
+      - run: coverage report --fail-under=100

zyncio-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

zyncio-0.1.0/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.

zyncio-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,142 @@
+# `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/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "zyncio"
+dynamic = ["version"]
+description = "Write dual sync/async interfaces with minimal duplication."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = []
+authors = [{ name = "Benjy Wiener", email = "benjywiener@gmail.com" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = ["typing_extensions~=4.0"]
+
+[project.optional-dependencies]
+dev = ["coverage", "pytest", "pytest-cov"]
+
+[project.urls]
+Documentation = "https://github.com/BenjyWiener/zyncio#readme"
+Issues = "https://github.com/BenjyWiener/zyncio/issues"
+Source = "https://github.com/BenjyWiener/zyncio"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 150
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+extend-select = ["D", "I"]
+ignore = [
+    "D105", # undocumented-magic-method
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+lines-after-imports = 2
+extra-standard-library = ["typing_extensions"]
+
+[tool.pyright]
+reportUnnecessaryTypeIgnoreComment = "error"
+
+pythonVersion = "3.10"
+[tool.coverage.run]
+source_pkgs = ["zyncio", "tests"]
+branch = true
+
+[tool.coverage.paths]
+zyncio = ["src/zyncio"]
+tests = ["tests"]
+
+[tool.coverage.report]
+precision = 2
+exclude_lines = ["# pragma: no cover", "def __repr__", "@overload"]
+omit = ["tests/typing_tests.py"]
+show_missing = true