Implement uvloop.run()

Author: 1st1

README.rst

@@ -53,6 +53,27 @@ uvloop with::
 Using uvloop
 ------------
 
+As of uvloop 0.18, the preferred way of using it is via the
+``uvloop.run()`` helper function:
+
+
+.. code:: python
+
+import uvloop
+
+asyncdefmain():
+# Main entry-point.
+...
+
+ uvloop.run(main())
+
+``uvloop.run()`` works by simply configuring ``asyncio.run()``
+to use uvloop, passing all of the arguments to it, such as ``debug``,
+e.g. ``uvloop.run(main(), debug=True)``.
+
+With Python 3.11 and earlier the following alternative
+snippet can be used:
+
 .. code:: python
 
 import asyncio

tests/test_dealloc.py

@@ -30,14 +30,12 @@ def test_dealloc_1(self):
 asyncdeftest():
 prog='''\
 import uvloop
-import asyncio
 
 async def foo():
  return 42
 
 def main():
- uvloop.install()
- loop = asyncio.get_event_loop()
+ loop = uvloop.new_event_loop()
  loop.set_debug(True)
  loop.run_until_complete(foo())
  # Do not close the loop on purpose: let __dealloc__ methods run.

tests/test_process.py

@@ -851,8 +851,7 @@ async def test():
  )
  await proc.communicate()
 
- uvloop.install()
- asyncio.run(test())
+ uvloop.run(test())
 
  stdin, stdout, stderr = dups
  (r, w), = pipes

tests/test_runner.py

@@ -0,0 +1,39 @@
+importasyncio
+importunittest
+importuvloop
+
+
+classTestSourceCode(unittest.TestCase):
+
+deftest_uvloop_run_1(self):
+CNT=0
+
+asyncdefmain():
+nonlocalCNT
+CNT+=1
+
+loop=asyncio.get_running_loop()
+
+self.assertTrue(isinstance(loop, uvloop.Loop))
+self.assertTrue(loop.get_debug())
+
+return'done'
+
+result=uvloop.run(main(), debug=True)
+
+self.assertEqual(result, 'done')
+self.assertEqual(CNT, 1)
+
+deftest_uvloop_run_2(self):
+
+asyncdefmain():
+pass
+
+coro=main()
+withself.assertRaisesRegex(TypeError, ' a non-uvloop event loop'):
+uvloop.run(
+coro,
+loop_factory=asyncio.DefaultEventLoopPolicy().new_event_loop,
+ )
+
+coro.close()

uvloop/__init__.py

@@ -1,5 +1,7 @@
 importasyncioas__asyncio
 importtypingas_typing
+importsysas_sys
+importwarningsas_warnings
 
 fromasyncio.eventsimportBaseDefaultEventLoopPolicyas__BasePolicy
 
@@ -22,9 +24,102 @@ def new_event_loop() -> Loop:
 
 definstall() ->None:
 """A helper function to install uvloop policy."""
+if_sys.version_info[:2] >= (3, 12):
+_warnings.warn(
+'uvloop.install() is deprecated in favor of uvloop.run() '
+'starting with Python 3.12.',
+DeprecationWarning,
+stacklevel=1,
+ )
 __asyncio.set_event_loop_policy(EventLoopPolicy())
 
 
+defrun(main, *, loop_factory=new_event_loop, debug=None, **run_kwargs):
+"""The preferred way of running a coroutine with uvloop."""
+
+asyncdefwrapper():
+# If `loop_factory` is provided we want it to return
+# either uvloop.Loop or a subtype of it, assuming the user
+# is using `uvloop.run()` intentionally.
+loop=__asyncio._get_running_loop()
+ifnotisinstance(loop, Loop):
+raiseTypeError('uvloop.run() uses a non-uvloop event loop')
+returnawaitmain
+
+vi=_sys.version_info[:2]
+
+ifvi<= (3, 10):
+# Copied from python/cpython
+
+if__asyncio._get_running_loop() isnotNone:
+raiseRuntimeError(
+"asyncio.run() cannot be called from a running event loop")
+
+ifnot__asyncio.iscoroutine(main):
+raiseValueError("a coroutine was expected, got{!r}".format(main))
+
+loop=loop_factory()
+try:
+__asyncio.set_event_loop(loop)
+ifdebugisnotNone:
+loop.set_debug(debug)
+returnloop.run_until_complete(wrapper())
+finally:
+try:
+_cancel_all_tasks(loop)
+loop.run_until_complete(loop.shutdown_asyncgens())
+loop.run_until_complete(loop.shutdown_default_executor())
+finally:
+__asyncio.set_event_loop(None)
+loop.close()
+
+elifvi== (3, 11):
+if__asyncio._get_running_loop() isnotNone:
+raiseRuntimeError(
+"asyncio.run() cannot be called from a running event loop")
+
+with__asyncio.Runner(
+loop_factory=loop_factory,
+debug=debug,
+**run_kwargs
+ ) asrunner:
+returnrunner.run(wrapper())
+
+else:
+assertvi>= (3, 12)
+return__asyncio.run(
+wrapper(),
+loop_factory=loop_factory,
+debug=debug,
+**run_kwargs
+ )
+
+
+def_cancel_all_tasks(loop):
+# Copied from python/cpython
+
+to_cancel=__asyncio.all_tasks(loop)
+ifnotto_cancel:
+return
+
+fortaskinto_cancel:
+task.cancel()
+
+loop.run_until_complete(
+__asyncio.gather(*to_cancel, return_exceptions=True)
+ )
+
+fortaskinto_cancel:
+iftask.cancelled():
+continue
+iftask.exception() isnotNone:
+loop.call_exception_handler({
+'message': 'unhandled exception during asyncio.run() shutdown',
+'exception': task.exception(),
+'task': task,
+ })
+
+
 classEventLoopPolicy(__BasePolicy):
 """Event loop policy.
 

uvloop/__init__.pyi

@@ -0,0 +1,17 @@
+importsys
+
+fromasyncioimportAbstractEventLoop
+fromcollections.abcimportCallable, Coroutine
+fromcontextvarsimportContext
+fromtypingimportAny, TypeVar
+
+
+_T=TypeVar('_T')
+
+
+defrun(
+main: Coroutine[Any, Any, _T],
+*,
+debug: bool|None= ...,
+loop_factory: Callable[[], AbstractEventLoop] |None= ...,
+) ->_T: ...