![]() This provides an async REPL with the following features: - Run interactive REPL in the background. - Execute statements using await. - Simple history. Signed-off-by: Jim Mussared <jim.mussared@gmail.com> |
||
---|---|---|
.. | ||
README.md | ||
aiorepl.py | ||
manifest.py |
README.md
aiorepl
This library provides "asyncio REPL", a simple REPL that can be used even while your program is running, allowing you to inspect program state, create tasks, and await asynchronous functions.
This is inspired by Python's asyncio
module when run via python -m asyncio
.
Background
The MicroPython REPL is unavailable while your program is running. This library runs a background REPL using the asyncio scheduler.
Furthermore, it is not possible to await
at the main REPL because it does
not know about the asyncio scheduler.
Usage
To use this library, you need to import the library and then start the REPL task.
For example, in main.py:
import uasyncio as asyncio
import aiorepl
async def demo():
await asyncio.sleep_ms(1000)
print("async demo")
state = 20
async def task1():
while state:
#print("task 1")
await asyncio.sleep_ms(500)
print("done")
async def main():
print("Starting tasks...")
# Start other program tasks.
t1 = asyncio.create_task(task1())
# Start the aiorepl task.
repl = asyncio.create_task(aiorepl.task())
await asyncio.gather(t1, repl)
asyncio.run(main())
The optional globals passed to task([globals])
allows you to specify what
will be in scope for the REPL. By default it uses __main__
, which is the
same scope as the regular REPL (and main.py
). In the example above, the
REPL will be able to call the demo()
function as well as get/set the
state
variable.
Instead of the regular >>>
prompt, the asyncio REPL will show -->
.
--> 1+1
2
--> await demo()
async demo
--> state
20
--> import myapp.core
--> state = await myapp.core.query_state()
--> 1/0
ZeroDivisionError: divide by zero
--> def foo(x): return x + 1
--> await asyncio.sleep(foo(3))
-->
History is supported via the up/down arrow keys.
Cancellation
During command editing (the "R" phase), pressing Ctrl-C will cancel the current command and display a new prompt, like the regular REPL.
While a command is being executed, Ctrl-C will cancel the task that is executing the command. This will have no effect on blocking code (e.g. time.sleep()
), but this should be rare in an asyncio-based program.
Ctrl-D at the asyncio REPL command prompt will terminate the current event loop, which will stop the running program and return to the regular REPL.
Limitations
The following features are unsupported:
- Tab completion is not supported (also unsupported in
python -m asyncio
). - Multi-line continuation. However you can do single-line definitions of functions, see demo above.
- Exception tracebacks. Only the exception type and message is shown, see demo above.
- Emacs shortcuts (e.g. Ctrl-A, Ctrl-E, to move to start/end of line).
- Unicode handling for input.