pysys.utils.allocport

Dynamic TCP port allocation.

This is used by pysys.basetest.BaseTest.getNextAvailableTCPPort which should usually be used to access this functionality.

excludedTCPPorts

pysys.utils.allocport.excludedTCPPorts = {1719, 1720, 1723, 2049, 3659, 4045, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669, 6697, 10080}

A set containing TCP server ports which will never be allocated by pysys.basetest.BaseTest.getNextAvailableTCPPort (or TCPPortOwner).

By default this contains blocked ports that some web browsers do not permit connections to for security reasons, which would therefore cause browser-driven tests to fail.

If desired you can modify this set from a custom pysys.baserunner.BaseRunner module (before the BaseRunner constructor is executed).

TCPPortOwner

class pysys.utils.allocport.TCPPortOwner(hosts=['', 'localhost'], socketAddressFamily=<AddressFamily.AF_INET: 2>)

Bases: object

Class that allocates a free server port when constructed, and returns it to the pool of available ports when cleanup is called.

Parameters

• hosts (list(Str)) – A list of the host names or IP addresses to check when establishing that a potential allocated port isn’t already in use by a process outside the PySys framework. By default we check "" (which corresponds to INADDR_ANY and depending on the OS means either one or all non-localhost IPv4 addresses) and also localhost. Many machines have multiple network cards each with its own host IP address, and typically you’ll only be using one of them in your test, most commonly localhost. If you do know which host/IP you’ll actually be using, just specify that directly to save time, and avoid needlessly opening remote ports on hosts you’re not using. A list of available host addresses and corresponding family/type/proto can be found from socket.getaddrinfo('', None).

• socketAddressFamily (int) – The address family to use when checking if the port is in use, e.g. to indicate IPv4 vs IPv6. See socket.socket in the Python standard library for more information.

Variables

port (int) – The port allocated and owned by this instance.

cleanup()

Must be called when this port is no longer needed to return it to PySys’ pool of available ports.

getEphemeralTCPPortRange

pysys.utils.allocport.getEphemeralTCPPortRange()

Returns the minimum and maximum TCP ports this operating system uses to allocate ephemeral/dynamic ports (the client side of the TCP connection).

This function is used by getServerTCPPorts() to ensure that no ephemeral/client-side ports are allocated for server-side purposes by PySys (this could cause random port clashes).

If the available server ports are overridden using the PYSYS_PORTS or PYSYS_PORTS_FILE environment variables, this function is not called.

Returns

A tuple (ephemeral_min: int, ephemeral_max: int) giving the ephemeral port range for this platform.

Raises

Exception – If the ephemeral port range cannot be determined, which will prevent PySys from running any tests.

getServerTCPPorts

pysys.utils.allocport.getServerTCPPorts()

Returns a list of the TCP ports that PySys tests can use when starting servers that listen on a port.

This function is usually called when pysys.baserunner.BaseRunner is constructed to help decide the pool of available ports that can be allocated by pysys.basetest.BaseTest.getNextAvailableTCPPort().

PySys treats all ports from 1024-65536 as server ports except for the client-side ephemeral/dynamic port range as determined by getEphemeralTCPPortRange() and specific ports in the excludedTCPPorts set. Alternatively, the set of server ports can be overridden by the following environment variables:

• PYSYS_PORTS=minport-maxport,port,... PySys will use the specified ports and/or port ranges (inclusive) allocating server ports.

• PYSYS_PORTS_FILE=file_path.txt PySys will use ports from the specified ASCII text file, one port per line.

If using these variables, be sure to avoid none of the ports reserved for ephemeral use is in the set of server ports you specify.

See logPortAllocationStats() for information about how to log statistics showing how many server ports your tests are using.

Returns

A list of all the server ports that can be used, e.g. [1024, 1025, …].

Raises

Exception – If the port range cannot be determined, which will prevent PySys from running any tests.

logPortAllocationStats

pysys.utils.allocport.logPortAllocationStats(logger=<Logger pysys.portAllocationStats (INFO)>)

Logs a DEBUG level message indicating how many server ports were allocated so far over the lifetime of this PySys process, and the peak number in use any one time.

This method is called before PySys terminates after running all tests.

To see these messages, run PySys with:

pysys run -v portAllocationStats=DEBUG