Have exception name end in Error; Update the docs.
Update the docstrings and changelog, have the new exception name
end in Error rather than Exception.
diff --git a/ChangeLog.md b/ChangeLog.md
index 84f2483..6adc8d4 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -2,8 +2,10 @@
* Adds an optional `portserver_address` parameter to `pick_unused_port()` so
that callers can specify their own regardless of `os.environ`.
-* Fall back to `AF_INET` when `AF_UNIX` is not available to communicate with
- a portserver.
+* `pick_unused_port()` now raises `NoFreePortFoundError` when no available port
+ could be found rather than spinning in a loop trying forever.
+* Fall back to `socket.AF_INET` when `socket.AF_UNIX` support is not available
+ to communicate with a portserver.
## 1.2.0
diff --git a/src/portpicker.py b/src/portpicker.py
index cd92952..7636733 100644
--- a/src/portpicker.py
+++ b/src/portpicker.py
@@ -61,7 +61,7 @@
_random_ports = set()
-class NoFreePortFoundException(Exception):
+class NoFreePortFoundError(Exception):
"""Exception indicating that no free port could be found."""
pass
@@ -145,17 +145,18 @@
pid: PID to tell the portserver to associate the reservation with. If
None, the current process's PID is used.
portserver_address: The address (path) of a unix domain socket
- with which to connect to a portserver. A leading '@'
- character indicates an address in the "abstract namespace." If
- None, or no port is returned by the portserver at the provided
+ with which to connect to a portserver, a leading '@'
+ character indicates an address in the "abstract namespace". OR
+ On systems without socket.AF_UNIX, this is an AF_INET address.
+ If None, or no port is returned by the portserver at the provided
address, the environment will be checked for a PORTSERVER_ADDRESS
- variable. If that's not set, no port server will be used.
+ variable. If that is not set, no port server will be used.
Returns:
A port number that is unused on both TCP and UDP.
Raises:
- NoFreePortFoundException: No free port could be found.
+ NoFreePortFoundError: No free port could be found.
"""
if _free_ports:
port = _free_ports.pop()
@@ -188,7 +189,7 @@
A port number that is unused on both TCP and UDP.
Raises:
- NoFreePortFoundException: No free port could be found.
+ NoFreePortFoundError: No free port could be found.
"""
# Try random ports first.
rng = random.Random()
@@ -210,7 +211,7 @@
return port
# Give up.
- raise NoFreePortFoundException()
+ raise NoFreePortFoundError()
def get_port_from_port_server(portserver_address, pid=None):
@@ -227,6 +228,7 @@
portserver_address: The address (path) of a unix domain socket
with which to connect to the portserver. A leading '@'
character indicates an address in the "abstract namespace."
+ On systems without socket.AF_UNIX, this is an AF_INET address.
pid: The PID to tell the portserver to associate the reservation with.
If None, the current process's PID is used.
diff --git a/src/tests/portpicker_test.py b/src/tests/portpicker_test.py
index 8220ca0..ccc5500 100644
--- a/src/tests/portpicker_test.py
+++ b/src/tests/portpicker_test.py
@@ -205,7 +205,7 @@
for _ in range(100):
try:
port = portpicker._pick_unused_port_without_server()
- except portpicker.NoFreePortFoundException:
+ except portpicker.NoFreePortFoundError:
continue
else:
got_at_least_one_port = True
