Aiohost
Simple python library to async use https://check-host.net/about/api
Features
- Fully Asynchronous: Built on top of
httpxfor 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]
| Parameter | Type | Default | Description |
|---|---|---|---|
check_type |
str |
Required | Type of check: "ping", "http", "tcp", "dns", or "udp". |
host |
str |
Required | Target hostname or IP address. |
port |
int |
None |
Target port (required for tcp/udp, optional for others). Must be 1-65535. |
max_nodes |
int |
3 |
Number of random nodes to use for the check. |
max_wait |
float |
30.0 |
Maximum time in seconds to wait for all nodes to finish. |
poll_interval |
float |
1.5 |
Time in seconds between polling the API for results. |
nodes |
List[str] |
None |
Optional list of specific node hostnames to use (overrides max_nodes). |
License
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
Metadata
Release files for aiohost 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiohost-1.0.0.tar.gz | 29.1 kB | Without provenance | Details for aiohost-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiohost-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for aiohost-1.0.0-py3-none-any.whl |
Total release size: 45.5 kB
Release files / aiohost-1.0.0.tar.gz
| Download URL | aiohost-1.0.0.tar.gz |
|---|---|
| Size | 29.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
573dfbaa86e42d6381c9ca06dbfb2695d847912393e3a4e8a921e61d95382868
|
|
BLAKE2b-256 checksum How to use checksums |
0f2afed09520f9d5d65a92dfe1f3b158bfea893ad2ad14666b35e807cbc5626c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / aiohost-1.0.0-py3-none-any.whl
| Download URL | aiohost-1.0.0-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
edd282a0d3db661afc8919c81aa2c672325e551ca9630e0c06209cb9e1836484
|
|
BLAKE2b-256 checksum How to use checksums |
42b1bb4b987bb1ebba025af0ad8357e9031464d1cc674abb074e2684ea3485d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for aiohost 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.