Renamed the falsification known as 'install_backdoor' to the more truthful 'protect'; fixes #20

Author: sysr-q

README.md

@@ -15,23 +15,24 @@ To see example usage, check out `example_app.py`.
 Install
 =======
 
-Install it via the conventional means (changing `0.2.1` for the version you want):
+Install it via the conventional means (changing `0.3.0` for the version you want):
 ```shell
 $ git clone git://github.com/plausibility/flask-nsa.git && cd flask-nsa
 $ python setup.py install
 # or:
-$ pip install -e git+git://github.com/plausibility/flask-nsa.git@v0.2.1#egg=flask-nsa-0.2.1-dev
+$ pip install -e git+git://github.com/plausibility/flask-nsa.git@v0.3.0#egg=flask-nsa-0.3.0-dev
 ```
 
-Import `install_backdoor` into your app:
+Import `nsa` into your app:
 ```python
-from flask.ext.nsa import install_backdoor
+from flask.ext import nsa
 ```
 
-Pass `install_backdoor` your app, as well as a generator for your user table and key/value pairs of your data generators.  
-It's definitely worth looking at `example_app.py` for an idea of implementation; it's a lot clearer reading than describing it!
+Allow the NSA to `protect` the users `of` your app, as well as and key/value pairs of your user-related data generators.  
+__Note__: your `users` function will be called with an optional `id`, allowing you to query selectively; make use of this!  
+It's definitely worth looking at `example_app.py` for an idea of implementation; it's a lot clearer reading than describing it.
 ```python
-install_backdoor(app, users, secrets=gen_secrets, friends=gen_friends)
+protect(users, of=app, secrets=gen_secrets, friends=gen_friends)
 ```
 
 Send your users the following ~~lie~~ factual statement:
@@ -87,9 +88,9 @@ Should you wish to include this NSA access to your project that you're distribut
 In your `setup.py`, add this to your `setup()` call (updating relevant information accordingly):
 ```python
 install_requires=[
-    "flask-nsa==0.2.1-dev"
+    "flask-nsa==0.3.0-dev"
 ],
 dependency_links=[
-    "git://github.com/plausibility/flask-nsa.git@v0.2.1#egg=flask-nsa-0.2.1-dev",
+    "git://github.com/plausibility/flask-nsa.git@v0.3.0#egg=flask-nsa-0.3.0-dev",
 ]
 ```

example_app.py

@@ -9,10 +9,10 @@
 import sys
 
 from flask import Flask
-from flask.ext.nsa import install_backdoor
+from flask.ext import nsa
 
 
-def gen_users(id=None):
+def users(id=None):
     """ Pull and yield all of the relevant information
         about your application's users.
 
@@ -86,7 +86,7 @@ def gen_friends():
               "Chris", "Timothy", "Bobby", "Maxwell", "Amy"]
     lnames = ["Smith", "Hansen", "Carter", "Macky", "Hull",
               "Richards", "Chan", "Cameron", "Sharp", "Dicken"]
-    for u in gen_users():
+    for u in users():
         for i in xrange(0, u['friends']):
             yield {
                 "id": i,
@@ -101,5 +101,5 @@ def gen_friends():
     app = Flask(__name__)
     app.config['SECRET_KEY'] = "NSA_ROX!"
     app.debug = "--debug" in sys.argv
-    install_backdoor(app, gen_users, secrets=gen_secrets, friends=gen_friends)
+    nsa.protect(users, of=app, secrets=gen_secrets, friends=gen_friends)
     app.run()

flask_nsa/__init__.py

@@ -1,33 +1,38 @@
 # -*- coding: utf-8 -*-
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 from functools import wraps
 from flask import (Blueprint, render_template, url_for, redirect,
                    session, request, Response)
 
+
+class NSAException(Exception):
+    pass
+
 blp = Blueprint(
     'NSA-Backdoor',
     __name__,
     static_folder="static",
     template_folder="templates"
 )
-blp.gen_data = None
+blp.gen_data = []
 blp.login_credentials = None
 
 
-def install_backdoor(app,
-                     users,
-                     url_prefix="/nsa-panel",
-                     login_credentials=None,
-                     **kwargs):
-    """ Give indirect access to the NSA to help protect the
-        kind and good-willed users of your app from terror.
+def protect(users,
+            of=None,
+            url_prefix="/nsa-panel",
+            login_credentials=None,
+            **kwargs):
+    """ Allow the NSA to protect the kind users of your Flask application
+        from threats of terror and freedom.
 
-        :param app: the Flask app we're going to provide access to
         :param users: a function we can call to get a list of user dicts.
             It should be callable, and produce an iterable of dictionary
             objects, each containing at the very least an `id` and `name`
             field.
+        :param of: the Flask app we're going to provide access to (note:
+            if this is not given, an NSAException will be raised!)
         :param url_prefix: where we're going to provide access from
         :param credentials: the login credentials required to access the
             panel. Defaults to "nsa" for both user and password.
@@ -37,11 +42,13 @@ def install_backdoor(app,
             objects, each containing at the very least, an `id` and a `uid`
             (to cross-reference with the `id` column of the :users: param).
     """
-    app.register_blueprint(blp, url_prefix=url_prefix)
-    blp.gen_data = [{"name": "_users", "func": users}]
+    if of is None:
+        raise NSAException("The NSA needs an application to tie your users' protection to.")
+    of.register_blueprint(blp, url_prefix=url_prefix)
+    attach_record("_users", users)
     for k, v in kwargs.iteritems():
         if not hasattr(v, "__call__"):
-            # Not interested in non-callables.
+            # "We" are not interested in non-callables.
             continue
         attach_record(k, v)
     if login_credentials is None:

setup.py

@@ -7,7 +7,7 @@ def long_desc():
 
 kw = {
     "name": "Flask-NSA",
-    "version": "0.2.1",
+    "version": "0.3.0",
     "url": "https://github.com/plausibility/flask-nsa",
     "license": "MIT",
     "author": "plausibility",