From d11ac8e977ab2e8de6dd55a2401e434eeffea07d Mon Sep 17 00:00:00 2001 From: Matt Wright Date: Mon, 12 Mar 2012 21:57:09 -0400 Subject: [PATCH] Added documentation for models --- docs/index.rst | 129 +++++++++++++++++++++++++++++++------ flask_security/__init__.py | 8 +-- 2 files changed, 114 insertions(+), 23 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index fdbbd5c..f162d98 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,8 +22,9 @@ 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: @@ -37,6 +38,7 @@ provide out of the box. They are: That being said, you can still hook into things such as the Flask-Login and Flask-Principal signals if need be. + Installation ------------ @@ -55,6 +57,7 @@ Then install your datastore requirement. $ pip install https://github.com/sbook/flask-mongoengine/tarball/master + Getting Started --------------- @@ -133,39 +136,65 @@ specific role:: Admin Panel {$ endif %} + Configuration Values -------------------- -* `SECURITY_URL_PREFIX`: Specifies the URL prefix for the Security blueprint -* `SECURITY_AUTH_PROVIDER`: Specifies the class to use as the authentication - provider. Such as `flask.ext.security.AuthenticationProvider` -* `SECURITY_PASSWORD_HASH`: Specifies the encryption method to use. e.g.: +* :attr:`SECURITY_URL_PREFIX`: Specifies the URL prefix for the Security + blueprint +* :attr:`SECURITY_AUTH_PROVIDER`: Specifies the class to use as the + authentication provider. Such as `flask.ext.security.AuthenticationProvider` +* :attr:`SECURITY_PASSWORD_HASH`: Specifies the encryption method to use. e.g.: plaintext, bcrypt, etc -* `SECURITY_USER_DATASTORE`: Specifies the property name to use for the user - datastore on the application instance -* `SECURITY_LOGIN_FORM`: Specifies the form class to use when processing an - authentication request -* `SECURITY_AUTH_URL`: Specifies the URL to process authentication requests -* `SECURITY_LOGOUT_URL`: Specifies the URL to process a logout request -* `SECURITY_LOGIN_VIEW`: Specifies the URL to redirect to when authentication is - required -* `SECURITY_POST_LOGIN`: Specifies the URL to redirect to after a user is +* :attr:`SECURITY_USER_DATASTORE`: Specifies the property name to use for the + user datastore on the application instance +* :attr:`SECURITY_LOGIN_FORM`: Specifies the form class to use when processing + an authentication request +* :attr:`SECURITY_AUTH_URL`: Specifies the URL to to handle authentication +* :attr:`SECURITY_LOGOUT_URL`: Specifies the URL to process a logout request +* :attr:`SECURITY_LOGIN_VIEW`: Specifies the URL to redirect to when + authentication is required +* :attr:`SECURITY_POST_LOGIN`: Specifies the URL to redirect to after a user is authenticated -* `SECURITY_POST_LOGOUT`: Specifies the URL to redirect to after a user logs out -* `SECURITY_FLASH_MESSAGES`: Specifies wether or not to flash messages during - authentication request +* :attr:`SECURITY_POST_LOGOUT`: Specifies the URL to redirect to after a user + logs out +* :attr:`SECURITY_FLASH_MESSAGES`: Specifies wether or not to flash messages + during authentication request API -___ +=== + .. autoclass:: flask_security.Security :members: +.. data:: flask_security.current_user + + A proxy for the current user. + + +Protecting Views +---------------- .. autofunction:: flask_security.login_required .. autofunction:: flask_security.roles_required .. autofunction:: flask_security.roles_accepted + +User Object Helpers +------------------- +.. autoclass:: flask_security.UserMixin + :members: + +.. autoclass:: flask_security.RoleMixin + :members: + +.. autoclass:: flask_security.AnonymousUser + :members: + + +Datastores +---------- .. autoclass:: flask_security.datastore.UserDatastore :members: @@ -174,7 +203,62 @@ ___ .. autoclass:: flask_security.datastore.mongoengine.MongoEngineUserDatastore :members: + + +Models +------ +.. autoclass:: flask_security.User + .. attribute:: id + + User ID + + .. attribute:: username + + Username + + .. attribute:: email + + Email address + + .. attribute:: password + + Password + + .. attribute:: active + + Active state + + .. attribute:: roles + + User roles + + .. attribute:: created_at + + Created date + + .. attribute:: modified_at + + Modified date + + +.. autoclass:: flask_security.Role + + .. attribute:: id + + Role ID + + .. attribute:: name + + Role name + + .. attribute:: description + + Role description + + +Exceptions +---------- .. autoexception:: flask_security.BadCredentialsError .. autoexception:: flask_security.AuthenticationError @@ -189,4 +273,11 @@ ___ .. autoexception:: flask_security.UserCreationError -.. autoexception:: flask_security.RoleCreationError \ No newline at end of file +.. autoexception:: flask_security.RoleCreationError + + +Signals +------- +See the documentation for the signals provided by the Flask-Login and +Flask-Principal extensions. Flask-Security does not provide any additional +signals. \ No newline at end of file diff --git a/flask_security/__init__.py b/flask_security/__init__.py index 5c49887..0ed3995 100644 --- a/flask_security/__init__.py +++ b/flask_security/__init__.py @@ -33,11 +33,11 @@ from passlib.context import CryptContext from werkzeug.utils import import_string from werkzeug.local import LocalProxy -#: User model -User = None +class User(object): + """User model""" -#: Role model -Role = None +class Role(object): + """Role model""" URL_PREFIX_KEY = 'SECURITY_URL_PREFIX' AUTH_PROVIDER_KEY = 'SECURITY_AUTH_PROVIDER'