Refresh erlang.sleep docs + add silent= flag to erlang.install

The asyncio.md and migration.md tables claimed sync erlang.sleep()
always releases the dirty scheduler. In v3.0 the dirty scheduler isn't
held during sync calls anyway (async NIF dispatch returns immediately);
what blocks is the worker pthread for py:call, the Erlang process for
py:exec/py:eval, or no thread at all for awaited async sleep. Update
the table and the sleep() docstring accordingly.

erlang.install() emits a DeprecationWarning on 3.12-3.13 by design,
but users who knowingly use the legacy pattern had no clean local
opt-out. Add a keyword-only silent=False; passing silent=True
suppresses the warning without disabling DeprecationWarning globally.
The 3.14+ RuntimeError stays unconditional.

Author: benoitc

docs/asyncio.md

@@ -707,14 +707,15 @@ def sync_handler():
     return "done"
 ```
 
-**Behavior by Context:**
+**Behavior by context (v3.0 worker-pthread architecture):**
 
-| Context | Mechanism | Effect |
-|---------|-----------|--------|
-| Async (`await erlang.sleep()`) | `asyncio.sleep()` via `call_later()` | Yields to event loop, dirty scheduler released |
-| Sync (`erlang.sleep()`) | `erlang.call('_py_sleep')` with `receive/after` | Blocks Python, Erlang process suspends, dirty scheduler released |
+| Context | Mechanism | What blocks |
+|---------|-----------|-------------|
+| Async (`await erlang.sleep()`) | `asyncio.sleep()` via Erlang `send_after` | Yields to the event loop. The worker pthread is free to handle other tasks. |
+| Sync from `py:exec` / `py:eval` | `erlang.call('_py_sleep', secs)` triggers suspension; the dirty scheduler is released and an Erlang `receive ... after` parks the caller | Caller's Erlang process. Dirty scheduler free for other work. |
+| Sync from `py:call` (worker mode) | Falls back to `time.sleep`; replaying the Python frame around a suspension would change time-measurement semantics | The context's worker pthread for the sleep duration. Async NIF dispatch returns immediately so the BEAM dirty scheduler is **not** held; other Erlang processes and other contexts run normally. |
 
-Both modes allow other Erlang processes and Python contexts to run during the sleep.
+In every case the BEAM dirty scheduler is freed during the sleep — the difference is which thread blocks (Erlang process, dirty scheduler, or worker pthread).
 
 #### asyncio.sleep(delay)
 

docs/migration.md

@@ -541,20 +541,25 @@ erlang.send(("my_server", "node@host"), {"event": "user_login", "user": 123})
 erlang.send(pid, "hello")
 ```
 
-### `erlang.sleep()` with Dirty Scheduler Release
+### `erlang.sleep()` cooperates with the BEAM scheduler
 
-Synchronous sleep that releases the Erlang dirty scheduler thread:
+Synchronous sleep that lets other Erlang processes and Python
+contexts make progress during the wait:
 
 ```python
 import erlang
 
 def slow_handler():
-    # Sleep without blocking Erlang scheduler
-    erlang.sleep(1.0)  # Releases dirty scheduler during sleep
+    erlang.sleep(1.0)
     return "done"
 ```
 
-Unlike `time.sleep()`, `erlang.sleep()` releases the dirty NIF thread while waiting, allowing other Python calls to use the scheduler slot.
+The BEAM dirty scheduler is never held during the sleep. The exact
+thread that blocks depends on context — the Erlang process for
+`py:exec` / `py:eval`, or the context's private worker pthread for
+`py:call`. See the [behavior-by-context table in the asyncio
+guide](asyncio.md#erlangsleepseconds) for the full breakdown. In all
+cases, other contexts and other Erlang processes continue running.
 
 ### `erlang.call()` Blocking with Explicit Scheduling
 

priv/_erlang_impl/__init__.py

@@ -226,17 +226,26 @@ def sleep(seconds):
     - Async context: Returns an awaitable (use with await)
     - Sync context: Blocks synchronously
 
-    **Dirty Scheduler Release:**
-
-    In async context, uses asyncio.sleep() which routes through the Erlang
-    timer system via erlang:send_after. The dirty scheduler is released
-    because the Python code yields back to the event loop.
-
-    In sync context (when called from py:exec or py:eval), the sleep uses
-    Erlang's receive/after via erlang.call('_py_sleep', seconds), which
-    releases the dirty NIF scheduler thread. When called from py:call
-    contexts, falls back to Python's time.sleep() which blocks the dirty
-    scheduler but ensures correct time measurement behavior.
+    **Behavior by context (v3.0 worker-pthread architecture)**:
+
+    The BEAM dirty scheduler is never held during the sleep — the
+    difference is which thread blocks.
+
+    - Async (``await erlang.sleep()``) uses ``asyncio.sleep()``, which
+      routes through Erlang's ``send_after`` timer. The coroutine
+      yields to the event loop; the worker pthread handles other tasks.
+    - Sync from ``py:exec`` / ``py:eval`` calls
+      ``erlang.call('_py_sleep', seconds)``. The suspension machinery
+      releases the dirty scheduler and parks the caller's Erlang
+      process in a ``receive ... after``.
+    - Sync from ``py:call`` falls back to ``time.sleep`` — the worker
+      pthread blocks for the sleep duration. The BEAM dirty scheduler
+      is *not* held here either: the NIF dispatch returned immediately
+      and the caller is waiting in an Erlang ``receive`` on the
+      context process. Other Erlang processes and other contexts run
+      normally during the sleep. (Replaying a suspended Python frame
+      around ``time.time()`` would change time-measurement semantics,
+      which is why ``py:call`` doesn't take the suspension path.)
 
     Args:
         seconds: Duration to sleep in seconds (float or int).
@@ -246,13 +255,13 @@ def sleep(seconds):
         In sync context: None (blocks until sleep completes).
 
     Example:
-        # Async context - releases dirty scheduler via event loop yield
+        # Async context
         async def main():
-            await erlang.sleep(0.5)  # Uses Erlang timer system
+            await erlang.sleep(0.5)
 
         # Sync context
         def handler():
-            erlang.sleep(0.5)  # Blocks for 0.5 seconds
+            erlang.sleep(0.5)
     """
     try:
         asyncio.get_running_loop()
@@ -396,7 +405,7 @@ def _run_async_from_erlang(module, func, args, kwargs):
     return run(coro)
 
 
-def install():
+def install(*, silent=False):
     """Install ErlangEventLoopPolicy as the default event loop policy.
 
     Deprecated in Python 3.12+; raises ``RuntimeError`` on Python 3.14+
@@ -408,23 +417,32 @@ def install():
     both work on every supported Python version and don't touch the
     global policy.
 
+    Args:
+        silent: If True (keyword-only), suppress the per-call
+            ``DeprecationWarning`` on Python 3.12-3.13. Useful when
+            you knowingly rely on the legacy pattern and don't want
+            to silence ``DeprecationWarning`` globally. The 3.14+
+            ``RuntimeError`` is *not* suppressible — that pattern
+            won't work on 3.16 and the call has no fallback there.
+
     Example (legacy pattern, Python 3.9–3.13 only):
         import asyncio
         import erlang
 
-        erlang.install()
-        asyncio.run(main())  # Uses Erlang event loop
+        erlang.install(silent=True)  # opt out of the warning
+        asyncio.run(main())          # Uses Erlang event loop
     """
     if sys.version_info >= (3, 14):
         raise RuntimeError(
             "erlang.install() is not supported on Python 3.14+. "
             "Use erlang.run(main) or "
             "asyncio.Runner(loop_factory=erlang.new_event_loop) instead."
         )
-    if sys.version_info >= (3, 12):
+    if sys.version_info >= (3, 12) and not silent:
         warnings.warn(
             "erlang.install() is deprecated in Python 3.12+. "
-            "Use erlang.run(main()) instead.",
+            "Use erlang.run(main()) instead, or pass silent=True "
+            "to suppress this warning.",
             DeprecationWarning,
             stacklevel=2
         )

priv/tests/test_erlang_api.py

@@ -279,6 +279,17 @@ def test_install_function(self):
                         any(issubclass(warning.category, DeprecationWarning)
                             for warning in w)
                     )
+
+                # silent=True must suppress the warning even with
+                # simplefilter("always").
+                with warnings.catch_warnings(record=True) as w:
+                    warnings.simplefilter("always")
+                    erlang.install(silent=True)
+                    install_warnings = [
+                        warning for warning in w
+                        if "erlang.install()" in str(warning.message)
+                    ]
+                    self.assertEqual(install_warnings, [])
             else:
                 erlang.install()