updated front matter and other documentation

4 files changed, 54 insertions, 32 deletions

diff --git a/passlib/apache.py b/passlib/apache.py
index cd95990..b1c4a47 100644
--- a/passlib/apache.py
+++ b/passlib/apache.py
@@ -1,4 +1,5 @@
 """passlib.apache - apache password support"""
+# XXX: relocate this to passlib.ext.apache?
 #=========================================================
 #imports
 #=========================================================
@@ -109,8 +110,9 @@ class _CommonFile(object):
     def from_string(cls, data, **kwds):
         """create new object from raw string.
 
+        :type data: unicode or bytes
         :arg data:
-            unicode or bytes string to load
+            database to load, as single string.
 
         :param \*\*kwds:
             all other keywords are the same as in the class constructor
@@ -125,6 +127,7 @@ class _CommonFile(object):
     def from_path(cls, path, **kwds):
         """create new object from file, without binding object to file.
 
+        :type path: str
         :arg path:
             local filepath to load from
 
@@ -212,8 +215,10 @@ class _CommonFile(object):
         """Load state from local file.
         If no path is specified, attempts to load from ``self.path``.
 
+        :type path: str
         :arg path: local file to load from
 
+        :type force: bool
         :param force:
             if ``force=False``, only load from ``self.path`` if file
             has changed since last load.
@@ -407,7 +412,7 @@ class HtpasswdFile(_CommonFile):
            This feature is new in Passlib 1.6, and is the default if no
            ``path`` value is provided to the constructor.
 
-        This is exposed as a readonly instance attribute.
+        This is also exposed as a readonly instance attribute.
 
     :type new: bool
     :param new:
@@ -429,7 +434,7 @@ class HtpasswdFile(_CommonFile):
         if ``autosave=True`` is specified, any changes made will be
         saved to disk immediately (assuming *path* has been set).
 
-        This is exposed as a writeable instance attribute.
+        This is also exposed as a writeable instance attribute.
 
     :type encoding: str
     :param encoding:
@@ -438,7 +443,7 @@ class HtpasswdFile(_CommonFile):
         and hash passwords. Defaults to ``utf-8``, though ``latin-1``
         is the only other commonly encountered encoding.
 
-        This is exposed as a readonly instance attribute.
+        This is also exposed as a readonly instance attribute.
 
     :type default_scheme: str
     :param default_scheme:
@@ -457,14 +462,14 @@ class HtpasswdFile(_CommonFile):
         The default value is a pre-built context which supports all
         of the hashes officially allowed in an htpasswd file.
 
-        This is exposed as a readonly instance attribute.
+        This is also exposed as a readonly instance attribute.
 
         .. warning::
 
-            This option is useful to add support for non-standard hash
+            This option may be used to add support for non-standard hash
             formats to an htpasswd file. However, the resulting file
             will probably not be usuable by another application,
-            particularly Apache itself.
+            and particularly not by Apache.
 
     Loading & Saving
     ================
@@ -677,7 +682,7 @@ class HtdigestFile(_CommonFile):
            This feature is new in Passlib 1.6, and is the default if no
            ``path`` value is provided to the constructor.
 
-        This is exposed as a readonly instance attribute.
+        This is also exposed as a readonly instance attribute.
 
     :type default_realm: str
     :param default_realm:
@@ -687,7 +692,7 @@ class HtdigestFile(_CommonFile):
         provided explicitly. If unset, they will raise an error stating
         that an explicit realm is required.
 
-        This is exposed as a writeable instance attribute.
+        This is also exposed as a writeable instance attribute.
 
         .. versionadded:: 1.6
 
@@ -711,7 +716,7 @@ class HtdigestFile(_CommonFile):
         if ``autosave=True`` is specified, any changes made will be
         saved to disk immediately (assuming *path* has been set).
 
-        This is exposed as a writeable instance attribute.
+        This is also exposed as a writeable instance attribute.
 
     :type encoding: str
     :param encoding:
@@ -720,7 +725,7 @@ class HtdigestFile(_CommonFile):
         and hash passwords. Defaults to ``utf-8``, though ``latin-1``
         is the only other commonly encountered encoding.
 
-        This is exposed as a readonly instance attribute.
+        This is also exposed as a readonly instance attribute.
 
     Loading & Saving
     ================
diff --git a/passlib/exc.py b/passlib/exc.py
index 5f7d1dd..e3c175b 100644
--- a/passlib/exc.py
+++ b/passlib/exc.py
@@ -9,26 +9,27 @@ class MissingBackendError(RuntimeError):
     :exc:`!MissingBackendError` derives
     from :exc:`RuntimeError`, since this usually indicates
     lack of an external library or OS feature.
-
     This is primarily used by handlers which derive
     from :class:`~passlib.utils.handlers.HasManyBackends`.
     """
 
 class PasswordSizeError(ValueError):
-    """Error raised if the password provided exceeds the limit set by Passlib.
-
-    Many password hashes take proportionately larger amounts of
-    time and/or memory depending on the size of the password provided.
-    This could present a potential denial of service (DOS) situation
-    if a maliciously large password was provided to the application.
-
-    Because of this, Passlib enforces a maximum of 4096 characters.
-    This error will be thrown if a password larger than
-    this is provided to any of the hashes in Passlib.
-
-    Applications wishing to use a different limit should set the
-    ``PASSLIB_MAX_PASSWORD_SIZE`` environmental variable before Passlib
-    is loaded.
+    """Error raised if a password exceeds the maximum size enforced
+    by Passlib (4096 characters).
+
+    Many password hash algorithms take proportionately larger amounts of time and/or
+    memory depending on the size of the password provided. This could present
+    a potential denial of service (DOS) situation if a maliciously large
+    password is provided to an application. Because of this, Passlib enforces
+    a maximum size limit, but one which should be larger
+    than any legitimate password.
+
+    .. note::
+        Applications wishing to use a different limit should set the
+        ``PASSLIB_MAX_PASSWORD_SIZE`` environmental variable before
+        Passlib is loaded. The value can be any large positive integer.
+
+    .. versionadded:: 1.6
     """
     def __init__(self):
         ValueError.__init__(self, "password exceeds maximum allowed size")
@@ -40,7 +41,10 @@ class PasswordSizeError(ValueError):
 # warnings
 #==========================================================================
 class PasslibWarning(UserWarning):
-    """base class for Passlib's user warnings"""
+    """base class for Passlib's user warnings.
+
+    .. versionadded:: 1.6
+    """
 
 class PasslibConfigWarning(PasslibWarning):
     """Warning issued when non-fatal issue is found related to the configuration
@@ -151,6 +155,8 @@ def ZeroPaddedRoundsError(handler=None):
 #----------------------------------------------------------------
 def ChecksumSizeError(handler, raw=False):
     "error raised if hash was recognized, but checksum was wrong size"
+    # TODO: if handler.use_defaults is set, this came from app-provided value,
+    # not from parsing a hash string, might want different error msg.
     checksum_size = handler.checksum_size
     unit = "bytes" if raw else "chars"
     return ValueError("checksum wrong size (%s checksum must be "
diff --git a/passlib/utils/__init__.py b/passlib/utils/__init__.py
index aea7abf..f2f08bd 100644
--- a/passlib/utils/__init__.py
+++ b/passlib/utils/__init__.py
@@ -681,6 +681,15 @@ class Base64Engine(object):
     """provides routines for encoding/decoding base64 data using
     arbitrary character mappings, selectable endianness, etc.
 
+    :arg charmap:
+        A string of 64 unique characters,
+        which will be used to encode successive 6-bit chunks.
+        A character's position within the string will correspond
+        to it's 6-bit value.
+
+    :param big:
+        Whether the encoding should be big-endian (default False).
+
     Raw Bytes <-> Encoded Bytes
     ===========================
     .. automethod:: encode_bytes
@@ -782,6 +791,7 @@ class Base64Engine(object):
     #=============================================================
     def encode_bytes(self, source):
         """encode bytes to engine's specific base64 variant.
+
         :arg source: byte string to encode.
         :returns: byte string containing encoded data.
         """
@@ -884,6 +894,7 @@ class Base64Engine(object):
 
     def decode_bytes(self, source):
         """decode bytes from engine's specific base64 variant.
+
         :arg source: byte string to decode.
         :returns: byte string containing decoded data.
         """
@@ -1289,7 +1300,7 @@ _A64_PAD2 = b("==")
 def ab64_encode(data):
     """encode using variant of base64
 
-    the output of this function is identical to b64_encode,
+    the output of this function is identical to stdlib's b64_encode,
     except that it uses ``.`` instead of ``+``,
     and omits trailing padding ``=`` and whitepsace.
 
@@ -1300,7 +1311,7 @@ def ab64_encode(data):
 def ab64_decode(data):
     """decode using variant of base64
 
-    the input of this function is identical to b64_decode,
+    the input of this function is identical to stdlib's b64_decode,
     except that it uses ``.`` instead of ``+``,
     and should not include trailing padding ``=`` or whitespace.
 
@@ -1602,12 +1613,12 @@ def is_crypt_context(obj):
 ##    return hasattr(handler, "set_backend")
 
 def has_rounds_info(handler):
-    "check if handler provides the optional :ref:`rounds information <optional-rounds-attributes>` attributes"
+    "check if handler provides the optional :ref:`rounds information <rounds-attributes>` attributes"
     return ('rounds' in handler.setting_kwds and
             getattr(handler, "min_rounds", None) is not None)
 
 def has_salt_info(handler):
-    "check if handler provides the optional :ref:`salt information <optional-salt-attributes>` attributes"
+    "check if handler provides the optional :ref:`salt information <salt-attributes>` attributes"
     return ('salt' in handler.setting_kwds and
             getattr(handler, "min_salt_size", None) is not None)
 
diff --git a/passlib/utils/pbkdf2.py b/passlib/utils/pbkdf2.py
index 8ce8984..0c8a505 100644
--- a/passlib/utils/pbkdf2.py
+++ b/passlib/utils/pbkdf2.py
@@ -146,7 +146,7 @@ if _EVP:
     except ValueError: #pragma: no cover
         #this is probably not a good sign if it happens.
         from passlib.exc import PasslibRuntimeWarning
-        warn("PassLib: M2Crypt.EVP.hmac() unexpected threw value error during "
+        warn("Passlib: M2Crypt.EVP.hmac() unexpected threw value error during "
              "passlib startup test", PasslibRuntimeWarning)
     else:
         if result == b(',\x1cb\xe0H\xa5\x82M\xfb>\xd6\x98\xef\x8e\xf9oQ\x85\xa3i'):