{"id":13617298,"url":"https://github.com/aio-libs/aiomonitor","last_synced_at":"2025-04-14T06:33:25.791Z","repository":{"id":41967585,"uuid":"75670021","full_name":"aio-libs/aiomonitor","owner":"aio-libs","description":"aiomonitor is module that adds monitor and python REPL capabilities for asyncio application","archived":false,"fork":false,"pushed_at":"2025-04-07T16:25:24.000Z","size":5355,"stargazers_count":690,"open_issues_count":17,"forks_count":43,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-07T17:35:17.677Z","etag":null,"topics":["async-await","asyncio","mypy","uvloop"],"latest_commit_sha":null,"homepage":"https://aiomonitor.aio-libs.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aio-libs.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-05T21:58:16.000Z","updated_at":"2025-04-05T14:59:33.000Z","dependencies_parsed_at":"2024-01-17T00:54:10.732Z","dependency_job_id":"9c93fea7-4041-47eb-9ea1-dcba0449fdcf","html_url":"https://github.com/aio-libs/aiomonitor","commit_stats":{"total_commits":336,"total_committers":20,"mean_commits":16.8,"dds":0.6071428571428572,"last_synced_commit":"1b04ff82f22e35a77b4a96def09dff237c001c55"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aio-libs%2Faiomonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aio-libs%2Faiomonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aio-libs%2Faiomonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aio-libs%2Faiomonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aio-libs","download_url":"https://codeload.github.com/aio-libs/aiomonitor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248834774,"owners_count":21169087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async-await","asyncio","mypy","uvloop"],"created_at":"2024-08-01T20:01:39.675Z","updated_at":"2025-04-14T06:33:25.781Z","avatar_url":"https://github.com/aio-libs.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"aiomonitor\n==========\n\n.. image:: https://github.com/aio-libs/aiomonitor/workflows/CI/badge.svg\n   :target: https://github.com/aio-libs/aiomonitor/actions?query=workflow%3ACI\n   :alt: GitHub Actions status for the main branch\n\n.. image:: https://codecov.io/gh/aio-libs/aiomonitor/branch/main/graph/badge.svg\n   :target: https://codecov.io/gh/aio-libs/aiomonitor\n   :alt: codecov.io status for the main branch\n\n.. image:: https://badge.fury.io/py/aiomonitor.svg\n   :target: https://pypi.org/project/aiomonitor\n   :alt: Latest PyPI package version\n\n.. image:: https://img.shields.io/pypi/dm/aiomonitor\n   :target: https://pypistats.org/packages/aiomonitor\n   :alt: Downloads count\n\n.. image:: https://readthedocs.org/projects/aiomonitor-ng/badge/?version=latest\n   :target: https://aiomonitor.aio-libs.org/en/latest/?badge=latest\n   :alt: Documentation Status\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/aio-libs/aiomonitor/main/docs/screenshot-ps-where-example.png\n   :alt: An example to run the aiomonitor shell\n\nInstallation\n------------\nInstallation process is simple, just::\n\n    $ pip install aiomonitor\n\n\nExample\n-------\nMonitor has context manager interface:\n\n.. code:: python\n\n    import asyncio\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 20101\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        print('Start sleeping')\n        await asyncio.sleep(100)\n        return web.Response(text=\"Simple answer\")\n\n    loop = asyncio.get_event_loop()\n    # create application and register route\n    app = web.Application()\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, loop=loop)\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 20101\n    Asyncio Monitor: 1 tasks running\n    Type help for commands\n    monitor \u003e\u003e\u003e\n\nNow you can type commands, for instance, ``help``::\n\n    monitor \u003e\u003e\u003e 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      ps-terminated (pst,pt)  List recently terminated/cancelled tasks\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 the task creation chain of a task\n      where-terminated (wt)   Show stack frames and the termination/cancellation 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 \u003e\u003e\u003e 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    \u003e\u003e\u003e await asyncio.sleep(1, result=3)\n    3\n    \u003e\u003e\u003e\n\nTo leave the console type ``exit()`` or press Ctrl+D::\n\n    \u003e\u003e\u003e exit()\n\n    ✓ The console session is closed.\n    monitor \u003e\u003e\u003e\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 \u003chttps://github.com/aio-libs/aiomonitor/tree/main/examples/console-variables.py\u003e`_\n\nCustom console commands\n~~~~~~~~~~~~~~~~~~~~~~~\n\n``aiomonitor`` is very easy to extend with your own console commands.\nRefer `the extension example code \u003chttps://github.com/aio-libs/aiomonitor/tree/main/examples/extension.py\u003e`_\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faio-libs%2Faiomonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faio-libs%2Faiomonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faio-libs%2Faiomonitor/lists"}