Skip to main content

Utility that helps with local TCP ports management. It can find an unused TCP localhost port and remember the association.

Project description

PyPI Version Code Coverage

port-for is a command-line utility and a python library that helps with local TCP ports management.

It can find an unused TCP localhost port and remember the association:

$ sudo port-for foo
37987

This can be useful when you are installing a stack of software with multiple parts needing port numbers.

There are several rules port-for is trying to follow to find and return a new unused port:

  1. Port must be unused: port-for checks this by trying to connect to the port and to bind to it.

  2. Port must be IANA unassigned and otherwise not well-known: this is acheived by maintaining unassigned ports list (parsed from IANA and Wikipedia).

  3. Port shouldn’t be inside ephemeral port range. This is important because ports from ephemeral port range can be assigned temporary by OS (e.g. by machine’s IP stack) and this may prevent service restart in some circumstances. port-for doesn’t return ports from ephemeral port ranges configured at the current machine.

  4. Other heuristics are also applied: port-for tries to return a port from larger port ranges; it also doesn’t return ports that are too close to well-known ports.

Installation

System-wide using easy_install (something like python-setuptools should be installed):

sudo pip install port-for

or:

sudo easy_install port-for

or inside a virtualenv:

pip install port-for

Script usage

port-for <foo> script finds an unused port and associates it with <foo>. Subsequent calls return the same port number.

This utility doesn’t actually bind the port or otherwise prevents the port from being taken by another software. It tries to select a port that is less likely to be used by another software (and that is unused at the time of calling of course). Utility also makes sure that port-for bar won’t return the same port as port-for foo on the same machine.

$ sudo port-for foo
37987

$ port-for foo
37987

You may want to develop some naming conventions (e.g. prefix your app names) in order to enable multiple sites on the same server:

$ sudo port-for example.com/apache
35456

Please note that port-for script requires read and write access to /etc/port-for.conf. This usually means regular users can read port values but sudo is required to associate a new port.

List all associated ports:

$ port-for --list
foo: 37987
example.com/apache: 35456

Remove an association:

$ sudo port-for --unbind foo
$ port-for --list
example.com/apache: 35456

Library usage

>>> import port_for
>>> port_for.select_random()
37774

>>> port_for.select_random()
48324

>>> 80 in port_for.available_good_ports()
False

>>> port_for.get_port()
34455

>>> port_for.get_port("1234")
1234

>>> port_for.get_port((2000, 3000))
2345

>>> port_for.get_port({4001, 4003, 4005})
4005

>>> port_for.get_port([{4000, 4001}, (4100, 4200)])
4111

Dig into source code for more.

Contributing

Development happens at github: https://github.com/kmike/port-for/

Issue tracker: https://github.com/kmike/port-for/issues/new

Release

Install pipenv and –dev dependencies first, Then run:

pipenv run tbump [NEW_VERSION]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

port-for-0.6.3.tar.gz (22.9 kB view details)

Uploaded Source

Built Distribution

port_for-0.6.3-py3-none-any.whl (21.2 kB view details)

Uploaded Python 3

File details

Details for the file port-for-0.6.3.tar.gz.

File metadata

  • Download URL: port-for-0.6.3.tar.gz
  • Upload date:
  • Size: 22.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.1

File hashes

Hashes for port-for-0.6.3.tar.gz
Algorithm Hash digest
SHA256 232bd999015b7fbdf19f90f3a9298cc742252d67650108123940bfc75c6f4d4e
MD5 08cf298b0cfa7d2f0810c974dc8adc41
BLAKE2b-256 13834afa8435dbd55cf00d7f02c9aef77ef6696cbcb6d3f09de3501e169eea45

See more details on using hashes here.

File details

Details for the file port_for-0.6.3-py3-none-any.whl.

File metadata

  • Download URL: port_for-0.6.3-py3-none-any.whl
  • Upload date:
  • Size: 21.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.1

File hashes

Hashes for port_for-0.6.3-py3-none-any.whl
Algorithm Hash digest
SHA256 31860afde6cb552e1830c927def3288350c8fbbe9aea8aed8150ed9d1aa0de81
MD5 1bf7e950093b0c7f0bc6f2126aaf5196
BLAKE2b-256 8b91e7cda315901f71b23535f9c6c193fe70237931a5e80b6e3ba709b5732d5c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page