documentation updates for latest round of changes

5 files changed, 106 insertions, 77 deletions

diff --git a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst
index 1dfd832..04e7acb 100644
--- a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst
+++ b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst
@@ -47,7 +47,7 @@ where:
   stored as lowercase hexidecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations).
 
 * :samp:`{salt}` is the salt string, which can be any number of characters,
-  drawn from the :ref:`hash64 charset <h64charset>`
+  drawn from the :data:`hash64 charset <passlib.utils.HASH64_CHARS>`
   (``.pPqsEwHD7MiECU0`` in the example).
 
 * :samp:`{checksum}` is 32 characters, which encode
diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst
index e732c5d..a4830c1 100644
--- a/docs/lib/passlib.hash.pbkdf2_digest.rst
+++ b/docs/lib/passlib.hash.pbkdf2_digest.rst
@@ -36,7 +36,7 @@ All of the following classes can be used directly as follows::
     '$pbkdf2-sha256$6400$0ZrzXitFSGltTQnBWOsdAw$Y11AchqV4b0sUisdZd0Xr97KWoymNE0LNNrnEgY4H9M'
 
     >>> #same, but with explicit number of rounds and salt length
-    >>> engine.encrypt("password", rounds=8000, salt_size=10) 
+    >>> engine.encrypt("password", rounds=8000, salt_size=10)
     '$pbkdf2-sha256$8000$XAuBMIYQQogxRg$tRRlz8hYn63B9LYiCd6PRo6FMiunY9ozmMMI3srxeRE'
 
     >>> #check if hash is a pbkdf2-sha256 hash
diff --git a/docs/lib/passlib.utils.compat.rst b/docs/lib/passlib.utils.compat.rst
new file mode 100644
index 0000000..5add85d
--- /dev/null
+++ b/docs/lib/passlib.utils.compat.rst
@@ -0,0 +1,56 @@
+======================================================
+:mod:`passlib.utils.compat` - Python 2/3 Compatibility
+======================================================
+
+.. module:: passlib.utils.compat
+    :synopsis: python 2/3 compatibility wrappers
+
+This module contains a number of wrapper functions used by Passlib
+to run under Python 2 and 3 without changes.
+
+.. todo::
+
+    finish documenting this module.
+
+Unicode Helpers
+===============
+.. autofunction:: uascii_to_str
+.. autofunction:: str_to_uascii
+
+.. function:: ujoin
+
+    Join a sequence of unicode strings, e.g.
+    ``ujoin([u"a",u"b",u"c"]) -> u"abc"``.
+
+Bytes Helpers
+=============
+.. autofunction:: bascii_to_str
+.. autofunction:: str_to_bascii
+
+.. function:: bjoin
+
+    Join a sequence of byte strings, e.g.
+    ``bjoin([b"a",b"b",b"c"]) -> b"abc"``.
+
+.. function:: bjoin_ints
+
+    Join a sequence of integers into a byte string,
+    e.g. ``bjoin_ints([97,98,99]) -> b"abc"``.
+
+.. function:: bjoin_elems
+
+    Join a sequence of byte elements into a byte string.
+
+    Python 2 & 3 return different things when accessing
+    a single element of a byte string:
+
+    * Python 2 returns a 1-element byte string (e.g. ``b"abc"[0] -> b"a"``).
+    * Python 3 returns the ordinal value (e.g. ``b"abc"[0] -> 97``).
+
+    This function will join a sequence of the appropriate type
+    for the given python version -- under Python 2, this is an alias
+    for :func:`bjoin`, under Python 3 this is an alias for :func:`bjoin_ints`.
+
+.. function:: belem_ord
+
+    Function to convert byte element to integer (a no-op under PY3)
diff --git a/docs/lib/passlib.utils.h64.rst b/docs/lib/passlib.utils.h64.rst
deleted file mode 100644
index 89c5bde..0000000
--- a/docs/lib/passlib.utils.h64.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-================================================
-:mod:`passlib.utils.h64` - Hash-64 Codec helpers
-================================================
-
-.. module:: passlib.utils.h64
-    :synopsis: Hash-64 Codec helpers
-
-Many of the password hash algorithms in passlib
-use a encoding scheme very similar to (but not compatible with)
-the standard base64 encoding scheme. the main differences are that
-it assigns the characters *completely* different numeric values compared
-to base64, as well as using ``.`` instead of ``+`` in it's character set.
-
-This encoding system appears to have originated with des-crypt hash,
-but is used by md5-crypt, sha-256-crypt, and others.
-within passlib, this encoding is referred as ``hash64`` encoding,
-and this module contains various utilities functions for encoding
-and decoding strings in that format.
-
-.. note::
-    It may *look* like bcrypt uses this scheme,
-    when in fact bcrypt uses yet another ordering,
-    which does not match hash64 or other base64 schemes.
-
-.. _h64charset:
-
-Constants
-=========
-.. data:: CHARS = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
-
-    The character set used by the Hash-64 format.
-    A character's index in CHARS denotes it's corresponding 6-bit integer value.
-
-Bytes <-> Hash64
-================
-
-.. autofunction:: encode_bytes
-.. autofunction:: decode_bytes
-
-.. autofunction:: encode_transposed_bytes
-.. autofunction:: decode_transposed_bytes
-
-Int <-> Hash64
-==============
-
-.. autofunction:: decode_int6
-.. autofunction:: encode_int6
-
-.. autofunction:: decode_int12
-.. autofunction:: encode_int12
-
-.. autofunction:: decode_int24
-.. autofunction:: encode_int24
-
-.. autofunction:: decode_int64
-.. autofunction:: encode_int64
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index 4aa97f2..404e9f5 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -38,15 +38,33 @@ Constants
 
 .. autoexception:: PasslibPolicyWarning
 
+..
+
+    PYPY
+    JYTHON
+    rounds_cost_values
+
 Decorators
 ==========
 .. autofunction:: classproperty
 
-Bytes Manipulation
-==================
+Unicode Helpers
+===============
+.. autofunction:: consteq
+.. autofunction:: saslprep
 
+Bytes Helpers
+=============
 .. autofunction:: xor_bytes
-.. autofunction:: consteq
+.. autofunction:: render_bytes
+
+Encoding Helpers
+================
+.. autofunction:: is_same_codec
+.. autofunction:: is_ascii_safe
+.. autofunction:: to_bytes
+.. autofunction:: to_unicode
+.. autofunction:: to_native_str
 
 Base64 Encoding
 ===============
@@ -72,7 +90,12 @@ Common Character Maps
 
     Base64 character map used by a number of hash formats;
     the ordering is wildly different from the standard base64 character map.
-    (see :data:`h64` for details).
+
+    This encoding system appears to have originated with
+    :class:`~passlib.hash.des_crypt`, but is used by
+    :class:`~passlib.hash.md5_crypt`, :class:`~passlib.hash.sha256_crypt`,
+    and others. Within Passlib, this encoding is referred as ``hash64`` encoding
+    to distinguish it from normal base64 and other encodings.
 
 .. data:: BCRYPT_CHARS
 
@@ -83,27 +106,24 @@ Common Character Maps
 Predefined Instances
 --------------------
 .. data:: h64
-    Predefined instance of :class:`Base64Engine` which uses
-    the :data:`HASH64_CHARS` character map and little-endian encoding.
 
-    This encoding system appears to have originated with
-    :class:`~passlib.hash.des_crypt`, but is used by
-    :class:`~passlib.hash.md5-crypt`, `~passlib.hash.sha256_crypt`,
-    and others. Within Passlib, this encoding is referred as ``hash64`` encoding
-    to distinguish it from normal base64 and other encodings.
+    Predefined instance of :class:`Base64Engine` which uses
+    the :data:`!HASH64_CHARS` character map and little-endian encoding.
+    (see :data:`!HASH64_CHARS` for more details).
 
 .. data:: h64big
+
     Predefined variant of :data:`h64` which uses big-endian encoding.
     This is mainly used by :class:`~passlib.hash.des_crypt`.
 
 .. note::
 
-   *changed in Passlib 1.6:* the :mod:`passlib.utils.h64` module used by
-   Passlib <= 1.5 has been replaced by the the ``h64`` and ``h64big``
-   instances; but the interface remains mostly unchanged.
+   *changed in Passlib 1.6:* Previous versions of Passlib contained
+   a module named :mod:`!passlib.utils.h64`; As of Passlib 1.6 this
+   was replaced by the the ``h64`` and ``h64big`` instances;
+   the interface remains mostly unchanged.
 
 ..
-
     .. data:: AB64_CHARS
 
         Variant of standard Base64 character map used by some
@@ -114,6 +134,12 @@ Predefined Instances
     .. autofunction:: ab64_encode
     .. autofunction:: ab64_decode
 
+..
+    Host OS
+    =======
+    .. autofunction:: safe_os_crypt
+    .. autofunction:: tick
+
 Randomness
 ==========
 .. data:: rng
@@ -129,11 +155,10 @@ Randomness
 
 .. autofunction:: getrandbytes
 .. autofunction:: getrandstr
-
 .. autofunction:: generate_password(size=10, charset=<default>)
 
-Object Tests
-============
+Interface Tests
+===============
 .. autofunction:: is_crypt_handler
 .. autofunction:: is_crypt_context
 .. autofunction:: has_rounds_info
@@ -146,7 +171,11 @@ There are also a few sub modules which provide additional utility functions:
 .. toctree::
     :maxdepth: 1
 
+    passlib.utils.handlers
     passlib.utils.des
     passlib.utils.md4
     passlib.utils.pbkdf2
-    passlib.utils.handlers
+
+..
+
+    passlib.utils.compat