one-ring-loop 0.1.0__tar.gz

one_ring_loop-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Tools
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+*.swp
+*.swo
+
+# Docs
+site/
+
+# Secrets
+.env
+.env.*
+*.pem
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Personal testing.
+tmp/
+
+# Agents
+.claude

one_ring_loop-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

one_ring_loop-0.1.0/CLAUDE.md

@@ -0,0 +1,28 @@
+# one-ring-loop — Package Context
+
+Part of the **one-ring** monorepo. See the root `CLAUDE.md` for shared conventions.
+
+## Purpose
+
+<!-- Describe what this package does -->
+
+## Package Commands
+
+```bash
+# From this directory:
+just test          # Run tests for this package
+just test-cov      # Tests with coverage
+just typecheck     # Type check this package
+
+# From monorepo root:
+just test-pkg one-ring-loop   # Test this package
+just check                # Run all checks (all packages)
+```
+
+## Layout
+
+```
+src/one_ring_loop/    # Source code
+tests/                                # Tests
+pyproject.toml                        # Package metadata (tool config inherited from root)
+```

one_ring_loop-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: one-ring-loop
+Version: 0.1.0
+Summary: Custom async event loop built on io_uring with structured concurrency, file/socket IO, and timers
+Project-URL: Homepage, https://github.com/otto-sellerstam/one-ring
+Project-URL: Repository, https://github.com/otto-sellerstam/one-ring
+Project-URL: Issues, https://github.com/otto-sellerstam/one-ring/issues
+Author-email: Otto Sellerstam <ottosellerstam@gmail.com>
+License: MIT
+Keywords: async,coroutines,event-loop,io_uring,linux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: one-ring-core>=0.1.0
+Requires-Dist: structlog>=24.0
+Description-Content-Type: text/markdown
+
+# one-ring-loop
+
+Custom async event loop built on [one-ring-core](https://pypi.org/project/one-ring-core/) and Linux io_uring.
+
+Part of the [one-ring](https://github.com/otto-sellerstam/one-ring) project.
+
+## What it provides
+
+- **Task scheduling** with `Task` and `TaskGroup` (structured concurrency)
+- **File IO** - async file operations via io_uring
+- **Socket IO** - TCP server/client with `create_server`, `Connection.receive`/`send`
+- **Timers** - async `sleep` backed by io_uring timeouts
+- **Streams** - buffered byte streams, TLS wrapping, memory streams
+- **Cancellation** - `move_on_after`/`fail_after` scoped timeout/cancellation
+
+## Example
+
+```python
+from one_ring_loop import TaskGroup, run
+from one_ring_loop.socketio import Connection, create_server
+
+def echo_handler(conn):
+    try:
+        while True:
+            data = yield from conn.receive(1024)
+            if not data:
+                break
+            yield from conn.send(b"Echo: " + data)
+    finally:
+        yield from conn.close()
+
+def main():
+    server = yield from create_server(b"0.0.0.0", 9999)
+    tg = TaskGroup()
+    tg.enter()
+    try:
+        while True:
+            conn = yield from server.accept()
+            tg.create_task(echo_handler(conn))
+    finally:
+        yield from tg.exit()
+        yield from server.close()
+
+run(main())
+```
+
+## Requirements
+
+- **Linux** with io_uring support (kernel 6.7+)
+- **Python 3.14+**
+
+## Installation
+
+```bash
+uv add one-ring-loop
+```
+
+## License
+
+MIT

one_ring_loop-0.1.0/README.md

@@ -0,0 +1,60 @@
+# one-ring-loop
+
+Custom async event loop built on [one-ring-core](https://pypi.org/project/one-ring-core/) and Linux io_uring.
+
+Part of the [one-ring](https://github.com/otto-sellerstam/one-ring) project.
+
+## What it provides
+
+- **Task scheduling** with `Task` and `TaskGroup` (structured concurrency)
+- **File IO** - async file operations via io_uring
+- **Socket IO** - TCP server/client with `create_server`, `Connection.receive`/`send`
+- **Timers** - async `sleep` backed by io_uring timeouts
+- **Streams** - buffered byte streams, TLS wrapping, memory streams
+- **Cancellation** - `move_on_after`/`fail_after` scoped timeout/cancellation
+
+## Example
+
+```python
+from one_ring_loop import TaskGroup, run
+from one_ring_loop.socketio import Connection, create_server
+
+def echo_handler(conn):
+    try:
+        while True:
+            data = yield from conn.receive(1024)
+            if not data:
+                break
+            yield from conn.send(b"Echo: " + data)
+    finally:
+        yield from conn.close()
+
+def main():
+    server = yield from create_server(b"0.0.0.0", 9999)
+    tg = TaskGroup()
+    tg.enter()
+    try:
+        while True:
+            conn = yield from server.accept()
+            tg.create_task(echo_handler(conn))
+    finally:
+        yield from tg.exit()
+        yield from server.close()
+
+run(main())
+```
+
+## Requirements
+
+- **Linux** with io_uring support (kernel 6.7+)
+- **Python 3.14+**
+
+## Installation
+
+```bash
+uv add one-ring-loop
+```
+
+## License
+
+MIT

one_ring_loop-0.1.0/justfile

@@ -0,0 +1,20 @@
+# List available recipes
+default:
+    @just --list
+
+pkg := "one_ring_loop"
+
+# Run tests for this package
+test *args:
+    uv run pytest tests/ {{args}}
+
+# Run tests with coverage
+test-cov:
+    uv run pytest tests/ --cov={{pkg}} --cov-report=term-missing
+
+# Run type checker for this package
+typecheck:
+    uv run pyrefly check src/ tests/
+
+# Run all checks for this package
+check: typecheck test

one_ring_loop-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "one-ring-loop"
+version = "0.1.0"
+description = "Custom async event loop built on io_uring with structured concurrency, file/socket IO, and timers"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [
+    { name = "Otto Sellerstam", email = "ottosellerstam@gmail.com" },
+]
+readme = "README.md"
+keywords = ["io_uring", "async", "event-loop", "coroutines", "linux"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+dependencies = [
+    "one-ring-core>=0.1.0",
+    "structlog>=24.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/otto-sellerstam/one-ring"
+Repository = "https://github.com/otto-sellerstam/one-ring"
+Issues = "https://github.com/otto-sellerstam/one-ring/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/one_ring_loop"]
+
+# ── Coverage (per-package source) ───────────────────────────────────────
+# Other coverage settings (fail_under, exclude_lines) are in root pyproject.toml.
+
+[tool.coverage.run]
+source = ["one_ring_loop"]
+branch = true

one_ring_loop-0.1.0/src/one_ring_loop/__init__.py

@@ -0,0 +1,12 @@
+"""One Ring Loop package."""
+
+__version__ = "0.1.0"
+
+from one_ring_loop.loop import run
+from one_ring_loop.task import Task, TaskGroup
+
+__all__ = [
+    "Task",
+    "TaskGroup",
+    "run",
+]

one_ring_loop-0.1.0/src/one_ring_loop/_utils.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import threading
+from collections import deque
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, cast
+
+from one_ring_core.results import IOResult
+
+if TYPE_CHECKING:
+    from one_ring_core.operations import IOOperation
+    from one_ring_loop.loop import Loop
+    from one_ring_loop.typedefs import Coro, TaskID
+
+
+def _get_new_operation_id() -> TaskID:
+    """Gets an unused ID to submit to the IO worker."""
+    ret = _local.free_operation_id
+    _local.free_operation_id += 1
+
+    return ret
+
+
+def _execute[T: IOResult](op: IOOperation[T]) -> Coro[T]:
+    """Unwrap an IO completion into the expected result type."""
+    expected = op.result_type
+    completion = yield cast("IOOperation[IOResult]", op)
+    if completion is not None and isinstance(result := completion.unwrap(), expected):
+        return result
+    elif completion is None:
+        raise RuntimeError("Low level coroutine was sent None")
+
+    msg = f"Expected {expected.__name__}, got {type(completion)}. Expected {expected}"
+    raise TypeError(msg)
+
+
+@dataclass(kw_only=True)
+class _Local(threading.local):
+    """Wrapper around threading.local for proper type annotations."""
+
+    loop: Loop | None = None
+    free_operation_id: int = 1
+
+    # TODO: Move the below two to be attributes on Loop.
+    cancel_queue: deque[TaskID] = field(default_factory=deque)
+    unpark_queue: deque[TaskID] = field(default_factory=deque)
+
+    def cleanup(self) -> None:
+        """Resets all attributes."""
+        self.loop = None
+        self.free_operation_id = 1
+
+        self.cancel_queue = deque()
+        self.unpark_queue = deque()
+
+
+_local = _Local()
+
+__all__ = [
+    "_execute",
+    "_get_new_operation_id",
+    "_local",
+]

one_ring_loop-0.1.0/src/one_ring_loop/cancellation.py

@@ -0,0 +1,49 @@
+from contextlib import contextmanager, suppress
+from typing import TYPE_CHECKING
+
+from one_ring_loop.exceptions import Cancelled
+from one_ring_loop.log import get_logger
+from one_ring_loop.task import CancelScope, _create_standalone_task
+from one_ring_loop.timerio import sleep
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from one_ring_loop.typedefs import Coro
+
+logger = get_logger(__name__)
+
+
+@contextmanager
+def fail_after(delay: float, *, shield: bool = False) -> Generator[CancelScope]:
+    """Cancels cancel scope and throws Cancelled after delay."""
+
+    def cancellation_task(cancel_scope: CancelScope) -> Coro[None]:
+        """Background task that sleeps for delay.
+
+        Cancels the cancel scope if not finished after sleep.
+        """
+        with suppress(Cancelled):
+            yield from sleep(delay)
+
+        if not finished:
+            cancel_scope.cancel()
+
+    finished = False
+    with CancelScope(shielded=shield) as scope:
+        task = _create_standalone_task(cancellation_task(scope), None, None)
+        yield scope
+        task.current_cancel_scope().cancel()
+    finished = True
+
+
+@contextmanager
+def move_on_after(delay: float, *, shield: bool = False) -> Generator[CancelScope]:
+    """Moves on after delay by catching Cancelled."""
+    with fail_after(delay, shield=shield) as cancel_scope:
+        try:
+            yield cancel_scope
+        except Cancelled:
+            if not cancel_scope.cancelled:
+                # Another scope cancelled from above. Re-raise.
+                raise

one_ring_loop-0.1.0/src/one_ring_loop/exceptions.py

@@ -0,0 +1,2 @@
+class Cancelled(BaseException):
+    """Thrown when coroutine is cancelled, like asyncio.CancelledError."""

one_ring_loop-0.1.0/src/one_ring_loop/fileio/__init__.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from one_ring_core.operations import Close, FileOpen, FileRead, FileWrite
+from one_ring_loop._utils import _execute
+
+if TYPE_CHECKING:
+    from one_ring_loop.typedefs import Coro
+
+
+@dataclass(slots=True, kw_only=True)
+class File:
+    """Utility wrapper for file operations. Represents a single regular file."""
+
+    fd: int
+
+    def read(self) -> Coro[str]:
+        """Read file low-level coroutine."""
+        result = yield from _execute(FileRead(fd=self.fd))
+        return result.content.decode()
+
+    def write(self, data: bytes | str) -> Coro[int]:
+        """Write file low-level coroutine."""
+        _data = data.encode() if isinstance(data, str) else data
+        result = yield from _execute(FileWrite(fd=self.fd, data=_data))
+        return result.size
+
+    def close(self) -> Coro[None]:
+        """Close file low-level coroutine."""
+        yield from _execute(Close(fd=self.fd))
+        return None
+
+
+def open_file(path: str | Path, mode: str = "r") -> Coro[File]:
+    """Open file coroutine."""
+    _path = str(path) if isinstance(path, Path) else path
+
+    result = yield from _execute(FileOpen(path=_path.encode(), mode=mode))
+    return File(fd=result.fd)

one_ring_loop-0.1.0/src/one_ring_loop/log.py

@@ -0,0 +1,56 @@
+"""Structured logging configuration using structlog."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import structlog
+
+
+def setup_logging() -> None:
+    """Configure structlog with sensible defaults.
+
+    Uses JSON output when ``LOG_FORMAT=json`` (e.g. production),
+    otherwise uses colored console output for development.
+    """
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        # structlog.stdlib.add_logger_name,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if os.environ.get("LOG_FORMAT") == "json":
+        renderer: structlog.types.Processor = structlog.processors.JSONRenderer()
+    else:
+        renderer = structlog.dev.ConsoleRenderer()
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(0),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=True,
+    )
+
+
+_configured = False
+
+
+def get_logger(*args: object, **kwargs: object) -> structlog.stdlib.BoundLogger:
+    """Return a structlog logger, configuring on first call.
+
+    This avoids running ``setup_logging()`` at import time, which would
+    interfere with tests and multi-process setups.
+    """
+    global _configured  # noqa: PLW0603
+    if not _configured:
+        setup_logging()
+        _configured = True
+    return structlog.get_logger(*args, **kwargs)