diff options
| author | Gregory P. Smith [Google LLC] <gps@google.com> | 2021-05-24 15:32:59 -0700 |
|---|---|---|
| committer | Gregory P. Smith [Google LLC] <gps@google.com> | 2021-05-24 15:32:59 -0700 |
| commit | e9faffbd1287aec48b074c1966ca943a01a19ba4 (patch) | |
| tree | 5d5a523765a2c33d16172dc366c32b718077bf94 | |
| parent | c33bdd51b8d2e0a24b05a17b8e9b2192f0977dc8 (diff) | |
| download | portpicker-e9faffbd1287aec48b074c1966ca943a01a19ba4.tar.gz | |
Add GH action badge, describe py2, reformat.
| -rw-r--r-- | README.md | 39 |
1 files changed, 20 insertions, 19 deletions
@@ -1,21 +1,22 @@ # Python portpicker module [](https://badge.fury.io/py/portpicker) -[](https://travis-ci.org/google/python_portpicker) + +[](https://travis-ci.org/google/python_portpicker) -This module is useful for finding unused network ports on a host. -It supports both Python 2 and Python 3. +This module is useful for finding unused network ports on a host. If you need +legacy Python 2 support, use the 1.3.x releases. -This module provides a pure Python `pick_unused_port()` function. -It can also be called via the command line for use in shell scripts. +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 using `socket.bind(('localhost', 0))` to bind atomically to an available port rather than using this library at all. There is a race condition between picking a port and your application code -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. +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 `pick_unused_port()` to obtain an additional port are not guaranteed to return a unique port. @@ -23,22 +24,22 @@ obtain an additional port are not guaranteed to return a unique port. ### What is the optional port server? A port server is intended to be run as a daemon, for use by all processes -running on the host. It coordinates uses of network ports by anything using -a portpicker library. If you are using hosts as part of a test automation -cluster, each one should run a port server as a daemon. You should set the +running on the host. It coordinates uses of network ports by anything using a +portpicker library. If you are using hosts as part of a test automation cluster, +each one should run a port server as a daemon. You should set the `PORTSERVER_ADDRESS=@unittest-portserver` environment variable on all of your test runners so that portpicker makes use of it. -A sample port server is included. This portserver implementation works but has -not spent time in production. If you use it with good results please report -back so that this statement can be updated to reflect that. :) +A sample port server is included. This portserver implementation works but has +not spent time in production. If you use it with good results please report back +so that this statement can be updated to reflect that. :) -A port server listens on a unix socket, reads a pid from a new connection, -tests the ports it is managing and replies with a port assignment port for that -pid. A port is only reclaimed for potential reassignment to another process -after the process it was originally assigned to has died. Processes that need -multiple ports can simply issue multiple requests and are guaranteed they will -each be unique. +A port server listens on a unix socket, reads a pid from a new connection, tests +the ports it is managing and replies with a port assignment port for that pid. A +port is only reclaimed for potential reassignment to another process after the +process it was originally assigned to has died. Processes that need multiple +ports can simply issue multiple requests and are guaranteed they will each be +unique. ## Typical usage: |