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
.. image:: https://raw.githubusercontent.com/achimnol/aiomonitor-ng/master/docs/screenshot-ps-where-example.png
Installation
------------
Installation process is simple, just::
$ pip install aiomonitor-ng
Example
-------
Monitor has context manager interface:
.. code:: python
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.
.. code:: python
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
signal Send a Unix signal
stacktrace (st,stack) Print a stack trace from the event loop thread
where (w) Show stack frames and its task creation 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 <https://github.com/achimnol/aiomonitor-ng/tree/master/examples/console-variables.py>`_
Custom console commands
~~~~~~~~~~~~~~~~~~~~~~~
``aiomonitor`` is very easy to extend with your own console commands.
Refer `the extension example code <https://github.com/achimnol/aiomonitor-ng/tree/master/examples/extension.py>`_
Requirements
------------
* Python_ 3.8+ (3.10.7+ recommended)
* aioconsole_
* Click_
* prompt_toolkit_
* uvloop_ (optional)
.. _PEP492: https://www.python.org/dev/peps/pep-0492/
.. _Python: https://www.python.org
.. _aioconsole: https://github.com/vxgmichel/aioconsole
.. _aiohttp: https://github.com/aio-libs/aiohttp
.. _asyncio: http://docs.python.org/3/library/asyncio.html
.. _Click: https://click.palletsprojects.com
.. _curio: https://github.com/dabeaz/curio
.. _prompt_toolkit: https://python-prompt-toolkit.readthedocs.io
.. _uvloop: https://github.com/MagicStack/uvloop
.. _cmd: http://docs.python.org/3/library/cmd.html
CHANGES
=======
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/achimnol/aiomonitor-ng",
"name": "aiomonitor-ng",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Nikolay Novik",
"author_email": "nickolainovik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fb/18/05c571cdcc5c6b8d8be0d4023dd592831fcdce432e2381b88146a3b49d50/aiomonitor-ng-0.7.0.tar.gz",
"platform": "POSIX",
"description": "aiomonitor-ng\n=============\n\n**aiomonitor-ng** is a (temporary) fork of **aiomonitor** with support for\nPython 3.10+ and additional usability & debuggability improvements.\n\n**aiomonitor** is a module that adds monitor and cli capabilities\nfor asyncio_ applications. Idea and code were borrowed from curio_ project.\nTask monitor that runs concurrently to the asyncio_ loop (or fast drop-in\nreplacement uvloop_) in a separate thread as result monitor will work even if\nthe event loop is blocked for some reason.\n\nThis library provides a python console using aioconsole_ module. It is possible\nto execute asynchronous commands inside your running application. Extensible\nwith you own commands, in the style of the standard library's cmd_ module\n\n.. image:: https://raw.githubusercontent.com/achimnol/aiomonitor-ng/master/docs/screenshot-ps-where-example.png\n\nInstallation\n------------\nInstallation process is simple, just::\n\n $ pip install aiomonitor-ng\n\n\nExample\n-------\nMonitor has context manager interface:\n\n.. code:: python\n\n import aiomonitor\n\n async def main():\n loop = asyncio.get_running_loop()\n run_forever = loop.create_future()\n with aiomonitor.start_monitor(loop):\n await run_forever\n\n try:\n asyncio.run(main())\n except KeyboardInterrupt:\n pass\n\nNow from separate terminal it is possible to connect to the application::\n\n $ telnet localhost 50101\n\nor the included python client::\n\n $ python -m aiomonitor.cli\n \n \nTutorial\n--------\n\nLet's create a simple aiohttp_ application, and see how ``aiomonitor`` can\nbe integrated with it.\n\n.. code:: python\n\n import asyncio\n\n import aiomonitor\n from aiohttp import web\n\n # Simple handler that returns response after 100s\n async def simple(request):\n loop = request.app.loop\n\n print('Start sleeping')\n await asyncio.sleep(100, loop=loop)\n return web.Response(text=\"Simple answer\")\n\n loop = asyncio.get_event_loop()\n # create application and register route\n app = web.Application(loop=loop)\n app.router.add_get('/simple', simple)\n\n # it is possible to pass a dictionary with local variables\n # to the python console environment\n host, port = \"localhost\", 8090\n locals_ = {\"port\": port, \"host\": host}\n # init monitor just before run_app\n with aiomonitor.start_monitor(loop=loop, locals=locals_):\n # run application with built-in aiohttp run_app function\n web.run_app(app, port=port, host=host)\n\nLet's save this code in file ``simple_srv.py``, so we can run it with the following command::\n\n $ python simple_srv.py\n ======== Running on http://localhost:8090 ========\n (Press CTRL+C to quit)\n\nAnd now one can connect to a running application from a separate terminal, with\nthe ``telnet`` command, and ``aiomonitor`` will immediately respond with prompt::\n\n $ telnet localhost 50101\n Asyncio Monitor: 1 tasks running\n Type help for commands\n monitor >>>\n\nNow you can type commands, for instance, ``help``::\n\n monitor >>> help\n Usage: help [OPTIONS] COMMAND [ARGS]...\n \n To see the usage of each command, run them with \"--help\" option.\n \n Commands:\n cancel Cancel an indicated task\n console Switch to async Python REPL\n exit (q,quit) Leave the monitor client session\n help (?,h) Show the list of commands\n ps (p) Show task table\n signal Send a Unix signal\n stacktrace (st,stack) Print a stack trace from the event loop thread\n where (w) Show stack frames and its task creation chain of a task\n\n``aiomonitor`` also supports async python console inside a running event loop\nso you can explore the state of your application::\n\n monitor >>> console\n Python 3.10.7 (main, Sep 9 2022, 12:31:20) [Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin\n Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n ---\n This console is running in an asyncio event loop.\n It allows you to wait for coroutines using the 'await' syntax.\n Try: await asyncio.sleep(1, result=3)\n ---\n >>> await asyncio.sleep(1, result=3)\n 3\n >>>\n\nTo leave the console type ``exit()`` or press Ctrl+D::\n\n >>> exit()\n\n \u2713 The console session is closed.\n monitor >>>\n\nExtension\n---------\n\nAdditional console variables\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou may add more variables that can be directly referenced in the ``console`` command.\nRefer `the console-variables example code <https://github.com/achimnol/aiomonitor-ng/tree/master/examples/console-variables.py>`_\n\nCustom console commands\n~~~~~~~~~~~~~~~~~~~~~~~\n\n``aiomonitor`` is very easy to extend with your own console commands.\nRefer `the extension example code <https://github.com/achimnol/aiomonitor-ng/tree/master/examples/extension.py>`_\n\nRequirements\n------------\n\n* Python_ 3.8+ (3.10.7+ recommended)\n* aioconsole_\n* Click_\n* prompt_toolkit_\n* uvloop_ (optional)\n\n\n.. _PEP492: https://www.python.org/dev/peps/pep-0492/\n.. _Python: https://www.python.org\n.. _aioconsole: https://github.com/vxgmichel/aioconsole\n.. _aiohttp: https://github.com/aio-libs/aiohttp\n.. _asyncio: http://docs.python.org/3/library/asyncio.html\n.. _Click: https://click.palletsprojects.com\n.. _curio: https://github.com/dabeaz/curio\n.. _prompt_toolkit: https://python-prompt-toolkit.readthedocs.io\n.. _uvloop: https://github.com/MagicStack/uvloop\n.. _cmd: http://docs.python.org/3/library/cmd.html\n\nCHANGES\n=======\n\n0.7.0 (2022-10-19)\n------------------\n\n* Selective persistent termination logs (#9)\n\n* Implement cancellation chain tracker (#8)\n\n* Trigger auto-completion only when Tab is pressed\n\n* Support auto-completion of commands and arguments (#7)\n\n* Add missing explicit dependency to Click\n\n\n0.6.0 (2022-09-26)\n------------------\n\n* Promote `console_locals` as public attr\n\n* Reimplement console command (#6)\n\n* Migrate to Click-based command line interface (#5)\n\n* Adopt `prompt_toolkit` and support concurrent clients (#4)\n\n* Show the total number of tasks when executing `ps` (#3)\n\n* Apply black, isort, mypy, flake8 and automate CI workflows using GitHub Actions\n\n\n0.5.1 (2022-08-29)\n------------------\n\n* Fix the task creation location in the 'ps' command output\n\n0.5.0 (2022-08-26)\n------------------\n\n* Made it compatible with Python 3.10\n\n* Added the task creation stack chain display to the 'where' command by setting a custom task factory (#1)\n\n* Changed the 'ps' command view to be more concise and display many tasks in a better way (#2)\n\n\n0.4.5 (2019-11-03)\n------------------\n\n* Fixed endless loop on EOF (thanks @apatrushev)\n\n\n0.4.4 (2019-03-23)\n------------------\n\n* Simplified python console start end #175\n\n* Added python 3.7 compatibility #176\n\n\n0.4.3 (2019-02-02)\n------------------\n\n* Reworked console server start/close logic #169\n\n\n0.4.2 (2019-01-13)\n------------------\n\n* Fixed issue with type annotations from 0.4.1 release #164\n\n\n0.4.1 (2019-01-10)\n------------------\n\n* Fixed Python 3.5 support #161 (thanks @bmerry)\n\n\n0.4.0 (2019-01-04)\n------------------\n\n* Added support for custom commands #133 (thanks @yggdr)\n\n* Fixed OptLocals being passed as the default value for \"locals\" #122 (thanks @agronholm)\n\n* Added an API inspired by the standard library's cmd module #135 (thanks @yggdr)\n\n* Correctly report the port running aioconsole #124 (thanks @bmerry)\n\n\n0.3.1 (2018-07-03)\n------------------\n\n* Added the stacktrace command #120 (thanks @agronholm)\n\n\n0.3.0 (2017-09-08)\n------------------\n\n* Added _locals_ parameter for passing environment to python REPL\n\n\n0.2.1 (2016-01-03)\n------------------\n\n* Fixed import in telnet cli in #12 (thanks @hellysmile)\n\n\n0.2.0 (2016-01-01)\n------------------\n\n* Added basic documentation\n\n* Most of methods of Monitor class are not not private api\n\n\n0.1.0 (2016-12-14)\n------------------\n\n* Added missed LICENSE file\n\n* Updated API, added start_monitor() function\n\n\n0.0.3 (2016-12-11)\n------------------\n\n* Fixed README.rst\n\n\n0.0.2 (2016-12-11)\n------------------\n\n* Tests more stable now\n\n* Added simple tutorial to README.rst\n\n\n0.0.1 (2016-12-10)\n------------------\n\n* Initial release.\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "aiomonitor-ng adds monitor and python REPL capabilities for asyncio application",
"version": "0.7.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "3eefd3f9f4495ce309f7ec6f73603167",
"sha256": "9f159c1ac9bd0d103095ff03fa2020d5e3f46764d402ffc7fab6b7614235428d"
},
"downloads": -1,
"filename": "aiomonitor_ng-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3eefd3f9f4495ce309f7ec6f73603167",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25808,
"upload_time": "2022-10-19T08:30:23",
"upload_time_iso_8601": "2022-10-19T08:30:23.407349Z",
"url": "https://files.pythonhosted.org/packages/6c/b8/6555a292bd744e8ab8aae36005925ff67783dc69c2c873255c867bc0fb68/aiomonitor_ng-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "64fe17b2ce4b5fad7e16726d1d50a4e2",
"sha256": "8dcf63e60779da45e967077e82a41d3b352bafee4326e11f02ebd4d71e5b1f73"
},
"downloads": -1,
"filename": "aiomonitor-ng-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "64fe17b2ce4b5fad7e16726d1d50a4e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26700,
"upload_time": "2022-10-19T08:30:25",
"upload_time_iso_8601": "2022-10-19T08:30:25.512949Z",
"url": "https://files.pythonhosted.org/packages/fb/18/05c571cdcc5c6b8d8be0d4023dd592831fcdce432e2381b88146a3b49d50/aiomonitor-ng-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-10-19 08:30:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "achimnol",
"github_project": "aiomonitor-ng",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "aiomonitor-ng"
}
JSON
