Use pep8_style function names. Keep compatibility.
Updates version to 1.1.0 and adds a change log.
diff --git a/ChangeLog.md b/ChangeLog.md
new file mode 100644
index 0000000..de8628d
--- /dev/null
+++ b/ChangeLog.md
@@ -0,0 +1,14 @@
+## 1.1.0
+
+* Renamed portpicker APIs to use PEP8 style function names in code and docs.
+* Legacy CapWords API name compatibility is maintained (and explicitly tested).
+
+## 1.0.1
+
+* Code reindented to use 4 space indents and run through
+ [YAPF](https://github.com/google/yapf) for consistent style.
+* Not packaged for release.
+
+## 1.0.0
+
+* Original open source release.
diff --git a/README.md b/README.md
index 029febf..ec1f7c6 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
This module is useful finding unused network ports on a host.
It supports both Python 2 and Python 3.
-It provides a Python implementation of PickUnusedPort.
+This module provides a pure Python `pick_unused_port()` function.
It can also be called via the command line for use in shell scripts.
If your code can accept a bound TCP socket rather than a port number consider
@@ -14,7 +14,7 @@
binding to it. The use of a port server by all of your test code to avoid
that problem is recommended on loaded test hosts running many tests at a time.
-Unless you are using a port server, subsequent calls to PickUnusedPort() to
+Unless you are using a port server, subsequent calls to `pick_unused_port()` to
obtain an additional port are not guaranteed to return a unique port.
### What is the optional port server?
@@ -41,7 +41,7 @@
```python
import portpicker
-test_port = portpicker.PickUnusedPort()
+test_port = portpicker.pick_unused_port()
```
Or from the command line:
diff --git a/setup.py b/setup.py
index 52a22c5..744ed93 100644
--- a/setup.py
+++ b/setup.py
@@ -33,7 +33,7 @@
distutils.core.setup(
name='portpicker',
- version='1.0.1',
+ version='1.1.0',
description='A library to choose unique available network ports.',
long_description=textwrap.dedent("""\
Portpicker provides an API to find and return an available network
diff --git a/src/portpicker.py b/src/portpicker.py
index ae12b07..a77869e 100644
--- a/src/portpicker.py
+++ b/src/portpicker.py
@@ -16,7 +16,7 @@
#
"""Pure python code for finding unused ports on a host.
-This module provides a pure python implementation of PickUnusedPort.
+This module provides a pick_unused_port() function.
It can also be called via the command line for use in shell scripts.
When called from the command line, it takes one optional argument, which,
if given, is sent to portserver instead of portpicker's PID.
@@ -32,7 +32,7 @@
available port without a race condition rather than using this library.
Typical usage:
- test_port = portpicker.PickUnusedPort()
+ test_port = portpicker.pick_unused_port()
"""
from __future__ import print_function
@@ -41,11 +41,15 @@
import socket
import sys
+# The legacy Bind, IsPortFree, etc. names are not exported.
+__all__ = ('bind', 'is_port_free', 'pick_unused_port',
+ 'get_port_from_port_server')
+
_PROTOS = [(socket.SOCK_STREAM, socket.IPPROTO_TCP),
(socket.SOCK_DGRAM, socket.IPPROTO_UDP)]
-def Bind(port, socket_type, socket_proto):
+def bind(port, socket_type, socket_proto):
"""Try to bind to a socket of the specified type, protocol, and port.
This is primarily a helper function for PickUnusedPort, used to see
@@ -59,19 +63,20 @@
Returns:
The port number on success or None on failure.
"""
- s = socket.socket(socket.AF_INET, socket_type, socket_proto)
+ sock = socket.socket(socket.AF_INET, socket_type, socket_proto)
try:
- try:
- s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- s.bind(('', port))
- return s.getsockname()[1]
- except socket.error:
- return None
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ sock.bind(('', port))
+ return sock.getsockname()[1]
+ except socket.error:
+ return None
finally:
- s.close()
+ sock.close()
+
+Bind = bind # legacy API. pylint: disable=invalid-name
-def IsPortFree(port):
+def is_port_free(port):
"""Check if specified port is free.
Args:
@@ -79,11 +84,13 @@
Returns:
boolean, whether it is free to use for both TCP and UDP
"""
- return (Bind(port, _PROTOS[0][0], _PROTOS[0][1]) and
- Bind(port, _PROTOS[1][0], _PROTOS[1][1]))
+ return (bind(port, _PROTOS[0][0], _PROTOS[0][1]) and
+ bind(port, _PROTOS[1][0], _PROTOS[1][1]))
+
+IsPortFree = is_port_free # legacy API. pylint: disable=invalid-name
-def PickUnusedPort(pid=None):
+def pick_unused_port(pid=None):
"""A pure python implementation of PickUnusedPort.
Args:
@@ -97,14 +104,17 @@
port = None
# Provide access to the portserver on an opt-in basis.
if 'PORTSERVER_ADDRESS' in os.environ:
- port = GetPortFromPortServer(os.environ['PORTSERVER_ADDRESS'], pid=pid)
+ port = get_port_from_port_server(os.environ['PORTSERVER_ADDRESS'],
+ pid=pid)
if not port:
- return _PickUnusedPortWithoutServer()
+ return _pick_unused_port_without_server()
return port
+PickUnusedPort = pick_unused_port # legacy API. pylint: disable=invalid-name
-def _PickUnusedPortWithoutServer():
- """A pure python implementation of PickUnusedPort_NoServer().
+
+def _pick_unused_port_without_server(): # Protected. pylint: disable=invalid-name
+ """Pick an available network port without the help of a port server.
This code ensures that the port is available on both TCP and UDP.
@@ -115,10 +125,10 @@
A port number that is unused on both TCP and UDP. None on error.
"""
# Try random ports first.
- r = random.Random()
+ rng = random.Random()
for _ in range(10):
- port = int(r.randrange(32768, 60000))
- if IsPortFree(port):
+ port = int(rng.randrange(32768, 60000))
+ if is_port_free(port):
return port
# Try OS-assigned ports next.
@@ -126,21 +136,21 @@
# returns the same port over and over. So always try TCP first.
while True:
# Ask the OS for an unused port.
- port = Bind(0, _PROTOS[0][0], _PROTOS[0][1])
+ port = bind(0, _PROTOS[0][0], _PROTOS[0][1])
# Check if this port is unused on the other protocol.
- if port and Bind(port, _PROTOS[1][0], _PROTOS[1][1]):
+ if port and bind(port, _PROTOS[1][0], _PROTOS[1][1]):
return port
-def GetPortFromPortServer(portserver_address, pid=None):
+def get_port_from_port_server(portserver_address, pid=None):
"""Request a free a port from a system-wide portserver.
This follows a very simple portserver protocol:
The request consists of our pid (in ASCII) followed by a newline.
The response is a port number and a newline, 0 on failure.
- This function is an implementation detail of PickUnusedPort(), and
- should not normally be called by code outside of this module.
+ This function is an implementation detail of pick_unused_port().
+ It should not normally be called by code outside of this module.
Args:
portserver_address: The address (path) of a unix domain socket
@@ -189,11 +199,16 @@
print('Portserver failed to find a port.', file=sys.stderr)
return None
+GetPortFromPortServer = get_port_from_port_server # legacy API. pylint: disable=invalid-name
-if __name__ == '__main__':
- # If passed an argument, cast it to int and treat it as a PID, otherwise pass
- # pid=None to use portpicker's PID.
- port = PickUnusedPort(pid=int(sys.argv[1]) if len(sys.argv) > 1 else None)
+
+def main(argv):
+ """If passed an arg, treat it as a PID, otherwise portpicker uses getpid."""
+ port = pick_unused_port(pid=int(argv[1]) if len(argv) > 1 else None)
if not port:
sys.exit(1)
print(port)
+
+
+if __name__ == '__main__':
+ main(sys.argv)
diff --git a/src/tests/portpicker_test.py b/src/tests/portpicker_test.py
index 885ac4a..daabb41 100644
--- a/src/tests/portpicker_test.py
+++ b/src/tests/portpicker_test.py
@@ -38,13 +38,13 @@
return self._bind(port, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
def setUp(self):
- # So we can Bind even if portpicker.Bind is stubbed out.
- self._bind = portpicker.Bind
+ # So we can Bind even if portpicker.bind is stubbed out.
+ self._bind = portpicker.bind
def testPickUnusedPortActuallyWorks(self):
"""This test can be flaky."""
for _ in range(10):
- port = portpicker.PickUnusedPort()
+ port = portpicker.pick_unused_port()
self.assertTrue(self.IsUnusedTCPPort(port))
self.assertTrue(self.IsUnusedUDPPort(port))
@@ -52,23 +52,23 @@
'no port server to test against')
def testPickUnusedCanSuccessfullyUsePortServer(self):
- with mock.patch.object(portpicker, '_PickUnusedPortWithoutServer'):
- portpicker._PickUnusedPortWithoutServer.side_effect = (
+ with mock.patch.object(portpicker, '_pick_unused_port_without_server'):
+ portpicker._pick_unused_port_without_server.side_effect = (
Exception('eek!')
)
# Since _PickUnusedPortWithoutServer() raises an exception, if we
# can successfully obtain a port, the portserver must be working.
- port = portpicker.PickUnusedPort()
+ port = portpicker.pick_unused_port()
self.assertTrue(self.IsUnusedTCPPort(port))
self.assertTrue(self.IsUnusedUDPPort(port))
@unittest.skipIf('PORTSERVER_ADDRESS' not in os.environ,
'no port server to test against')
def testGetPortFromPortServer(self):
- """Exercise the GetPortFromPortServer() helper function."""
+ """Exercise the get_port_from_port_server() helper function."""
for _ in range(10):
- port = portpicker.GetPortFromPortServer(
+ port = portpicker.get_port_from_port_server(
os.environ['PORTSERVER_ADDRESS'])
self.assertTrue(self.IsUnusedTCPPort(port))
self.assertTrue(self.IsUnusedUDPPort(port))
@@ -77,7 +77,7 @@
server = mock.Mock()
server.recv.return_value = b'42768\n'
with mock.patch.object(socket, 'socket', return_value=server):
- port = portpicker.GetPortFromPortServer('portserver', pid=1234)
+ port = portpicker.get_port_from_port_server('portserver', pid=1234)
server.sendall.assert_called_once_with(b'1234\n')
self.assertEqual(port, 42768)
@@ -86,7 +86,7 @@
server.recv.return_value = b'52768\n'
with mock.patch.object(socket, 'socket', return_value=server):
with mock.patch.object(os, 'getpid', return_value=9876):
- port = portpicker.GetPortFromPortServer('portserver')
+ port = portpicker.get_port_from_port_server('portserver')
server.sendall.assert_called_once_with(b'9876\n')
self.assertEqual(port, 52768)
@@ -96,14 +96,14 @@
# port picking code, but may never hit the "OS assigns a port"
# code.
for _ in range(100):
- port = portpicker._PickUnusedPortWithoutServer()
+ port = portpicker._pick_unused_port_without_server()
self.assertTrue(self.IsUnusedTCPPort(port))
self.assertTrue(self.IsUnusedUDPPort(port))
def testOSAssignedPorts(self):
self.last_assigned_port = None
- def ErrorForExplicitPorts(port, socket_type, socket_proto):
+ def error_for_explicit_ports(port, socket_type, socket_proto):
# Only successfully return a port if an OS-assigned port is
# requested, or if we're checking that the last OS-assigned port
# is unused on the other protocol.
@@ -114,16 +114,16 @@
else:
return None
- with mock.patch.object(portpicker, 'Bind', ErrorForExplicitPorts):
+ with mock.patch.object(portpicker, 'bind', error_for_explicit_ports):
for _ in range(100):
- port = portpicker._PickUnusedPortWithoutServer()
+ port = portpicker._pick_unused_port_without_server()
self.assertTrue(self.IsUnusedTCPPort(port))
self.assertTrue(self.IsUnusedUDPPort(port))
def testPickPortsWithError(self):
r = random.Random()
- def BindWithError(port, socket_type, socket_proto):
+ def bind_with_error(port, socket_type, socket_proto):
# 95% failure rate means both port picking methods will be
# exercised.
if int(r.uniform(0, 20)) == 0:
@@ -131,12 +131,20 @@
else:
return None
- with mock.patch.object(portpicker, 'Bind', BindWithError):
+ with mock.patch.object(portpicker, 'bind', bind_with_error):
for _ in range(100):
- port = portpicker._PickUnusedPortWithoutServer()
+ port = portpicker._pick_unused_port_without_server()
self.assertTrue(self.IsUnusedTCPPort(port))
self.assertTrue(self.IsUnusedUDPPort(port))
+ def testThatLegacyCapWordsAPIsExist(self):
+ """The original APIs were CapWords style, 1.1 added PEP8 names."""
+ self.assertEqual(portpicker.bind, portpicker.Bind)
+ self.assertEqual(portpicker.is_port_free, portpicker.IsPortFree)
+ self.assertEqual(portpicker.pick_unused_port, portpicker.PickUnusedPort)
+ self.assertEqual(portpicker.get_port_from_port_server,
+ portpicker.GetPortFromPortServer)
+
if __name__ == '__main__':
unittest.main()
