<div align="center">
<br>
<br>
<img src="media/icmplib-logo.png" height="125" width="100" alt="icmplib">
<br>
<br>
<div>
<a href="#features">Features</a>
<a href="#installation">Installation</a>
<a href="#getting-started">Getting started</a>
<a href="#documentation">Documentation</a>
<a href="#contributing">Contributing</a>
<a href="#donate">Donate</a>
<a href="#license">License</a>
</div>
<br>
<pre>icmplib is a brand new and modern implementation of the ICMP protocol in Python.
Use the built-in functions or build your own, you have the choice!
<a href="CHANGELOG.md">icmplib 3.0 has been released! See what's new 🎉</a></pre>
<a href="https://pypi.org/project/icmplib">
<img src="https://img.shields.io/pypi/dm/icmplib.svg?style=flat-square&labelColor=0366d6&color=005cc5" alt="statistics">
</a>
</div>
<br>
## Features
- :deciduous_tree: **Ready-to-use:** icmplib offers ready-to-use functions such as the most popular ones: `ping`, `multiping` and `traceroute`. An extensive documentation also helps you get started.
- :gem: **Modern:** This library uses the latest mechanisms offered by Python 3.7+ and is fully object-oriented.
- :rocket: **Fast:** Each class and function has been designed and optimized to deliver the best performance. Some functions are also asynchronous like the `async_ping` and `async_multiping` functions. You can ping the world in seconds!
- :zap: **Powerful:** Use the library without root privileges, set the traffic class of ICMP packets, customize their payload, send broadcast requests and more!
- :nut_and_bolt: **Evolutive:** Easily build your own classes and functions with `ICMPv4` and `ICMPv6` sockets.
- :fire: **Seamless integration of IPv6:** Use IPv6 the same way you use IPv4.
- :beer: **Cross-platform:** Optimized for Linux, macOS and Windows. The library automatically manages the specificities of each system.
- :metal: **No dependency:** icmplib is a pure Python implementation of the ICMP protocol. It does not rely on any external dependency.
<br>
## Installation
- **Install icmplib**
The recommended way to install icmplib is to use `pip3`:
```shell
$ pip3 install icmplib
```
- **Import basic functions**
```python
from icmplib import ping, multiping, traceroute, resolve
```
- **Import asynchronous functions**
```python
from icmplib import async_ping, async_multiping, async_resolve
```
- **Import sockets (advanced)**
```python
from icmplib import ICMPv4Socket, ICMPv6Socket, AsyncSocket, ICMPRequest, ICMPReply
```
- **Import exceptions**
```python
from icmplib import ICMPLibError, NameLookupError, ICMPSocketError
from icmplib import SocketAddressError, SocketPermissionError
from icmplib import SocketUnavailableError, SocketBroadcastError, TimeoutExceeded
from icmplib import ICMPError, DestinationUnreachable, TimeExceeded
```
*Import only what you need.*
<br>
## Getting started
### ping
Send ICMP Echo Request packets to a network host.
```python
ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs)
```
#### Parameters
- `address`
The IP address, hostname or FQDN of the host to which messages should be sent. For deterministic behavior, prefer to use an IP address.
- Type: `str`
- `count`
The number of ping to perform.
- Type: `int`
- Default: `4`
- `interval`
The interval in seconds between sending each packet.
- Type: `int` or `float`
- Default: `1`
- `timeout`
The maximum waiting time for receiving a reply in seconds.
- Type: `int` or `float`
- Default: `2`
- `id`
The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every ping process. On Linux, this identifier is ignored when the `privileged` parameter is disabled. The library handles this identifier itself by default.
- Type: `int`
- Default: `None`
- `source`
The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination.
- Type: `str`
- Default: `None`
- `family`
The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses.
- Type: `int`
- Default: `None`
- `privileged`
When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers.
[Learn more about the `privileged` parameter.]
*Only available on Unix systems. Ignored on Windows.*
- Type: `bool`
- Default: `True`
- `payload`
The payload content in bytes. A random payload is used by default.
- Type: `bytes`
- Default: `None`
- `payload_size`
The payload size. Ignored when the `payload` parameter is set.
- Type: `int`
- Default: `56`
- `traffic_class`
The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature.
*Only available on Unix systems. Ignored on Windows.*
- Type: `int`
- Default: `0`
#### Return value
- A `Host` object containing statistics about the desired destination:<br>
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`
#### Exceptions
- [`NameLookupError`]
If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved.
- [`SocketPermissionError`]
If the privileges are insufficient to create the socket.
- [`SocketAddressError`]
If the source address cannot be assigned to the socket.
- [`ICMPSocketError`]
If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details.
#### Example
```python
>>> from icmplib import ping
>>> host = ping('1.1.1.1', count=10, interval=0.2)
>>> host.address # The IP address of the host that responded
'1.1.1.1' # to the request
>>> host.min_rtt # The minimum round-trip time in milliseconds
5.761
>>> host.avg_rtt # The average round-trip time in milliseconds
12.036
>>> host.max_rtt # The maximum round-trip time in milliseconds
16.207
>>> host.rtts # The list of round-trip times expressed in
[ 11.595, 13.135, 9.614, # milliseconds
16.018, 11.960, 5.761, # The results are not rounded unlike other
16.207, 11.937, 12.098 ] # properties
>>> host.packets_sent # The number of requests transmitted to the
10 # remote host
>>> host.packets_received # The number of ICMP responses received from
9 # the remote host
>>> host.packet_loss # Packet loss occurs when packets fail to
0.1 # reach their destination. Returns a float
# between 0 and 1 (all packets are lost)
>>> host.jitter # The jitter in milliseconds, defined as the
4.575 # variance of the latency of packets flowing
# through the network
>>> host.is_alive # Indicates whether the host is reachable
True
```
<br>
### multiping
Send ICMP Echo Request packets to several network hosts.
```python
multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs)
```
#### Parameters
- `addresses`
The IP addresses of the hosts to which messages should be sent. Hostnames and FQDNs are allowed but not recommended. You can easily retrieve their IP address by calling the built-in [`resolve`] function.
- Type: `list[str]`
- `count`
The number of ping to perform per address.
- Type: `int`
- Default: `2`
- `interval`
The interval in seconds between sending each packet.
- Type: `int` or `float`
- Default: `0.5`
- `timeout`
The maximum waiting time for receiving a reply in seconds.
- Type: `int` or `float`
- Default: `2`
- `concurrent_tasks`
The maximum number of concurrent tasks to speed up processing. This value cannot exceed the maximum number of file descriptors configured on the operating system.
- Type: `int`
- Default: `50`
- `source`
The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destinations. This parameter should not be used if you are passing both IPv4 and IPv6 addresses to this function.
- Type: `str`
- Default: `None`
- `family`
The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses.
- Type: `int`
- Default: `None`
- `privileged`
When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers.
[Learn more about the `privileged` parameter.]
*Only available on Unix systems. Ignored on Windows.*
- Type: `bool`
- Default: `True`
- `payload`
The payload content in bytes. A random payload is used by default.
- Type: `bytes`
- Default: `None`
- `payload_size`
The payload size. Ignored when the `payload` parameter is set.
- Type: `int`
- Default: `56`
- `traffic_class`
The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature.
*Only available on Unix systems. Ignored on Windows.*
- Type: `int`
- Default: `0`
#### Return value
- A list of `Host` objects containing statistics about the desired destinations:<br>
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`
The list is sorted in the same order as the addresses passed in parameters.
#### Exceptions
- [`NameLookupError`]
If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved.
- [`SocketPermissionError`]
If the privileges are insufficient to create the socket.
- [`SocketAddressError`]
If the source address cannot be assigned to the socket.
- [`ICMPSocketError`]
If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details.
#### Example
```python
>>> from icmplib import multiping
>>> hosts = multiping(['10.0.0.5', '127.0.0.1', '::1'])
>>> for host in hosts:
... if host.is_alive:
... # See the Host class for details
... print(f'{host.address} is up!')
... else:
... print(f'{host.address} is down!')
# 10.0.0.5 is down!
# 127.0.0.1 is up!
# ::1 is up!
```
<br>
### traceroute
Determine the route to a destination host.
The Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking the route one's packets follow can be difficult. This function uses the IP protocol time to live field and attempts to elicit an ICMP Time Exceeded response from each gateway along the path to some host.
*This function requires root privileges to run.*
```python
traceroute(address, count=2, interval=0.05, timeout=2, first_hop=1, max_hops=30, fast=False, id=None, source=None, family=None, **kwargs)
```
#### Parameters
- `address`
The IP address, hostname or FQDN of the host to reach. For deterministic behavior, prefer to use an IP address.
- Type: `str`
- `count`
The number of ping to perform per hop.
- Type: `int`
- Default: `2`
- `interval`
The interval in seconds between sending each packet.
- Type: `int` or `float`
- Default: `0.05`
- `timeout`
The maximum waiting time for receiving a reply in seconds.
- Type: `int` or `float`
- Default: `2`
- `first_hop`
The initial time to live value used in outgoing probe packets.
- Type: `int`
- Default: `1`
- `max_hops`
The maximum time to live (max number of hops) used in outgoing probe packets.
- Type: `int`
- Default: `30`
- `fast`
When this option is enabled and an intermediate router has been reached, skip to the next hop rather than perform additional requests. The `count` parameter then becomes the maximum number of requests in the event of no response.
- Type: `bool`
- Default: `False`
- `id`
The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every traceroute process. The library handles this identifier itself by default.
- Type: `int`
- Default: `None`
- `source`
The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination.
- Type: `str`
- Default: `None`
- `family`
The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses.
- Type: `int`
- Default: `None`
- `payload`
The payload content in bytes. A random payload is used by default.
- Type: `bytes`
- Default: `None`
- `payload_size`
The payload size. Ignored when the `payload` parameter is set.
- Type: `int`
- Default: `56`
- `traffic_class`
The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature.
*Only available on Unix systems. Ignored on Windows.*
- Type: `int`
- Default: `0`
#### Return value
- A list of `Hop` objects representing the route to the desired destination. A `Hop` has the same properties as a `Host` object but it also has a `distance`:<br>
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`, `distance`
The list is sorted in ascending order according to the distance, in terms of hops, that separates the remote host from the current machine. Gateways that do not respond to requests are not added to this list.
#### Exceptions
- [`NameLookupError`]
If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved.
- [`SocketPermissionError`]
If the privileges are insufficient to create the socket.
- [`SocketAddressError`]
If the source address cannot be assigned to the socket.
- [`ICMPSocketError`]
If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details.
#### Example
```python
>>> from icmplib import traceroute
>>> hops = traceroute('1.1.1.1')
>>> print('Distance/TTL Address Average round-trip time')
>>> last_distance = 0
>>> for hop in hops:
... if last_distance + 1 != hop.distance:
... print('Some gateways are not responding')
...
... # See the Hop class for details
... print(f'{hop.distance} {hop.address} {hop.avg_rtt} ms')
...
... last_distance = hop.distance
# Distance/TTL Address Average round-trip time
# 1 10.0.0.1 5.196 ms
# 2 194.149.169.49 7.552 ms
# 3 194.149.166.54 12.21 ms
# * Some gateways are not responding
# 5 212.73.205.22 22.15 ms
# 6 1.1.1.1 13.59 ms
```
<br>
### async_ping
Send ICMP Echo Request packets to a network host.
*This function is non-blocking.*
```python
async_ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs)
```
#### Parameters, return value and exceptions
The same parameters, return value and exceptions as for the [`ping`] function.
#### Example
```python
>>> import asyncio
>>> from icmplib import async_ping
>>> async def is_alive(address):
... host = await async_ping(address, count=10, interval=0.2)
... return host.is_alive
>>> asyncio.run(is_alive('1.1.1.1'))
True
```
<br>
### async_multiping
Send ICMP Echo Request packets to several network hosts.
*This function is non-blocking.*
```python
async_multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs)
```
#### Parameters, return value and exceptions
The same parameters, return values and exceptions as for the [`multiping`] function.
#### Example
```python
>>> import asyncio
>>> from icmplib import async_multiping
>>> async def are_alive(*addresses):
... hosts = await async_multiping(addresses)
...
... for host in hosts:
... if not host.is_alive:
... return False
...
... return True
>>> asyncio.run(are_alive('10.0.0.5', '127.0.0.1', '::1'))
False
```
<br>
## Documentation
This page only gives an overview of the features of icmplib.
To learn more about the built-in functions, on how to create your own and handle exceptions, you can click on the following link:
- :rocket: [Documentation]
## Contributing
Comments and enhancements are welcome.
All development is done on [GitHub]. Use [Issues] to report problems and submit feature requests. Please include a minimal example that reproduces the bug.
## Donate
icmplib is completely free and open source. It has been fully developed on my free time. If you enjoy it, please consider donating to support the development.
- :tada: [Donate via PayPal]
## License
Copyright 2017-2023 Valentin BELYN.
Code released under the GNU LGPLv3 license. See the [LICENSE] for details.
[Learn more about the `privileged` parameter.]: docs/6-use-icmplib-without-privileges.md
[Documentation]: docs
[GitHub]: https://github.com/ValentinBELYN/icmplib
[Issues]: https://github.com/ValentinBELYN/icmplib/issues
[Donate via PayPal]: https://paypal.me/ValentinBELYN
[LICENSE]: LICENSE
[`ping`]: #ping
[`multiping`]: #multiping
[`ICMPv4Socket`]: docs/3-sockets.md#ICMPv4Socket
[`ICMPv6Socket`]: docs/3-sockets.md#ICMPv6Socket
[`NameLookupError`]: docs/4-exceptions.md#NameLookupError
[`ICMPSocketError`]: docs/4-exceptions.md#ICMPSocketError
[`SocketAddressError`]: docs/4-exceptions.md#SocketAddressError
[`SocketPermissionError`]: docs/4-exceptions.md#SocketPermissionError
[`resolve`]: docs/5-utilities.md#resolve
Raw data
{
"_id": null,
"home_page": "https://github.com/ValentinBELYN/icmplib",
"name": "icmplibs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "icmp, sockets, ping, multiping, traceroute, async, asyncio, ipv4, ipv6, python, python3",
"author": "Valentin BELYN",
"author_email": "valentin-hello@gmx.com",
"download_url": "https://files.pythonhosted.org/packages/36/c6/c05b94184e9707ad3d0dda7eedd88eb3889c34fcd7ed49e1678778698a7a/icmplibs-3.0.4.tar.gz",
"platform": null,
"description": "<div align=\"center\">\r\n <br>\r\n <br>\r\n <img src=\"media/icmplib-logo.png\" height=\"125\" width=\"100\" alt=\"icmplib\">\r\n <br>\r\n\r\n <br>\r\n <div>\r\n <a href=\"#features\">Features</a> \r\n <a href=\"#installation\">Installation</a> \r\n <a href=\"#getting-started\">Getting started</a> \r\n <a href=\"#documentation\">Documentation</a> \r\n <a href=\"#contributing\">Contributing</a> \r\n <a href=\"#donate\">Donate</a> \r\n <a href=\"#license\">License</a>\r\n </div>\r\n <br>\r\n\r\n <pre>icmplib is a brand new and modern implementation of the ICMP protocol in Python.\r\nUse the built-in functions or build your own, you have the choice!\r\n\r\n<a href=\"CHANGELOG.md\">icmplib 3.0 has been released! See what's new \ud83c\udf89</a></pre>\r\n\r\n <a href=\"https://pypi.org/project/icmplib\">\r\n <img src=\"https://img.shields.io/pypi/dm/icmplib.svg?style=flat-square&labelColor=0366d6&color=005cc5\" alt=\"statistics\">\r\n </a>\r\n</div>\r\n\r\n<br>\r\n\r\n## Features\r\n\r\n- :deciduous_tree: **Ready-to-use:** icmplib offers ready-to-use functions such as the most popular ones: `ping`, `multiping` and `traceroute`. An extensive documentation also helps you get started.\r\n- :gem: **Modern:** This library uses the latest mechanisms offered by Python 3.7+ and is fully object-oriented.\r\n- :rocket: **Fast:** Each class and function has been designed and optimized to deliver the best performance. Some functions are also asynchronous like the `async_ping` and `async_multiping` functions. You can ping the world in seconds!\r\n- :zap: **Powerful:** Use the library without root privileges, set the traffic class of ICMP packets, customize their payload, send broadcast requests and more!\r\n- :nut_and_bolt: **Evolutive:** Easily build your own classes and functions with `ICMPv4` and `ICMPv6` sockets.\r\n- :fire: **Seamless integration of IPv6:** Use IPv6 the same way you use IPv4.\r\n- :beer: **Cross-platform:** Optimized for Linux, macOS and Windows. The library automatically manages the specificities of each system.\r\n- :metal: **No dependency:** icmplib is a pure Python implementation of the ICMP protocol. It does not rely on any external dependency.\r\n\r\n<br>\r\n\r\n## Installation\r\n\r\n- **Install icmplib**\r\n\r\n The recommended way to install icmplib is to use `pip3`:\r\n\r\n ```shell\r\n $ pip3 install icmplib\r\n ```\r\n\r\n- **Import basic functions**\r\n\r\n ```python\r\n from icmplib import ping, multiping, traceroute, resolve\r\n ```\r\n\r\n- **Import asynchronous functions**\r\n\r\n ```python\r\n from icmplib import async_ping, async_multiping, async_resolve\r\n ```\r\n\r\n- **Import sockets (advanced)**\r\n\r\n ```python\r\n from icmplib import ICMPv4Socket, ICMPv6Socket, AsyncSocket, ICMPRequest, ICMPReply\r\n ```\r\n\r\n- **Import exceptions**\r\n\r\n ```python\r\n from icmplib import ICMPLibError, NameLookupError, ICMPSocketError\r\n from icmplib import SocketAddressError, SocketPermissionError\r\n from icmplib import SocketUnavailableError, SocketBroadcastError, TimeoutExceeded\r\n from icmplib import ICMPError, DestinationUnreachable, TimeExceeded\r\n ```\r\n\r\n *Import only what you need.*\r\n\r\n<br>\r\n\r\n## Getting started\r\n\r\n### ping\r\n\r\nSend ICMP Echo Request packets to a network host.\r\n\r\n```python\r\nping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs)\r\n```\r\n\r\n#### Parameters\r\n\r\n- `address`\r\n\r\n The IP address, hostname or FQDN of the host to which messages should be sent. For deterministic behavior, prefer to use an IP address.\r\n\r\n - Type: `str`\r\n\r\n- `count`\r\n\r\n The number of ping to perform.\r\n\r\n - Type: `int`\r\n - Default: `4`\r\n\r\n- `interval`\r\n\r\n The interval in seconds between sending each packet.\r\n\r\n - Type: `int` or `float`\r\n - Default: `1`\r\n\r\n- `timeout`\r\n\r\n The maximum waiting time for receiving a reply in seconds.\r\n\r\n - Type: `int` or `float`\r\n - Default: `2`\r\n\r\n- `id`\r\n\r\n The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every ping process. On Linux, this identifier is ignored when the `privileged` parameter is disabled. The library handles this identifier itself by default.\r\n\r\n - Type: `int`\r\n - Default: `None`\r\n\r\n- `source`\r\n\r\n The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination.\r\n\r\n - Type: `str`\r\n - Default: `None`\r\n\r\n- `family`\r\n\r\n The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses.\r\n\r\n - Type: `int`\r\n - Default: `None`\r\n\r\n- `privileged`\r\n\r\n When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers.\r\n\r\n [Learn more about the `privileged` parameter.]\r\n\r\n *Only available on Unix systems. Ignored on Windows.*\r\n\r\n - Type: `bool`\r\n - Default: `True`\r\n\r\n- `payload`\r\n\r\n The payload content in bytes. A random payload is used by default.\r\n\r\n - Type: `bytes`\r\n - Default: `None`\r\n\r\n- `payload_size`\r\n\r\n The payload size. Ignored when the `payload` parameter is set.\r\n\r\n - Type: `int`\r\n - Default: `56`\r\n\r\n- `traffic_class`\r\n\r\n The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature.\r\n\r\n *Only available on Unix systems. Ignored on Windows.*\r\n\r\n - Type: `int`\r\n - Default: `0`\r\n\r\n#### Return value\r\n\r\n- A `Host` object containing statistics about the desired destination:<br>\r\n `address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`\r\n\r\n#### Exceptions\r\n\r\n- [`NameLookupError`]\r\n\r\n If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved.\r\n\r\n- [`SocketPermissionError`]\r\n\r\n If the privileges are insufficient to create the socket.\r\n\r\n- [`SocketAddressError`]\r\n\r\n If the source address cannot be assigned to the socket.\r\n\r\n- [`ICMPSocketError`]\r\n\r\n If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details.\r\n\r\n#### Example\r\n\r\n```python\r\n>>> from icmplib import ping\r\n\r\n>>> host = ping('1.1.1.1', count=10, interval=0.2)\r\n\r\n>>> host.address # The IP address of the host that responded\r\n'1.1.1.1' # to the request\r\n\r\n>>> host.min_rtt # The minimum round-trip time in milliseconds\r\n5.761\r\n\r\n>>> host.avg_rtt # The average round-trip time in milliseconds\r\n12.036\r\n\r\n>>> host.max_rtt # The maximum round-trip time in milliseconds\r\n16.207\r\n\r\n>>> host.rtts # The list of round-trip times expressed in\r\n[ 11.595, 13.135, 9.614, # milliseconds\r\n 16.018, 11.960, 5.761, # The results are not rounded unlike other\r\n 16.207, 11.937, 12.098 ] # properties\r\n\r\n>>> host.packets_sent # The number of requests transmitted to the\r\n10 # remote host\r\n\r\n>>> host.packets_received # The number of ICMP responses received from\r\n9 # the remote host\r\n\r\n>>> host.packet_loss # Packet loss occurs when packets fail to\r\n0.1 # reach their destination. Returns a float\r\n # between 0 and 1 (all packets are lost)\r\n\r\n>>> host.jitter # The jitter in milliseconds, defined as the\r\n4.575 # variance of the latency of packets flowing\r\n # through the network\r\n\r\n>>> host.is_alive # Indicates whether the host is reachable\r\nTrue\r\n```\r\n\r\n<br>\r\n\r\n### multiping\r\n\r\nSend ICMP Echo Request packets to several network hosts.\r\n\r\n```python\r\nmultiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs)\r\n```\r\n\r\n#### Parameters\r\n\r\n- `addresses`\r\n\r\n The IP addresses of the hosts to which messages should be sent. Hostnames and FQDNs are allowed but not recommended. You can easily retrieve their IP address by calling the built-in [`resolve`] function.\r\n\r\n - Type: `list[str]`\r\n\r\n- `count`\r\n\r\n The number of ping to perform per address.\r\n\r\n - Type: `int`\r\n - Default: `2`\r\n\r\n- `interval`\r\n\r\n The interval in seconds between sending each packet.\r\n\r\n - Type: `int` or `float`\r\n - Default: `0.5`\r\n\r\n- `timeout`\r\n\r\n The maximum waiting time for receiving a reply in seconds.\r\n\r\n - Type: `int` or `float`\r\n - Default: `2`\r\n\r\n- `concurrent_tasks`\r\n\r\n The maximum number of concurrent tasks to speed up processing. This value cannot exceed the maximum number of file descriptors configured on the operating system.\r\n\r\n - Type: `int`\r\n - Default: `50`\r\n\r\n- `source`\r\n\r\n The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destinations. This parameter should not be used if you are passing both IPv4 and IPv6 addresses to this function.\r\n\r\n - Type: `str`\r\n - Default: `None`\r\n\r\n- `family`\r\n\r\n The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses.\r\n\r\n - Type: `int`\r\n - Default: `None`\r\n\r\n- `privileged`\r\n\r\n When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers.\r\n\r\n [Learn more about the `privileged` parameter.]\r\n\r\n *Only available on Unix systems. Ignored on Windows.*\r\n\r\n - Type: `bool`\r\n - Default: `True`\r\n\r\n- `payload`\r\n\r\n The payload content in bytes. A random payload is used by default.\r\n\r\n - Type: `bytes`\r\n - Default: `None`\r\n\r\n- `payload_size`\r\n\r\n The payload size. Ignored when the `payload` parameter is set.\r\n\r\n - Type: `int`\r\n - Default: `56`\r\n\r\n- `traffic_class`\r\n\r\n The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature.\r\n\r\n *Only available on Unix systems. Ignored on Windows.*\r\n\r\n - Type: `int`\r\n - Default: `0`\r\n\r\n#### Return value\r\n\r\n- A list of `Host` objects containing statistics about the desired destinations:<br>\r\n `address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`\r\n\r\n The list is sorted in the same order as the addresses passed in parameters.\r\n\r\n#### Exceptions\r\n\r\n- [`NameLookupError`]\r\n\r\n If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved.\r\n\r\n- [`SocketPermissionError`]\r\n\r\n If the privileges are insufficient to create the socket.\r\n\r\n- [`SocketAddressError`]\r\n\r\n If the source address cannot be assigned to the socket.\r\n\r\n- [`ICMPSocketError`]\r\n\r\n If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details.\r\n\r\n#### Example\r\n\r\n```python\r\n>>> from icmplib import multiping\r\n\r\n>>> hosts = multiping(['10.0.0.5', '127.0.0.1', '::1'])\r\n\r\n>>> for host in hosts:\r\n... if host.is_alive:\r\n... # See the Host class for details\r\n... print(f'{host.address} is up!')\r\n... else:\r\n... print(f'{host.address} is down!')\r\n\r\n# 10.0.0.5 is down!\r\n# 127.0.0.1 is up!\r\n# ::1 is up!\r\n```\r\n\r\n<br>\r\n\r\n### traceroute\r\n\r\nDetermine the route to a destination host.\r\n\r\nThe Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking the route one's packets follow can be difficult. This function uses the IP protocol time to live field and attempts to elicit an ICMP Time Exceeded response from each gateway along the path to some host.\r\n\r\n*This function requires root privileges to run.*\r\n\r\n```python\r\ntraceroute(address, count=2, interval=0.05, timeout=2, first_hop=1, max_hops=30, fast=False, id=None, source=None, family=None, **kwargs)\r\n```\r\n\r\n#### Parameters\r\n\r\n- `address`\r\n\r\n The IP address, hostname or FQDN of the host to reach. For deterministic behavior, prefer to use an IP address.\r\n\r\n - Type: `str`\r\n\r\n- `count`\r\n\r\n The number of ping to perform per hop.\r\n\r\n - Type: `int`\r\n - Default: `2`\r\n\r\n- `interval`\r\n\r\n The interval in seconds between sending each packet.\r\n\r\n - Type: `int` or `float`\r\n - Default: `0.05`\r\n\r\n- `timeout`\r\n\r\n The maximum waiting time for receiving a reply in seconds.\r\n\r\n - Type: `int` or `float`\r\n - Default: `2`\r\n\r\n- `first_hop`\r\n\r\n The initial time to live value used in outgoing probe packets.\r\n\r\n - Type: `int`\r\n - Default: `1`\r\n\r\n- `max_hops`\r\n\r\n The maximum time to live (max number of hops) used in outgoing probe packets.\r\n\r\n - Type: `int`\r\n - Default: `30`\r\n\r\n- `fast`\r\n\r\n When this option is enabled and an intermediate router has been reached, skip to the next hop rather than perform additional requests. The `count` parameter then becomes the maximum number of requests in the event of no response.\r\n\r\n - Type: `bool`\r\n - Default: `False`\r\n\r\n- `id`\r\n\r\n The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every traceroute process. The library handles this identifier itself by default.\r\n\r\n - Type: `int`\r\n - Default: `None`\r\n\r\n- `source`\r\n\r\n The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination.\r\n\r\n - Type: `str`\r\n - Default: `None`\r\n\r\n- `family`\r\n\r\n The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses.\r\n\r\n - Type: `int`\r\n - Default: `None`\r\n\r\n- `payload`\r\n\r\n The payload content in bytes. A random payload is used by default.\r\n\r\n - Type: `bytes`\r\n - Default: `None`\r\n\r\n- `payload_size`\r\n\r\n The payload size. Ignored when the `payload` parameter is set.\r\n\r\n - Type: `int`\r\n - Default: `56`\r\n\r\n- `traffic_class`\r\n\r\n The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature.\r\n\r\n *Only available on Unix systems. Ignored on Windows.*\r\n\r\n - Type: `int`\r\n - Default: `0`\r\n\r\n#### Return value\r\n\r\n- A list of `Hop` objects representing the route to the desired destination. A `Hop` has the same properties as a `Host` object but it also has a `distance`:<br>\r\n `address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`, `distance`\r\n\r\n The list is sorted in ascending order according to the distance, in terms of hops, that separates the remote host from the current machine. Gateways that do not respond to requests are not added to this list.\r\n\r\n#### Exceptions\r\n\r\n- [`NameLookupError`]\r\n\r\n If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved.\r\n\r\n- [`SocketPermissionError`]\r\n\r\n If the privileges are insufficient to create the socket.\r\n\r\n- [`SocketAddressError`]\r\n\r\n If the source address cannot be assigned to the socket.\r\n\r\n- [`ICMPSocketError`]\r\n\r\n If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details.\r\n\r\n#### Example\r\n\r\n```python\r\n>>> from icmplib import traceroute\r\n\r\n>>> hops = traceroute('1.1.1.1')\r\n\r\n>>> print('Distance/TTL Address Average round-trip time')\r\n>>> last_distance = 0\r\n\r\n>>> for hop in hops:\r\n... if last_distance + 1 != hop.distance:\r\n... print('Some gateways are not responding')\r\n...\r\n... # See the Hop class for details\r\n... print(f'{hop.distance} {hop.address} {hop.avg_rtt} ms')\r\n...\r\n... last_distance = hop.distance\r\n\r\n# Distance/TTL Address Average round-trip time\r\n# 1 10.0.0.1 5.196 ms\r\n# 2 194.149.169.49 7.552 ms\r\n# 3 194.149.166.54 12.21 ms\r\n# * Some gateways are not responding\r\n# 5 212.73.205.22 22.15 ms\r\n# 6 1.1.1.1 13.59 ms\r\n```\r\n\r\n<br>\r\n\r\n### async_ping\r\n\r\nSend ICMP Echo Request packets to a network host.\r\n\r\n*This function is non-blocking.*\r\n\r\n```python\r\nasync_ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs)\r\n```\r\n\r\n#### Parameters, return value and exceptions\r\n\r\nThe same parameters, return value and exceptions as for the [`ping`] function.\r\n\r\n#### Example\r\n\r\n```python\r\n>>> import asyncio\r\n>>> from icmplib import async_ping\r\n\r\n>>> async def is_alive(address):\r\n... host = await async_ping(address, count=10, interval=0.2)\r\n... return host.is_alive\r\n\r\n>>> asyncio.run(is_alive('1.1.1.1'))\r\nTrue\r\n```\r\n\r\n<br>\r\n\r\n### async_multiping\r\n\r\nSend ICMP Echo Request packets to several network hosts.\r\n\r\n*This function is non-blocking.*\r\n\r\n```python\r\nasync_multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs)\r\n```\r\n\r\n#### Parameters, return value and exceptions\r\n\r\nThe same parameters, return values and exceptions as for the [`multiping`] function.\r\n\r\n#### Example\r\n\r\n```python\r\n>>> import asyncio\r\n>>> from icmplib import async_multiping\r\n\r\n>>> async def are_alive(*addresses):\r\n... hosts = await async_multiping(addresses)\r\n... \r\n... for host in hosts:\r\n... if not host.is_alive:\r\n... return False\r\n...\r\n... return True\r\n\r\n>>> asyncio.run(are_alive('10.0.0.5', '127.0.0.1', '::1'))\r\nFalse\r\n```\r\n\r\n<br>\r\n\r\n## Documentation\r\n\r\nThis page only gives an overview of the features of icmplib.\r\n\r\nTo learn more about the built-in functions, on how to create your own and handle exceptions, you can click on the following link:\r\n\r\n- :rocket: [Documentation]\r\n\r\n## Contributing\r\n\r\nComments and enhancements are welcome.\r\n\r\nAll development is done on [GitHub]. Use [Issues] to report problems and submit feature requests. Please include a minimal example that reproduces the bug.\r\n\r\n## Donate\r\n\r\nicmplib is completely free and open source. It has been fully developed on my free time. If you enjoy it, please consider donating to support the development.\r\n\r\n- :tada: [Donate via PayPal]\r\n\r\n## License\r\n\r\nCopyright 2017-2023 Valentin BELYN.\r\n\r\nCode released under the GNU LGPLv3 license. See the [LICENSE] for details.\r\n\r\n[Learn more about the `privileged` parameter.]: docs/6-use-icmplib-without-privileges.md\r\n[Documentation]: docs\r\n[GitHub]: https://github.com/ValentinBELYN/icmplib\r\n[Issues]: https://github.com/ValentinBELYN/icmplib/issues\r\n[Donate via PayPal]: https://paypal.me/ValentinBELYN\r\n[LICENSE]: LICENSE\r\n[`ping`]: #ping\r\n[`multiping`]: #multiping\r\n[`ICMPv4Socket`]: docs/3-sockets.md#ICMPv4Socket\r\n[`ICMPv6Socket`]: docs/3-sockets.md#ICMPv6Socket\r\n[`NameLookupError`]: docs/4-exceptions.md#NameLookupError\r\n[`ICMPSocketError`]: docs/4-exceptions.md#ICMPSocketError\r\n[`SocketAddressError`]: docs/4-exceptions.md#SocketAddressError\r\n[`SocketPermissionError`]: docs/4-exceptions.md#SocketPermissionError\r\n[`resolve`]: docs/5-utilities.md#resolve\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "GNU Lesser General Public License v3.0",
"summary": "Easily forge ICMP packets and make your own ping and traceroute.",
"version": "3.0.4",
"project_urls": {
"Homepage": "https://github.com/ValentinBELYN/icmplib"
},
"split_keywords": [
"icmp",
" sockets",
" ping",
" multiping",
" traceroute",
" async",
" asyncio",
" ipv4",
" ipv6",
" python",
" python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "36c6c05b94184e9707ad3d0dda7eedd88eb3889c34fcd7ed49e1678778698a7a",
"md5": "22197145701496c493d0c9d23a3040f4",
"sha256": "d319561c38322c5fa36649605edac720fe83bda27211e2041ba361970ef6eed1"
},
"downloads": -1,
"filename": "icmplibs-3.0.4.tar.gz",
"has_sig": false,
"md5_digest": "22197145701496c493d0c9d23a3040f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26771,
"upload_time": "2024-04-24T11:44:26",
"upload_time_iso_8601": "2024-04-24T11:44:26.738690Z",
"url": "https://files.pythonhosted.org/packages/36/c6/c05b94184e9707ad3d0dda7eedd88eb3889c34fcd7ed49e1678778698a7a/icmplibs-3.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-24 11:44:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ValentinBELYN",
"github_project": "icmplib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "icmplibs"
}
JSON
