diff --git a/docs/conf.py b/docs/conf.py index 1f35de4..c4b51f6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,8 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +sys.path.append(os.path.abspath('_themes')) +sys.path.append(os.path.abspath('..')) # -- General configuration ----------------------------------------------------- @@ -89,17 +90,20 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'flask_small' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + 'github_fork': 'mattupstate/flask-security', + 'index_logo': False +} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -287,3 +291,20 @@ epub_copyright = u'2012, Matt Wright' # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} + +pygments_style = 'flask_theme_support.FlaskyStyle' + +# fall back if theme is not there +try: + __import__('flask_theme_support') +except ImportError, e: + print '-' * 74 + print 'Warning: Flask themes unavailable. Building with default theme' + print 'If you want the Flask themes, run this command and build again:' + print + print ' git submodule update --init' + print '-' * 74 + + pygments_style = 'tango' + html_theme = 'default' + html_theme_options = {} \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 00e3d58..314c087 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,20 +3,144 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Flask-Security's documentation! -========================================== +Flask-Security +============== -Contents: +.. module:: flask_security -.. toctree:: - :maxdepth: 2 +Simple security for Flask applications combining +`Flask-Login `_, +`Flask-Principal `_, +`Flask-WTF `_, +`passlib `_, and your choice of datastore. +Currently `SQLAlchemy `_ via +`Flask-SQLAlchemy `_ and +`MongoEngine `_ via +`Flask-MongoEngine `_ are supported +out of the box. You will need to install the necessary Flask extensions that +you'll be using on your own. Additionally, you may need to install an encryption +library such as `py-bcrypt `_ (if +you plan to use bcrypt) for your desired encryption method. +Overview +-------- +Flask-Security does a few things that Flask-Login and Flask-Principal don't +provide out of the box. They are: -Indices and tables -================== +1. Setting up login and logout endpoints +2. Authenticating users based on username or email +3. Limiting access based on user 'roles' +4. User and role creation +5. Password encryption -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +That being said, you can still hook into things such as the Flask-Login and +Flask-Principal signals if need be. +Installation +------------ + +First, install Flask-Security:: + + $ mkvirtualenv app-name + $ pip install https://github.com/mattupstate/flask-security/tarball/master + +Then install your datastore requirement. + +**SQLAlchemy**:: + + $ pip install Flask-SQLAlchemy + +**MongoEngine**:: + + $ pip install https://github.com/sbook/flask-mongoengine/tarball/master + +Getting Started +--------------- + +The following code samples will illustrate how to get started using SQLAlchemy. +First thing you'll want to do is setup your application and datastore:: + + from flask import Flask, render_template + from flask.ext.sqlalchemy import SQLAlchemy + from flask.ext.security import User, Security, LoginForm, + login_required, roles_accepted, user_datastore + from flask.ext.security.datastore.sqlalchemy import SQLAlchemyUserDataStore + + app = Flask(__name__) + app.config['SECRET_KEY'] = 'secret' + app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///:memory:' + + db = SQLAlchemy(app) + Security(app, SQLAlchemyUserDatastore(db)) + +You'll probably want to at least one user to the database to test this out, so +you can add something such as the following to quickly add an initial user:: + + @app.before_first_request + def before_first_request(): + user_datastore.create_role(name='admin') + user_datastore.create_user(username='matt', email='matt@something.com', + password='password', roles['admin']) + +Next you'll want to setup your login screen. Setup your view:: + + @app.route("/login") + def login(): + return render_template('login.html', form=LoginForm()) + +And corresponding template:: + +
+ {{ form.hidden_tag() }} + {{ form.username.label }} {{ form.username }}
+ {{ form.password.label }} {{ form.password }}
+ {{ form.remember.label }} {{ form.remember }}
+ {{ form.submit }} +
+ +By default, Flask-Security will redirect a user to `/profile` after logging in. +You can set this page up yourself or set the `SECURITY_POST_LOGIN` config +value to change this behavior. Regardless, setup a protected view as such:: + + @app.route('/profile') + @login_required + def profile(): + return render_template('profile.html') + +Now you have an application with basic authentication. If you run the local +development server you can visit `http://localhost:5000/login `_ +to login. + +The last thing you'll want to do is add a logout link to your templates. This +can be achieved with:: + + Logout + +Now, for instance, say you want to protect an admin area to users that are +administrators. You can use the `roles_accepted` decorator to prevent access. +The corresponding view would look like such:: + + @app.route('/admin') + @roles_accepted('admin') + def admin(): + return render_template('admin/index.html') + + +API +___ +.. autoclass:: flask_security.Security + :members: + +.. autofunction:: flask_security.roles_required + +.. autofunction:: flask_security.roles_accepted + +.. autoclass:: flask_security.datastore.UserDatastore + :members: + +.. autoclass:: flask_security.datastore.sqlalchemy.SQLAlchemyUserDatastore + :members: + +.. autoclass:: flask_security.datastore.mongoengine.MongoEngineUserDatastore + :members: \ No newline at end of file