comments & doc updates

2 files changed, 20 insertions, 0 deletions

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