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, 1 insertions, 1 deletions

diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
index 069fc19..32c683c 100644
--- a/docs/lib/passlib.hash.sha256_crypt.rst
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -23,7 +23,7 @@ This class can be used directly as follows::
     '$5$rounds=80000$wnsT7Yr92oJoP28r$cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5'
 
     >>> # same, but with explict number of rounds
-    >>> sha256_crypt.hash("password", rounds=12345)
+    >>> sha256_crypt.replace(rounds=12345).hash("password")
     '$5$rounds=12345$q3hvJE5mn5jKRsW.$BbbYTFiaImz9rTy03GGi.Jf9YY5bmxN0LU3p3uI1iUB'
 
     >>> # verify password