Underscore-prefix module names, fix circular dependencies, add actual deprecations

Author: oremanj

tests/conftest.py

@@ -1,9 +1,3 @@
-# XX this does not belong here -- b/c it's here, these things only apply to
-# the tests in trio/_core/tests, not in trio/tests. For now there's some
-# copy-paste...
-#
-# this stuff should become a proper pytest plugin
-
 import pytest
 import asyncio
 import trio_asyncio

trio_asyncio/__init__.py

@@ -1,9 +1,74 @@
 # This code implements basic asyncio compatibility
 
+# Submodules are organized into the following layers, from highest to lowest;
+# to avoid circular dependencies, submodules can only depend on other submodules
+# in a strictly lower layer.
+#
+#                    nice facade: _adapter
+# event loop dispatch and policy: _loop
+#     event loop implementations: _async, _sync
+#                event loop base: _base
+#                      utilities: _handles, _util, _child, _deprecate, _version
+
 from ._version import __version__  # noqa
 
-from .base import *  # noqa
-from .loop import *  # noqa
-from .util import *  # noqa
-from .async_ import *  # noqa
-from .adapter import *  # noqa
+from ._deprecate import TrioAsyncioDeprecationWarning
+from ._util import run_aio_future, run_aio_generator
+from ._base import BaseTrioEventLoop, TrioExecutor
+from ._async import TrioEventLoop
+from ._loop import (
+    # main entry point:
+    open_loop,
+    # trio.run() + trio_asyncio.open_loop():
+    run,
+    # loop selection:
+    TrioChildWatcher,
+    TrioPolicy,
+    current_loop,
+    current_policy,
+    # forwarders to event loop methods:
+    run_trio_task,
+    run_trio,
+    run_aio_coroutine,
+    # forwarders to deprecated event loop methods:
+    run_future,
+    run_coroutine,
+    run_asyncio,
+    wrap_generator,
+    run_iterator,
+)
+from ._adapter import (
+    aio_as_trio,
+    trio_as_aio,
+    # aliases for the above:
+    asyncio_as_trio,
+    trio_as_asyncio,
+    # deprecated aliases for the above:
+    trio2aio,
+    aio2trio,
+    # additional experimental goodie:
+    allow_asyncio,
+)
+
+import importlib as _importlib
+from . import _deprecate, _util
+
+_deprecate.enable_attribute_deprecations(__name__)
+__deprecated_attributes__ = {
+    name: _deprecate.DeprecatedAttribute(
+        _importlib.import_module("trio_asyncio._" + name.rstrip("_")),
+        "0.11.0",
+        issue=64,
+        instead="an import from the top-level trio_asyncio package",
+    )
+    for name in (
+        "adapter", "async_", "base", "child", "handles", "loop", "sync", "util"
+    )
+}
+
+# Provide aliases in the old place for names that moved between modules.
+# Remove these when the non-underscore-prefixed module names are removed.
+from . import _loop, _async
+_async.open_loop = _loop.open_loop
+
+_util.fixup_module_metadata(__name__, globals())

trio_asyncio/adapter.py trio_asyncio/_adapter.pytrio_asyncio/adapter.py renamed to trio_asyncio/_adapter.py

@@ -8,32 +8,15 @@
 import trio_asyncio
 from contextvars import ContextVar
 
-from .util import run_aio_generator, run_aio_future, run_trio_generator
-
-current_loop = ContextVar('trio_aio_loop', default=None)
-current_policy = ContextVar('trio_aio_policy', default=None)
+from ._deprecate import deprecated_alias
+from ._util import run_aio_generator, run_aio_future, run_trio_generator
+from ._loop import current_loop, current_policy
 
 # import logging
 # logger = logging.getLogger(__name__)
 
 from functools import wraps, partial
 
-__all__ = [
-    'trio2aio', 'aio2trio', 'aio_as_trio', 'trio_as_aio', 'allow_asyncio', 'current_loop',
-    'current_policy', 'asyncio_as_trio', 'trio_as_asyncio'
-]
-
-
-def trio2aio(proc):
-    """Call asyncio code from Trio.
-
-        Deprecated: Use aio_as_trio() instead.
-
-        """
-    warnings.warn("Use 'aio_as_trio(proc)' instead'", DeprecationWarning)
-
-    return aio_as_trio(proc)
-
 
 async def _call_defer(proc, *args, **kwargs):
     return await proc(*args, **kwargs)
@@ -210,30 +193,6 @@ def trio_as_aio(proc, *, loop=None):
 trio_as_asyncio = trio_as_aio
 
 
-def aio2trio(proc):
-    """Call asyncio code from Trio.
-
-        Deprecated: Use aio_as_trio() instead.
-
-        """
-    warnings.warn("Use 'trio_as_aio(proc)' instead'", DeprecationWarning)
-
-    return trio_as_aio(proc)
-
-
-def aio2trio_task(proc):
-    warnings.warn("Use loop.run_trio_task() instead", DeprecationWarning)
-
-    @wraps(proc)
-    async def call(*args, **kwargs):
-        proc_ = proc
-        if kwargs:
-            proc_ = partial(proc_, **kwargs)
-        trio_asyncio.run_trio_task(proc_, *args)
-
-    return call
-
-
 @types.coroutine
 def _allow_asyncio(fn, *args):
     shim = trio_asyncio.base._shim_running
@@ -261,6 +220,8 @@ def _allow_asyncio(fn, *args):
             p, a = coro.send, next_send
 
 
+_shim_running = ContextVar("shim_running", default=False)
+
 async def allow_asyncio(fn, *args):
     """
     This wrapper allows you to indiscrimnately mix :mod:`trio` and
@@ -287,11 +248,15 @@ async def main():
 
     This function must be called from :mod:`trio` context.
     """
-    shim = trio_asyncio.base._shim_running
+    shim = _shim_running
     if shim.get():  # nested call: skip
         return await fn(*args)
     token = shim.set(True)
     try:
         return await _allow_asyncio(fn, *args)
     finally:
         shim.reset(token)
+
+
+trio2aio = deprecated_alias("trio_asyncio.trio2aio", aio_as_trio, "0.10.0", issue=38)
+aio2trio = deprecated_alias("trio_asyncio.aio2trio", trio_as_aio, "0.10.0", issue=38)

trio_asyncio/async_.py trio_asyncio/_async.pytrio_asyncio/async_.py renamed to trio_asyncio/_async.py

@@ -1,11 +1,7 @@
 import trio
 
-from async_generator import async_generator, yield_, asynccontextmanager
-
-from .base import BaseTrioEventLoop
-from .handles import Handle
-
-__all__ = ['TrioEventLoop', 'open_loop']
+from ._base import BaseTrioEventLoop
+from ._handles import Handle
 
 
 class TrioEventLoop(BaseTrioEventLoop):
@@ -81,53 +77,3 @@ def _close(self):
         if not self._stopped.is_set():
             raise RuntimeError("You need to stop the loop before closing it")
         super()._close()
-
-
-@asynccontextmanager
-@async_generator
-async def open_loop(queue_len=None):
-    """Main entry point: run an asyncio loop on top of Trio.
-
-    This is a context manager.
-
-    Example usage::
-
-            async def async_main(*args):
-                async with trio_asyncio.open_loop() as loop:
-                    pass
-                    # async part of your main program here
-
-    """
-
-    # TODO: make sure that there is no asyncio loop already running
-
-    def _main_loop_exit(self):
-        super()._main_loop_exit()
-        self._thread = None
-
-    from .loop import current_loop, current_policy, TrioPolicy
-
-    async with trio.open_nursery() as nursery:
-        policy = current_policy.get()
-        if not isinstance(policy, TrioPolicy):
-            policy = TrioPolicy()
-        old_policy = current_policy.set(policy)
-
-        loop = TrioEventLoop(queue_len=queue_len)
-        old_loop = current_loop.set(loop)
-        try:
-            loop._closed = False
-            await loop._main_loop_init(nursery)
-            await nursery.start(loop._main_loop)
-            await yield_(loop)
-        finally:
-            try:
-                await loop.stop().wait()
-            finally:
-                try:
-                    await loop._main_loop_exit()
-                finally:
-                    loop.close()
-                    nursery.cancel_scope.cancel()
-                    current_loop.reset(old_loop)
-                    current_policy.reset(old_policy)