noio 0.1__tar.gz

noio-0.1/.github/workflows/build.yml

@@ -0,0 +1,63 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    strategy:
+      matrix:
+        python: ["3.15", "3.15t"]
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+      - name: Set up Python
+        run: uv python install "${{ matrix.python }}"
+      - name: Install dependencies
+        run: uv sync --all-groups
+      - name: Check formatting
+        run: uv run ruff format --check
+      - name: Run ruff linting
+        run: uv run ruff check
+      - name: Run basedpyright
+        run: uv run basedpyright
+      - name: Verify free threading
+        if: matrix.python == '3.15t'
+        run: uv run python -c "import noio, sys; assert not sys._is_gil_enabled()"
+      - name: Run tests
+        run: uv run pytest --cov --cov-report=term-missing
+        timeout-minutes: 2
+      - name: Verify built package
+        run: |
+          uv build
+          uv run --isolated --no-project --with dist/noio-*.whl python -I -c "import noio"
+      - name: Verify release version
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          assert os.environ["RELEASE_TAG"] == version, "Release tag must match package version"
+          PY
+      - name: Upload distributions
+        if: github.event_name == 'release' && matrix.python == '3.15'
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error

noio-0.1/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    uses: ./.github/workflows/build.yml
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment:
+      name: pypi
+      url: https://pypi.org/project/noio/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.2
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.2

noio-0.1/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage*
+htmlcov/
+
+# Virtual environments
+.venv
+
+# uv
+uv.lock
+.python-version
+.ruff_cache/
+.ropeproject/
+
+# MkDocs
+site/

noio-0.1/AGENTS.md

@@ -0,0 +1 @@
+README.md

noio-0.1/CHANGELOG.md

@@ -0,0 +1,20 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com).
+
+[0.1] - 2026-10-17
+-----------------
+
+Initial experimental release.
+Requires Python 3.15 or later.
+
+### Added
+
+- `@noio.routine` to support ordinary calls and awaited `.a()` calls
+  from a single coroutine implementation.
+- A guard against ordinary routine calls inside routine implementations.
+
+[0.1]: https://github.com/ryanhiebert/noio/releases/tag/0.1

noio-0.1/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+Contributing
+============
+
+Choose APIs that best serve noio's goals.
+Compatibility with existing libraries is valuable,
+but we are free to make different choices when they improve the API.
+Trio has a history of thoughtful API design
+and is a useful reference when evaluating those choices.
+Consider the reasoning behind its decisions,
+without treating them as requirements for noio.
+
+Do not attempt to retain backward compatibility between versions,
+even for features that have already been released.
+Document incompatible changes under Breaking Changes in the changelog.
+
+Small releases are welcome as long as the included features are ready for people to use,
+and we have reasonable confidence that any breaking changes are documented in the changelog.
+
+Before adding a dependency, check that its license is compatible with
+distributing noio under the MIT license.
+Check any attribution or license notice requirements as well.
+
+Design primitives so the same instance can be shared across supported runtimes,
+including runtimes running concurrently in different threads.
+Where applicable, test interaction between runtimes,
+not just each runtime independently.
+Treat compatibility across supported runtimes as the default.
+Individual primitive docs only need to describe compatibility limitations.
+
+Do not rely on any kind of monkeypatching being in place.
+When monkeypatching is predictable, such as with gevent,
+make sure the implementation will work whether it is patched or not.
+
+Every bug fix must include a regression test
+that fails without the fix and passes with it.
+
+Record user-facing changes in `CHANGELOG.md` under an Unreleased section,
+creating that section when needed.
+At release time, turn it into a dated version entry.
+
+Use semantic line breaks in Markdown prose.
+Start each sentence on a new line,
+and break longer sentences at natural clause or phrase boundaries
+rather than wrapping to a fixed width.

noio-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Hiebert
+
+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.

noio-0.1/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: noio
+Version: 0.1
+Summary: Experimental coroutine libraries for ordinary-function applications
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.15
+Requires-Dist: aiologic>=0.17.1
+Description-Content-Type: text/markdown
+
+noio
+====
+
+There are many opinions on the right way to do IO.
+There are so many libraries.
+Some use regular functions, while some use coroutines.
+Some use threads.
+Some use green threads.
+Some existing abstractions only work with coroutines on single threads.
+You just want people to be able to use your library.
+
+`noio` is a minimal IO interface
+that provides primitives that work no matter what IO the user chooses,
+with clear documentation of any compatibility limitations.
+
+Getting Started
+---------------
+
+`noio` believes that coroutines are an advanced feature
+that should be avoided wherever reasonable.
+That includes getting started writing a library with `noio`.
+When writing a new library, start with regular functions,
+which are able to support threads and green threads.
+It might look something like this:
+
+```python
+def greeting(name: str) -> str:
+    return f"Hello, {name}!"
+
+assert greeting("world") == "Hello, world!"
+```
+
+When it's important for your function to also support coroutine libraries
+like `asyncio`, `trio` and `anyio`,
+just update it to look like something like this:
+
+```python
+import asyncio
+import noio
+
+@noio.routine
+async def greeting(name: str) -> str:
+    return f"Hello, {name}!"
+
+@noio.routine
+async def introduction(name: str) -> str:
+    return await greeting.a(name)
+
+assert greeting("world") == "Hello, world!"
+assert introduction("world") == "Hello, world!"
+assert asyncio.run(introduction.a("world")) == "Hello, world!"
+```
+
+When existing callers call your function the same way they used to,
+it will work without modification
+because it will drive the coroutine implementation to completion directly.
+Other routines will await a new `.a()` version
+that allows the run loop to handle scheduling.
+
+Finding all the places to convert can be tricky,
+so `noio` will raise an error
+if a routine implementation calls another routine with a regular function call.
+
+Contributing
+------------
+
+Before making changes, read [CONTRIBUTING.md](CONTRIBUTING.md).

noio-0.1/README.md

@@ -0,0 +1,67 @@
+noio
+====
+
+There are many opinions on the right way to do IO.
+There are so many libraries.
+Some use regular functions, while some use coroutines.
+Some use threads.
+Some use green threads.
+Some existing abstractions only work with coroutines on single threads.
+You just want people to be able to use your library.
+
+`noio` is a minimal IO interface
+that provides primitives that work no matter what IO the user chooses,
+with clear documentation of any compatibility limitations.
+
+Getting Started
+---------------
+
+`noio` believes that coroutines are an advanced feature
+that should be avoided wherever reasonable.
+That includes getting started writing a library with `noio`.
+When writing a new library, start with regular functions,
+which are able to support threads and green threads.
+It might look something like this:
+
+```python
+def greeting(name: str) -> str:
+    return f"Hello, {name}!"
+
+assert greeting("world") == "Hello, world!"
+```
+
+When it's important for your function to also support coroutine libraries
+like `asyncio`, `trio` and `anyio`,
+just update it to look like something like this:
+
+```python
+import asyncio
+import noio
+
+@noio.routine
+async def greeting(name: str) -> str:
+    return f"Hello, {name}!"
+
+@noio.routine
+async def introduction(name: str) -> str:
+    return await greeting.a(name)
+
+assert greeting("world") == "Hello, world!"
+assert introduction("world") == "Hello, world!"
+assert asyncio.run(introduction.a("world")) == "Hello, world!"
+```
+
+When existing callers call your function the same way they used to,
+it will work without modification
+because it will drive the coroutine implementation to completion directly.
+Other routines will await a new `.a()` version
+that allows the run loop to handle scheduling.
+
+Finding all the places to convert can be tricky,
+so `noio` will raise an error
+if a routine implementation calls another routine with a regular function call.
+
+Contributing
+------------
+
+Before making changes, read [CONTRIBUTING.md](CONTRIBUTING.md).

noio-0.1/noio/__init__.py

@@ -0,0 +1,3 @@
+from .routine import routine as routine
+
+__all__ = ["routine"]

noio-0.1/noio/_lock.py

@@ -0,0 +1,49 @@
+from types import TracebackType
+from typing import Self
+
+import aiologic
+from aiologic.lowlevel import current_async_library
+
+from .routine import _sync_call
+from .routine import routine
+
+
+class Lock:
+    """An owned, non-reentrant lock shared by threads, greenlets, and async tasks."""
+
+    def __init__(self) -> None:
+        self.__lock = aiologic.Lock()
+
+    @routine
+    async def __enter__(self) -> Self:
+        """Wait for ownership; reacquiring raises RuntimeError."""
+        if _sync_call.get():
+            self.__lock.green_acquire()
+        else:
+            await self.__lock.async_acquire()
+        return self
+
+    @routine
+    async def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Release from the owning thread, greenlet, or async task."""
+        # An ordinary acquisition inside an async function still has green ownership.
+        if self.__lock.green_owned() or current_async_library(failsafe=True) is None:
+            self.__lock.green_release()
+        else:
+            self.__lock.async_release()
+
+    async def __aenter__(self) -> Self:
+        return await self.__enter__.a()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.__exit__.a(exc_type, exc_value, traceback)