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, 58 insertions, 32 deletions

diff --git a/passlib/utils/handlers.py b/passlib/utils/handlers.py
index ea346d7..8fdacf0 100644
--- a/passlib/utils/handlers.py
+++ b/passlib/utils/handlers.py
@@ -14,7 +14,8 @@ from warnings import warn
 #site
 #libs
 from passlib.registry import get_crypt_handler
-from passlib.utils import classproperty, h64, getrandstr, getrandbytes, rng, is_crypt_handler, ALL_BYTE_VALUES
+from passlib.utils import classproperty, h64, getrandstr, getrandbytes, \
+        rng, is_crypt_handler, ALL_BYTE_VALUES
 #pkg
 #local
 __all__ = [
@@ -35,7 +36,7 @@ __all__ = [
 #constants
 #=========================================================
 
-#common salt_charset & checksum_charset values
+#common salt_chars & checksum_charset values
 H64_CHARS = h64.CHARS
 B64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
 HEX_CHARS = "0123456789abcdefABCDEF"
@@ -1071,7 +1072,7 @@ class HasSalt(GenericHandler):
     as well as generating new salts if one it not provided.
 
     :param salt: optional salt string
-    :param salt_size: optional size of salt (only used if no salt provided); defaults to :attr:`default_salt_chars`.
+    :param salt_size: optional size of salt (only used if no salt provided); defaults to :attr:`default_salt_size`.
     :param strict: if ``True``, requires a valid salt be provided; otherwise is tolerant of correctable errors (the default).
 
     Class Attributes
@@ -1079,13 +1080,13 @@ class HasSalt(GenericHandler):
     In order for :meth:`!norm_salt` to do it's job, the following
     attributes must be provided by the handler subclass:
 
-    .. attribute:: min_salt_chars
+    .. attribute:: min_salt_size
 
         [required]
         The minimum number of characters allowed in a salt string.
         An :exc:`ValueError` will be throw if the salt is too small.
 
-    .. attribute:: max_salt_chars
+    .. attribute:: max_salt_size
 
         [required]
         The maximum number of characters allowed in a salt string.
@@ -1094,14 +1095,14 @@ class HasSalt(GenericHandler):
         WHen ``strict=False`` (such as when parsing user-provided values),
         the salt will be silently trimmed to this length if it's too long.
 
-    .. attribute:: default_salt_chars
+    .. attribute:: default_salt_size
 
         [optional]
         If no salt is provided, this should specify the size of the salt
         that will be generated by :meth:`generate_salt`.
-        If this is not specified, it will default to :attr:`max_salt_chars`.
+        If this is not specified, it will default to :attr:`max_salt_size`.
 
-    .. attribute:: salt_charset
+    .. attribute:: salt_chars
 
         [required]
         A string containing all the characters which are allowed in the salt string.
@@ -1127,22 +1128,47 @@ class HasSalt(GenericHandler):
     #=========================================================
     #class attrs
     #=========================================================
-    min_salt_chars = None #required - minimum size of salt (error if too small)
-    max_salt_chars = None #required - maximum size of salt (truncated if too large)
+    #NOTE: min/max/default_salt_chars is deprecated, use min/max/default_salt_size instead
+
+    #: required - minimum size of salt (error if too small)
+    min_salt_size = None
+
+    #: required - maximum size of salt (truncated if too large)
+    max_salt_size = None
+
+    @classproperty
+    def default_salt_size(cls):
+        "default salt chars (defaults to max_salt_size if not specified by subclass)"
+        return cls.max_salt_size
+
+    #: set of characters allowed in salt string.
+    salt_chars = H64_CHARS
 
     @classproperty
     def default_salt_chars(cls):
-        "default salt chars (defaults to max_salt_chars if not specified by subclass)"
-        return cls.max_salt_chars
+        "set of characters used to generate *new* salt strings (defaults to salt_chars)"
+        return cls.salt_chars
 
-    salt_charset = H64_CHARS #set of characters allowed in salt string.
+    #: helper for HasRawSalt, shouldn't be used publically
+    _salt_is_bytes = False
 
+    #--------------------------------------------------------
+    #deprecated attrs
+    #--------------------------------------------------------
     @classproperty
-    def default_salt_charset(cls):
-        "set of characters used to generate *new* salt strings (defaults to salt_charset)"
-        return cls.salt_charset
+    def min_salt_chars(cls):
+        warn(".min_salt_chars is deprecated, use .min_salt_size instead; .min_salt_chars will be removed in passlib 1.5", DeprecationWarning)
+        return cls.min_salt_size
+
+    @classproperty
+    def max_salt_chars(cls):
+        warn(".max_salt_chars is deprecated, use .max_salt_size instead; .max_salt_chars will be removed in passlib 1.5", DeprecationWarning)
+        return cls.max_salt_size
 
-    _salt_is_bytes = False #helper for HasRawSalt
+    @classproperty
+    def salt_charset(cls):
+        warn(".salt_charset is deprecated, use .salt_chars instead; .salt_charset will be removed in passlib 1.5", DeprecationWarning)
+        return cls.salt_chars
 
     #=========================================================
     #instance attrs
@@ -1160,16 +1186,16 @@ class HasSalt(GenericHandler):
     def generate_salt(cls, salt_size=None, strict=False):
         """helper method for norm_salt(); generates a new random salt string.
 
-        :param salt_size: optional salt size, falls back to :attr:`default_salt_chars`.
+        :param salt_size: optional salt size, falls back to :attr:`default_salt_size`.
         :param strict: if too-large salt should throw error, or merely be trimmed.
         """
         if salt_size is None:
-            salt_size = cls.default_salt_chars
+            salt_size = cls.default_salt_size
         else:
-            mn = cls.min_salt_chars
+            mn = cls.min_salt_size
             if mn and salt_size < mn:
                 raise ValueError("%s salt string must be at least %d characters" % (cls.name, mn))
-            mx = cls.max_salt_chars
+            mx = cls.max_salt_size
             if mx and salt_size > mx:
                 if strict:
                     raise ValueError("%s salt string must be at most %d characters" % (cls.name, mx))
@@ -1177,7 +1203,7 @@ class HasSalt(GenericHandler):
         if cls._salt_is_bytes:
             return getrandbytes(rng, salt_size)
         else:
-            return getrandstr(rng, cls.default_salt_charset, salt_size)
+            return getrandstr(rng, cls.default_salt_chars, salt_size)
 
     @classmethod
     def norm_salt(cls, salt, salt_size=None, strict=False):
@@ -1189,14 +1215,14 @@ class HasSalt(GenericHandler):
         :raises ValueError:
 
             * if ``strict=True`` and no salt is provided
-            * if ``strict=True`` and salt contains greater than :attr:`max_salt_chars` characters
-            * if salt contains chars that aren't in :attr:`salt_charset`.
-            * if salt contains less than :attr:`min_salt_chars` characters.
+            * if ``strict=True`` and salt contains greater than :attr:`max_salt_size` characters
+            * if salt contains chars that aren't in :attr:`salt_chars`.
+            * if salt contains less than :attr:`min_salt_size` characters.
 
         if no salt provided and ``strict=False``, a random salt is generated
-        using :attr:`default_salt_chars` and :attr:`default_salt_charset`.
-        if the salt is longer than :attr:`max_salt_chars` and ``strict=False``,
-        the salt string is clipped to :attr:`max_salt_chars`.
+        using :attr:`default_salt_size` and :attr:`default_salt_chars`.
+        if the salt is longer than :attr:`max_salt_size` and ``strict=False``,
+        the salt string is clipped to :attr:`max_salt_size`.
 
         :returns:
             normalized or generated salt
@@ -1212,18 +1238,18 @@ class HasSalt(GenericHandler):
             if isinstance(salt, unicode):
                 salt = salt.encode("utf-8")
         else:
-            sc = cls.salt_charset
+            sc = cls.salt_chars
             for c in salt:
                 if c not in sc:
                     raise ValueError("invalid character in %s salt: %r"  % (cls.name, c))
 
         #check min size
-        mn = cls.min_salt_chars
+        mn = cls.min_salt_size
         if mn and len(salt) < mn:
             raise ValueError("%s salt string must be at least %d characters" % (cls.name, mn))
 
         #check max size
-        mx = cls.max_salt_chars
+        mx = cls.max_salt_size
         if len(salt) > mx:
             if strict:
                 raise ValueError("%s salt string must be at most %d characters" % (cls.name, mx))
@@ -1244,7 +1270,7 @@ class HasRawSalt(HasSalt):
         document this class's usage
     """
 
-    salt_charset = ALL_BYTE_VALUES
+    salt_chars = ALL_BYTE_VALUES
     _salt_is_bytes = True
 
     #NOTE: code is currently shared with HasSalt, using internal _salt_is_bytes flag.