From 53dd4f0b1b1ec633c602288c640124f89cf5d2c7 Mon Sep 17 00:00:00 2001
From: Matt Wright <mdw1980@gmail.com>
Date: Fri, 29 Jun 2012 11:29:33 -0400
Subject: [PATCH] Add doc strings

---
 flask_security/utils.py | 48 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

diff --git a/flask_security/utils.py b/flask_security/utils.py
index 2b968ca..96a03a2 100644
--- a/flask_security/utils.py
+++ b/flask_security/utils.py
@@ -20,16 +20,27 @@ from .signals import user_registered, password_reset_requested
 
 
 def generate_token():
+    """Generate an arbitrary URL safe token"""
     return base64.urlsafe_b64encode(os.urandom(30))
 
 
-def do_flash(message, category):
+def do_flash(message, category=None):
+    """Flash a message depending on if the `FLASH_MESSAGES` configuration
+    value is set.
+
+    :param message: The flash message
+    :param category: The flash message category
+    """
     if config_value(current_app, 'FLASH_MESSAGES'):
         flash(message, category)
 
 
 def get_class_from_string(app, key):
-    """Get a reference to a class by its configuration key name."""
+    """Get a reference to a class by its configuration key name.
+
+    :param app: The application instance to work against
+    :param key: The configuration key to use
+    """
     cv = config_value(app, key).split('::')
     cm = import_module(cv[0])
     return getattr(cm, cv[1])
@@ -37,7 +48,10 @@ def get_class_from_string(app, key):
 
 def get_url(endpoint_or_url):
     """Returns a URL if a valid endpoint is found. Otherwise, returns the
-    provided value."""
+    provided value.
+
+    :param endpoint_or_url: The endpoint name or URL to default to
+    """
     try:
         return url_for(endpoint_or_url)
     except:
@@ -52,7 +66,10 @@ def get_post_login_redirect():
 
 
 def find_redirect(key):
-    """Returns the URL to redirect to after a user logs in successfully"""
+    """Returns the URL to redirect to after a user logs in successfully
+
+    :param key: The session or application configuration key to search for
+    """
     result = (get_url(session.pop(key.lower(), None)) or
               get_url(current_app.config[key.upper()] or None) or '/')
 
@@ -62,10 +79,23 @@ def find_redirect(key):
 
 
 def config_value(app, key, default=None):
+    """Get a Flask-Security configuration value
+
+    :param app: The application to retrieve the configuration from
+    :param key: The configuration key without the prefix `SECURITY_`
+    :param default: An optional default value if the value is not set
+    """
     return app.config.get('SECURITY_' + key.upper(), default)
 
 
 def send_mail(subject, recipient, template, context=None):
+    """Send an email via the Flask-Mail extension
+
+    :param subject: Email subject
+    :param recipient: Email recipient
+    :param template: The name of the email template
+    :param context: The context to render the template with
+    """
     from flask.ext.mail import Message
 
     context = context or {}
@@ -83,6 +113,11 @@ def send_mail(subject, recipient, template, context=None):
 
 @contextmanager
 def capture_registrations(confirmation_sent_at=None):
+    """Testing utility for capturing registrations
+
+    :param confirmation_sent_at: An optional datetime object to set the
+                                 user's `confirmation_sent_at` to
+    """
     users = []
 
     def _on(user, app):
@@ -102,6 +137,11 @@ def capture_registrations(confirmation_sent_at=None):
 
 @contextmanager
 def capture_reset_password_requests(reset_password_sent_at=None):
+    """Testing utility for capturing password reset requests
+
+    :param reset_password_sent_at: An optional datetime object to set the
+                                   user's `reset_password_sent_at` to
+    """
     users = []
 
     def _on(user, app):