added documentation for passlib.registry

1 files changed, 60 insertions, 0 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