added documentation for passlib.registry

2 files changed, 75 insertions, 4 deletions

diff --git a/docs/lib/passlib.registry.rst b/docs/lib/passlib.registry.rst
new file mode 100644
index 0000000..2d7a8a4
--- /dev/null
+++ b/docs/lib/passlib.registry.rst
@@ -0,0 +1,60 @@
+===================================================
+:mod:`passlib.registry` - Password Handler Registry
+===================================================
+
+.. module:: passlib.registry
+    :synopsis: registry for tracking password hash handlers.
+
+This module contains the code PassLib uses to track all password hash handlers
+that it knows about. While custom handlers can be used directly within an application,
+or even handed to a :class:`!CryptContext`; it is frequently useful to register
+them globally within a process and then refer to them by name.
+This module provides facilities for that, as well as programmatically
+querying passlib to detect what algorithms are available.
+
+Interface
+=========
+.. autofunction:: get_crypt_handler
+.. autofunction:: list_crypt_handlers
+.. autofunction:: register_crypt_handler_path
+.. autofunction:: register_crypt_handler
+
+.. note::
+
+    All password hashes registered with passlib are exposed as objects
+    importable from :mod:`passlib.hash`. This is true not just of the builtin
+    classes, but ones that are registered using the functions below.
+    The :mod:`!passlib.hash` module acts as a proxy object for this registry,
+    changes made here will affect it as well.
+
+Usage
+=====
+Example showing how to use :func:`!registry_crypt_handler_path`::
+
+        >>> #register the location of a handler without loading it
+        >>> from passlib.registry import register_crypt_handler_path
+        >>> register_crypt_handler_path("myhash", "myapp.support.hashes")
+
+        >>> #even before being loaded, it's name will show up as available
+        >>> from passlib.registry import list_crypt_handlers
+        >>> 'myhash' in list_crypt_handlers()
+        True
+        >>> 'myhash' in list_crypt_handlers(loaded_only=True)
+        False
+
+        >>> #when the name "myhash" is next referenced,
+        >>> #the class "myhash" will be imported from the module "myapp.support.hashes"
+        >>> from passlib.context import CryptContext
+        >>> cc = CryptContext(schemes=["myhash"]) #<-- this will cause autoimport
+
+Example showing how to load a hash by name::
+
+        >>> from passlib.registry import get_crypt_handler
+        >>> get_crypt_handler("sha512_crypt")
+        <class 'passlib.handlers.sha2_crypt.sha512_crypt'>
+
+        >>> get_crypt_handler("missing_hash")
+        KeyError: "no crypt handler found for algorithm: 'missing_hash'"
+
+        >>> get_crypt_handler("missing_hash", None)
+        None
diff --git a/passlib/registry.py b/passlib/registry.py
index 2d4f5b3..cb380bd 100644
--- a/passlib/registry.py
+++ b/passlib/registry.py
@@ -136,12 +136,19 @@ def register_crypt_handler_path(name, path):
 def register_crypt_handler(handler, force=False, name=None):
     """register password hash handler.
 
-    this method registers a handler with the internal passlib registry,
+    this method immediately registers a handler with the internal passlib registry,
     so that it will be returned by :func:`get_crypt_handler` when requested.
 
     :arg handler: the password hash handler to register
     :param force: force override of existing handler (defaults to False)
 
+    :raises TypeError:
+        if the specified object does not appear to be a valid handler.
+
+    :raises ValueError:
+        if the specified object's name (or other required attributes)
+        contain invalid values.
+
     :raises KeyError:
         if a (different) handler was already registered with
         the same name, and ``force=True`` was not specified.
@@ -188,8 +195,7 @@ def get_crypt_handler(name, default=Undef):
 
     this method looks up a handler for the specified scheme.
     if the handler is not already loaded,
-    it checks if the location of one is known (:func:`register_crypt_handler`)
-    and loads it first.
+    it checks if the location is known, and loads it first.
 
     :arg name: name of handler to return
     :param default: if specified, returns default value if no handler found.
@@ -245,7 +251,12 @@ def get_crypt_handler(name, default=Undef):
         return default
 
 def list_crypt_handlers(loaded_only=False):
-    "return sorted list of all known crypt handler names"
+    """return sorted list of all known crypt handler names.
+
+    :param loaded_only: if ``True``, only returns names of handlers which have actually been loaded.
+
+    :returns: list of names of all known handlers
+    """
     global _handlers, _handler_locations
     names = set(_handlers)
     if not loaded_only: