Aiohost

Simple python library to async use https://check-host.net/about/api

Features

• Fully Asynchronous: Built on top of httpx for non-blocking I/O.
• Zero Boilerplate: No client initialization required. Just a single function call.
• Auto-Polling: Automatically waits for all nodes to complete the check and returns the final result.
• Foolproof: Strict input validation for types, ports, and check types.

Installation

Install via pip:

pip install aiohost

Or using uv:

uv add aiohost

Usage

Basic Check

The simplest way to check a host. The function will automatically initiate the check, poll the API, and return the final result.

import asyncio
from aiohost import check


async def main():
    # Check TCP port 443 on google.com using 3 random nodes
    result = await check("tcp", "google.com", port=443, max_nodes=3)
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

Advanced Check (Specific Nodes)

You can specify exact nodes to use for the check.

import asyncio
from aiohost import check


async def main():
    result = await check(
        check_type="ping",
        host="1.1.1.1",
        max_nodes=2,
        nodes=["us1.node.check-host.net", "de1.node.check-host.net"],
    )
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

Error Handling

The library raises standard Python exceptions for invalid inputs or API errors.

import asyncio
from aiohost import check


async def main():
    try:
        # This will raise a ValueError due to invalid port
        await check("tcp", "google.com", port=99999)
    except ValueError as e:
        print(f"Validation Error: {e}")
    except RuntimeError as e:
        print(f"API Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())

API Reference

check

Initiates a check and returns the final result dictionary.

async def check(
    check_type: Literal["ping", "http", "tcp", "dns", "udp"],
    host: str,
    port: Optional[int] = None,
    max_nodes: int = 3,
    max_wait: float = 30.0,
    poll_interval: float = 1.5,
    nodes: Optional[List[str]] = None,
) -> Dict[str, Any]

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.