gatenet.diagnostics package

Submodules

gatenet.diagnostics.bandwidth module

bandwidth.py

Bandwidth measurement utilities for gatenet.

This module provides functions to measure upload and download bandwidth to a target host using TCP sockets.

Example

from gatenet.diagnostics.bandwidth import measure_bandwidth result = measure_bandwidth(“example.com”, port=5201) print(result)

gatenet.diagnostics.bandwidth.measure_bandwidth(host, port=5201, duration=5.0, payload_size=65536, direction='download')

Example

>>> from gatenet.diagnostics.bandwidth import measure_bandwidth
>>> result = measure_bandwidth("example.com", port=5201, duration=2.0)
>>> print(result)
{'bandwidth_mbps': 94.2, 'bytes_transferred': 2359296, 'duration': 2.0}
Measure bandwidth to a target host using TCP sockets.

Parameters:

• host (str) – Target host to connect to.

• port (int, optional) – Target port (default: 5201).

• duration (float, optional) – Duration of the test in seconds (default: 5.0).

• payload_size (int, optional) – Size of each payload in bytes (default: 65536).

• direction ({"download", "upload"}, optional) – Direction of measurement (default: “download”).

Returns:

Dictionary with keys ‘bandwidth_mbps’, ‘bytes_transferred’, and ‘duration’.

Return type:

dict

Notes

This function requires a bandwidth server (e.g., iperf3) running on the target host.

gatenet.diagnostics.dns module

gatenet.diagnostics.dns.dns_lookup(hostname)

Example

>>> from gatenet.diagnostics.dns import dns_lookup
>>> dns_lookup("google.com")
'8.8.8.8'
Perform a DNS lookup for a given hostname.

Parameters:

hostname (str) – The hostname to look up.

Return type:

str

Returns:

The IP address associated with the hostname, or ‘Unknown’ if not found.

gatenet.diagnostics.dns.reverse_dns_lookup(ip)

Example

>>> from gatenet.diagnostics.dns import reverse_dns_lookup
>>> reverse_dns_lookup("8.8.8.8")
'dns.google'
Perform a reverse DNS lookup for a given IP address.

Parameters:

ip (str) – The IP address to look up.

Return type:

str

Returns:

The hostname associated with the IP address, or ‘Unknown’ if not found.

gatenet.diagnostics.geo module

gatenet.diagnostics.geo.get_geo_info(ip)

Example

>>> from gatenet.diagnostics.geo import get_geo_info
>>> get_geo_info("8.8.8.8")
{'status': 'success', 'country': 'United States', ...}
Get geographical information for a given IP address using the ip-api.com service.

Parameters:

ip (str) – The IP address to look up.

Returns:

A dictionary containing geographical information. Example:

{
    'status': 'success',
    'country': 'United States',
    'regionName': 'California',
    'city': 'Mountain View',
    ...
}

If an error occurs, returns a dict with ‘error’ and ‘message’ keys.

Return type:

dict

gatenet.diagnostics.ping module

async gatenet.diagnostics.ping.async_ping(host, count=4, method='icmp')

Asynchronously ping a host and return detailed latency statistics, including jitter and all RTTs.

Return type:

Dict[str, Union[str, float, int, bool, list]]

Example

>>> from gatenet.diagnostics.ping import async_ping
>>> import asyncio
>>> result = asyncio.run(async_ping("google.com", count=5, method="icmp"))
>>> print(result["rtt_avg"])

gatenet.diagnostics.ping.ping(host, count=4, timeout=2, method='icmp')

Ping a host and return detailed latency statistics, including jitter and all RTTs.

Return type:

Dict[str, Union[str, float, int, bool, list]]

Example

>>> from gatenet.diagnostics.ping import ping
>>> result = ping("google.com", count=5, method="icmp")
>>> print(result["rtt_avg"])

gatenet.diagnostics.ping.ping_with_rf(host, radio=None, count=4, timeout=2, method='icmp')

Ping a host with optional RF signal logging (stub implementation).

This is a compatibility function that performs a regular ping and adds an empty RF field for future radio functionality integration.

Parameters:

• host (str) – Host to ping

• radio – Radio instance (currently unused - for future implementation)

• count (int) – Number of pings

• timeout (int) – Timeout per ping

• method (str) – Ping method

Returns:

Ping results with an empty ‘rf’ field for compatibility

Return type:

dict

Example

>>> from gatenet.diagnostics.ping import ping_with_rf
>>> result = ping_with_rf("8.8.8.8", count=2)
>>> assert "rf" in result

gatenet.diagnostics.port_scan module

async gatenet.diagnostics.port_scan.check_port(host, port)

Asynchronously check if a TCP port is open on a given host.

Return type:

Tuple[int, bool]

Example

>>> import asyncio
>>> from gatenet.diagnostics.port_scan import check_port
>>> asyncio.run(check_port("localhost", 22))
(22, False)

gatenet.diagnostics.port_scan.check_public_port(host='1.1.1.1', port=53, timeout=2.0)

Check if a TCP port is publicly reachable.

Return type:

bool

Example

>>> from gatenet.diagnostics.port_scan import check_public_port
>>> check_public_port("1.1.1.1", 53)
True

gatenet.diagnostics.port_scan.scan_ports(host, ports=[21, 22, 23, 25, 53, 80, 110, 143, 443, 3306, 8080, 8443, 9000, 27017], timeout=2.0)

Scan a list of ports on a given host to check if they are open.

Return type:

List[Tuple[int, bool]]

Example

>>> from gatenet.diagnostics.port_scan import scan_ports
>>> scan_ports("localhost", ports=[22, 80, 443])
[(22, False), (80, True), (443, True)]

async gatenet.diagnostics.port_scan.scan_ports_async(host, ports=[21, 22, 23, 25, 53, 80, 110, 143, 443, 3306, 8080, 8443, 9000, 27017])

Asynchronously scan a list of ports on a given host.

Return type:

List[Tuple[int, bool]]

Example

>>> import asyncio
>>> from gatenet.diagnostics.port_scan import scan_ports_async
>>> asyncio.run(scan_ports_async("localhost", ports=[22, 80]))
[(22, False), (80, True)]

gatenet.diagnostics.traceroute module

gatenet.diagnostics.traceroute.traceroute(host, max_hops=30, timeout=2.0, protocol='udp', print_output=True)

Perform a traceroute to the given host using UDP or ICMP.

Return type:

List[dict]

Example

>>> from gatenet.diagnostics.traceroute import traceroute
>>> hops = traceroute("google.com", protocol="udp", print_output=False)
>>> for hop in hops:
...     print(hop)
{'hop': 1, 'ip': '192.168.1.1', 'hostname': 'router.local', 'rtt_ms': 2.34}

Module contents

Gatenet diagnostics module.

Provides networking diagnostic tools including ping, traceroute, DNS lookups, port scanning, geolocation, and bandwidth testing.

async gatenet.diagnostics.async_ping(host, count=4, method='icmp')

Asynchronously ping a host and return detailed latency statistics, including jitter and all RTTs.

Return type:

Dict[str, Union[str, float, int, bool, list]]

Example

>>> from gatenet.diagnostics.ping import async_ping
>>> import asyncio
>>> result = asyncio.run(async_ping("google.com", count=5, method="icmp"))
>>> print(result["rtt_avg"])

async gatenet.diagnostics.check_port(host, port)

Asynchronously check if a TCP port is open on a given host.

Return type:

Tuple[int, bool]

Example

>>> import asyncio
>>> from gatenet.diagnostics.port_scan import check_port
>>> asyncio.run(check_port("localhost", 22))
(22, False)

gatenet.diagnostics.check_public_port(host='1.1.1.1', port=53, timeout=2.0)

Check if a TCP port is publicly reachable.

Return type:

bool

Example

>>> from gatenet.diagnostics.port_scan import check_public_port
>>> check_public_port("1.1.1.1", 53)
True

gatenet.diagnostics.dns_lookup(hostname)

Example

>>> from gatenet.diagnostics.dns import dns_lookup
>>> dns_lookup("google.com")
'8.8.8.8'
Perform a DNS lookup for a given hostname.

Parameters:

hostname (str) – The hostname to look up.

Return type:

str

Returns:

The IP address associated with the hostname, or ‘Unknown’ if not found.

gatenet.diagnostics.get_geo_info(ip)

Example

>>> from gatenet.diagnostics.geo import get_geo_info
>>> get_geo_info("8.8.8.8")
{'status': 'success', 'country': 'United States', ...}
Get geographical information for a given IP address using the ip-api.com service.

Parameters:

ip (str) – The IP address to look up.

Returns:

A dictionary containing geographical information. Example:

{
    'status': 'success',
    'country': 'United States',
    'regionName': 'California',
    'city': 'Mountain View',
    ...
}

If an error occurs, returns a dict with ‘error’ and ‘message’ keys.

Return type:

dict

gatenet.diagnostics.measure_bandwidth(host, port=5201, duration=5.0, payload_size=65536, direction='download')

Example

>>> from gatenet.diagnostics.bandwidth import measure_bandwidth
>>> result = measure_bandwidth("example.com", port=5201, duration=2.0)
>>> print(result)
{'bandwidth_mbps': 94.2, 'bytes_transferred': 2359296, 'duration': 2.0}
Measure bandwidth to a target host using TCP sockets.

Parameters:

• host (str) – Target host to connect to.

• port (int, optional) – Target port (default: 5201).

• duration (float, optional) – Duration of the test in seconds (default: 5.0).

• payload_size (int, optional) – Size of each payload in bytes (default: 65536).

• direction ({"download", "upload"}, optional) – Direction of measurement (default: “download”).

Returns:

Dictionary with keys ‘bandwidth_mbps’, ‘bytes_transferred’, and ‘duration’.

Return type:

dict

Notes

This function requires a bandwidth server (e.g., iperf3) running on the target host.

gatenet.diagnostics.ping(host, count=4, timeout=2, method='icmp')

Ping a host and return detailed latency statistics, including jitter and all RTTs.

Return type:

Dict[str, Union[str, float, int, bool, list]]

Example

>>> from gatenet.diagnostics.ping import ping
>>> result = ping("google.com", count=5, method="icmp")
>>> print(result["rtt_avg"])

gatenet.diagnostics.ping_with_rf(host, radio=None, count=4, timeout=2, method='icmp')

Ping a host with optional RF signal logging (stub implementation).

This is a compatibility function that performs a regular ping and adds an empty RF field for future radio functionality integration.

Parameters:

• host (str) – Host to ping

• radio – Radio instance (currently unused - for future implementation)

• count (int) – Number of pings

• timeout (int) – Timeout per ping

• method (str) – Ping method

Returns:

Ping results with an empty ‘rf’ field for compatibility

Return type:

dict

Example

>>> from gatenet.diagnostics.ping import ping_with_rf
>>> result = ping_with_rf("8.8.8.8", count=2)
>>> assert "rf" in result

gatenet.diagnostics.reverse_dns_lookup(ip)

Example

>>> from gatenet.diagnostics.dns import reverse_dns_lookup
>>> reverse_dns_lookup("8.8.8.8")
'dns.google'
Perform a reverse DNS lookup for a given IP address.

Parameters:

ip (str) – The IP address to look up.

Return type:

str

Returns:

The hostname associated with the IP address, or ‘Unknown’ if not found.

gatenet.diagnostics.scan_ports(host, ports=[21, 22, 23, 25, 53, 80, 110, 143, 443, 3306, 8080, 8443, 9000, 27017], timeout=2.0)

Scan a list of ports on a given host to check if they are open.

Return type:

List[Tuple[int, bool]]

Example

>>> from gatenet.diagnostics.port_scan import scan_ports
>>> scan_ports("localhost", ports=[22, 80, 443])
[(22, False), (80, True), (443, True)]

async gatenet.diagnostics.scan_ports_async(host, ports=[21, 22, 23, 25, 53, 80, 110, 143, 443, 3306, 8080, 8443, 9000, 27017])

Asynchronously scan a list of ports on a given host.

Return type:

List[Tuple[int, bool]]

Example

>>> import asyncio
>>> from gatenet.diagnostics.port_scan import scan_ports_async
>>> asyncio.run(scan_ports_async("localhost", ports=[22, 80]))
[(22, False), (80, True)]

gatenet.diagnostics.traceroute(host, max_hops=30, timeout=2.0, protocol='udp', print_output=True)

Perform a traceroute to the given host using UDP or ICMP.

Return type:

List[dict]

Example

>>> from gatenet.diagnostics.traceroute import traceroute
>>> hops = traceroute("google.com", protocol="udp", print_output=False)
>>> for hop in hops:
...     print(hop)
{'hop': 1, 'ip': '192.168.1.1', 'hostname': 'router.local', 'rtt_ms': 2.34}