hbutils.system.network.telnet_

Network connectivity helpers for port availability checks.

This module provides lightweight, telnet-like connectivity checks to determine whether a TCP port is open and accepting connections. It also provides a polling utility to wait for a port to become available within a specified timeout.

The module contains the following main components:

• telnet() - Check connectivity to a TCP host and port.

• wait_for_port_online() - Poll a host and port until it becomes available.

Note

These utilities establish a TCP connection only. They do not perform any protocol-level handshake beyond the TCP connect operation.

Example:

>>> from hbutils.system.network.telnet_ import telnet, wait_for_port_online
>>> telnet('127.0.0.1', 8080, timeout=1.0)
False
>>> wait_for_port_online('127.0.0.1', 8080, timeout=5.0, interval=0.5)

__all__

hbutils.system.network.telnet_.__all__ = ['telnet', 'wait_for_port_online']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

telnet

hbutils.system.network.telnet_.telnet(host: str, port: int, timeout: float = 5.0) → bool

Attempt to connect to a TCP host and port.

This function performs a TCP connection attempt, similar to a telnet check, and returns whether the connection was successfully established within the provided timeout.

Parameters:

• host (str) – Host address to connect to, for example "127.0.0.1".

• port (int) – TCP port number to test, for example 8080.

• timeout (float) – Maximum timeout duration in seconds, defaults to 5.0.

Returns:

True if the port is online and responding, False otherwise.

Return type:

bool

Raises:

OSError – For unexpected socket errors not related to refusal or timeout.

Note

This function only checks for the ability to establish a TCP connection. It does not validate application-level protocols.

Example:

>>> telnet('127.0.0.1', 8080, timeout=3.0)
True
>>> telnet('127.0.0.1', 9999, timeout=1.0)
False

wait_for_port_online

hbutils.system.network.telnet_.wait_for_port_online(host: str, port: int, timeout: float | None = 5, interval: float = 0.3) → None

Wait until a TCP port becomes available.

This function repeatedly calls telnet() at a fixed interval until the target port is online or the timeout is reached.

Parameters:

• host (str) – Host address to connect to, for example "127.0.0.1".

• port (int) – TCP port number to test, for example 8080.

• timeout (Optional[float]) – Maximum timeout duration in seconds. None means wait indefinitely, defaults to 5.

• interval (float) – Time interval between consecutive checks in seconds, defaults to 0.3.

Returns:

None. The function returns when the port is online.

Return type:

None

Raises:

TimeoutError – If the timeout is reached and the port is still offline.

Example:

>>> wait_for_port_online('127.0.0.1', 8080, timeout=10, interval=0.5)
>>> wait_for_port_online('localhost', 3306, timeout=None)