gufo.ping

Gufo Ping is the accelerated Python asyncio IPv4/IPv6 ping implementation.

Attributes:

Name	Type	Description
__version__	str	Current version.

Ping

Bases: object

High-performance asyncronous ICMPv4/ICMPv6 ping client.

Parameters:

Name	Type	Description	Default
policy	SelectionPolicy	Probe selection policy.	RAW
size	int	Set outgoing packet's size, including IP header.	64
src_addr	None | str | Iterable[str]	Set source address for outgoing packets. Depends upon address family. May be one of: * None - detect source address automatically. * str - containing source address for one address family. * Iterable of strings, containing multiple addresses which to be distributed among the address families. First address for given address family will be used.	None
ttl	int | None	Set outgoing packet's TTL. Use OS defaults when empty. Warning This option is ignored on IPv6 socket due to issue #4	None
tos	int | None	Set DSCP/TOS/TCLASS field to outgoing packets. Use OS defaults when empty. Warning This option is ignored on IPv6 socket due to issue #2	None
timeout	float	Default timeout in seconds.	1.0
send_buffer_size	int | None	Send buffer size. Use OS defaults when empty.	None
recv_buffer_size	int | None	Receive buffer size. Use OS defaults when empty.	None
coarse	bool	Use CLOCK_MONOTONIC_COARSE when set, fall back to CLOCK_MONOTONIC otherwise.	False

Note

Opening the Raw Socket may require super-user priveleges or additional permissions. Refer to the operation system's documentation for details.

Example

Ping single packet.

from gufo.ping import Ping

async def ping(address):
    p = Ping()
    rtt = await p.ping(address)
    print(rtt)

Ping multiple packets.

from gufo.ping import Ping

async def ping(address):
    p = Ping()
    async for rtt in p.iter_rtt(address):
        print(rtt)

__get_socket(address)

Get PingSocket instace.

Get ping socket instance for specified address. Initialize when necessary.

Parameters:

Name	Type	Description	Default
address	str	Address to ping	required

Returns:

Type	Description
PingSocket	Initialized socket instance

iter_rtt(addr, *, size=None, interval=1.0, count=None) async

Do the serie of ping probes.

Send echo request every interval seconds, await and yield the result.

Parameters:

Name	Type	Description	Default
addr	str	Address to ping.	required
size	int | None	Packets' size, including IP headers. Use PingSocket intialized defaults, when empty.	None
interval	float | None	Interval between requests, in seconds.	1.0
count	int | None	Stop after count requests, if set. Do not stop otherwise.	None

Returns:

Type	Description
AsyncIterable[float | None]	Yields for each attempt:
AsyncIterable[float | None]	Round-trip time in seconds (as float) if success.
AsyncIterable[float | None]	None - if failed or timed out.

ping(addr, size=None) async

Do ping probe.

Send ICMP echo request to the given address and await for response or timeout.

Parameters:

Name	Type	Description	Default
addr	str	IPv4/IPv6 address to ping.	required
size	int | None	Packet's size, including IP headers. Use PingSocket intialized defaults, when empty.	None

Returns:

Type	Description
float | None	Round-trip time in seconds (as float) if success.
float | None	None - if failed or timed out.

SelectionPolicy

Bases: IntEnum

Probe selection policy.

Allows automatical selection between implementations:

• RAW - Raw sockets, requires root user (POSIX platforms) or CAP_NET_RAW capability (Linux).
• DGRAM - ICMP datagram socket (Linux only). Requires net.ipv4.ping_group_range to contain process' group.

Attributes:

Name	Type	Description
RAW		Use RAW only.
RAW_DGRAM		Try RAW, fallback to DGRAM.
DGRAM_RAW		Try DGRAM, fallback to RAW.
DGRAM		Use DGRAM only.