Portend is a Python library for TCP port monitoring and discovery. It provides routines to wait for a port to become free or occupied, check the current state of a port, or identify a suitable port available for binding locally. The library is currently at version 3.2.1 and is actively maintained with a stable release cadence.
pip install portendVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to use `portend.occupied` to wait for a port to become active and `portend.free` to wait for a port to be released. It includes a simple simulation of a server binding and unbinding a port.
Check the exit code (e.g., `$?` in bash) after execution, or use the library programmatically in Python for more granular error handling.
Wrap calls to `portend.assert_free()` in a `try...except portend.PortNotFree` block to handle cases where the port is not free as expected.
Always use the documented functions and methods directly from the `portend` module, such as `portend.occupied` and `portend.free`.
Review the brief release notes for version 3.0.0 and subsequent releases on GitHub (github.com/jaraco/portend/releases) for any subtle changes, although none appear to impact the core usage patterns. Ensure `tempora` is installed as a dependency.
Install the library using pip: `pip install portend`
Ensure the specified port is not in use by another application before calling `portend.assert_free()`, or use `portend.wait_for_free()` to block until it becomes free. Example: `import portend; portend.wait_for_free('localhost', 8080, timeout=10)`Ensure that port numbers are passed as integer types. Example: `portend.occupied('localhost', 8000)` instead of `portend.occupied('localhost', '8000')`