switch from run_trio method to aio_as_trio wrapper

Author: smurfix

docs/source/usage.rst

@@ -378,56 +378,87 @@ Thus, you really should not use it for "real" programs or libraries.
 Calling Trio from asyncio
 +++++++++++++++++++++++++
 
-For basic async calls, pass the function and any arguments to
-``loop.run_trio()``. This method returns a standard asyncio Future which
-you can await, add callbacks to, or whatever.
+Wrap the callable, awaitable, generator, or iterator in :func:`trio_as_aio`.
 
-::
+Thus, you can call a :mod:`trio` function from :mod:`asyncio` thus::
 
-    async def some_trio_code(foo):
-        await trio.sleep(1)
-        return foo*2
-    
-    future = loop.run_trio(some_trio_code, 21)
-    res = await future
-    assert res == 42
+    async def trio_sleep(sec=1):
+        await trio.sleep(sec)
+    async def aio_sleep(sec=2):
+        await aio_as_trio(trio_sleep)(sec)
+    trio_asyncio.run(aio_as_trio, aio_sleep, 3)
 
-You can also use the ``aio2trio`` decorator::
+or pre-wrapped::
 
-    @aio2trio
-    async def some_trio_code(self, foo):
-        await trio.sleep(1)
-        return foo+33
+    @trio_as_aio
+    async def trio_sleep(sec=1):
+        await trio.sleep(sec)
+    async def aio_sleep(sec=2):
+        await trio_sleep(sec)
+    trio_asyncio.run(aio_as_trio, aio_sleep, 3)
 
-    res = await some_trio_code(9)
-    assert res == 42
+In contrast to :func:`aio_as_trio`, using an awaitable is not supported
+because that's not an idiom :mod:`trio` uses.
 
-.. autodoc: trio_asyncio.adapter.aio2trio
+Calling a function wrapped with :func:`trio_as_aio` returns a regular
+:class:`asyncio.Future`. Thus, you can call it from a synchronous context
+(e.g. a callback hook). Of course, you're responsible for catching any
+errors – either arrange to ``await`` the future, or use
+``.add_done_callback()`` ::
 
-.. autodoc: trio_asyncio.adapter.aio2trio_task
+    async def trio_sleep(sec=1):
+        await trio.sleep(sec)
+        return 42
+    def cb(f):
+        assert f.result == 42
+    async def aio_sleep(sec=2):
+        f = trio_as_aio(trio_sleep)(1)
+        f.add_done_callback(cb)
+        r = await f
+        assert r == 42
+    trio_asyncio.run(aio_as_trio, aio_sleep, 3)
 
-``run_trio()`` is not itself an async function, so you can call it from a
-synchronous context (e.g. a callback hook). However, you're responsible for
-catching any errors – either await() the future, or use
-``.add_done_callback()``.
+You can wrap context handlers::
 
-If you want to start a task that shall be monitored by ``trio_asyncio``
-(i.e. an uncaught error will propagate to, and terminate, the loop), use
-``run_trio_task()`` instead.
+    class TrioCtx:
+        async def __aenter__(self):
+            await trio.sleep(1)
+            return self
+        async def __aexit__(self, *tb):
+            await trio.sleep(1)
+        async def delay(self, sec=1):
+            await trio.sleep(sec)
+    async def aio_ctx():
+        async with trio_as_aio(AsyncCtx()) as ctx:
+            print("within")
+            await trio_as_aio(ctx.delay)(2)
+    trio_asyncio.run(aio_as_trio, aio_ctx)
+
+You can also wrap async generators or iterators::
+
+    async def trio_slow():
+        n = 0
+        while True:
+            await trio.sleep(n)
+            yield n
+            n += 1
+    async def printer():
+        async for n in trio_as_aio(aio_slow()):
+            print(n)
+    trio_asyncio.run(aio_as_trio, printer)
 
-.. autodoc: trio_asyncio.adapter.aio2trio_task
+.. autodoc: trio_asyncio.trio_as_aio
 
-If you need to call a Trio-style async context manager from asyncio, use
-``loop.wrap_trio_context()``::
 
-    async with loop.wrap_trio_context(context()) as ctx:
-        await loop.run_trio(ctx.do_whatever)
+Trio background tasks
+---------------------
 
-As you can see from this example, the context that's returned is a "native"
-Trio context, so you still need to use ``run_trio()`` if you call its
-methods.
+If you want to start a Trio task that shall be monitored by ``trio_asyncio``
+(i.e. an uncaught error will propagate to, and terminate, the asyncio event
+loop) instead of a :class:`asyncio.Future`, use
+:meth:`TrioEventLoop.run_trio_task`.
 
-.. autodoc: trio_asyncio.wrap_trio_context
+.. autodoc: trio_asyncio.TrioEventLoop.run_trio_task
 
 Multiple asyncio loops
 ++++++++++++++++++++++

tests/interop/test_adapter.py

@@ -1,5 +1,5 @@
 import pytest
-from trio_asyncio import aio_as_trio, allow_asyncio
+from trio_asyncio import aio_as_trio, trio_as_aio, allow_asyncio
 from trio_asyncio import aio2trio, trio2aio
 import asyncio
 import trio
@@ -15,14 +15,29 @@ class SomeThing:
     def __init__(self, loop):
         self.loop = loop
 
-    @aio2trio
     async def dly_trio(self):
         if sys.version_info >= (3, 7):
             assert sniffio.current_async_library() == "trio"
         await trio.sleep(0.01)
         self.flag |= 2
         return 8
 
+    @trio_as_aio
+    async def dly_trio_adapted(self):
+        if sys.version_info >= (3, 7):
+            assert sniffio.current_async_library() == "trio"
+        await trio.sleep(0.01)
+        self.flag |= 2
+        return 8
+
+    @aio2trio
+    async def dly_trio_depr(self):
+        if sys.version_info >= (3, 7):
+            assert sniffio.current_async_library() == "trio"
+        await trio.sleep(0.01)
+        self.flag |= 2
+        return 8
+
     @trio2aio
     async def dly_asyncio_depr(self):
         if sys.version_info >= (3, 7):
@@ -39,15 +54,15 @@ async def dly_asyncio_adapted(self):
         self.flag |= 1
         return 4
 
-    async def dly_asyncio(self):
-        if sys.version_info >= (3, 7):
+    async def dly_asyncio(self, do_test=True):
+        if do_test and sys.version_info >= (3, 7):
             assert sniffio.current_async_library() == "asyncio"
         await asyncio.sleep(0.01, loop=self.loop)
         self.flag |= 1
         return 4
 
-    async def iter_asyncio(self):
-        if sys.version_info >= (3, 7):
+    async def iter_asyncio(self, do_test=True):
+        if do_test and sys.version_info >= (3, 7):
             assert sniffio.current_async_library() == "asyncio"
         await asyncio.sleep(0.01, loop=self.loop)
         yield 1
@@ -56,6 +71,16 @@ async def iter_asyncio(self):
         await asyncio.sleep(0.01, loop=self.loop)
         self.flag |= 1
 
+    async def iter_trio(self):
+        if sys.version_info >= (3, 7):
+            assert sniffio.current_async_library() == "trio"
+        await trio.sleep(0.01)
+        yield 1
+        await trio.sleep(0.01)
+        yield 2
+        await trio.sleep(0.01)
+        self.flag |= 1
+
     @asynccontextmanager
     async def ctx_asyncio(self):
         await asyncio.sleep(0.01, loop=self.loop)
@@ -64,13 +89,30 @@ async def ctx_asyncio(self):
         await asyncio.sleep(0.01, loop=self.loop)
         self.flag |= 2
 
+    @asynccontextmanager
+    async def ctx_trio(self):
+        await trio.sleep(0.01)
+        self.flag |= 1
+        yield self
+        await trio.sleep(0.01)
+        self.flag |= 2
+
 class TestAdapt(aiotest.TestCase):
     @pytest.mark.trio
-    async def test_asyncio_trio(self, loop):
+    async def test_asyncio_trio_depr(self, loop):
+        """Call asyncio from trio"""
+
+        sth = SomeThing(loop)
+        res = await aio_as_trio(sth.dly_trio_depr, loop=loop)()
+        assert res == 8
+        assert sth.flag == 2
+
+    @pytest.mark.trio
+    async def test_asyncio_trio_adapted(self, loop):
         """Call asyncio from trio"""
 
         sth = SomeThing(loop)
-        res = await aio_as_trio(sth.dly_trio, loop=loop)()
+        res = await aio_as_trio(sth.dly_trio_adapted, loop=loop)()
         assert res == 8
         assert sth.flag == 2
 
@@ -80,7 +122,7 @@ async def test_asyncio_trio_depr(self, loop):
 
         sth = SomeThing(loop)
         with test_utils.deprecate(self):
-            res = await loop.run_asyncio(sth.dly_trio)
+            res = await loop.run_asyncio(sth.dly_trio_adapted)
         assert res == 8
         assert sth.flag == 2
 
@@ -108,7 +150,7 @@ async def test_trio_asyncio_awaitable(self, loop):
     @pytest.mark.trio
     async def test_trio_asyncio_future(self, loop):
         sth = SomeThing(loop)
-        f = sth.dly_asyncio()
+        f = sth.dly_asyncio(do_test=False)
         f = asyncio.ensure_future(f)
         res = await aio_as_trio(f)
         assert res == 4
@@ -125,24 +167,65 @@ async def test_trio_asyncio_depr(self, loop):
     async def test_trio_asyncio_iter(self, loop):
         sth = SomeThing(loop)
         n = 0
+        if sys.version_info >= (3, 7):
+            assert sniffio.current_async_library() == "trio"
         async for x in aio_as_trio(sth.iter_asyncio()):
             n += 1
             assert x == n
         assert n == 2
         assert sth.flag == 1
 
+    async def run_asyncio_trio_iter(self, loop):
+        sth = SomeThing(loop)
+        n = 0
+        if sys.version_info >= (3, 7):
+            assert sniffio.current_async_library() == "asyncio"
+        async for x in trio_as_aio(sth.iter_trio()):
+            n += 1
+            assert x == n
+        assert n == 2
+        assert sth.flag == 1
+
+    @pytest.mark.trio
+    async def test_asyncio_trio_iter(self, loop):
+        await aio_as_trio(self.run_asyncio_trio_iter)(loop)
+
     @pytest.mark.trio
     async def test_trio_asyncio_ctx(self, loop):
         sth = SomeThing(loop)
         async with aio_as_trio(sth.ctx_asyncio()):
             assert sth.flag == 1
         assert sth.flag == 3
 
+    async def run_asyncio_trio_ctx(self, loop):
+        sth = SomeThing(loop)
+        async with trio_as_aio(sth.ctx_trio()):
+            assert sth.flag == 1
+        assert sth.flag == 3
+
+    @pytest.mark.trio
+    async def test_asyncio_trio_ctx(self, loop):
+        await aio_as_trio(self.run_asyncio_trio_ctx)(loop)
+
 class TestAllow(aiotest.TestCase):
     async def run_asyncio_trio(self, loop):
         """Call asyncio from trio"""
         sth = SomeThing(loop)
-        res = await sth.dly_trio()
+        res = await trio_as_aio(sth.dly_trio, loop=loop)()
+        assert res == 8
+        assert sth.flag == 2
+
+    async def run_asyncio_trio_adapted(self, loop):
+        """Call asyncio from trio"""
+        sth = SomeThing(loop)
+        res = await sth.dly_trio_adapted()
+        assert res == 8
+        assert sth.flag == 2
+
+    async def run_asyncio_trio_depr(self, loop):
+        """Call asyncio from trio"""
+        sth = SomeThing(loop)
+        res = await sth.dly_trio_depr()
         assert res == 8
         assert sth.flag == 2
 
@@ -152,7 +235,7 @@ async def test_asyncio_trio(self, loop):
 
     async def run_trio_asyncio(self, loop):
         sth = SomeThing(loop)
-        res = await sth.dly_asyncio()
+        res = await sth.dly_asyncio(do_test=False)
         assert res == 4
         assert sth.flag == 1
 
@@ -162,7 +245,7 @@ async def test_trio_asyncio(self, loop):
 
     async def run_trio_asyncio_future(self, loop):
         sth = SomeThing(loop)
-        f = sth.dly_asyncio()
+        f = sth.dly_asyncio(do_test=False)
         f = asyncio.ensure_future(f)
         res = await f
         assert res == 4
@@ -185,7 +268,7 @@ async def test_trio_asyncio_depr(self, loop):
     async def run_trio_asyncio_iter(self, loop):
         sth = SomeThing(loop)
         n = 0
-        async for x in sth.iter_asyncio():
+        async for x in sth.iter_asyncio(do_test=False):
             n += 1
             assert x == n
         assert n == 2