sort imports and groom docstrings

Author: qrkourier

netfoundry/__init__.py

@@ -1,9 +1,8 @@
-""" Interface to NetFoundry API
-"""
+"""Interface to NetFoundry management API."""
 
+from . import _version
 from .network import Network
 from .network_group import NetworkGroup
 from .organization import Organization
 
-from . import _version
 __version__ = _version.get_versions()['version']

netfoundry/ctl.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
-r"""Command-line interface to the NetFoundry API
+r"""[Experimental] command-line interface to the NetFoundry API
 Usage::
     $ python3 -m netfoundry.ctl --credentials credentials.json
 
 PYTHON_ARGCOMPLETE_OK
 """
+
 import pkg_resources  # part of setuptools
 from milc import cli
 
@@ -34,4 +35,4 @@ def main(cli):
     network_group = netfoundry.NetworkGroup(Organization)
 
 if __name__ == '__main__':
-    cli()
+    cli()

netfoundry/demo.py

@@ -10,11 +10,12 @@
 import sys
 from pathlib import Path
 
-from .organization import Organization
-from .network_group import NetworkGroup
 from .network import Network
+from .network_group import NetworkGroup
+from .organization import Organization
 from .utility import DC_PROVIDERS
 
+
 def main():
     """Run the demo script."""
     print("DEBUG: running demo script in \"{:s}\"".format(sys.argv[0]))
@@ -453,4 +454,4 @@ def query_yes_no(question: str, default: str="no"):
                             "(or 'y' or 'n').\n")
 
 if __name__ == '__main__':
-    main()
+    main()

netfoundry/network.py

@@ -1,3 +1,5 @@
+"""Use a network and find and manage its resources."""
+
 import json
 import re  # regex
 import sys
@@ -7,8 +9,9 @@
 
 from .utility import (DC_PROVIDERS, EXCLUDED_PATCH_PROPERTIES, HOST_PROPERTIES,
                       MAJOR_REGIONS, RESOURCES, STATUS_CODES, VALID_SEPARATORS,
-                      VALID_SERVICE_PROTOCOLS, docstring_parameters, eprint,
-                      http, plural, singular, Utility)
+                      VALID_SERVICE_PROTOCOLS, Utility, docstring_parameters,
+                      eprint, http, plural, singular)
+
 utility = Utility()
 
 class Network:

netfoundry/network_group.py

@@ -1,6 +1,9 @@
+"""Use a network group and find its networks."""
+
 import json
 
-from .utility import (RESOURCES, STATUS_CODES, eprint, http, Utility)
+from .utility import RESOURCES, STATUS_CODES, Utility, eprint, http
+
 utility = Utility()
 
 class NetworkGroup:

netfoundry/organization.py

@@ -1,3 +1,5 @@
+"""Use an identity organization and find authorized network groups and networks."""
+
 import json
 import os
 import re  # regex
@@ -10,12 +12,15 @@
 
 
 class Organization:
-    """ Default is to use the Organization of the caller's user or API account identity
-    :param: organization_id is optional string UUID of an alternative Organization
-    :param: organization_label is optional string `label` property of an alternative Organization
-    :param token: continue using a session with this optional token from an existing instance of Organization
-    :param credentials: optional alternative path to API account credentials file, default is ~/.netfoundry/credentials.json
-    :param proxy: optional HTTP proxy, e.g., http://localhost:8080
+    """Authenticate as an identity ID in an organization.
+    
+    The default is to use the callering identity ID's organization. 
+
+    :param str organization_id: optional UUID of an alternative organization
+    :param str organization_label: is optional `label` property of an alternative organization
+    :param str token: continue using a session with this optional token from an existing instance of organization
+    :param str credentials: optional alternative path to API account credentials file, default is project, user, or device default directories containing file name credentials.json
+    :param str proxy: optional HTTP proxy, e.g., http://localhost:8080
     """
 
     def __init__(self, 
@@ -24,7 +29,7 @@ def __init__(self,
         organization_label: str=None,
         token=None, 
         proxy=None):
-
+        """Initialize an instance of Organization."""
         # verify auth endpoint's server certificate if proxy is type SOCKS or None
         self.proxy = proxy
         if proxy is None:

netfoundry/utility.py

@@ -1,21 +1,25 @@
+"""Shared helper functions, constants, and classes."""
+
 import sys  # open stderr
 import unicodedata  # case insensitive compare in Utility
 from re import sub
 
 import inflect  # singular and plural nouns
 from requests import \
     Session  # HTTP user agent will not emit server cert warnings if verify=False
-from urllib3.exceptions import InsecureRequestWarning
-
 from requests import status_codes
 from requests.adapters import HTTPAdapter
-from urllib3.util.retry import Retry
 from urllib3 import disable_warnings
+from urllib3.exceptions import InsecureRequestWarning
+from urllib3.util.retry import Retry
 
 disable_warnings(InsecureRequestWarning)
 
 class Utility:
+    """Shared functions intended for use within the module and without."""
+
     def __init__(self):
+        """No-op."""
         pass
 
     def camel(self, snake_str):
@@ -40,7 +44,8 @@ def caseless_equal(self, left, right):
         return self.normalize_caseless(left) == self.normalize_caseless(right)
 
 class LookupDict(dict):
-    """Dictionary lookup object."""
+    """Helper class to create a lookup dictionary from a set."""
+
     def __init__(self, name=None):
         """Initialize a lookup dictionary."""
         self.name = name
@@ -62,13 +67,15 @@ def eprint(*args, **kwargs):
 
 p = inflect.engine()
 def plural(singular):
+    """Pluralize a singular form."""
     # if already plural then return, else pluralize
     if singular[-1:] == 's':
         return(singular)
     else:
         return(p.plural_noun(singular))
 
 def singular(plural):
+    """Singularize a plural form."""
     return(p.singular_noun(plural))
 
 STATUSES_BY_CODE = {
@@ -170,6 +177,8 @@ def decorated(ref):
 DEFAULT_TIMEOUT = 31 # seconds, Gateway Service waits 30s before responding with an error code e.g. 503 and
 # so waiting at least 31s is necessary to obtain that information
 class TimeoutHTTPAdapter(HTTPAdapter):
+    """Configure Python requests library to have retry and timeout defaults."""
+
     def __init__(self, *args, **kwargs):
         self.timeout = DEFAULT_TIMEOUT
         if "timeout" in kwargs:
@@ -189,4 +198,4 @@ def send(self, request, **kwargs):
 http.mount("https://", adapter)
 http.mount("http://", adapter)
 
-STATUS_CODES = status_codes
+STATUS_CODES = status_codes

netfoundry/version.py

@@ -1,5 +1,6 @@
 """Print the version string."""
 from ._version import get_versions
+
 try:
     print("v"+get_versions()['version'] )
 except: