documentation updates for last two commits

17 files changed, 70 insertions, 62 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 41da9ad..6e0d6d1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -100,7 +100,8 @@ version = csp.get_version(release)
 # directories to ignore when looking for source files.
 exclude_patterns = [
     #disabling documentation of this until module is more mature.
-    "lib/passlib.ext.django.rst"
+    "lib/passlib.ext.django.rst",
+    "lib/passlib.utils.compat.rst",
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
diff --git a/docs/lib/passlib.hash.apr_md5_crypt.rst b/docs/lib/passlib.hash.apr_md5_crypt.rst
index 6ae5361..ee4ac73 100644
--- a/docs/lib/passlib.hash.apr_md5_crypt.rst
+++ b/docs/lib/passlib.hash.apr_md5_crypt.rst
@@ -20,7 +20,7 @@ see that class for details.
 
 Interface
 =========
-.. autoclass:: apr_md5_crypt(checksum=None, salt=None, strict=False)
+.. autoclass:: apr_md5_crypt()
 
 Format & Algorithm
 ==================
diff --git a/docs/lib/passlib.hash.bigcrypt.rst b/docs/lib/passlib.hash.bigcrypt.rst
index e16c261..5f2429e 100644
--- a/docs/lib/passlib.hash.bigcrypt.rst
+++ b/docs/lib/passlib.hash.bigcrypt.rst
@@ -20,7 +20,7 @@ This class can be used in exactly the same manner as :class:`~passlib.hash.des_c
 
 Interface
 =========
-.. autoclass:: bigcrypt(checksum=None, salt=None, strict=False)
+.. autoclass:: bigcrypt()
 
 Format
 ======
diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst
index 6a60f79..99e7231 100644
--- a/docs/lib/passlib.hash.bsdi_crypt.rst
+++ b/docs/lib/passlib.hash.bsdi_crypt.rst
@@ -35,7 +35,7 @@ This class can be used directly as follows::
 
 Interface
 =========
-.. autoclass:: bsdi_crypt(checksum=None, salt=None, rounds=None, strict=False)
+.. autoclass:: bsdi_crypt()
 
 Format
 ======
diff --git a/docs/lib/passlib.hash.crypt16.rst b/docs/lib/passlib.hash.crypt16.rst
index 2cdd5eb..43f63c6 100644
--- a/docs/lib/passlib.hash.crypt16.rst
+++ b/docs/lib/passlib.hash.crypt16.rst
@@ -25,7 +25,7 @@ This class can be used in exactly the same manner as :class:`~passlib.hash.des_c
 
 Interface
 =========
-.. autoclass:: crypt16(checksum=None, salt=None, strict=False)
+.. autoclass:: crypt16()
 
 Format
 ======
diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
index ba5202e..1c808c5 100644
--- a/docs/lib/passlib.hash.des_crypt.rst
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -34,7 +34,7 @@ This class can be used directly as follows::
 
 Interface
 =========
-.. autoclass:: des_crypt(checksum=None, salt=None, strict=False)
+.. autoclass:: des_crypt()
 
 Format
 ======
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index a75187f..538ced5 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -33,7 +33,7 @@ PassLib provides an md5_crypt class, which can be can be used directly as follow
 
 Interface
 =========
-.. autoclass:: md5_crypt(checksum=None, salt=None, strict=False)
+.. autoclass:: md5_crypt()
 
 Format
 ======
diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst
index c879bc0..9f5ea02 100644
--- a/docs/lib/passlib.hash.oracle11.rst
+++ b/docs/lib/passlib.hash.oracle11.rst
@@ -38,7 +38,7 @@ PassLib provides an oracle11 class, which can be can be used directly as follows
 
 Interface
 =========
-.. autoclass:: oracle11(checksum=None, salt=None, strict=False)
+.. autoclass:: oracle11()
 
 Format & Algorithm
 ==================
diff --git a/docs/lib/passlib.hash.phpass.rst b/docs/lib/passlib.hash.phpass.rst
index 20a3bb0..ee5c036 100644
--- a/docs/lib/passlib.hash.phpass.rst
+++ b/docs/lib/passlib.hash.phpass.rst
@@ -21,7 +21,7 @@ this scheme is used in exactly the same way as :doc:`bcrypt <passlib.hash.bcrypt
 
 Interface
 =========
-.. autoclass:: phpass(checksum=None, salt=None, rounds=None, strict=False)
+.. autoclass:: phpass()
 
 Format
 ==================
diff --git a/docs/lib/passlib.hash.scram.rst b/docs/lib/passlib.hash.scram.rst
index fff87bf..397f743 100644
--- a/docs/lib/passlib.hash.scram.rst
+++ b/docs/lib/passlib.hash.scram.rst
@@ -94,7 +94,7 @@ for SCRAM-specific actions::
 
 Interface
 =========
-.. autoclass:: scram(algs=None, salt=None, rounds=None, strict=False)
+.. autoclass:: scram()
 
 .. rst-class:: html-toggle
 
diff --git a/docs/lib/passlib.hash.sha1_crypt.rst b/docs/lib/passlib.hash.sha1_crypt.rst
index fa80a6b..639429d 100644
--- a/docs/lib/passlib.hash.sha1_crypt.rst
+++ b/docs/lib/passlib.hash.sha1_crypt.rst
@@ -15,7 +15,7 @@ this scheme is used in exactly the same way as :doc:`sha512_crypt <passlib.hash.
 
 Functions
 =========
-.. autoclass:: sha1_crypt(checksum=None, salt=None, rounds=None, strict=False)
+.. autoclass:: sha1_crypt()
 
 Format
 ======
diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
index 2ae3243..9b7adce 100644
--- a/docs/lib/passlib.hash.sha256_crypt.rst
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -17,7 +17,7 @@ This class can be used in exactly the same manner as :class:`~passlib.hash.sha51
 
 Interface
 =========
-.. autoclass:: sha256_crypt(checksum=None, salt=None, rounds=None, strict=False)
+.. autoclass:: sha256_crypt()
 
 Format & Algorithm
 ==================
diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst
index f9e438c..963c61f 100644
--- a/docs/lib/passlib.hash.sha512_crypt.rst
+++ b/docs/lib/passlib.hash.sha512_crypt.rst
@@ -42,7 +42,7 @@ This class can be used directly as follows::
 
 Interface
 =========
-.. autoclass:: sha512_crypt(checksum=None, salt=None, rounds=None, strict=False)
+.. autoclass:: sha512_crypt()
 
 Format & Algorithm
 ==================
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
index b3b891a..2a5cf4b 100644
--- a/docs/lib/passlib.hash.sun_md5_crypt.rst
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -25,7 +25,7 @@ as :doc:`SHA-512 Crypt <passlib.hash.sha512_crypt>`.
 
 Interface
 =========
-.. autoclass:: sun_md5_crypt(checksum=None, salt=None, rounds=None, bare_salt=False, strict=False)
+.. autoclass:: sun_md5_crypt()
 
 Format
 ======
diff --git a/docs/lib/passlib.utils.handlers.rst b/docs/lib/passlib.utils.handlers.rst
index 301448c..385e5a2 100644
--- a/docs/lib/passlib.utils.handlers.rst
+++ b/docs/lib/passlib.utils.handlers.rst
@@ -14,6 +14,11 @@
     definitely need to be rewritten for clarity. They are not yet
     organized, and may leave out some important details.
 
+.. note::
+
+    Since this module is primarily a support module used internally
+    by Passlib, it's interface may change slightly between major releases.
+
 Implementing Custom Handlers
 ============================
 All that is required in order to write a custom handler that will work with
@@ -45,7 +50,7 @@ workflow for hashes is some combination of the following:
 
 1. parse hash into constituent parts - performed by :meth:`~GenericHandler.from_string`.
 2. validate constituent parts - performed by :class:`!GenericHandler`'s constructor,
-   and the normalization functions such as :meth:`~GenericHandler.norm_checksum` and :meth:`~HasSalt.norm_salt`
+   and the normalization functions such as :meth:`~GenericHandler._norm_checksum` and :meth:`~HasSalt._norm_salt`
    which are provided by it's related mixin classes.
 3. calculate the raw checksum for a specific password - performed by :meth:`~GenericHandler.calc_checksum`.
 4. assemble hash, including new checksum, into a new string - performed by :meth:`~GenericHandler.to_string`.
@@ -157,7 +162,7 @@ checking if a handler adheres to the :ref:`password-hash-api`.
 Usage
 -----
 As an example of how to use :class:`!HandlerCase`,
-the following is an annoted version
+the following is an annotated version
 of the unittest for :class:`passlib.hash.des_crypt`::
 
     from passlib.hash import des_crypt
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index 5508191..ca82c57 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -35,7 +35,6 @@ Constants
     are known to support which hashes.
 
 ..
-
     PYPY
     JYTHON
     rounds_cost_values
@@ -105,16 +104,15 @@ Predefined Instances
 
     Predefined instance of :class:`Base64Engine` which uses
     the :data:`!HASH64_CHARS` character map and little-endian encoding.
-    (see :data:`!HASH64_CHARS` for more details).
+    (see :data:`HASH64_CHARS` for more details).
 
 .. data:: h64big
 
     Predefined variant of :data:`h64` which uses big-endian encoding.
     This is mainly used by :class:`~passlib.hash.des_crypt`.
 
-.. note::
-
-   *changed in Passlib 1.6:* Previous versions of Passlib contained
+.. versionchanged:: 1.6
+   Previous versions of Passlib contained
    a module named :mod:`!passlib.utils.h64`; As of Passlib 1.6 this
    was replaced by the the ``h64`` and ``h64big`` instances;
    the interface remains mostly unchanged.
@@ -173,5 +171,4 @@ There are also a few sub modules which provide additional utility functions:
     passlib.utils.pbkdf2
 
 ..
-
     passlib.utils.compat
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index e824fea..5e59f83 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -143,6 +143,14 @@ Required Attributes
         the same hash. The class's documentation will generally list
         the allowed values, allowing alternate output formats to be selected.
 
+    ``relaxed``
+        If supported, ``relaxed=True`` will cause the handler to
+        be more forgiving about invalid input. Instead of immediately throwing
+        a :exc:`ValueError`, it will first attempt to correct the input,
+        and issue a :exc:`~passlib.exc.PasslibHandlerWarning` if successful.
+        This includes actions like clamping out-of-range rounds values,
+        and truncating salts that are too long.
+
 .. attribute:: PasswordHash.context_kwds
 
     This attribute should contain a tuple of keywords
@@ -197,23 +205,34 @@ which scheme a hash belongs to when multiple schemes are in use.
         Common settings keywords include ``salt`` and ``rounds``.
 
     :raises ValueError:
-        * if settings are invalid and handler cannot correct them.
-          (eg: if a ``salt`` string is to short, this will
-          cause an error; but a ``rounds`` value that's too large
-          should be silently clipped).
 
-        * if a context keyword contains an invalid value, or was required
-          but omitted.
+        * If a keyword's value is invalid (e.g. if a ``salt`` string
+          is too small, or a ``rounds`` value is out of range).
 
-        * if secret contains forbidden characters (e.g: des-crypt forbids null characters).
-          this should rarely occur, since most modern algorithms have no limitations
-          on the types of characters.
+        * If the secret contains characters forbidden by the handler
+          (e.g. :class:`!des_crypt` forbids NULL characters). This should not
+          happen often, since most modern algorithms have no limitations on
+          the character values they accept.
 
-    :raises TypeError: if :samp:`{secret}` is not a bytes or unicode instance.
+    :raises TypeError:
+
+        * if :samp:`{secret}` is not a bytes or unicode instance.
+
+        * if a required option (such as a context keyword) was not set.
 
     :returns:
         Hash string, using an algorithm-specific format.
 
+    .. versionchanged:: 1.6
+
+        Previous versions of Passlib would raise :exc:`ValueError` if a
+        required keyword was missing; this has been changed to :exc:`TypeError`
+        in order to conform with normal Python behavior.
+
+        Previous versions of Passlib would silently correct invalid settings
+        where possible (e.g. silently clamping out-of-range ``rounds``); as
+        of Passlib 1.6 the policy is to raise an explicit error.
+
 .. classmethod:: PasswordHash.identify(hash)
 
     identify if a hash string belongs to this algorithm.
@@ -292,41 +311,27 @@ and :meth:`~PasswordHash.genhash`.
     referred to as a ``salt string``, though it may contain much more
     than just a salt).
 
-    This function takes in optional configuration options (a complete list
-    of which should be found in :attr:`~PasswordHash.setting_kwds`), validates
-    the inputs, fills in defaults where appropriate, and returns
-    a configuration string.
-    For algorithms which do not have any configuration options,
-    this function should always return ``None``.
-
-    While each algorithm may have it's own configuration options,
-    the following keywords (if supported) should always have a consistent
-    meaning:
+    This function takes in configuration options specific to the handler,
+    validates the inputs, fills in defaults where appropriate, and returns
+    a configuration string. For algorithms which do not have any configuration
+    options, this function should always return ``None``.
 
-    * ``salt`` - algorithm uses a salt. if passed into genconfig,
-      should contain an encoded salt string of length and character set
-      required by the specific handler.
-
-      salt strings which are too small or have invalid characters
-      should cause an error, salt strings which are too large
-      should be truncated but accepted.
+    :param \*\*settings_kwds:
 
-    * ``rounds`` - algorithm uses a variable number of rounds. if passed
-      into genconfig, should contain an integer number of rounds
-      (this may represent logarithmic rounds, eg bcrypt, or linear, eg sha-crypt).
-      if the number of rounds is too small or too large, it should
-      be clipped but accepted.
+        While each algorithm may have it's own specific configuration options
+        (detailed in it's documentation), a list of common options can be
+        found in in :attr:`~PasswordHash.setting_kwds`.
 
-    :param \*\*settings_kwds:
-        this function takes in keywords as specified in :attr:`~PasswordHash.setting_kwds`.
         commonly supported keywords include ``salt`` and ``rounds``.
 
+    :raises TypeError:
+        if any required configuration options are omitted
+        (most options do not need to be specified; e.g. an appropriate
+        value for ``salt`` will be autogenerated for each call).
+
     :raises ValueError:
-        * if any configuration options are required, missing, AND
-          a default value cannot be autogenerated.
-          (for example: salt strings should be autogenerated if not specified).
-        * if any configuration options are invalid, and cannot be
-          normalized in a reasonble manner (eg: salt strings clipped to maximum size).
+        if any configuration options are invalid (and cannot
+        be corrected, if in relaxed parsing mode).
 
     :returns:
         the configuration string, or ``None`` if the algorithm does not support
@@ -582,7 +587,7 @@ and ease of implementation issues:
     use ``utf-8`` to encode unicode passwords,
     and reproduce existing passwords as opaque bytes.
 
-*   Internally, it is recommended that handlers use 
+*   Internally, it is recommended that handlers use
     :class:`unicode` for parsing / formatting
     purposes, and only use :class:`bytes` for decoded
     binary data ready to be passed into their digest routines.