import socket def find_available_port( preferred_port: int | None = None, host: str = "127.0.0.1", ) -> int: """Return an available TCP port on the given host. The preferred port is returned when available. Otherwise, the operating system selects an available ephemeral port. """ if preferred_port is not None: if not 1 <= preferred_port <= 65535: raise ValueError("preferred_port must be between 1 and 65535") with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock: try: sock.bind((host, preferred_port)) except OSError: pass else: return preferred_port with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock: sock.bind((host, 0)) return int(sock.getsockname()[1])