Metadata-Version: 1.0
Name: port-for
Version: 0.1
Summary: Utility that helps with local TCP ports managment. It can find an unused TCP localhost port and remember the association.
Home-page: https://github.com/kmike/port-for/
Author: Mikhail Korobov
Author-email: kmike84@gmail.com
License: MIT license
Description: ========
        port-for
        ========
        
        ``port-for`` is a command-line utility and a python library that
        helps with local TCP ports managment.
        
        It can find an unused TCP localhost port and remember the association.
        
        This can be useful when you are installing a stack of software
        with multiple parts needing port numbers.
        
        .. note::
        
            If you're looking for a temporary port then ``socket.bind((host, 0))``
            is your best bet::
        
                >>> import socket
                >>> s = socket.socket()
                >>> s.bind(("", 0))
                >>> s.getsockname()
                ('0.0.0.0', 54485)
        
            ``port-for`` is necessary when you need persistent free local port number.
        
            ``port-for`` is the exact opposite of ``s.bind((host, 0))``
            is sense that it shouldn't return ports that ``s.bind((host, 0))``
            may return (because such ports are likely to be temporary reassigned by OS).
        
        
        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.
           gimme_port 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::
        
            sudo easy_install port-for
        
        
        Script usage
        ============
        
        ``port-for <foo>`` script finds an unused port and associates
        it with ``<foo>``. Subsequent calls will 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 however 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
        
            $ sudo port-for foo
            37987
        
        You may also want to prefix your app name::
        
            $ sudo port-for instance1.apache
            35456
        
        Please note that ``port-for`` script requires read and write access
        to ``/etc/port-for.conf`` so sudo may be necessary in order to run it.
        
        Library usage
        =============
        
        ::
        
            >>> import port_for
            >>> port_for.select_random()
            37774
        
            >>> port_for.select_random()
            48324
        
            >>> 80 in port_for.available_good_ports()
            False
        
        Dig into source code for more.
        
        Contributing
        ============
        
        Development happens at github and bitbucket:
        
        * https://github.com/kmike/port-for/
        * https://bitbucket.org/kmike/port-for/
        
        The issue tracker is at github: https://github.com/kmike/port-for/issues/new
        
        In order to run tests make sure you have `tox <http://tox.testrun.org/>`_
        installed, then type
        
        ::
        
            tox
        
        from the source checkout.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Operating System :: POSIX
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
