doc tweaks

8 files changed, 36 insertions, 21 deletions

diff --git a/CHANGES b/CHANGES
index dadf66b..7e79614 100644
--- a/CHANGES
+++ b/CHANGES
@@ -121,6 +121,8 @@ Release History
 
     Other
 
+        * Handle platform-specific error strings returned by :func:`!crypt.crypt`.
+
         * Passlib is now source-compatible with Python 2.5+ and Python 3,
           and no longer requires the use of :command:`2to3` to run under Python 3.
 
@@ -438,7 +440,7 @@ Release History
 ====================
 
     * CryptContext & CryptHandler framework
-    * added support for: des-crypt, bcrypt (via pybcrypt), postgres, mysql
+    * added support for: des-crypt, bcrypt (via py-bcrypt), postgres, mysql
     * added unit tests
 
 **0.5** (2008-05-10)
diff --git a/README b/README
index afe3a7b..7bec5cd 100644
--- a/README
+++ b/README
@@ -17,8 +17,8 @@ The latest documentation can be found online at `<http://packages.python.org/pas
 
 Requirements
 ============
-* Python 2.5 - 2.7 or Python 3
-* PyBCrypt or BCryptor (optional; required only if bcrypt support is needed)
+* Python 2.5 - 2.7 or Python 3.x
+* py-bcrypt or bcryptor (optional; required only if bcrypt support is needed)
 * M2Crypto (optional; accelerates PBKDF2-based hashes)
 
 Installation
diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst
index 40d3b7a..a47df43 100644
--- a/docs/lib/passlib.apps.rst
+++ b/docs/lib/passlib.apps.rst
@@ -54,7 +54,14 @@ Django
     password hashes, as used by Django's ``django.contrib.auth`` module.
     It recognizes all the :doc:`builtin Django hashes <passlib.hash.django_std>`.
     It defaults to using the :class:`~passlib.hash.django_salted_sha1` hash.
-    
+
+    .. note::
+
+        This object may not match the hashes in your database if a third-party
+        library has been used to patch Django to support alternate hash formats.
+        This includes the `django-bcrypt <http://pypi.python.org/pypi/django-bcrypt>`_
+        plugin, or Passlib's builtin :mod:`django extension <passlib.ext.django>`.
+
 .. _ldap-contexts:
 
 LDAP
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 11c1a25..50eba4f 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -14,7 +14,7 @@ for new applications.
 .. note::
 
     It is strongly recommended to install
-    :ref:`PyBcrypt or BCryptor <optional-libraries>`
+    :ref:`py-bcrypt or bcryptor <optional-libraries>`
     if this algorithm is going to be used.
 
 Usage
@@ -63,7 +63,7 @@ Bcrypt hashes have the format :samp:`$2a${rounds}${salt}{checksum}`, where:
 * :samp:`{checksum}` is the 31 character checksum, using the same characters as the salt (``AnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` in the example).
 
 While BCrypt's basic algorithm is described in it's design document [#f1]_,
-the OpenBSD implementation [#f2]_ is considered the canonical reference, even 
+the OpenBSD implementation [#f2]_ is considered the canonical reference, even
 though it differs from the design document in a few small ways.
 
 Deviations
@@ -118,7 +118,7 @@ This implementation of bcrypt differs from others in a few ways:
 
   ``$2y$``, the default for crypt_blowfish 1.1 and newer, indicates
   the hash was generated with the canonical OpenBSD-compatible algorithm,
-  and should match *correctly* generated ``$2a$`` hashes. 
+  and should match *correctly* generated ``$2a$`` hashes.
   Passlib 1.6 can generate and verify these hashes.
 
   As well, crypt_blowfish 1.2 modified the way it generates ``$2a$`` hashes,
@@ -134,5 +134,5 @@ This implementation of bcrypt differs from others in a few ways:
 .. [#f2] the OpenBSD BCrypt source -
          `<http://www.openbsd.org/cgi-bin/cvsweb/src/lib/libc/crypt/bcrypt.c>`_
 
-.. [#eight] The flaw in pre-1.1 crypt_blowfish is described here - 
+.. [#eight] The flaw in pre-1.1 crypt_blowfish is described here -
             `CVE-2011-2483 <http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-2483>`_
diff --git a/docs/lib/passlib.utils.compat.rst b/docs/lib/passlib.utils.compat.rst
index 2536b0a..6ee6a19 100644
--- a/docs/lib/passlib.utils.compat.rst
+++ b/docs/lib/passlib.utils.compat.rst
@@ -54,3 +54,8 @@ Bytes Helpers
 .. function:: byte_elem_value
 
     Function to convert byte element to integer (a no-op under PY3)
+
+.. function:: iter_byte_values
+
+    Function to iterate over a byte string as a series of integers.
+    (This is just the native bytes iterator under PY3).
diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst
index d18afb3..32df641 100644
--- a/docs/new_app_quickstart.rst
+++ b/docs/new_app_quickstart.rst
@@ -66,7 +66,7 @@ All three password hashes share the following properties:
 The following comparison should help you choose which hash is
 most appropriate for your application; if in doubt,
 any of these is a good choice, though PBKDF2 is probably the best
-for portability. 
+for portability.
 
 .. rst-class:: html-toggle
 
@@ -96,7 +96,7 @@ of simultaneous logon attempts (eg web apps).
     For BCrypt support on non-BSD systems,
     Passlib requires a C-extension module
     provided by the external
-    :ref:`PyBcrypt or BCryptor <optional-libraries>`  packages.
+    :ref:`py-bcrypt or bcryptor <optional-libraries>`  packages.
     Neither of these currently supports Python 3.
 
 SHA512-Crypt
diff --git a/passlib/handlers/sha2_crypt.py b/passlib/handlers/sha2_crypt.py
index 56ed086..94472dc 100644
--- a/passlib/handlers/sha2_crypt.py
+++ b/passlib/handlers/sha2_crypt.py
@@ -48,7 +48,7 @@ def _raw_sha_crypt(secret, salt, rounds, hash):
     :arg secret: password to encode (if unicode, encoded to utf-8)
     :arg salt: salt string to use (required)
     :arg rounds: int rounds
-    :arg hash: hash constructor function for 256/512 variant
+    :arg hash: hash constructor function for sha-256 or sha-512
 
     :returns:
         Returns tuple of ``(unencoded checksum, normalized salt, normalized rounds)``.
@@ -105,8 +105,8 @@ def _raw_sha_crypt(secret, salt, rounds, hash):
     #
     # NOTE: The code below is quite different in appearance from how the
     # specification performs this step. the original algorithm was that:
-    # C should start out set to A
-    # for i in [0,rounds)... the next value of C is calculated as the digest of:
+    # C starts out set to A
+    # for i in [0,rounds), the next value of C is calculated as the digest of:
     #       if i%2>0 then DP else C
     #       +
     #       if i%3>0 then DS else ""
@@ -115,7 +115,7 @@ def _raw_sha_crypt(secret, salt, rounds, hash):
     #       +
     #       if i%2>0 then C else DP
     #
-    # The algorithm can be seen as a series of paired even/odd rounds,
+    # This algorithm can be seen as a series of paired even/odd rounds,
     # with each pair performing 'C = md5(odd_data + md5(C + even_data))',
     # where even_data & odd_data cycle through a fixed series of
     # combinations of DP & DS, repeating every 42 rounds (since lcm(2,3,7)==42)
@@ -144,12 +144,12 @@ def _raw_sha_crypt(secret, salt, rounds, hash):
     # perform any leftover rounds
     if tail:
         # perform any pairs of rounds
-        half = tail>>1
-        for even, odd in data[:half]:
+        pairs = tail>>1
+        for even, odd in data[:pairs]:
             c = hash(odd + hash(c + even).digest()).digest()
         # if rounds was odd, do one last round
         if tail & 1:
-            c = hash(c + data[half][0]).digest()
+            c = hash(c + data[pairs][0]).digest()
 
     #return unencoded result, along w/ normalized config values
     return c, salt, rounds
@@ -495,7 +495,8 @@ class sha512_crypt(uh.HasManyBackends, uh.HasRounds, uh.HasSalt, uh.GenericHandl
                                           "yWeBdRDx4DU.1H3eGmse6pgsOgDisWBG"
                                           "I5c7TZauS0")
 
-    #NOTE: testing w/ HashTimer shows 64-bit linux's crypt to be ~2.6x faster than builtin (627253 vs 238152 rounds/sec)
+    # NOTE: testing w/ HashTimer shows 64-bit linux's crypt to be ~2.6x faster
+    # than builtin (627253 vs 238152 rounds/sec)
 
     def _calc_checksum_builtin(self, secret):
         if isinstance(secret, unicode):
diff --git a/passlib/utils/_blowfish/base.py b/passlib/utils/_blowfish/base.py
index 22f6bbe..9be048b 100644
--- a/passlib/utils/_blowfish/base.py
+++ b/passlib/utils/_blowfish/base.py
@@ -19,7 +19,7 @@ def _init_constants():
     global BLOWFISH_P, BLOWFISH_S
 
     # NOTE: blowfish's spec states these numbers are the hex representation
-    # of the fractional portion of PI, in order. 
+    # of the fractional portion of PI, in order.
 
     # Initial contents of key schedule - 18 integers
     BLOWFISH_P = [
@@ -318,8 +318,8 @@ class BlowfishEngine(object):
     #=========================================================
     @staticmethod
     def key_to_words(data, size=18):
-        """convert data to tuple of integers, repeated or truncating data
-        as needed to reach specified size"""
+        """convert data to tuple of <size> 4-byte integers, repeating or
+        truncating data as needed to reach specified size"""
         assert isinstance(data, bytes)
         dlen = len(data)
         if not dlen: