Skip to content

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
size int

Set outgoing packet's size, including IP header.

64
src_addr Union[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 Optional[int]

Set outgoing packet's TTL. Use OS defaults when empty.

Warning

This option is ignored on IPv6 socket due to issue #4

None
tos Optional[int]

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 Optional[int]

Send buffer size. Use OS defaults when empty.

None
recv_buffer_size Optional[int]

Receive buffer size. Use OS defaults when empty.

None
coarse bool

Use CLOCK_MONOTONIC_COARSE when set, fall back to CLOCK_MONOTONIC otherwise.

False
accelerated bool

Enable platform-dependend accelerated socket processing.

True
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_request_id()

Get request id.

Generate ICMP request id and starting sequence number.

Returns:

Type Description
Tuple[int, int]

Tuple of (request_id, sequence)

__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 Optional[int]

Packets' size, including IP headers. Use PingSocket intialized defaults, when empty.

None
interval Optional[float]

Interval between requests, in seconds.

1.0
count Optional[int]

Stop after count requests, if set. Do not stop otherwise.

None

Returns:

Type Description
AsyncIterable[Optional[float]]

Yields for each attempt:

AsyncIterable[Optional[float]]
  • Round-trip time in seconds (as float) if success.
AsyncIterable[Optional[float]]
  • 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 Optional[int]

Packet's size, including IP headers. Use PingSocket intialized defaults, when empty.

None

Returns:

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