api change - renaming (min|max|default)_salt_chars attributes -> (min|max|default)_salt_size

* part of finalization of password hash api, these should not change name again
* the names are rather ambiguous, "_size" makes it clearer what they mean
* also renamed salt_charset -> salt_chars for the same reason
* for applications that were reading old attributes, left aliases in place
  which will issue a warning when access - these will be removed in passlib 1.5
*

1 files changed, 41 insertions, 5 deletions

diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 140626a..1491280 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -390,23 +390,59 @@ Salt Information
 ----------------
 For schemes which support a salt (ie, ``'salt' in PasswordHash.setting_kwds``),
 the following attributes are usually exposed.
-(Applications can test for this suites' presence by checking if ``getattr(handler,"max_salt_chars",None)>0``)
+(Applications can test for this suites' presence by checking if ``getattr(handler,"max_salt_size",None)>0``)
 
-.. attribute:: PasswordHash.max_salt_chars
+.. attribute:: PasswordHash.max_salt_size
 
     maximum number of characters which will be *used*
     if a salt string is provided to :meth:`~PasswordHash.genconfig` or :meth:`~PasswordHash.encrypt`.
     must be positive integer if salts are supported,
     may be ``None`` or ``0`` if salts are not supported.
 
-.. attribute:: PasswordHash.min_salt_chars
+.. attribute:: PasswordHash.min_salt_size
 
     minimum number of characters required in salt string,
     if provided to :meth:`~PasswordHash.genconfig` or :meth:`~PasswordHash.encrypt`.
-    must be non-negative integer that is not greater than :attr:`~PasswordHash.max_salt_chars`.
+    must be non-negative integer that is not greater than :attr:`~PasswordHash.max_salt_size`.
 
-.. attribute:: PasswordHash.salt_charset
+.. attribute:: PasswordHash.salt_chars
 
     string containing list of all characters which are allowed
     to be specified in salt parameter.
     for most hashes, this is equal to `passlib.utils.h64.CHARS`.
+
+.. warning::
+
+    In Passlib 1.3 and earlier, these attributes were named ``min_salt_chars``,
+    ``max_salt_chars``, and ``salt_charset``, respectively.
+    These names have been deprecated, due to their ambiguity. Passlib 1.4 contains aliases
+    for these names, so client applications may continue to use them;
+    but these aliases will be removed in Passlib 1.5.
+
+.. todo::
+
+    this list the behavior for handlers which accept
+    an salt string containing characters.
+    some handlers take raw bytes
+    for their salt keyword, how these attributes change
+    in that situtation should be documentated.
+
+..
+
+    not yet documentated, want to make sure this is how we want to do things:
+
+    .. attribute:: PasswordHash.default_salt_size
+
+        size of salts generated by genconfig
+        when no salt is provided by caller.
+        for most hashes, this defaults to :attr:`!PasswordHash.max_salt_size`.
+
+    .. attribute:: PasswordHash.default_salt_chars
+
+        sequence of characters used to generated new salts
+        when no salt is provided by caller.
+        for most hashes, this is the same as :attr:`!PasswordHash.salt_chars`;
+        but some hashes accept a much larger range of values
+        than are typically used. This field allows
+        the full range to be accepted, while only
+        a select subset to be used for generation.