nettool

Author: Jacek ‘Szumak’ Kotlarski –<szumak@virthost.pl> Created: 2025-08-29

Purpose: Provide helpers for IPv4/IPv6 reachability checks, traceroute and host validation utilities used by NetTool modules.

This module aggregates lightweight wrappers around ping, traceroute and socket.getaddrinfo, exposing a consistent API across supported platforms.

class jsktoolbox.nettool.Pinger(timeout=1)[source]

Bases: BData

Ping remote IPv4 hosts using available system utilities.

Parameters:

timeout (int)

__init__(timeout=1)[source]

Initialise pinger configuration.

### Arguments: * timeout: int - Timeout in seconds applied to the selected system command.

### Returns: None - Constructor.

### Raises: * TypeError: Propagated from BData._set_data when invalid timeout type is provided.

Parameters:

timeout (int)

Return type:

None

is_alive(ip)[source]

Check whether the target host responds to ICMP echo.

### Arguments: * ip: str - IPv4 address to probe.

### Returns: bool - True when the remote host replies successfully.

### Raises: * ChildProcessError: Raised when no suitable ping command is available.

Parameters:

ip (str)

Return type:

bool

__setattr__(name, value)

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:
Return type:

None

class jsktoolbox.nettool.Tracert[source]

Bases: BData

Execute traceroute commands against IPv4 destinations.

__init__()[source]

Initialise traceroute command definitions.

### Returns: None - Constructor populates command candidates.

Return type:

None

execute(ip)[source]

Run traceroute against the provided IPv4 address.

### Arguments: * ip: str - Destination IPv4 address to trace.

### Returns: List[str] - Lines captured from traceroute output.

### Raises: * ChildProcessError: Raised when no traceroute utility is available.

Parameters:

ip (str)

Return type:

List[str]

__setattr__(name, value)

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:
Return type:

None

class jsktoolbox.nettool.HostResolvableChecker[source]

Bases: NoDynamicAttributes

Utility helpers for validating and resolving host identifiers.

static is_resolvable(host)[source]

Check whether DNS can resolve the provided host.

### Arguments: * host: str - Hostname or IP literal to inspect.

### Returns: bool - True when socket.getaddrinfo resolves the host.

Parameters:

host (str)

Return type:

bool

static is_ip_address(host)[source]

Check if the supplied host represents an IPv4 or IPv6 address.

### Arguments: * host: str - Hostname or IP literal to inspect.

### Returns: bool - True when the string parses into either Address or Address6.

Parameters:

host (str)

Return type:

bool

static is_hostname(host)[source]

Validate whether the string matches hostname conventions.

### Arguments: * host: str - Hostname or IP literal to inspect.

### Returns: bool - True when the string satisfies hostname formatting rules.

Parameters:

host (str)

Return type:

bool

static validate_host(host)[source]

Verify whether the host is a valid IP address or resolvable hostname.

### Arguments: * host: str - Hostname or IP literal to validate.

### Returns: Optional[str] - None when valid, otherwise an explanatory error message.

Parameters:

host (str)

Return type:

str | None

static ip_from_hostname(hostname)[source]

Return the first IP resolved for a hostname.

### Arguments: * hostname: str - Hostname to resolve using system DNS.

### Returns: Optional[str] - First resolved address string or None when resolution fails.

Parameters:

hostname (str)

Return type:

str | None

static validate_hosts(hosts)[source]

Validate multiple hosts in bulk.

### Arguments: * hosts: List[str] - Collection of hostnames or IP literals to validate.

### Returns: Dict[str, Optional[str]] - Mapping of host strings to validation errors or None.

Parameters:

hosts (List[str])

Return type:

Dict[str, str | None]

static filter_valid_hosts(hosts)[source]

Return only valid hosts from the provided sequence.

### Arguments: * hosts: List[str] - Hostnames or IP literals to inspect.

### Returns: List[str] - Subset containing only valid hosts.

Parameters:

hosts (List[str])

Return type:

List[str]

static filter_invalid_hosts(hosts)[source]

Return invalid hosts with diagnostic messages.

### Arguments: * hosts: List[str] - Hostnames or IP literals to inspect.

### Returns: Dict[str, str] - Mapping of invalid host strings to error explanations.

Parameters:

hosts (List[str])

Return type:

Dict[str, str]

static ip4_from_hostname(hostname)[source]

Resolve the first IPv4 address for the hostname.

### Arguments: * hostname: str - Hostname to resolve as IPv4.

### Returns: Optional[Address] - First IPv4 Address instance or None when resolution fails.

Parameters:

hostname (str)

Return type:

Address | None

static ip6_from_hostname(hostname)[source]

Resolve the first IPv6 address for the hostname.

### Arguments: * hostname: str - Hostname to resolve as IPv6.

### Returns: Optional[Address6] - First IPv6 Address6 instance or None when resolution fails.

Parameters:

hostname (str)

Return type:

Address6 | None

__setattr__(name, value)

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:
Return type:

None