Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.340s · 43.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.3s · import 1.236s · 46MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
aiomonitor
✓ import aiomonitor
start_monitor
✓ from aiomonitor import start_monitor
This quickstart demonstrates how to integrate `aiomonitor` into an asyncio application using its context manager interface. It starts a background worker task and keeps the main loop running. Once executed, you can connect via `telnet localhost 20101` or access the web UI at `http://localhost:20102` to inspect and interact with the running application.
import asyncio
import aiomonitor
async def worker():
print("Worker started...")
try:
await asyncio.sleep(100) # Simulate a long-running task
except asyncio.CancelledError:
print("Worker cancelled!")
finally:
print("Worker finished.")
async def main():
loop = asyncio.get_running_loop()
# start_monitor automatically starts telnet (20101) and web (20102) interfaces
with aiomonitor.start_monitor(loop=loop):
print("aiomonitor started. Connect via telnet localhost 20101 or browser http://localhost:20102")
task = loop.create_task(worker())
# Keep the main loop running indefinitely
await asyncio.Event().wait()
# The task might be cancelled from the monitor, so await it for cleanup
await task
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Application gracefully stopped.")
aiomonitor --version
Debug
Known issues
breakingPython 3.8 support was dropped in version 0.7.1. aiomonitor now requires Python 3.9 or higher.fixUpgrade your Python environment to 3.9+ or pin aiomonitor to <0.7.1.
affects: >=0.7.1
breakingSince version 0.5.0, connecting to the aiomonitor's REPL requires a proper telnet client (e.g., `telnetlib3` or the included `python -m aiomonitor.cli`). Simple socket-to-console redirectors like `nc` will no longer provide advanced features like auto-completion.fixUse `python -m aiomonitor.cli` or a compatible telnet client when connecting to the monitor.
affects: >=0.5.0
breakingThe default port numbers for the terminal UI, web UI, and console access changed in version 0.6.0. The telnet interface moved from 50101 to 20101 and the web UI from 50201 to 20102.fixUpdate your connection commands to use the new default ports: `telnet localhost 20101` and `http://localhost:20102` for the web UI.
affects: >=0.6.0
deprecatedThe `loop` argument for `asyncio.get_event_loop()` is deprecated in Python 3.10+ and should be replaced with `asyncio.get_running_loop()` if an event loop is already running. While `aiomonitor.start_monitor` still accepts a `loop` argument, it's often preferred to rely on `asyncio.get_running_loop()` implicitly within `asyncio.run()` contexts or pass `None` to `start_monitor` if a loop is already set.fixUse `loop = asyncio.get_running_loop()` to explicitly get the current loop, or consider if the `loop` argument to `start_monitor` can be omitted if a running loop is guaranteed.
affects: All versions, especially with Python >=3.10
gotchaUsers on Windows might encounter issues with `reuse_port` not being supported by the socket module when using `aiomonitor`, particularly with alternative event loops like `winloop`.fixCheck for official recommendations regarding Windows compatibility or consider alternative deployment environments if `reuse_port` conflicts arise.
affects: All versions on Windows
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiomonitor'
The 'aiomonitor' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install aiomonitor'.
ImportError: cannot import name 'start_monitor' from 'aiomonitor'
The 'start_monitor' function is not available in the 'aiomonitor' module, possibly due to an outdated version.
fixEnsure you have the latest version of 'aiomonitor' installed: 'pip install --upgrade aiomonitor'.
TypeError: start_monitor() missing 1 required positional argument: 'loop'
The 'start_monitor' function requires the 'loop' argument to be specified.
fixPass the event loop to 'start_monitor': 'with aiomonitor.start_monitor(loop=asyncio.get_event_loop()):'.
OSError: [Errno 98] Address already in use
The default port used by 'aiomonitor' is already occupied by another process.
fixSpecify a different port when starting the monitor: 'with aiomonitor.start_monitor(loop=loop, port=20102):'.
AttributeError: module 'aiomonitor' has no attribute 'Monitor'
The 'Monitor' class is not directly accessible from the 'aiomonitor' module.
fixUse the 'start_monitor' function instead: 'with aiomonitor.start_monitor(loop=loop):'.
Upgrade
Version history
0.7.1latest on PyPI · released Nov 11, 2024
Audit
Dependencies
aioconsolerequiredProvides the Python REPL capabilities.
aiohttprequiredUsed for the optional web-based UI.
telnetlib3requiredReplaced the deprecated telnet module for robust telnet client support since v0.7.1.
clickrequiredUsed for defining custom commands for the monitor CLI.