aiomonitor-ng adds monitor and python REPL capabilities for asyncio application
Project description
aiomonitor-ng
aiomonitor-ng is a (temporary) fork of aiomonitor with support for Python 3.10+ and additional usability & debuggability improvements.
aiomonitor is a module that adds monitor and cli capabilities for asyncio applications. Idea and code were borrowed from curio project. Task monitor that runs concurrently to the asyncio loop (or fast drop-in replacement uvloop) in a separate thread as result monitor will work even if the event loop is blocked for some reason.
This library provides a python console using aioconsole module. It is possible to execute asynchronous commands inside your running application. Extensible with you own commands, in the style of the standard library’s cmd module
Installation
Installation process is simple, just:
$ pip install aiomonitor-ng
Example
Monitor has context manager interface:
import aiomonitor
async def main():
loop = asyncio.get_running_loop()
run_forever = loop.create_future()
with aiomonitor.start_monitor(loop):
await run_forever
try:
asyncio.run(main())
except KeyboardInterrupt:
pass
Now from separate terminal it is possible to connect to the application:
$ telnet localhost 50101
or the included python client:
$ python -m aiomonitor.cli
Tutorial
Let’s create a simple aiohttp application, and see how aiomonitor can be integrated with it.
import asyncio
import aiomonitor
from aiohttp import web
# Simple handler that returns response after 100s
async def simple(request):
loop = request.app.loop
print('Start sleeping')
await asyncio.sleep(100, loop=loop)
return web.Response(text="Simple answer")
loop = asyncio.get_event_loop()
# create application and register route
app = web.Application(loop=loop)
app.router.add_get('/simple', simple)
# it is possible to pass a dictionary with local variables
# to the python console environment
host, port = "localhost", 8090
locals_ = {"port": port, "host": host}
# init monitor just before run_app
with aiomonitor.start_monitor(loop=loop, locals=locals_):
# run application with built-in aiohttp run_app function
web.run_app(app, port=port, host=host)
Let’s save this code in file simple_srv.py, so we can run it with the following command:
$ python simple_srv.py ======== Running on http://localhost:8090 ======== (Press CTRL+C to quit)
And now one can connect to a running application from a separate terminal, with the telnet command, and aiomonitor will immediately respond with prompt:
$ telnet localhost 50101 Asyncio Monitor: 1 tasks running Type help for commands monitor >>>
Now you can type commands, for instance, help:
monitor >>> help Usage: help [OPTIONS] COMMAND [ARGS]... To see the usage of each command, run them with "--help" option. Commands: cancel Cancel an indicated task console Switch to async Python REPL exit (q,quit) Leave the monitor client session help (?,h) Show the list of commands ps (p) Show task table ps-terminated (pst,pt) List recently terminated/cancelled tasks signal Send a Unix signal stacktrace (st,stack) Print a stack trace from the event loop thread where (w) Show stack frames and the task creation chain of a task where-terminated (wt) Show stack frames and the termination/cancellation chain of a task
aiomonitor also supports async python console inside a running event loop so you can explore the state of your application:
monitor >>> console Python 3.10.7 (main, Sep 9 2022, 12:31:20) [Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin Type "help", "copyright", "credits" or "license" for more information. --- This console is running in an asyncio event loop. It allows you to wait for coroutines using the 'await' syntax. Try: await asyncio.sleep(1, result=3) --- >>> await asyncio.sleep(1, result=3) 3 >>>
To leave the console type exit() or press Ctrl+D:
>>> exit() ✓ The console session is closed. monitor >>>
Extension
Additional console variables
You may add more variables that can be directly referenced in the console command. Refer the console-variables example code
Custom console commands
aiomonitor is very easy to extend with your own console commands. Refer the extension example code
Requirements
CHANGES
0.7.1 (2023-04-16)
Support Python 3.11 properly by allowing the optional name and context kwargs passed to asyncio.create_task() in the hooked task factory function (#10)
Update development dependencies
0.7.0 (2022-10-19)
Selective persistent termination logs (#9)
Implement cancellation chain tracker (#8)
Trigger auto-completion only when Tab is pressed
Support auto-completion of commands and arguments (#7)
Add missing explicit dependency to Click
0.6.0 (2022-09-26)
Promote console_locals as public attr
Reimplement console command (#6)
Migrate to Click-based command line interface (#5)
Adopt prompt_toolkit and support concurrent clients (#4)
Show the total number of tasks when executing ps (#3)
Apply black, isort, mypy, flake8 and automate CI workflows using GitHub Actions
0.5.1 (2022-08-29)
Fix the task creation location in the ‘ps’ command output
0.5.0 (2022-08-26)
Made it compatible with Python 3.10
Added the task creation stack chain display to the ‘where’ command by setting a custom task factory (#1)
Changed the ‘ps’ command view to be more concise and display many tasks in a better way (#2)
0.4.5 (2019-11-03)
Fixed endless loop on EOF (thanks @apatrushev)
0.4.4 (2019-03-23)
Simplified python console start end #175
Added python 3.7 compatibility #176
0.4.3 (2019-02-02)
Reworked console server start/close logic #169
0.4.2 (2019-01-13)
Fixed issue with type annotations from 0.4.1 release #164
0.4.1 (2019-01-10)
Fixed Python 3.5 support #161 (thanks @bmerry)
0.4.0 (2019-01-04)
Added support for custom commands #133 (thanks @yggdr)
Fixed OptLocals being passed as the default value for “locals” #122 (thanks @agronholm)
Added an API inspired by the standard library’s cmd module #135 (thanks @yggdr)
Correctly report the port running aioconsole #124 (thanks @bmerry)
0.3.1 (2018-07-03)
Added the stacktrace command #120 (thanks @agronholm)
0.3.0 (2017-09-08)
Added _locals_ parameter for passing environment to python REPL
0.2.1 (2016-01-03)
Fixed import in telnet cli in #12 (thanks @hellysmile)
0.2.0 (2016-01-01)
Added basic documentation
Most of methods of Monitor class are not not private api
0.1.0 (2016-12-14)
Added missed LICENSE file
Updated API, added start_monitor() function
0.0.3 (2016-12-11)
Fixed README.rst
0.0.2 (2016-12-11)
Tests more stable now
Added simple tutorial to README.rst
0.0.1 (2016-12-10)
Initial release.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aiomonitor_ng-0.7.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 25be20a3ffdbc2d334f890bcd2413d2566b8993251a7d137bfb986ec3c694b27 |
|
MD5 | 45d933a2b481faf02d0c36ff7f7b569f |
|
BLAKE2b-256 | 6b866b891d6e2286389eea6d84cd2da509bba79b45aeb963cb8a69edeeaaa3d7 |