Connection Utilities¶

Connection and networking based utility functions.

Module Overview:

download - download from a given url
get_connections - quieries the connections belonging to a given process
system_resolvers - provides connection resolution methods that are likely to be available
port_usage - brief description of the common usage for a port

is_valid_ipv4_address - checks if a string is a valid IPv4 address
is_valid_ipv6_address - checks if a string is a valid IPv6 address
is_valid_port - checks if something is a valid representation for a port
is_private_address - checks if an IPv4 address belongs to a private range or not

address_to_int - provides an integer representation of an IP address

expand_ipv6_address - provides an IPv6 address with its collapsed portions expanded
get_mask_ipv4 - provides the mask representation for a given number of bits
get_mask_ipv6 - provides the IPv6 mask representation for a given number of bits

stem.util.connection.Resolver(enum)¶

Method for resolving a process' connections.

New in version 1.1.0.

Changed in version 1.4.0: Added NETSTAT_WINDOWS.

Changed in version 1.6.0: Added BSD_FSTAT.

Deprecated since version 1.6.0: The SOCKSTAT connection resolver is proving to be unreliable (ticket 23057), and will be dropped in the 2.0.0 release unless fixed.

Resolver	Description
PROC	/proc contents
NETSTAT	netstat
NETSTAT_WINDOWS	netstat command under Windows
SS	ss command
LSOF	lsof command
SOCKSTAT	sockstat command under *nix
BSD_SOCKSTAT	sockstat command under FreeBSD
BSD_PROCSTAT	procstat command under FreeBSD
BSD_FSTAT	fstat command under OpenBSD

class stem.util.connection.Connection[source]¶

Bases: stem.util.connection.Connection

Network connection information.

Changed in version 1.5.0: Added the is_ipv6 attribute.

Variables:	local_address (str) -- ip address the connection originates from local_port (int) -- port the connection originates from remote_address (str) -- destionation ip address remote_port (int) -- destination port protocol (str) -- protocol of the connection ('tcp', 'udp', etc) is_ipv6 (bool) -- addresses are ipv6 if true, and ipv4 otherwise

stem.util.connection.download(url, timeout=None, retries=None)[source]¶

Download from the given url.

New in version 1.8.0.

Parameters:	url (str) -- uncompressed url to download from timeout (int) -- timeout when connection becomes idle, no timeout applied if None retires (int) -- maximum attempts to impose
Returns:	bytes content of the given url
Raises :	`DownloadTimeout` if our request timed out `DownloadFailed` if our request fails

stem.util.connection.get_connections(resolver=None, process_pid=None, process_name=None)[source]¶

Retrieves a list of the current connections for a given process. This provides a list of Connection. Note that addresses may be IPv4 or IPv6 depending on what the platform supports.

New in version 1.1.0.

Changed in version 1.5.0: Made our resolver argument optional.

Changed in version 1.5.0: IPv6 support when resolving via proc, netstat, lsof, or ss.

Parameters:	resolver (Resolver) -- method of connection resolution to use, if not provided then one is picked from among those that should likely be available for the system process_pid (int) -- pid of the process to retrieve process_name (str) -- name of the process to retrieve
Returns:	list of `Connection` instances
Raises :	ValueError if neither a process_pid nor process_name is provided IOError if no connections are available or resolution fails (generally they're indistinguishable). The common causes are the command being unavailable or permissions.

stem.util.connection.system_resolvers(system=None)[source]¶

Provides the types of connection resolvers likely to be available on this platform.

New in version 1.1.0.

Changed in version 1.3.0: Renamed from get_system_resolvers() to system_resolvers(). The old name still works as an alias, but will be dropped in Stem version 2.0.0.

Parameters:	system (str) -- system to get resolvers for, this is determined by platform.system() if not provided
Returns:	list of `Resolver` instances available on this platform

stem.util.connection.port_usage(port)[source]¶

Provides the common use of a given port. For example, 'HTTP' for port 80 or 'SSH' for 22.

New in version 1.2.0.

Parameters:	port (int) -- port number to look up
Returns:	str with a description for the port, None if none is known

stem.util.connection.is_valid_ipv4_address(address)[source]¶

Checks if a string is a valid IPv4 address.

Parameters:	address (str) -- string to be checked
Returns:	True if input is a valid IPv4 address, False otherwise

stem.util.connection.is_valid_ipv6_address(address, allow_brackets=False)[source]¶

Checks if a string is a valid IPv6 address.

Parameters:	address (str) -- string to be checked allow_brackets (bool) -- ignore brackets which form '[address]'
Returns:	True if input is a valid IPv6 address, False otherwise

stem.util.connection.is_valid_port(entry, allow_zero=False)[source]¶

Checks if a string or int is a valid port number.

Parameters:	entry (list,str,int) -- string, integer or list to be checked allow_zero (bool) -- accept port number of zero (reserved by definition)
Returns:	True if input is an integer and within the valid port range, False otherwise

stem.util.connection.is_private_address(address)[source]¶

Checks if the IPv4 address is in a range belonging to the local network or loopback. These include:

Private ranges: 10.*, 172.16.* - 172.31.*, 192.168.*

Loopback: 127.*

New in version 1.1.0.

Parameters:	address (str) -- string to be checked
Returns:	True if input is in a private range, False otherwise
Raises :	ValueError if the address isn't a valid IPv4 address

stem.util.connection.address_to_int(address)[source]¶

Provides an integer representation of a IPv4 or IPv6 address that can be used for sorting.

New in version 1.5.0.

Parameters:	address (str) -- IPv4 or IPv6 address
Returns:	int representation of the address

stem.util.connection.expand_ipv6_address(address)[source]¶

Expands abbreviated IPv6 addresses to their full colon separated hex format. For instance...

>>> expand_ipv6_address('2001:db8::ff00:42:8329')
'2001:0db8:0000:0000:0000:ff00:0042:8329'

>>> expand_ipv6_address('::')
'0000:0000:0000:0000:0000:0000:0000:0000'

>>> expand_ipv6_address('::ffff:5.9.158.75')
'0000:0000:0000:0000:0000:ffff:0509:9e4b'

Parameters:	address (str) -- IPv6 address to be expanded
Raises :	ValueError if the address can't be expanded due to being malformed

stem.util.connection.get_mask_ipv4(bits)[source]¶

Provides the IPv4 mask for a given number of bits, in the dotted-quad format.

Parameters:	bits (int) -- number of bits to be converted
Returns:	str with the subnet mask representation for this many bits
Raises :	ValueError if given a number of bits outside the range of 0-32

stem.util.connection.get_mask_ipv6(bits)[source]¶

Provides the IPv6 mask for a given number of bits, in the hex colon-delimited format.

Parameters:	bits (int) -- number of bits to be converted
Returns:	str with the subnet mask representation for this many bits
Raises :	ValueError if given a number of bits outside the range of 0-128

stem.util.connection.get_system_resolvers(system=None)¶

Provides the types of connection resolvers likely to be available on this platform.

New in version 1.1.0.

Changed in version 1.3.0: Renamed from get_system_resolvers() to system_resolvers(). The old name still works as an alias, but will be dropped in Stem version 2.0.0.

Parameters:	system (str) -- system to get resolvers for, this is determined by platform.system() if not provided
Returns:	list of `Resolver` instances available on this platform

Stem Docs

Connection Utilities

Connection Utilities¶