Asynchronous network probes for Python
Project description
mtrpacket
Asynchronous network probes for Python
mtrpacket is a package for sending IPv4 and IPv6 network probes ('pings') asynchronously from Python programs. Python's asyncio library provides the event loop and mechanism for incorporating mtrpacket's network probes with other concurrent operations.
mtrpacket supports a variety of probe customization options. Time-to-live (TTL) may be explicitly used for traceroute-like functionality. Probes can be sent using a variety of protocols: ICMP, UDP, TCP and SCTP. UDP, TCP and SCTP probes may be sent with specific source and destination ports. Probes can be sent with a particular packet size and payload bit-pattern. On Linux, probes can be sent with a routing "mark".
mtrpacket works on Linux, MacOS, Windows (with Cygwin) and various Unix systems. Requirements are Python (>= 3.6) and mtr (>= 0.88). mtr is distributed with many Linux distributions -- you may have it installed already. For other operating systems, see https://github.com/traviscross/mtr
Getting started
The easiest way to get started with mtrpacket is to use async with
to open an mtrpacket session, and then call probe on that session.
This must be done in an asyncio coroutine. asyncio manages the event loop.
For example:
import asyncio
import mtrpacket
# A simple coroutine which will start an mtrpacket session and
# ping localhost
async def probe():
async with mtrpacket.MtrPacket() as mtr:
return await mtr.probe('localhost')
# Use asyncio's event loop to start the coroutine and wait for the probe
loop = asyncio.get_event_loop()
result = loop.run_until_complete(probe())
# Print the probe result
print(result)
Keyword arguments may be used with mtr.probe
to further customize
the network probe. For example:
# Send a probe to the HTTPS port of example.com and limit the probe
# to four network hops
result = await mtr.probe(
'example.com',
ttl=4,
protocol='tcp',
port=443)
MtrPacket
MtrPacket(self)
The mtr-packet subprocess which can send network probes
MtrPacket opens a subprocess to an external 'mtr-packet' program, and request that the subprocess send network probes. Multiple probe requests can be simultaneously in-transit, with results processed asynchronously, as they arrive.
open
MtrPacket.open(self) -> 'MtrPacket'
Launch an mtr-packet subprocess to accept commands (asynchronous)
Start a subprocess for accepting probe commands. The 'mtr-packet' executable in the PATH is used by default, however, the MTR_PACKET environment variable can be used to specify an alternate subprocess executable.
As an alternative to calling open() explicitly, an 'async with' block can be used with the MtrPacket object to open and close the subprocess.
Raises ProcessError if the subprocess fails to execute or if the subprocess doesn't support sending packets.
Raises StateError if the subprocess is already open.
close
MtrPacket.close(self) -> None
Close an open mtr-packet subprocess (asynchronous)
If open() was explicitly called to launch the mtr-packet subprocess, close() should be used to terminate the process and clean up resources.
check_support
MtrPacket.check_support(self, feature: str) -> bool
Check for support of a particular feature of mtr-packet (asynchronous)
check_support() can be used to check support for particular features in the mtr-packet subprocess. For example, 'udp', 'tcp' and 'sctp' can be used to check support for UDP probes, TCP probes, and SCTP probes.
See 'check-support' in the mtr-packet(8) man page for more information.
Raises ProcessError if the mtr-packet subprocess has unexpectedly terminated.
Raises StateError if the MtrPacket session hasn't been opened.
probe
MtrPacket.probe(self, host: str, **args) -> 'ProbeResult'
Asynchronously send a network probe (asynchronous)
Send a network probe to a particular hostname or IP address, returning a ProbeResult, which includes the status of the probe, the address of the host responding to the probe and the round trip time of the probe.
A number of optional keyword arguments can be used with the probe request:
ip_version: Set the IP protocol version to either IPv4 or IPv6.
ttl: Set the "time to live" of the probe request. This is used to limit the number of network hops the probe takes before the probe result is reported.
protocol: Can be 'icmp', 'udp', 'tcp' or 'sctp'. A probe of the requested protocol is used.
port: The destination port to use for 'udp', 'tcp' or 'sctp' probes.
local_ip: Set the source address of the probe to a particular IP address. Useful when sending from a host with multiple IP local addresses.
local_port: Send the probe from a particular port, when sending 'udp', 'tcp' or 'sctp' probes.
timeout: The number of seconds to wait for a response before assuming the probe has been lost.
size: The size of the generated probe packet, in bytes.
bit_pattern: A byte value used to fill the payload of the probe packet.
tos: The value to use in the "type of service" field for IPv4 packets, or the "traffic class" field of IPv6 packets.
mark: The packet "mark" value to be used by the Linux routing subsystem.
Raises ProcessError if the mtr-packet subprocess has unexpectedly terminated.
Raises HostResolveError if the hostname can't be resolved to an IP address.
Raises StateError if the MtrPacket session hasn't been opened.
ProbeResult
ProbeResult(self, /, *args, **kwargs)
A named tuple describing the result of a network probe
A call to MtrPacket.probe will result in an instance of ProbeResult with the following members:
success: a bool which is True only if the probe arrived at the target host.
result: the command reply string from mtr-packet. Common values are 'reply' for a probe which arrives at the target host, 'ttl-expired' for a probe which has its "time to live" counter reach zero before arriving at the target host, and 'no-reply' for a probe which is unanswered.
See the mtr-packet(8) man page for further command reply
strings.
time_ms: a floating point value indicating the number of milliseconds the probe was in-transit, prior to receiving a result. Will be None in cases other than 'reply' or 'ttl-expired'.
responder: a string with the IP address of the host responding to the probe. Will be None in cases other than 'reply' or 'ttl-expired'.
mpls: a list of Mpls tuples representing the MPLS label stack present in a 'ttl-expired' response, when Multiprotocol Label Switching (MPLS) is used to route the probe.
mpls
Alias for field number 4
responder
Alias for field number 3
result
Alias for field number 1
success
Alias for field number 0
time_ms
Alias for field number 2
Mpls
Mpls(self, /, *args, **kwargs)
A named tuple describing an MPLS header.
Multiprotocol Label Switching (MPLS) routes packet using explicit headers attach to the packet, rather than using the IP address for routing. When a probe's time-to-live (TTL) expires, and MPLS is used at the router where the expiration occurs, the MPLS headers attached to the packet may be returned with the TTL expiration notification.
Mpls contains one of those headers, with:
label: the numeric MPLS label.
traffic_class: the traffic class (for quality of service). This field was formerly known as "experimental use".
bottom_of_stack: a boolean indicating whether the label terminates the stack.
ttl: the time-to-live of the MPLS header
bottom_of_stack
Alias for field number 2
label
Alias for field number 0
traffic_class
Alias for field number 1
ttl
Alias for field number 3
StateError
StateError(self, /, *args, **kwargs)
Exception raised when attempting to use MtrPacket in an invalid state
StateError is raised when attempting to send a command to the mtr-packet subprocess without first opening the MtrPacket subprocess, or when attempting to open a subprocess which is already open.
HostResolveError
HostResolveError(self, /, *args, **kwargs)
Exception raised when attempting to probe a non-resolving hostname
If a hostname is passed to MtrPacket.probe, and that hostname fails to resolve to an IP address, HostResolveError is raised.
ProcessError
ProcessError(self, /, *args, **kwargs)
Exception raised when the mtr-packet subprocess unexpectedly exits
ProcessError is raised by a call to MtrPacket.probe or MtrPacket.check_support when the mtr-packet subprocess has unexpectly terminated. It is also raised by MtrPacket.open when the subprocess doesn't support the mtr-packet interface.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mtrpacket-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8ca0937b6971aacfc0d3cec8bd9d6494ffd8fa8320e56d6b2dc58374263bfdff |
|
MD5 | 1d59f61f7b892174d58037bf89c30a9a |
|
BLAKE2b-256 | 88b8dd87cbf2fbccb19324205e9bcbc0399db51fb71fb697837986df0b78ccfc |