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
(orTCPPortOwner
).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 theBaseRunner
constructor is executed).
TCPPortOwner¶
- class pysys.utils.allocport.TCPPortOwner(hosts=['', 'localhost'], socketAddressFamily=AddressFamily.AF_INET)[source]¶
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 toINADDR_ANY
and depending on the OS means either one or all non-localhost IPv4 addresses) and alsolocalhost
. 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 commonlylocalhost
. 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 fromsocket.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.
getEphemeralTCPPortRange¶
- pysys.utils.allocport.getEphemeralTCPPortRange()[source]¶
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
orPYSYS_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()[source]¶
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 bypysys.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 theexcludedTCPPorts
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)>)[source]¶
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