pysys.utils.allocport¶
Dynamic TCP port allocation.
This is used by the pysys.process.user.ProcessUser
class (and its subclasses e.g. BaseTest) which should
usually be used to access this functionality.
TCPPortOwner¶
-
class
pysys.utils.allocport.
TCPPortOwner
(hosts=['', 'localhost'], socketAddressFamily=<AddressFamily.AF_INET: 2>)[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()
. 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.
- Returns
A list or set 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.