From e9faffbd1287aec48b074c1966ca943a01a19ba4 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Mon, 24 May 2021 15:32:59 -0700 Subject: Add GH action badge, describe py2, reformat. --- README.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 436fbe6..d24cf26 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,22 @@ # Python portpicker module [![PyPI version](https://badge.fury.io/py/portpicker.svg)](https://badge.fury.io/py/portpicker) -[![Build Status](https://travis-ci.org/google/python_portpicker.svg?branch=master)](https://travis-ci.org/google/python_portpicker) +![GH Action Status](https://github.com/github/docs/actions/workflows/main.yml/badge.svg) +[![Travis CI org Status](https://travis-ci.org/google/python_portpicker.svg?branch=master)](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: -- cgit v1.2.3