Document utilites

This commit adds docstrings to the utilities module,
the __init__ file, and the exceptions module.

Part of #7

Author: DirectXMan12

gssapi/__init__.py

@@ -5,3 +5,5 @@
 from gssapi.creds import Credentials  # noqa
 from gssapi.names import Name  # noqa
 from gssapi.sec_contexts import SecurityContext  # noqa
+
+"""The High-Level GSSAPI Wrapper"""

gssapi/_utils.py

@@ -8,6 +8,20 @@
 
 
 def import_gssapi_extension(name):
+    """Import a GSSAPI extension module
+
+    This method imports a GSSAPI extension module based
+    on the name of the extension (not including the
+    'ext_' prefix).  If the extension is not available,
+    the method retuns None.
+
+    Args:
+        name (str): the name of the extension
+
+    Returns:
+        module: Either the extension module or None
+    """
+
     try:
         path = 'gssapi.raw.ext_{0}'.format(name)
         __import__(path)
@@ -29,7 +43,20 @@ def getter(self):
     return property(getter, setter)
 
 
-def inquire_property(name):
+def inquire_property(name, doc=None):
+    """Creates a property based on an inquire result
+
+    This method creates a property that calls the
+    :python:`_inquire` method, and return the value of the
+    requested information.
+
+    Args:
+        name (str): the name of the 'inquire' result information
+
+    Returns:
+        property: the created property
+    """
+
     def inquire_property(self):
         if not self._started:
             msg = ("Cannot read {0} from a security context whose "
@@ -38,23 +65,41 @@ def inquire_property(self):
 
         return getattr(self._inquire(**{name: True}), name)
 
-    return property(inquire_property)
+    return property(inquire_property, doc=doc)
 
 
 # use UTF-8 as the default encoding, like Python 3
 _ENCODING = 'UTF-8'
 
 
 def _get_encoding():
+    """Gets the current encoding used for strings.
+
+    This value is used to encode and decode string
+    values like names.
+
+    Returns:
+        str: the current encoding
+    """
     return _ENCODING
 
 
 def set_encoding(enc):
+    """Sets the current encoding used for strings
+
+    This value is used to encode and decode string
+    values like names.
+
+    Args:
+        enc: the encoding to use
+    """
+
     global _ENCODING
     _ENCODING = enc
 
 
 def _encode_dict(d):
+    """Encodes any relevant strings in a dict"""
     def enc(x):
         if isinstance(x, six.text_type):
             return x.encode(_ENCODING)
@@ -67,6 +112,17 @@ def enc(x):
 # in case of Python 3, just use exception chaining
 @deco.decorator
 def catch_and_return_token(func, self, *args, **kwargs):
+    """Optionally defer exceptions and return a token instead
+
+    When `__DEFER_STEP_ERRORS__` is set on the implementing class
+    or instance, methods wrapped with this wrapper will
+    catch and save their :python:`GSSError` exceptions and
+    instead return the result token attached to the exception.
+
+    The exception can be later retrived through :python:`_last_err`
+    (and :python:`_last_tb` when Python 2 is in use).
+    """
+
     try:
         return func(self, *args, **kwargs)
     except GSSError as e:
@@ -85,6 +141,13 @@ def catch_and_return_token(func, self, *args, **kwargs):
 
 @deco.decorator
 def check_last_err(func, self, *args, **kwargs):
+    """Check and raise deferred errors before running the function
+
+    This method checks :python:`_last_err` before running the wrapped
+    function.  If present and not None, the exception will be raised
+    with its original traceback.
+    """
+
     if self._last_err is not None:
         try:
             if six.PY2:
@@ -115,6 +178,14 @@ def check_last_err(func, self, *args, **kwargs):
 
 
 class CheckLastError(type):
+    """Check for a deferred error on all methods
+
+    This metaclass applies the :python:`check_last_err` decorator
+    to all methods not prefixed by '_'.
+
+    Additionally, it enabled `__DEFER_STEP_ERRORS__` by default.
+    """
+
     def __new__(cls, name, parents, attrs):
         attrs['__DEFER_STEP_ERRORS__'] = True
 

gssapi/exceptions.py

@@ -1,9 +1,17 @@
 from gssapi.raw.exceptions import *  # noqa
 from gssapi.raw.misc import GSSError  # noqa
 
+"""High-Level API Errors
+
+This module includes several high-level exceptions,
+in addition to GSSError and exceptions from
+:mod:`gssapi.raw.exceptions`.
+"""
+
 
 # non-GSS exceptions
 class GeneralError(Exception):
+    """A General High-Level API Error"""
     MAJOR_MESSAGE = "General error"
     FMT_STR = "{maj}: {min}."
 
@@ -14,10 +22,12 @@ def __init__(self, minor_message, **kwargs):
 
 
 class UnknownUsageError(GeneralError):
+    """An Error indicating an unknown usage type"""
     MAJOR_MESSAGE = "Unable to determine {obj} usage"
 
 
 class EncryptionNotUsed(GeneralError):
+    """An Error indicating that encryption was requested, but not used"""
     MAJOR_MESSAGE = "Confidentiality was requested, but not used"
 
     def __init__(self, minor_message, unwrapped_message=None, **kwargs):