CryptPolicy deprecation, part 5 - updated docs, changelog, benchmark script

5 files changed, 113 insertions, 88 deletions

diff --git a/docs/lib/passlib.context-interface.rst b/docs/lib/passlib.context-interface.rst
index 8331992..a760d06 100644
--- a/docs/lib/passlib.context-interface.rst
+++ b/docs/lib/passlib.context-interface.rst
@@ -8,8 +8,7 @@
 
 .. currentmodule:: passlib.context
 
-This details all the constructors and methods provided by :class:`!CryptContext`
-and :class:`!CryptPolicy`.
+This details all the constructors and methods provided by :class:`!CryptContext`.
 
 .. seealso::
 
@@ -19,12 +18,14 @@ and :class:`!CryptPolicy`.
 
 The Context Object
 ==================
-.. autoclass:: CryptContext(schemes=None, policy=<default policy>, \*\*kwds)
-
-The Policy Object
-=================
-.. autoclass:: CryptPolicy(\*\*kwds)
+.. autoclass:: CryptContext(schemes=None, \*\*kwds)
 
 Other Helpers
 =============
-.. autoclass:: LazyCryptContext([schemes=None,] **kwds [, create_policy=None])
+.. autoclass:: LazyCryptContext([schemes=None,] \*\*kwds [, onload=None])
+
+.. rst-class:: html-toggle
+
+(deprecated) The CryptPolicy Class
+==================================
+.. autoclass:: CryptPolicy
diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst
index 4f0bcbe..36cb89e 100644
--- a/docs/lib/passlib.context-options.rst
+++ b/docs/lib/passlib.context-options.rst
@@ -9,9 +9,13 @@
 .. currentmodule:: passlib.context
 
 The :class:`CryptContext` accepts a number of keyword options.
-These are divides into the "context options", which affect
-the context instance directly, and the "hash options",
-which affect the context treats a particular type of hash:
+These can be provided to any of the CryptContext constructor methods,
+as well as the :meth:`CryptContext.update` method, or any configuration
+string or INI file passed to :meth:`CryptContext.load`.
+
+The options are divided into two categories: "context options", which directly
+affect the :class:`!CryptContext` object itself; and "hash options", which
+affect the behavior of a particular password hashing scheme.
 
 .. seealso::
 
@@ -21,8 +25,7 @@ which affect the context treats a particular type of hash:
 
 Context Options
 ===============
-The following keyword options are accepted by both the :class:`CryptContext`
-and :class:`CryptPolicy` constructors, and directly affect the behavior
+The following keyword options directly affect the behavior
 of the :class:`!CryptContext` instance itself:
 
 ``schemes``
@@ -41,15 +44,14 @@ of the :class:`!CryptContext` instance itself:
 ``deprecated``
 
     List of handler names which should be considered deprecated by the CryptContext.
-    This should be a subset of the names of the handlers listed in schemes.
-    This is optional, if not specified, no handlers will be considered deprecated.
+    This should be a subset of the names of the handlers listed in *schemes*.
+    This is optional, and if not specified, no handlers will be considered deprecated.
 
-    For use in INI files, this may also be specified as a single comma-separated string
+    For INI files, this may also be specified as a single comma-separated string
     of handler names.
 
-    This is primarily used by :meth:`CryptContext.hash_needs_update` and
-    :meth:`CryptPolicy.handler_is_deprecated`. If the application does not use
-    these methods, this option can be ignored.
+    This is primarily used by :meth:`CryptContext.hash_needs_update`.
+    If the application does not use this method, this option can be ignored.
 
     Example: ``deprecated=["des_crypt"]``.
 
@@ -77,25 +79,22 @@ of the :class:`!CryptContext` instance itself:
 
     For symmetry with the format of the hash option keywords (below),
     all of the above context option keywords may also be specified
-    using the format :samp:`context__{option}` (note double underscores),
-    or :samp:`context.{option}` within INI files.
+    using the format :samp:`context__{option}` (note double underscores).
 
 .. note::
 
     To override context options for a particular :ref:`user category <user-categories>`,
-    use the format :samp:`{category}__context__{option}`,
-    or :samp:`{category}.context.{option}` within an INI file.
+    use the format :samp:`{category}__context__{option}`.
 
 Hash Options
 ============
-The following keyword options are accepted by both the :class:`CryptContext`
-and :class:`CryptPolicy` constructors, and affect how a :class:`!CryptContext` instance
-treats hashes belonging to a particular hash scheme, as identified by the hash's handler name.
+The following keyword option affect how a :class:`!CryptContext` instance
+treats hashes belonging to a particular hash scheme,
+as identified by the scheme's name.
 
 All hash option keywords should be specified using the format :samp:`{hash}__{option}`
 (note double underscores); where :samp:`{hash}` is the name of the hash's handler,
 and :samp:`{option}` is the name of the specific options being set.
-Within INI files, this may be specified using the alternate format :samp:`{hash}.{option}`.
 
 :samp:`{hash}__default_rounds`
 
@@ -111,11 +110,9 @@ Within INI files, this may be specified using the alternate format :samp:`{hash}
     to have a rounds value random chosen from the range :samp:`{default_rounds} +/- {vary_rounds}`.
 
     This may be specified as an integer value, or as a string containing an integer
-    with a percent suffix (eg: ``"10%"``). if specified as a percent,
+    with a percent suffix (eg: ``"10%"``). If specified as a percent,
     the amount varied will be calculated as a percentage of the :samp:`{default_rounds}` value.
 
-    The default Passlib policy sets this to ``"10%"``.
-
     .. note::
 
         If this is specified as a percentage, and the hash algorithm
@@ -217,48 +214,61 @@ of the category string it wants to use, and add an additional separator to the k
     the need to use a different hash for a particular category
     can instead be acheived by overridden the ``default`` context option.
 
-Sample Policy File
+Sample Config File
 ==================
-A sample policy file:
+A sample config file:
 
 .. code-block:: ini
 
     [passlib]
-    #configure what schemes the context supports (note the "context." prefix is implied for these keys)
+    # configure what schemes the context supports
+    # (note that the "context__" prefix is implied for these keys)
     schemes = md5_crypt, sha512_crypt, bcrypt
     deprecated = md5_crypt
     default = sha512_crypt
 
-    #set some common options for all schemes
-    all.vary_rounds = 10%%
-        ; NOTE the '%' above has to be escaped due to configparser interpolation
+    # set some common options for all schemes
+    # (this particular setting causes the rounds value to be varied
+    # +/- 10% for each encrypt call)
+    all__vary_rounds = 0.1
 
-    #setup some hash-specific defaults
-    sha512_crypt.min_rounds = 40000
-    bcrypt.min_rounds = 10
+    # setup some hash-specific defaults
+    sha512_crypt__min_rounds = 40000
+    bcrypt__min_rounds = 10
 
-    #create a "admin" category, which uses bcrypt by default, and has stronger hashes
-    admin.context.default = bcrypt
-    admin.sha512_crypt.min_rounds = 100000
-    admin.bcrypt.min_rounds = 13
+    # create an "admin" category which uses bcrypt by default,
+    #  and has stronger default cost
+    admin__context__default = bcrypt
+    admin__sha512_crypt__min_rounds = 100000
+    admin__bcrypt__min_rounds = 13
 
-And the equivalent as a set of python keyword options::
+This can be turned into a :class:`!CryptContext` via :meth:`CryptContext.from_path`,
+or loaded into an existing object via :meth:`CryptContext.load`.
+
+And the equivalent of the above, as a set of Python keyword options::
 
     dict(
-        #configure what schemes the context supports (note the "context." prefix is implied for these keys)
+        # configure what schemes the context supports
+        # (note the "context__" prefix is implied for these keys)
         schemes = ["md5_crypt", "sha512_crypt", "bcrypt" ],
         deprecated = ["md5_crypt"],
         default = "sha512_crypt",
 
-        #set some common options for all schemes
-        all__vary_rounds = "10%",
+        # set some common options for all schemes
+        # (this particular setting causes the rounds value to be varied
+        # +/- 10% for each encrypt call)
+        all__vary_rounds = 0.1,
 
-        #setup some hash-specific defaults
+        # setup some hash-specific defaults
         sha512_crypt__min_rounds = 40000,
         bcrypt__min_rounds = 10,
 
-        #create a "admin" category, which uses bcrypt by default, and has stronger hashes
-        admin__context__default = bcrypt
-        admin__sha512_crypt__min_rounds = 100000
-        admin__bcrypt__min_rounds = 13
+        # create a "admin" category which uses bcrypt by default,
+        # and has stronger default cost
+        admin__context__default = bcrypt,
+        admin__sha512_crypt__min_rounds = 100000,
+        admin__bcrypt__min_rounds = 13,
     )
+
+This can be turned into a :class:`CryptContext` via the class constructor,
+or loaded into an existing object via :meth:`CryptContext.load`.
diff --git a/docs/lib/passlib.context-usage.rst b/docs/lib/passlib.context-usage.rst
index 9832203..4d897d4 100644
--- a/docs/lib/passlib.context-usage.rst
+++ b/docs/lib/passlib.context-usage.rst
@@ -77,28 +77,39 @@ copy; using the :meth:`CryptContext.replace` method to create
 a mutated copy of the original object::
 
     >>> from passlib.apps import ldap_context
-    >>> pwd_context = ldap_context.replace(default="ldap_md5_crypt")
+    >>> pwd_context = ldap_context.copy(default="ldap_md5_crypt")
     >>> pwd_context.encrypt("somepass")
     '{CRYPT}$1$Cw7t4sbP$dwRgCMc67mOwwus9m33z71'
 
 Examining a CryptContext Instance
 =================================
 All configuration options for a :class:`!CryptContext` instance
-are stored in a :class:`!CryptPolicy` instance accessible through
-the :attr:`CryptContext.policy` attribute::
+are accessible through various methods of the object:
 
     >>> from passlib.context import CryptContext
     >>> myctx = CryptContext([ "md5_crypt", "des_crypt" ], deprecated="des_crypt")
 
-    >>> #get a list of schemes recognized in this context:
-    >>> myctx.policy.schemes()
+    >>> # get a list of schemes recognized in this context:
+    >>> myctx.schemes()
     [ 'md5-crypt', 'bcrypt' ]
 
-    >>> #get the default handler class :
-    >>> myctx.policy.get_handler()
+    >>> # get the default handler object:
+    >>> myctx.handler("default")
     <class 'passlib.handlers.md5_crypt.md5_crypt'>
 
-See the :class:`CryptPolicy` class for more details on it's interface.
+    >>> # the results of a CryptContext object can be serialized as a dict,
+    >>> # suitable for passing to CryptContext's class constructor.
+    >>> myctx.to_dict()
+    {'schemes': ['md5_crypt, 'des_crypt'], 'deprecated': 'des_crypt'}
+
+    >>> # or serialized to an INI-style string, suitable for passing to
+    >>> # CryptContext's from_string() method.
+    >>> print myctx.to_string()
+    [passlib]
+    schemes = md5_crypt, des_crypt
+    deprecated = des_crypt
+
+See the :class:`CryptContext` reference for more details on it's interface.
 
 Full Integration Example
 ========================
@@ -123,31 +134,32 @@ applications with advanced policy requirements may want to create a hash policy
 
     [passlib]
 
-    ;setup the context to support pbkdf2_sha1, along with legacy md5_crypt hashes:
+    ; setup the context to support pbkdf2_sha1, along with legacy md5_crypt hashes:
     schemes = pbkdf2_sha1, md5_crypt
 
-    ;flag md5_crypt as deprecated
-    ;   (existing md5_crypt hashes will be flagged as needs-updating)
+    ; flag md5_crypt as deprecated
+    ; (existing md5_crypt hashes will be flagged as needs-updating)
     deprecated = md5_crypt
 
-    ;set boundaries for pbkdf2 rounds parameter
-    ;   (pbkdf2 hashes outside this range will be flagged as needs-updating)
-    pbkdf2_sha1.min_rounds = 10000
-    pbkdf2_sha1.max_rounds = 50000
-
-    ;set the default rounds to use when encrypting new passwords.
-    ;the 'vary' field will cause each new hash to randomly vary
-    ;from the default by the specified %.
-    pbkdf2_sha1.default_rounds = 20000
-    pbkdf2_sha1.vary_rounds = 10%%
-        ; NOTE the '%' above has to be doubled due to configparser interpolation
-
-    ;applications can choose to treat certain user accounts differently,
-    ;by assigning different types of account to a 'user category',
-    ;and setting special policy options for that category.
-    ;this create a category named 'admin', which will have a larger default rounds value.
-    admin.pbkdf2_sha1.min_rounds = 40000
-    admin.pbkdf2_sha1.default_rounds = 50000
+    ; set boundaries for pbkdf2 rounds parameter
+    ; (pbkdf2 hashes outside this range will be flagged as needs-updating)
+    pbkdf2_sha1__min_rounds = 10000
+    pbkdf2_sha1__max_rounds = 50000
+
+    ; set the default rounds to use when encrypting new passwords.
+    ; the 'vary' field will cause each new hash to randomly vary
+    ; from the default by the specified % of the default (in this case,
+    ; 20000 +/- 10% or 2000).
+    pbkdf2_sha1__default_rounds = 20000
+    pbkdf2_sha1__vary_rounds = 0.1
+
+    ; applications can choose to treat certain user accounts differently,
+    ; by assigning different types of account to a 'user category',
+    ; and setting special policy options for that category.
+    ; this create a category named 'admin', which will have a larger default
+    ; rounds value.
+    admin__pbkdf2_sha1__min_rounds = 40000
+    admin__pbkdf2_sha1__default_rounds = 50000
 
 Initializing the CryptContext
 -----------------------------
@@ -172,7 +184,6 @@ the configuration once the application starts:
         #
 
         from myapp.model.security import user_pwd_context
-        from passlib.context import CryptPolicy
 
         def myapp_startup():
 
@@ -180,10 +191,13 @@ the configuration once the application starts:
             # ... other code ...
             #
 
-            # vars:
-            #   policy_path - path to policy file defined in previous step
             #
-            user_pwd_context.policy = CryptPolicy.from_path(policy_path)
+            # load configuration from some application-specified path.
+            # the load() method also supports loading from a string,
+            # or from dictionary, and other options.
+            #
+            ##user_pwd_context.load(policy_config_string)
+            user_pwd_context.load_path(policy_config_path)
 
             #
             #if you want to reconfigure the context without restarting the application,
diff --git a/docs/lib/passlib.ext.django.rst b/docs/lib/passlib.ext.django.rst
index 225642e..d797e23 100644
--- a/docs/lib/passlib.ext.django.rst
+++ b/docs/lib/passlib.ext.django.rst
@@ -73,7 +73,7 @@ you may set the following options in django ``settings.py``:
    * ``"disabled"``, in which case this app will do nothing when Django is loaded.
 
    * A multiline configuration string suitable for passing to
-     :meth:`passlib.context.CryptPolicy.from_string`.
+     :meth:`passlib.context.CryptContext.from_string`.
      It is *strongly* recommended to use a configuration which will support
      the existing Django hashes
      (see :data:`~passlib.ext.django.utils.STOCK_CTX`).
diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst
index 5ca13db..85514e8 100644
--- a/docs/lib/passlib.hosts.rst
+++ b/docs/lib/passlib.hosts.rst
@@ -52,7 +52,7 @@ for the following Unix variants:
     All of the above contexts include the :class:`~passlib.hash.unix_disabled` handler
     as a final fallback. This special handler treats all strings as invalid passwords,
     particularly the common strings ``!`` and ``*`` which are used to indicate
-    that an account has been disabled [#shadow]_. 
+    that an account has been disabled [#shadow]_.
 
 A quick usage example, using the :data:`!linux_context` instance::
 
@@ -81,7 +81,7 @@ Current Host OS
     The main differences between this object and :func:`!crypt`:
 
     * this object provides introspection about *which* schemes
-      are available on a given system (via ``host_context.policy.schemes()``).
+      are available on a given system (via ``host_context.schemes()``).
     * it defaults to the strongest algorithm available,
       automatically configured to an appropriate strength
       for encrypting new passwords.