Merging upstream version 0.7.2.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

7 files changed, 52 insertions, 44 deletions

diff --git a/port_for/__init__.py b/port_for/__init__.py
index 15c664d..289c396 100644
--- a/port_for/__init__.py
+++ b/port_for/__init__.py
@@ -1,19 +1,19 @@
 # -*- coding: utf-8 -*-
 """port_for package."""
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 
 from ._ranges import UNASSIGNED_RANGES
 from .api import (
     available_good_ports,
     available_ports,
-    is_available,
+    get_port,
     good_port_ranges,
+    is_available,
     port_is_used,
     select_random,
-    get_port,
 )
-from .store import PortStore
 from .exceptions import PortForException
+from .store import PortStore
 
 __all__ = (
     "UNASSIGNED_RANGES",
diff --git a/port_for/api.py b/port_for/api.py
index 4ecf9f8..c4e15e6 100644
--- a/port_for/api.py
+++ b/port_for/api.py
@@ -1,15 +1,16 @@
-# -*- coding: utf-8 -*-
+"""main port-for functionality."""
 import contextlib
-import socket
 import errno
 import random
+import socket
 from itertools import chain
-from typing import Optional, Set, List, Tuple, Iterable, TypeVar, Type, Union
+from typing import Iterable, List, Optional, Set, Tuple, Type, TypeVar, Union
+
 from port_for import ephemeral, utils
+
 from ._ranges import UNASSIGNED_RANGES
 from .exceptions import PortForException
 
-
 SYSTEM_PORT_RANGE = (0, 1024)
 
 
@@ -17,9 +18,7 @@ def select_random(
     ports: Optional[Set[int]] = None,
     exclude_ports: Optional[Iterable[int]] = None,
 ) -> int:
-    """
-    Returns random unused port number.
-    """
+    """Return random unused port number."""
     if ports is None:
         ports = available_good_ports()
 
@@ -35,9 +34,7 @@ def select_random(
 
 
 def is_available(port: int) -> bool:
-    """
-    Returns if port is good to choose.
-    """
+    """Return if port is good to choose."""
     return port in available_ports() and not port_is_used(port)
 
 
@@ -46,9 +43,12 @@ def available_ports(
     high: int = 65535,
     exclude_ranges: Optional[List[Tuple[int, int]]] = None,
 ) -> Set[int]:
-    """
-    Returns a set of possible ports (excluding system,
-    ephemeral and well-known ports).
+    """Return a set of possible ports.
+
+    .. note::
+
+        Excluding system, ephemeral and well-known ports.
+
     Pass ``high`` and/or ``low`` to limit the port range.
     """
     if exclude_ranges is None:
@@ -74,8 +74,8 @@ def available_ports(
 def good_port_ranges(
     ports: Optional[Set[int]] = None, min_range_len: int = 20, border: int = 3
 ) -> List[Tuple[int, int]]:
-    """
-    Returns a list of 'good' port ranges.
+    """Return a list of 'good' port ranges.
+
     Such ranges are large and don't contain ephemeral or well-known ports.
     Ranges borders are also excluded.
     """
@@ -94,14 +94,16 @@ def good_port_ranges(
 
 
 def available_good_ports(min_range_len: int = 20, border: int = 3) -> Set[int]:
+    """List available good ports."""
     return utils.ranges_to_set(
         good_port_ranges(min_range_len=min_range_len, border=border)
     )
 
 
 def port_is_used(port: int, host: str = "127.0.0.1") -> bool:
-    """
-    Returns if port is used. Port is considered used if the current process
+    """Return if port is used.
+
+    Port is considered used if the current process
     can't bind to it or the port doesn't refuse connections.
     """
     unused = _can_bind(port, host) and _refuses_connection(port, host)
@@ -130,7 +132,7 @@ T = TypeVar("T")
 
 
 def filter_by_type(lst: Iterable, type_of: Type[T]) -> List[T]:
-    """Returns a list of elements with given type."""
+    """Return a list of elements with given type."""
     return [e for e in lst if isinstance(e, type_of)]
 
 
@@ -152,9 +154,10 @@ def get_port(
     ports: Optional[PortType],
     exclude_ports: Optional[Iterable[int]] = None,
 ) -> Optional[int]:
-    """
-    Retuns a random available port. If there's only one port passed
-    (e.g. 5000 or '5000') function does not check if port is available.
+    """Retun a random available port.
+
+    If there's only one port passed (e.g. 5000 or '5000') function
+    does not check if port is available.
     If there's -1 passed as an argument, function returns None.
 
     :param ports:
diff --git a/port_for/cmd.py b/port_for/cmd.py
index be28902..ba9add7 100644
--- a/port_for/cmd.py
+++ b/port_for/cmd.py
@@ -1,6 +1,5 @@
 #!/usr/bin/env python
-"""
-cmd.py is a command-line utility that helps with local TCP ports management.
+"""cmd.py is a command-line utility that helps with local TCP ports management.
 
 It finds 'good' unused TCP localhost port and remembers the association.
 
@@ -26,6 +25,7 @@ Options:
 
 import sys
 from typing import Optional
+
 import port_for
 from port_for.docopt import docopt
 
diff --git a/port_for/ephemeral.py b/port_for/ephemeral.py
index a3c03ec..41a4685 100644
--- a/port_for/ephemeral.py
+++ b/port_for/ephemeral.py
@@ -1,21 +1,19 @@
 # -*- coding: utf-8 -*-
-"""
-This module provide utilities to find ephemeral port ranges for the current OS.
+"""Module provide utilities to find ephemeral port ranges for the current OS.
+
 See http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html for more info
 about ephemeral port ranges.
 
 Currently only Linux and BSD (including OS X) are supported.
 """
 import subprocess
-from typing import List, Tuple, Dict
+from typing import Dict, List, Tuple
 
 DEFAULT_EPHEMERAL_PORT_RANGE = (32768, 65535)
 
 
 def port_ranges() -> List[Tuple[int, int]]:
-    """
-    Returns a list of ephemeral port ranges for current machine.
-    """
+    """Return a list of ephemeral port ranges for current machine."""
     try:
         return _linux_ranges()
     except (OSError, IOError):  # not linux, try BSD
diff --git a/port_for/exceptions.py b/port_for/exceptions.py
index 256a255..dc03591 100644
--- a/port_for/exceptions.py
+++ b/port_for/exceptions.py
@@ -1,3 +1,7 @@
-# -*- coding: utf-8 -*-
+"""Port-for exceptions."""
+
+
 class PortForException(Exception):
+    """Main port-for exception class."""
+
     pass
diff --git a/port_for/store.py b/port_for/store.py
index a07b737..685753c 100644
--- a/port_for/store.py
+++ b/port_for/store.py
@@ -1,22 +1,25 @@
-# -*- coding: utf-8 -*-
+"""PortStore implementation."""
 import os
-from configparser import ConfigParser, DEFAULTSECT
-from typing import Optional, List, Tuple, Union
+from configparser import DEFAULTSECT, ConfigParser
+from typing import List, Optional, Tuple, Union
 
 from .api import select_random
 from .exceptions import PortForException
 
-
 DEFAULT_CONFIG_PATH = "/etc/port-for.conf"
 
 
 class PortStore(object):
+    """PortStore binds, reads and stores bound ports in config."""
+
     def __init__(self, config_filename: str = DEFAULT_CONFIG_PATH):
+        """Initialize PortStore."""
         self._config = config_filename
 
     def bind_port(
         self, app: str, port: Optional[Union[int, str]] = None
     ) -> int:
+        """Binds port to app in the config."""
         if "=" in app or ":" in app:
             raise Exception('invalid app name: "%s"' % app)
 
@@ -61,11 +64,13 @@ class PortStore(object):
         return int(requested_port)
 
     def unbind_port(self, app: str) -> None:
+        """Remove port assignement to application."""
         parser = self._get_parser()
         parser.remove_option(DEFAULTSECT, app)
         self._save(parser)
 
     def bound_ports(self) -> List[Tuple[str, int]]:
+        """List all bound ports."""
         return [
             (app, int(port))
             for app, port in self._get_parser().items(DEFAULTSECT)
diff --git a/port_for/utils.py b/port_for/utils.py
index 361d5c0..997f63a 100644
--- a/port_for/utils.py
+++ b/port_for/utils.py
@@ -1,11 +1,10 @@
-# -*- coding: utf-8 -*-
+"""Port for utils."""
 import itertools
-from typing import Iterable, Iterator, Tuple, Set
+from typing import Iterable, Iterator, Set, Tuple
 
 
 def ranges_to_set(lst: Iterable[Tuple[int, int]]) -> Set[int]:
-    """
-    Convert a list of ranges to a set of numbers::
+    """Convert a list of ranges to a set of numbers.
 
     >>> ranges = [(1,3), (5,6)]
     >>> sorted(list(ranges_to_set(ranges)))
@@ -16,8 +15,7 @@ def ranges_to_set(lst: Iterable[Tuple[int, int]]) -> Set[int]:
 
 
 def to_ranges(lst: Iterable[int]) -> Iterator[Tuple[int, int]]:
-    """
-    Convert a list of numbers to a list of ranges::
+    """Convert a list of numbers to a list of ranges.
 
     >>> numbers = [1,2,3,5,6]
     >>> list(to_ranges(numbers))