PasswordHash.hash() api shift: deprecating passing settings kwds into hash() --

callers should use handler.replace(**settings).hash() instead.

this is being done because it greatly streamlines the internals of the .hash()
implementation, and allows some redundant configuration parsing to be extracted
from the .hash() methods and merged in with existing code in .replace().

this also opens things up for alternate code architectures for implementing new hashers,
making it easier to wrap existing libraries (e.g. argon2).

internals
---------
* replaced a bunch of internal .hash(**settings) calls

* GenericHandler
    - stripped out 'relaxed' keyword from constructor, since it's no longer
      passed by hash() etc.
    - _norm_checksum() now only invoked if checksum is specified (simplifies logic).
      keeping support for 'relaxed' mode, but only as explicit keyword.
    - removed some unused comments about .from_string() & .to_string()

* HasSalt mixin:
    - .replace() now supports 'salt' keyword, creates variant
      which has a fixed salt string.

    - 'salt size' keyword removed from ctor, now handled by .replace() call

    - _norm_salt() converted to class method so it can be
       used by .replace() 'salt' keyword code.

    - per-instance bits of _norm_salt() relocated to HasSalt.__init__ proper

    - _generate_salt() converted to class method, since no longer depends on instance config.

* HasRounds mixin:

    - similar to HasSalt, relocates per-instance bits of _norm_rounds()
      into HasRounds.__init__() proper.

    - remainder of _norm_rounds() turned into class method, merged
      with ._clip_to_valid_rounds() helper to reduce duplication.

    - _generate_rounds() converted to class method, since no longer depends on instance config.

hashers
-------
* fshp: added support for 'variant' keyword to replace()
* unix_disabled: added support for 'marker' keyword to replace(), added UTs.
* cisco_type7: to match HasSalt, added support for 'salt' keyword to replace(), added UTs.
* sha256/512_crypt: now uses custom salt & rounds parsing, rather than relaxed kwd,
  to handle correctable-but-invalid config strings.

unittests
---------
* removed checks for PasslibConfigWarning when setting hash(rounds=) out of policy bounds,
  since that now *is* setting the policy.
* adapted some handler ctor to deal w/ lack of 'relaxed' kwd

docs
----
* updated docstrings listing hash() keywords for each scheme to list them
  as .replace() keywords.
* updated example code to use .replace()
* fleshed out api docs about the change

1 files changed, 14 insertions, 13 deletions

diff --git a/passlib/handlers/des_crypt.py b/passlib/handlers/des_crypt.py
index 1de21e1..a6aae6b 100644
--- a/passlib/handlers/des_crypt.py
+++ b/passlib/handlers/des_crypt.py
@@ -113,7 +113,7 @@ class des_crypt(uh.HasManyBackends, uh.HasSalt, uh.GenericHandler):
 
     It supports a fixed-length salt.
 
-    The :meth:`~passlib.ifc.PasswordHash.hash` and :meth:`~passlib.ifc.PasswordHash.genconfig` methods accept the following optional keywords:
+    The :meth:`~passlib.ifc.PasswordHash.replace` method accepts the following optional keywords:
 
     :type salt: str
     :param salt:
@@ -210,7 +210,7 @@ class bsdi_crypt(uh.HasManyBackends, uh.HasRounds, uh.HasSalt, uh.GenericHandler
 
     It supports a fixed-length salt, and a variable number of rounds.
 
-    The :meth:`~passlib.ifc.PasswordHash.hash` and :meth:`~passlib.ifc.PasswordHash.genconfig` methods accept the following optional keywords:
+    The :meth:`~passlib.ifc.PasswordHash.replace` method accepts the following optional keywords:
 
     :type salt: str
     :param salt:
@@ -296,17 +296,18 @@ class bsdi_crypt(uh.HasManyBackends, uh.HasRounds, uh.HasSalt, uh.GenericHandler
     #       want to eventually expose rounds logic to that script in better way.
     _avoid_even_rounds = True
 
-    def _norm_rounds(self, rounds):
-        rounds = super(bsdi_crypt, self)._norm_rounds(rounds)
+    def _parse_rounds(self, rounds):
+        rounds = super(bsdi_crypt, self)._parse_rounds(rounds)
         # issue warning if app provided an even rounds value
-        if self.use_defaults and not rounds & 1:
+        if not rounds & 1:
             warn("bsdi_crypt rounds should be odd, "
                  "as even rounds may reveal weak DES keys",
                  uh.exc.PasslibSecurityWarning)
         return rounds
 
-    def _generate_rounds(self):
-        rounds = super(bsdi_crypt, self)._generate_rounds()
+    @classmethod
+    def _generate_rounds(cls):
+        rounds = super(bsdi_crypt, cls)._generate_rounds()
         # ensure autogenerated rounds are always odd
         # NOTE: doing this even for default_rounds so needs_update() doesn't get
         #       caught in a loop.
@@ -369,7 +370,7 @@ class bigcrypt(uh.HasSalt, uh.GenericHandler):
 
     It supports a fixed-length salt.
 
-    The :meth:`~passlib.ifc.PasswordHash.hash` and :meth:`~passlib.ifc.PasswordHash.genconfig` methods accept the following optional keywords:
+    The :meth:`~passlib.ifc.PasswordHash.replace` method accepts the following optional keywords:
 
     :type salt: str
     :param salt:
@@ -422,11 +423,11 @@ class bigcrypt(uh.HasSalt, uh.GenericHandler):
         hash = u("%s%s") % (self.salt, self.checksum)
         return uascii_to_str(hash)
 
-    def _norm_checksum(self, value):
-        value = super(bigcrypt, self)._norm_checksum(value)
-        if value and len(value) % 11:
+    def _norm_checksum(self, checksum, relaxed=False):
+        checksum = super(bigcrypt, self)._norm_checksum(checksum, relaxed=relaxed)
+        if len(checksum) % 11:
             raise uh.exc.InvalidHashError(self)
-        return value
+        return checksum
 
     #===================================================================
     # backend
@@ -452,7 +453,7 @@ class crypt16(uh.HasSalt, uh.GenericHandler):
 
     It supports a fixed-length salt.
 
-    The :meth:`~passlib.ifc.PasswordHash.hash` and :meth:`~passlib.ifc.PasswordHash.genconfig` methods accept the following optional keywords:
+    The :meth:`~passlib.ifc.PasswordHash.replace` method accepts the following optional keywords:
 
     :type salt: str
     :param salt: