add the installable policy API

Author: egorsmkv

README.md

@@ -19,7 +19,8 @@ The package exposes:
 
 - a native extension module at `rsloop._loop`
 - a Python wrapper in [`python/rsloop/__init__.py`](./python/rsloop/__init__.py)
-- `rsloop.Loop`, `rsloop.new_event_loop()`, and `rsloop.run(...)`
+- `rsloop.Loop`, `rsloop.EventLoopPolicy`, `rsloop.new_event_loop()`,
+  `rsloop.run(...)`, `rsloop.install()`, and `rsloop.uninstall()`
 
 Repository metadata currently targets Python `>=3.8`. The packaged project now
 supports the core event-loop surface on Linux, macOS, and Windows, including
@@ -69,6 +70,19 @@ async def main():
 rsloop.run(main())
 ```
 
+Install as the default asyncio event loop policy:
+
+```python
+import asyncio
+import rsloop
+
+rsloop.install()
+try:
+    asyncio.run(main())
+finally:
+    rsloop.uninstall()
+```
+
 Manual loop creation also works:
 
 ```python

docs/getting-started.md

@@ -21,8 +21,11 @@ uv add rsloop
 The package exports a small public surface:
 
 - `rsloop.Loop`
+- `rsloop.EventLoopPolicy`
 - `rsloop.new_event_loop()`
 - `rsloop.run(...)`
+- `rsloop.install()`
+- `rsloop.uninstall()`
 - `rsloop.profile()`
 - `rsloop.start_profiler()`
 - `rsloop.stop_profiler()`
@@ -46,6 +49,28 @@ print(result)
 
 This is similar to `asyncio.run(...)`, but it creates and uses an `rsloop` loop.
 
+## Install as the default asyncio loop
+
+Use `install()` when you want plain `asyncio` entry points to create `rsloop`
+loops:
+
+```python
+import asyncio
+import rsloop
+
+
+rsloop.install()
+try:
+    asyncio.run(main())
+finally:
+    rsloop.uninstall()
+```
+
+`uninstall()` restores the event loop policy that was active before
+`install()`, which is useful in tests that switch between loop implementations.
+If another library has already installed a different policy, `uninstall()`
+leaves that newer policy in place.
+
 ## Manual loop creation
 
 Use manual loop creation when you need more control:

docs/how-it-works.md

@@ -28,7 +28,8 @@ The Python package lives in `python/rsloop/`.
 Important files:
 
 - `__init__.py`: exports the public API
-- `_run.py`: defines `run(...)` and `new_event_loop()`
+- `_run.py`: defines `run(...)`, `new_event_loop()`, and the installable event
+  loop policy
 - `_loop_compat.py`: compatibility helpers and monkeypatches
 - `_bootstrap.py`: startup helpers, including Windows DLL and SSL-related setup
 - `_profile.py`: small Python wrappers around the profiler API

docs/index.md

@@ -24,6 +24,8 @@ That means:
 
 - `rsloop.run(...)` is the easiest way to start.
 - `rsloop.new_event_loop()` creates a loop object manually.
+- `rsloop.install()` installs an asyncio event loop policy that creates `rsloop`
+  loops by default.
 - `rsloop.Loop` is the main event loop class.
 - Importing `rsloop` also installs a few compatibility patches so it fits better into normal `asyncio` code.
 

python/rsloop/__init__.py

@@ -10,16 +10,22 @@
 from ._profile import profiler_running
 from ._profile import start_profiler
 from ._profile import stop_profiler
+from ._run import EventLoopPolicy
+from ._run import install
 from ._run import new_event_loop
 from ._run import run
+from ._run import uninstall
 
 __all__: tuple[str, ...] = (
+    "EventLoopPolicy",
     "Loop",
     "__version__",
+    "install",
     "new_event_loop",
     "profile",
     "profiler_running",
     "run",
     "start_profiler",
     "stop_profiler",
+    "uninstall",
 )

python/rsloop/_run.py

@@ -8,12 +8,46 @@
 from ._loop_compat import cancel_all_tasks as __cancel_all_tasks
 
 _T = __typing.TypeVar("_T")
+_PREVIOUS_EVENT_LOOP_POLICY: __typing.Optional[__asyncio.AbstractEventLoopPolicy] = None
 
 
 def new_event_loop() -> Loop:
     return Loop()
 
 
+class EventLoopPolicy(__asyncio.DefaultEventLoopPolicy):
+    """Event loop policy that creates rsloop loops by default."""
+
+    def new_event_loop(self) -> Loop:
+        return new_event_loop()
+
+
+def install() -> None:
+    """Install rsloop as asyncio's default event loop policy."""
+
+    global _PREVIOUS_EVENT_LOOP_POLICY
+
+    policy = __asyncio.get_event_loop_policy()
+    if isinstance(policy, EventLoopPolicy):
+        return
+
+    _PREVIOUS_EVENT_LOOP_POLICY = policy
+    __asyncio.set_event_loop_policy(EventLoopPolicy())
+
+
+def uninstall() -> None:
+    """Restore the event loop policy that was active before install()."""
+
+    global _PREVIOUS_EVENT_LOOP_POLICY
+
+    if _PREVIOUS_EVENT_LOOP_POLICY is None:
+        return
+
+    if isinstance(__asyncio.get_event_loop_policy(), EventLoopPolicy):
+        __asyncio.set_event_loop_policy(_PREVIOUS_EVENT_LOOP_POLICY)
+    _PREVIOUS_EVENT_LOOP_POLICY = None
+
+
 if __typing.TYPE_CHECKING:
 
     def run(

src/stream_transport.rs

@@ -1482,7 +1482,7 @@ impl StreamTransportCore {
             };
             let low = low.unwrap_or(high / 4);
 
-            if high < low  {
+            if high < low {
                 return Err(PyValueError::new_err(format!(
                     "high ({high:?}) must be >= low ({low:?}) must be >= 0"
                 )));
@@ -3208,9 +3208,7 @@ pub(crate) fn run_server_accept_blocking(params: BlockingAcceptLoop<ServerListen
 #[cfg(target_os = "linux")]
 async fn run_tcp_accept_task(server: Arc<ServerCore>, listener: StdTcpListener) {
     profiling::scope!("stream.run_tcp_accept_task");
-    let poll_fd = listener
-        .try_clone()
-        .and_then(PollFd::new);
+    let poll_fd = listener.try_clone().and_then(PollFd::new);
 
     let Ok(poll_fd) = poll_fd else {
         return;
@@ -3352,10 +3350,7 @@ fn run_unix_accept_loop(params: BlockingAcceptLoop<StdUnixListener>) {
 
 #[cfg(target_os = "linux")]
 async fn run_unix_accept_task(server: Arc<ServerCore>, listener: StdUnixListener) {
-    let Ok(poll_fd) = listener
-        .try_clone()
-        .and_then(PollFd::new)
-    else {
+    let Ok(poll_fd) = listener.try_clone().and_then(PollFd::new) else {
         return;
     };
 

tests/test_run.py

@@ -22,6 +22,71 @@ async def run_in_thread(func, /, *args):
 
 
 class RunTests(unittest.TestCase):
+    def test_install_makes_asyncio_create_rsloop_loops(self) -> None:
+        original_policy = asyncio.get_event_loop_policy()
+        try:
+            asyncio.set_event_loop_policy(asyncio.DefaultEventLoopPolicy())
+
+            rsloop.install()
+            self.assertIsInstance(
+                asyncio.get_event_loop_policy(),
+                rsloop.EventLoopPolicy,
+            )
+
+            loop = asyncio.new_event_loop()
+            try:
+                self.assertIsInstance(loop, rsloop.Loop)
+            finally:
+                loop.close()
+        finally:
+            rsloop.uninstall()
+            asyncio.set_event_loop_policy(original_policy)
+
+    def test_installed_policy_affects_asyncio_run(self) -> None:
+        original_policy = asyncio.get_event_loop_policy()
+        try:
+            asyncio.set_event_loop_policy(asyncio.DefaultEventLoopPolicy())
+            rsloop.install()
+
+            async def main() -> bool:
+                return isinstance(asyncio.get_running_loop(), rsloop.Loop)
+
+            self.assertTrue(asyncio.run(main()))
+        finally:
+            rsloop.uninstall()
+            asyncio.set_event_loop_policy(original_policy)
+
+    def test_uninstall_restores_previous_event_loop_policy(self) -> None:
+        original_policy = asyncio.get_event_loop_policy()
+        previous_policy = asyncio.DefaultEventLoopPolicy()
+        try:
+            asyncio.set_event_loop_policy(previous_policy)
+            rsloop.install()
+            rsloop.uninstall()
+
+            self.assertIs(asyncio.get_event_loop_policy(), previous_policy)
+            loop = asyncio.new_event_loop()
+            try:
+                self.assertNotIsInstance(loop, rsloop.Loop)
+            finally:
+                loop.close()
+        finally:
+            rsloop.uninstall()
+            asyncio.set_event_loop_policy(original_policy)
+
+    def test_uninstall_does_not_replace_newly_installed_policy(self) -> None:
+        original_policy = asyncio.get_event_loop_policy()
+        other_policy = asyncio.DefaultEventLoopPolicy()
+        try:
+            rsloop.install()
+            asyncio.set_event_loop_policy(other_policy)
+            rsloop.uninstall()
+
+            self.assertIs(asyncio.get_event_loop_policy(), other_policy)
+        finally:
+            rsloop.uninstall()
+            asyncio.set_event_loop_policy(original_policy)
+
     def test_set_event_loop_accepts_rsloop_loop(self) -> None:
         loop = rsloop.new_event_loop()
         try: