AsyncPing
![PyPI - Downloads](https://img.shields.io/pypi/dm/asyncping3.svg)
AsyncPing is an async-friendly pure python3 version of ICMP ping implementation using raw sockets.
(Note that on Linux and Windows, ICMP messages can only be sent from processes running as root.)
The Python2 version originally from here.
The Python3 version originally from here.
This version maintained at this github repo.
CHANGELOG
Get Started
- If you met "permission denied", you may need to run this as root. Alternatively see this for troubleshooting on linux.
pip install asyncping3
>>> from asyncping3 import ping, verbose_ping
>>> anyio.run(ping,'example.com')
0.215697261510079666
>>> anyio.run(verbose_ping,'example.com')
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
Installation
pip install asyncping3
pip install --upgrade asyncping3
pip uninstall asyncping3
Functions
>>> from ping3 import ping, verbose_ping
>>> ping('example.com')
0.215697261510079666
>>> ping('not.exist.com')
False
>>> ping("224.0.0.0")
None
>>> ping('example.com', timeout=10)
0.215697261510079666
>>> ping('example.com', unit='ms')
215.9627876281738
>>> ping('example.com', src_addr='192.168.1.15')
0.215697261510079666
>>> ping('example.com', interface='eth0')
0.215697261510079666
>>> ping('example.com', ttl=5)
None
>>> ping('example.com', size=56)
0.215697261510079666
>>> verbose_ping('example.com')
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
>>> verbose_ping('example.com', timeout=10)
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
>>> verbose_ping('example.com', count=6)
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
>>> verbose_ping('example.com', count=0)
ping 'example.com' ... 215ms
...
>>> verbose_ping('example.com', src_addr='192.168.1.15')
ping 'example.com' from '192.168.1.15' ... 215ms
ping 'example.com' from '192.168.1.15' ... 216ms
ping 'example.com' from '192.168.1.15' ... 219ms
ping 'example.com' from '192.168.1.15' ... 217ms
>>> verbose_ping('example.com', interface='wifi0')
ping 'example.com' from '192.168.1.15' ... 215ms
ping 'example.com' from '192.168.1.15' ... 216ms
ping 'example.com' from '192.168.1.15' ... 219ms
ping 'example.com' from '192.168.1.15' ... 217ms
>>> verbose_ping('example.com', unit='s')
ping 'example.com' ... 1s
ping 'example.com' ... 2s
ping 'example.com' ... 1s
ping 'example.com' ... 1s
>>> verbose_ping('example.com', ttl=5)
ping 'example.com' ... Timeout
ping 'example.com' ... Timeout
ping 'example.com' ... Timeout
ping 'example.com' ... Timeout
>>> verbose_ping('example.com', interval=5)
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
>>> verbose_ping('example.com', size=56)
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
DEBUG mode
Show more info for developers.
>>> import asyncping3
>>> asyncping3.DEBUG = True
>>> asyncping3.ping("example.com")
[DEBUG] IP HEADER: {'version': 69, 'tos': 0, 'len': 14336, 'id': 8620, 'flags': 0, 'ttl': 51, 'protocol': 1, 'checksum': *, 'src_addr': *, 'dest_addr': *}
[DEBUG] ICMP HEADER: {'type': 0, 'code': 0, 'checksum': 8890, 'id': 21952, 'seq': 0}
0.215697261510079666
>>> asyncping3.ping("example.com", timeout=0.0001)
[DEBUG] Request timeout for ICMP packet. (Timeout = 0.0001s)
None
>>> asyncping3.ping("not.exist.com")
[DEBUG] Cannot resolve: Unknown host. (Host = not.exist.com)
False
>>> asyncping3.ping("example.com", ttl=1)
[DEBUG] Time exceeded: Time To Live expired.
None
EXCEPTIONS mode
Raise exceptions when there are errors instead of return None
>>> import asyncping3, anyio, functools
>>> asyncping3.EXCEPTIONS = True
>>> def pia(*a, **k):
... return anyio.run(functools.partial(asyncping3.ping, *a, **k))
>>> pia("example.com", timeout=0.0001))
[... Traceback ...]
ping3.errors.Timeout: Request timeout for ICMP packet. (Timeout = 0.0001s)
>>> pia("not.exist.com")
[... Traceback ...]
ping3.errors.HostUnknown: Cannot resolve: Unknown host. (Host = not.exist.com)
>>> pia("example.com", ttl=1)
[... Traceback ...]
ping3.errors.TimeToLiveExpired: Time exceeded: Time To Live expired.
>>> try:
>>> pia("example.com", ttl=1)
>>> except asyncping3.errors.TimeToLiveExpired as err:
>>> print(err.ip_header["src_addr"])
1.2.3.4
>>> help(ping3.errors)
>>> try:
>>> pia("invalid.com")
>>> except ping3.errors.HostUnknown:
>>> print("Host unknown error raised.")
>>> except ping3.errors.PingError:
>>> print("A ping error raised.")
Command Line Execution
Execute pping
from command-line.
Note: pping
needs root
privilege to send/receive packets. You may want to use sudo pping
.
$ pping --help
$ python -m asyncping3 --help
$ pping -v
3.0.0
$ pping example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping example.com 8.8.8.8
ping 'example.com' ... 215ms
ping 'example.com' ... 217ms
ping '8.8.8.8' ... 5ms
ping 'example.com' ... 216ms
ping '8.8.8.8' ... 2ms
ping '8.8.8.8' ... 6ms
ping 'example.com' ... 219ms
ping '8.8.8.8' ... 5ms
$ pping --count 1 example.com
ping 'example.com' ... 215ms
$ pping --count 0 example.com
...
$ pping --timeout 10 example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping --ttl 5 example.com
ping 'example.com' ... Timeout
ping 'example.com' ... Timeout
ping 'example.com' ... Timeout
ping 'example.com' ... Timeout
$ pping --size 56 example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping --interval 5 example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping --interface eth0 example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping --src 192.168.1.15 example.com
ping 'example.com' ... 215ms
ping 'example.com' ... 216ms
ping 'example.com' ... 219ms
ping 'example.com' ... 217ms
$ pping --exceptions --timeout 0.001 example.com
[... Traceback ...]
asyncping.errors.Timeout: Request timeout for ICMP packet. (Timeout = 0.0001s)
$ pping --debug --timeout 0.001 example.com
[DEBUG] Request timeout for ICMP packet. (Timeout = 0.001s)
ping 'example.com' ... Timeout > 0.001s
[DEBUG] Request timeout for ICMP packet. (Timeout = 0.001s)
ping 'example.com' ... Timeout > 0.001s
[DEBUG] Request timeout for ICMP packet. (Timeout = 0.001s)
ping 'example.com' ... Timeout > 0.001s
[DEBUG] Request timeout for ICMP packet. (Timeout = 0.001s)
ping 'example.com' ... Timeout > 0.001s