Registry / http-networking / portend

portend

JSON →
library3.2.1pypypi✓ verified 24d ago

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 portend
INSTALL
IMPORT
SIG · PORTEND
P
portend
http-networkingpythonv3.2.1
Install
3.3s avg
Import
229ms
Disk
30MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.246s · 33.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.3s · import 0.212s · 34MB
30MB installed
● package 30MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

portend
import portend
Most functionality is accessed directly via the 'portend' module, e.g., 'portend.occupied()'.

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.

import portend import socket import time def demo_port_usage(): # Example: Wait for an occupied port (e.g., a simple server) # Start a dummy server in a separate thread/process for this to work # For demonstration, we'll simulate a server binding/unbinding # Find a free port s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) s.bind(('localhost', 0)) port = s.getsockname()[1] s.close() print(f"Found a free port: {port}") # Simulate a process binding to the port server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) server_socket.bind(('localhost', port)) server_socket.listen(1) print(f"Server bound to localhost:{port}") # Use portend to wait for the port to be occupied print(f"Waiting for localhost:{port} to be occupied (max 5s)...") try: portend.occupied('localhost', port, timeout=5) print(f"Success: localhost:{port} is occupied.") except portend.Timeout: # Removed the direct import for Timeout as it's an attribute of portend module and was causing an error. print(f"Error: Timeout waiting for localhost:{port} to be occupied.") finally: server_socket.close() print(f"Server unbound from localhost:{port}") # Use portend to wait for the port to be free print(f"Waiting for localhost:{port} to be free (max 5s)...") try: portend.free('localhost', port, timeout=5) print(f"Success: localhost:{port} is free.") except portend.Timeout: print(f"Error: Timeout waiting for localhost:{port} to be free.") demo_port_usage()
Debug
Known issues
gotchaWhen running `portend` directly as a module (e.g., `python -m portend localhost:8080 occupied`), it exits with a status of 0 on success and 1 on failure. This is standard for command-line tools but important to note for scripting.
fix
Check the exit code (e.g., `$?` in bash) after execution, or use the library programmatically in Python for more granular error handling.
affects: >=1.2.0
gotchaThe `portend.assert_free()` function will raise a `portend.PortNotFree` exception if the specified host/port combination is already occupied by a bound listener. Ensure proper exception handling if you intend to assert a port's availability.
fix
Wrap calls to `portend.assert_free()` in a `try...except portend.PortNotFree` block to handle cases where the port is not free as expected.
affects: >=1.2.0
deprecatedIn older versions (specifically v1.2), there were 'original names' that were kept as aliases. While the current primary API (`portend.occupied`, `portend.free`, etc.) appears stable, relying on undocumented or historical aliases might lead to issues in future major versions.
fix
Always use the documented functions and methods directly from the `portend` module, such as `portend.occupied` and `portend.free`.
affects: <=1.2.x
breakingNo significant breaking changes for the core `portend` API (like `portend.occupied` or `portend.free`) between v2 and v3 are explicitly documented in the official GitHub repository or PyPI project description. Users migrating across these major versions are unlikely to encounter API breakage for core functionalities, but should review the release notes for any minor adjustments or behavioral changes.
fix
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.
affects: 3.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'portend'
The 'portend' library has not been installed in your Python environment, or the environment where you are running the code does not have it installed.
fix
Install the library using pip: `pip install portend`
portend.PortNotFree: Port 8080 on localhost is not free
The `portend.assert_free()` method was called for a specific host and port, but another process is already listening on that port, making it occupied.
fix
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)`
TypeError: 'str' object cannot be interpreted as an integer
A function expecting a port number as an integer (e.g., `portend.occupied`, `portend.free`, `portend.find_available_local_port`) received a string instead.
fix
Ensure that port numbers are passed as integer types. Example: `portend.occupied('localhost', 8000)` instead of `portend.occupied('localhost', '8000')`
Upgrade
Version history
3.2.1latest on PyPI · released May 29, 2025
Audit
Dependencies
temporarequiredProvides Python objects and routines pertaining to date and time, used internally by portend.
Agent activity
9 hits · last 30 days
node
8
Resources
portend — pip install portend · libregistry