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

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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
