Merge pull request #23 from graingert/provide-thread-local

Author: graingert

docs/source/index.rst

@@ -52,53 +52,53 @@ If you'd like your library to be detected by ``sniffio``, it's pretty
 easy.
 
 **Step 1:** Pick the magic string that will identify your library. To
-avoid collisions, this should match your library's name on PyPI.
+avoid collisions, this should match your library's PEP 503 normalized name on PyPI.
 
-**Step 2:** There's a special :class:`contextvars.ContextVar` object:
+**Step 2:** There's a special :class:`threading.local` object:
 
-.. data:: current_async_library_cvar
+.. data:: thread_local.name
 
-Make sure that whenever your library is running, this is set to your
-identifier string. In most cases, this will be as simple as:
+Make sure that whenever your library is calling a coroutine ``throw()``, ``send()``, or ``close()``
+that this is set to your identifier string. In most cases, this will be as simple as:
 
 .. code-block:: python3
 
-   from sniffio import current_async_library_cvar
+   from sniffio import thread_local
 
-   # Your library's run function
-   def run(...):
-        token = current_async_library_cvar.set("my-library's-PyPI-name")
+   # Your library's step function
+   def step(...):
+        old_name, thread_local.name = thread_local.name, "my-library's-PyPI-name"
         try:
-            # The actual body of your run() function:
-            ...
+            result = coro.send(None)
         finally:
-            current_async_library_cvar.reset(token)
+            thread_local.name = old_name
 
 **Step 3:** Send us a PR to add your library to the list of supported
 libraries above.
 
 That's it!
 
-Notes:
+There are libraries that directly drive a sniffio-naive coroutine from another,
+outer sniffio-aware coroutine such as `trio_asyncio`.
+These libraries should make sure to set the correct value
+while calling a synchronous function that will go on to drive the
+sniffio-naive coroutine.
 
-On older Pythons without native contextvars support, sniffio
-transparently uses `the official contextvars backport
-<https://pypi.org/project/contextvars/>`__, so you don't need to worry
-about that.
 
-There are libraries that can switch back and forth between different
-async modes within a single call-task – like ``trio_asyncio`` or
-Twisted's asyncio operability. These libraries should make sure to set
-the value back and forth at appropriate points.
+.. code-block:: python3
+
+   from sniffio import thread_local
 
-The general rule of thumb: :data:`current_async_library_cvar` should
-be set to X exactly at those moments when ``await X.sleep(...)`` will
-work.
+   # Your library's compatibility loop
+   async def main_loop(self, ...) -> None:
+        ...
+        handle: asyncio.Handle = await self.get_next_handle()
+        old_name, thread_local.name = thread_local.name, "asyncio"
+        try:
+            result = handle._callback(obj._args)
+        finally:
+            thread_local.name = old_name
 
-.. warning:: You shouldn't attempt to read the value of
-   ``current_async_library_cvar`` directly –
-   :func:`current_async_library` has a little bit more cleverness than
-   that.
 
 .. toctree::
    :maxdepth: 1

sniffio/__init__.py

@@ -11,4 +11,5 @@
     current_async_library,
     AsyncLibraryNotFoundError,
     current_async_library_cvar,
+    thread_local,
 )

sniffio/_impl.py

@@ -1,12 +1,23 @@
 from contextvars import ContextVar
 from typing import Optional
 import sys
+import threading
 
 current_async_library_cvar = ContextVar(
     "current_async_library_cvar", default=None
 )  # type: ContextVar[Optional[str]]
 
 
+class _ThreadLocal(threading.local):
+    # Since threading.local provides no explicit mechanism is for setting
+    # a default for a value, a custom class with a class attribute is used
+    # instead.
+    name = None  # type: Optional[str]
+
+
+thread_local = _ThreadLocal()
+
+
 class AsyncLibraryNotFoundError(RuntimeError):
     pass
 
@@ -52,6 +63,10 @@ async def generic_sleep(seconds):
                    raise RuntimeError(f"Unsupported library {library!r}")
 
     """
+    value = thread_local.name
+    if value is not None:
+        return value
+
     value = current_async_library_cvar.get()
     if value is not None:
         return value

sniffio/_tests/test_sniffio.py

@@ -4,11 +4,11 @@
 
 from .. import (
     current_async_library, AsyncLibraryNotFoundError,
-    current_async_library_cvar
+    current_async_library_cvar, thread_local
 )
 
 
-def test_basics():
+def test_basics_cvar():
     with pytest.raises(AsyncLibraryNotFoundError):
         current_async_library()
 
@@ -22,6 +22,20 @@ def test_basics():
         current_async_library()
 
 
+def test_basics_tlocal():
+    with pytest.raises(AsyncLibraryNotFoundError):
+        current_async_library()
+
+    old_name, thread_local.name = thread_local.name, "generic-lib"
+    try:
+        assert current_async_library() == "generic-lib"
+    finally:
+        thread_local.name = old_name
+
+    with pytest.raises(AsyncLibraryNotFoundError):
+        current_async_library()
+
+
 def test_asyncio():
     import asyncio