Debian Codegraph @

src/autocommand/autoasync.py

raw
1 # Copyright 2014-2015 Nathan West
2 #
3 # This file is part of autocommand.
4 #
5 # autocommand is free software: you can redistribute it and/or modify
6 # it under the terms of the GNU Lesser General Public License as published by
7 # the Free Software Foundation, either version 3 of the License, or
8 # (at your option) any later version.
9 #
10 # autocommand is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU Lesser General Public License for more details.
14 #
15 # You should have received a copy of the GNU Lesser General Public License
16 # along with autocommand. If not, see <http://www.gnu.org/licenses/>.
17
18 from asyncio import get_event_loop, iscoroutine
19 from functools import wraps
20 from inspect import signature
21
22
23 async def _run_forever_coro(coro, args, kwargs, loop):
24 '''
25 This helper function launches an async main function that was tagged with
26 forever=True. There are two possibilities:
27
28 - The function is a normal function, which handles initializing the event
29 loop, which is then run forever
30 - The function is a coroutine, which needs to be scheduled in the event
31 loop, which is then run forever
32 - There is also the possibility that the function is a normal function
33 wrapping a coroutine function
34
35 The function is therefore called unconditionally and scheduled in the event
36 loop if the return value is a coroutine object.
37
38 The reason this is a separate function is to make absolutely sure that all
39 the objects created are garbage collected after all is said and done; we
40 do this to ensure that any exceptions raised in the tasks are collected
41 ASAP.
42 '''
43
44 # Personal note: I consider this an antipattern, as it relies on the use of
45 # unowned resources. The setup function dumps some stuff into the event
46 # loop where it just whirls in the ether without a well defined owner or
47 # lifetime. For this reason, there's a good chance I'll remove the
48 # forever=True feature from autoasync at some point in the future.
49 thing = coro(*args, **kwargs)
50 if iscoroutine(thing):
51 await thing
52
53
54 def autoasync(coro=None, *, loop=None, forever=False, pass_loop=False):
55 '''
56 Convert an asyncio coroutine into a function which, when called, is
57 evaluted in an event loop, and the return value returned. This is intented
58 to make it easy to write entry points into asyncio coroutines, which
59 otherwise need to be explictly evaluted with an event loop's
60 run_until_complete.
61
62 If `loop` is given, it is used as the event loop to run the coro in. If it
63 is None (the default), the loop is retreived using asyncio.get_event_loop.
64 This call is defered until the decorated function is called, so that
65 callers can install custom event loops or event loop policies after
66 @autoasync is applied.
67
68 If `forever` is True, the loop is run forever after the decorated coroutine
69 is finished. Use this for servers created with asyncio.start_server and the
70 like.
71
72 If `pass_loop` is True, the event loop object is passed into the coroutine
73 as the `loop` kwarg when the wrapper function is called. In this case, the
74 wrapper function's __signature__ is updated to remove this parameter, so
75 that autoparse can still be used on it without generating a parameter for
76 `loop`.
77
78 This coroutine can be called with ( @autoasync(...) ) or without
79 ( @autoasync ) arguments.
80
81 Examples:
82
83 @autoasync
84 def get_file(host, port):
85 reader, writer = yield from asyncio.open_connection(host, port)
86 data = reader.read()
87 sys.stdout.write(data.decode())
88
89 get_file(host, port)
90
91 @autoasync(forever=True, pass_loop=True)
92 def server(host, port, loop):
93 yield_from loop.create_server(Proto, host, port)
94
95 server('localhost', 8899)
96
97 '''
98 if coro is None:
99 return lambda c: autoasync(
100 c, loop=loop,
101 forever=forever,
102 pass_loop=pass_loop)
103
104 # The old and new signatures are required to correctly bind the loop
105 # parameter in 100% of cases, even if it's a positional parameter.
106 # NOTE: A future release will probably require the loop parameter to be
107 # a kwonly parameter.
108 if pass_loop:
109 old_sig = signature(coro)
110 new_sig = old_sig.replace(parameters=(
111 param for name, param in old_sig.parameters.items()
112 if name != "loop"))
113
114 @wraps(coro)
115 def autoasync_wrapper(*args, **kwargs):
116 # Defer the call to get_event_loop so that, if a custom policy is
117 # installed after the autoasync decorator, it is respected at call time
118 local_loop = get_event_loop() if loop is None else loop
119
120 # Inject the 'loop' argument. We have to use this signature binding to
121 # ensure it's injected in the correct place (positional, keyword, etc)
122 if pass_loop:
123 bound_args = old_sig.bind_partial()
124 bound_args.arguments.update(
125 loop=local_loop,
126 **new_sig.bind(*args, **kwargs).arguments)
127 args, kwargs = bound_args.args, bound_args.kwargs
128
129 if forever:
130 local_loop.create_task(_run_forever_coro(
131 coro, args, kwargs, local_loop
132 ))
133 local_loop.run_forever()
134 else:
135 return local_loop.run_until_complete(coro(*args, **kwargs))
136
137 # Attach the updated signature. This allows 'pass_loop' to be used with
138 # autoparse
139 if pass_loop:
140 autoasync_wrapper.__signature__ = new_sig
141
142 return autoasync_wrapper