Merge with stable

7 files changed, 62 insertions, 8 deletions

diff --git a/docs/contents.rst b/docs/contents.rst
index 099c5f8..700735f 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -20,6 +20,7 @@ Table Of Contents
 
     lib/passlib.apache
     lib/passlib.ext.django
+    lib/passlib.pwd
 
     lib/passlib.exc
     lib/passlib.registry
diff --git a/docs/index.rst b/docs/index.rst
index 270fcba..97be1fc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -85,6 +85,9 @@ Application Helpers
     :mod:`passlib.ext.django`
         Django plugin which monkeypatches support for (almost) any hash in Passlib.
 
+    :mod:`passlib.pwd`
+        Password generation helpers.
+
 ..
     Support Modules
     ---------------
diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst
index 6df24ba..6d40067 100644
--- a/docs/lib/passlib.context.rst
+++ b/docs/lib/passlib.context.rst
@@ -458,8 +458,8 @@ if any invalid-but-correctable values are encountered
 :class:`~passlib.hash.sha256_crypt` 's minimum of 1000).
 
 .. versionchanged:: 1.6
-    Previous releases issued a generic :exc:`UserWarning` instead
-    of the more specific :exc:`PasslibConfigWarning`.
+    Previous releases used Python's builtin :exc:`UserWarning` instead
+    of the more specific :exc:`!passlib.exc.PasslibConfigWarning`.
 
 Other Helpers
 =============
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index c4d7574..8fbea1d 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -123,7 +123,6 @@ they can be used compatibly along side other modular crypt format hashes.
     :maxdepth: 1
 
     passlib.hash.apr_md5_crypt
-    passlib.hash.bcrypt_sha256
     passlib.hash.phpass
     passlib.hash.pbkdf2_digest
     passlib.hash.cta_pbkdf2_sha1
diff --git a/docs/lib/passlib.pwd.rst b/docs/lib/passlib.pwd.rst
new file mode 100644
index 0000000..48441df
--- /dev/null
+++ b/docs/lib/passlib.pwd.rst
@@ -0,0 +1,48 @@
+.. module:: passlib.pwd
+	:synopsis: password generation helpers
+
+=================================================
+:mod:`passlib.pwd` -- password generation helpers
+=================================================
+
+.. versionadded:: 1.7
+
+.. todo::
+    This module is still a work in progress, it's API may change
+    before release. See module source for detailed todo list.
+
+Generation
+==========
+.. warning::
+
+    Before using these routines, be sure your system's RNG state is safe,
+    and that you use a sufficiently high ``entropy`` value for
+    the intended purpose.
+
+.. autofunction:: generate(size=None, entropy=None, count=None, preset=None, charset=None, wordset=None, spaces=True)
+
+.. rst-class:: html-toggle
+
+Generator Backends
+------------------
+The following classes are used by the :func:`generate` function behind the scenes,
+to perform word- and phrase- generation. They are useful for folks who want
+a little more information about the password generation process, and/or
+want to use a preconfigured generator.
+
+.. autoclass:: SecretGenerator
+.. autoclass:: WordGenerator
+.. autoclass:: PhraseGenerator
+
+Analysis
+========
+.. warning::
+
+    *Disclaimer:*
+    There can be no accurate estimate of the quality of a password,
+    because it depends on too many conditions that are unknowable from just
+    looking at the password. This code attempts to rule out the worst passwords,
+    and identify potentially-weak passwords, but should be used only as a guide.
+
+.. autofunction:: strength
+.. autofunction:: classify
diff --git a/docs/lib/passlib.utils.pbkdf2.rst b/docs/lib/passlib.utils.pbkdf2.rst
index f8eb89f..7fa9f98 100644
--- a/docs/lib/passlib.utils.pbkdf2.rst
+++ b/docs/lib/passlib.utils.pbkdf2.rst
@@ -26,7 +26,10 @@ PKCS#5 Key Derivation Functions
 Helper Functions
 ================
 .. autofunction:: norm_hash_name
+.. autofunction:: get_hash_info
+
 .. autofunction:: get_prf
+.. autofunction:: get_keyed_prf
 
 ..
     given how this module is expanding in scope,
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 69e0d5c..c9d6191 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -630,7 +630,7 @@ and the following attributes should be defined:
 
     The maximum number of rounds the scheme allows.
     Specifying a value beyond this will result in a :exc:`ValueError`.
-    Will be a positive integer, or ``None`` (indicating
+    This will be either a positive integer, or ``None`` (indicating
     the algorithm has no effective upper limit).
 
 .. attribute:: PasswordHash.min_rounds
@@ -720,8 +720,8 @@ and the following attributes should be defined:
 
 Choosing the right rounds value
 ===============================
-For hash algorithms which support a variable time-cost,
-Passlib's default ``rounds`` choices attempt to be secure enough for
+For hash algorithms with a variable time-cost, 
+Passlib's :attr:`~PasswordHash.default_rounds` values attempt to be secure enough for
 the average [#avgsys]_ system. But the "right" value for a given hash
 is dependant on the server, its cpu, its expected load, and its users.
 Since larger values mean increased work for an attacker,
@@ -733,8 +733,8 @@ take upwards of 250ms - 400ms before users start getting annoyed.
 For superuser accounts, it should take as much time as the admin can stand
 (usually ~4x more delay than a regular account).
 
-Passlib's ``default_rounds`` values are retuned periodically
-by taking a rough estimate of what an "average" system is capable of,
+Passlib's :attr:`!default_rounds` values are retuned periodically,
+starting with a rough estimate of what an "average" system is capable of,
 and then setting all :samp:`{hash}.default_rounds` values to take ~300ms on such a system.
 However, some older algorithms (e.g. :class:`~passlib.hash.bsdi_crypt`) are weak enough that
 a tradeoff must be made, choosing "secure but intolerably slow" over "fast but unacceptably insecure".