comments & doc updates

3 files changed, 24 insertions, 4 deletions

diff --git a/passlib/totp.py b/passlib/totp.py
index 00e7573..c51a165 100644
--- a/passlib/totp.py
+++ b/passlib/totp.py
@@ -377,7 +377,7 @@ class BaseOTP(object):
     """
     Base class for generating and verifying OTP codes.
 
-    .. rst-class:: inline
+    .. rst-class:: inline-title
 
     .. note::
 
@@ -437,7 +437,7 @@ class BaseOTP(object):
         The number of digits in the generated / accepted tokens. Defaults to ``6``.
         Must be in range [6 .. 10].
 
-        .. rst-class:: inline
+        .. rst-class:: inline-title
         .. caution::
            Due to a limitation of the HOTP algorithm, the 10th digit can only take on values 0 .. 2,
            and thus offers very little extra security.
@@ -1350,7 +1350,7 @@ class HOTP(BaseOTP):
            How many additional steps past ``counter`` to search when looking for a match
            Defaults to 1.
 
-           .. rst-class:: inline
+           .. rst-class:: inline-title
            .. note::
               This is a forward-looking window only, as searching backwards
               would allow token-reuse, defeating the whole purpose of HOTP.
@@ -1401,7 +1401,7 @@ class HOTP(BaseOTP):
            How many additional steps past ``counter`` to search when looking for a match
            Defaults to 1.
 
-           .. rst-class:: inline
+           .. rst-class:: inline-title
            .. note::
               This is a forward-looking window only, as using a backwards window
               would allow token-reuse, defeating the whole purpose of HOTP.
diff --git a/passlib/utils/compat/__init__.py b/passlib/utils/compat/__init__.py
index c7cc5db..51c5b72 100644
--- a/passlib/utils/compat/__init__.py
+++ b/passlib/utils/compat/__init__.py
@@ -53,6 +53,7 @@ __all__ = [
     'int_types',
     'num_types',
     'unicode_or_bytes_types',
+    'native_string_types',
 
     # unicode/bytes types & helpers
     'u',
@@ -105,6 +106,11 @@ else:
     unicode_or_bytes_types = (basestring,)
     native_string_types = (basestring,)
 
+# unicode -- unicode type, regardless of python version
+# bytes -- bytes type, regardless of python version
+# unicode_or_bytes_types -- types that text can occur in, whether encoded or not
+# native_string_types -- types that native python strings (dict keys etc) can occur in.
+
 #=============================================================================
 # unicode & bytes helpers
 #=============================================================================
diff --git a/passlib/utils/handlers.py b/passlib/utils/handlers.py
index 6fdb0ba..3636829 100644
--- a/passlib/utils/handlers.py
+++ b/passlib/utils/handlers.py
@@ -1616,6 +1616,11 @@ class HasManyBackends(GenericHandler):
     .. automethod:: set_backend
     .. automethod:: has_backend
 
+    .. warning::
+
+        :meth:`set_backend` and :meth:`has_backend` are intended to be called
+        during application startup -- they affect global state, are not threadsafe.
+
     Private API (Subclass Hooks)
     ----------------------------
     The following attributes and methods should be filled in by the subclass
@@ -1635,6 +1640,15 @@ class HasManyBackends(GenericHandler):
 
         .. versionadded:: 1.7
 
+        .. warning::
+
+            Due to the way passlib's internals are arranged,
+            backends should always store stateful data at the class level
+            (not the module level), and be prepared to be called on subclasses
+            which may be set to a different backend from their parent.
+
+            Idempotent module-level data such as lazy imports are fine.
+
     .. attribute:: _has_backend_{name}
 
         private class attribute checked by :meth:`has_backend` to see if a