Flask-User API¶
Config Settings¶
# Features # Default # Description
USER_ENABLE_CHANGE_PASSWORD = True # Allow users to change their password
USER_ENABLE_CHANGE_USERNAME = True # Allow users to change their username
# Requires USER_ENABLE_USERNAME=True
USER_ENABLE_CONFIRM_EMAIL = True # Force users to confirm their email
# Requires USER_ENABLE_EMAIL=True
USER_ENABLE_FORGOT_PASSWORD = True # Allow users to reset their passwords
# Requires USER_ENABLE_EMAIL=True
USER_ENABLE_EMAIL = True # Register with Email
# Requires USER_ENABLE_REGISTRATION=True
USER_ENABLE_MULTIPLE_EMAILS = False # Users may register multiple emails
# Requires USER_ENABLE_EMAIL=True
USER_ENABLE_REGISTRATION = True # Allow new users to register
USER_ENABLE_RETYPE_PASSWORD = True # Prompt for `retype password` in:
# - registration form,
# - change password form, and
# - reset password forms.
USER_ENABLE_USERNAME = True # Register and Login with username
# Settings # Default # Description
USER_APP_NAME = 'AppName' # Used by email templates
USER_CONFIRM_EMAIL_EXPIRATION = 2*24*3600 # Confirmation expiration in seconds
# (2*24*3600 represents 2 days)
USER_PASSWORD_HASH = 'bcrypt' # Any passlib crypt algorithm
USER_PASSWORD_HASH_MODE = 'passlib' # Set to 'Flask-Security' for
# Flask-Security compatible hashing
USER_PASSWORD_SALT = SECURITY_PASSWORD_SALT # Only needed for
# Flask-Security compatible hashing
USER_REQUIRE_INVITATION = False # Registration requires invitation
# Not yet implemented
# Requires USER_ENABLE_EMAIL=True
USER_RESET_PASSWORD_EXPIRATION = 2*24*3600 # Reset password expiration in seconds
# (2*24*3600 represents 2 days)
USER_SEND_PASSWORD_CHANGED_EMAIL = True # Send registered email
# Requires USER_ENABLE_EMAIL=True
USER_SEND_REGISTERED_EMAIL = True # Send registered email
# Requires USER_ENABLE_EMAIL=True
USER_SEND_USERNAME_CHANGED_EMAIL = True # Send registered email
# Requires USER_ENABLE_EMAIL=True
# URLs # Default
USER_CHANGE_PASSWORD_URL = '/user/change-password'
USER_CHANGE_USERNAME_URL = '/user/change-username'
USER_CONFIRM_EMAIL_URL = '/user/confirm-email/<token>'
USER_EMAIL_ACTION_URL = '/user/email/<id>/<action>' # v0.5.1 and up
USER_FORGOT_PASSWORD_URL = '/user/forgot-password'
USER_LOGIN_URL = '/user/login'
USER_LOGOUT_URL = '/user/logout'
USER_MANAGE_EMAILS_URL = '/user/manage-emails'
USER_REGISTER_URL = '/user/register'
USER_RESEND_CONFIRM_EMAIL_URL = '/user/resend-confirm-email' # v0.5.0 and up
USER_RESET_PASSWORD_URL = '/user/reset-password/<token>'
# Endpoints are converted to URLs using url_for()
# The empty endpoint ('') will be mapped to the root URL ('/')
USER_AFTER_CHANGE_PASSWORD_ENDPOINT = '' # v0.5.3 and up
USER_AFTER_CHANGE_USERNAME_ENDPOINT = '' # v0.5.3 and up
USER_AFTER_CONFIRM_ENDPOINT = '' # v0.5.3 and up
USER_AFTER_FORGOT_PASSWORD_ENDPOINT = '' # v0.5.3 and up
USER_AFTER_LOGIN_ENDPOINT = '' # v0.5.3 and up
USER_AFTER_LOGOUT_ENDPOINT = 'user.login' # v0.5.3 and up
USER_AFTER_REGISTER_ENDPOINT = '' # v0.5.3 and up
USER_AFTER_RESEND_CONFIRM_EMAIL_ENDPOINT = '' # v0.5.3 and up
# Unauthenticated users trying to access
# a view that has been decorated with @login_required or @roles_required
# will be redirected to this endpoint
USER_UNAUTHENTICATED_ENDPOINT = 'user.login' # v0.5.3 and up
# Unauthorized users trying to access
# a view that has been decorated with @roles_required
# will be redirected to this endpoint
USER_UNAUTHORIZED_ENDPOINT = '' # v0.5.3 and up
# Email template files # Defaults
USER_CONFIRM_EMAIL_EMAIL_TEMPLATE = 'flask_user/emails/confirm_email'
USER_FORGOT_PASSWORD_EMAIL_TEMPLATE = 'flask_user/emails/forgot_password'
USER_PASSWORD_CHANGED_EMAIL_TEMPLATE = 'flask_user/emails/password_changed'
USER_REGISTERED_EMAIL_TEMPLATE = 'flask_user/emails/registered'
USER_USERNAME_CHANGED_EMAIL_TEMPLATE = 'flask_user/emails/username_changed'
# These settings correspond to the start of three template files:
# SOMETHING_subject.txt # Email subject
# SOMETHING_message.html # Email message in HTML format
# SOMETHING_message.txt # Email message in Text format
# Form template files # Defaults
USER_CHANGE_PASSWORD_TEMPLATE = 'flask_user/change_password.html'
USER_CHANGE_USERNAME_TEMPLATE = 'flask_user/change_username.html'
USER_FORGOT_PASSWORD_TEMPLATE = 'flask_user/forgot_password.html'
USER_LOGIN_TEMPLATE = 'flask_user/login.html'
USER_MANAGE_EMAILS_TEMPLATE = 'flask_user/manage_emails.html' # v0.5.1 and up
USER_REGISTER_TEMPLATE = 'flask_user/register.html'
USER_RESEND_CONFIRM_EMAIL_TEMPLATE = 'flask_user/resend_confirm_email.html' # v0.5.0 and up
USER_RESET_PASSWORD_TEMPLATE = 'flask_user/reset_password.html'
# Place the Login form and the Register form on one page:
# Only works for Flask-User v0.4.9 and up
USER_LOGIN_TEMPLATE = 'flask_user/login_or_register.html'
USER_REGISTER_TEMPLATE = 'flask_user/login_or_register.html'
SQLAlchemyAdapter()¶
Flask-User shields itself from database operations through a DBAdapter. It ships with a SQLAlchemyAdapter, but the API is very simple, so other adapters can be easily added.
class SQLAlchemyAdapter(DBAdapter):
""" This object shields Flask-User from database specific functions. """
def get_object(self, ObjectClass, pk):
""" Retrieve one object specified by the primary key 'pk' """
def find_all_objects(self, ObjectClass, **kwargs):
""" Retrieve all objects matching the case sensitive filters in 'kwargs'. """
def find_first_object(self, ObjectClass, **kwargs):
""" Retrieve the first object matching the case sensitive filters in 'kwargs'. """
def ifind_first_object(self, ObjectClass, **kwargs):
""" Retrieve the first object matching the case insensitive filters in 'kwargs'. """
def add_object(self, ObjectClass, **kwargs):
""" Add an object with fields and values specified in kwargs. """
def update_object(self, object, **kwargs):
""" Update an object with fields and values specified in kwargs. """
def delete_object(self, object):
""" Delete an object. """
def commit(self):
""" Commit an Add, Update or Delete. """
Template variables¶
The following template variables are available for use in email and form templates:
user_manager # points to the UserManager object
Template functions¶
The following template functions are available for use in email and form templates:
# Function Setting # Default
url_for('user.change_password') USER_CHANGE_PASSWORD_URL = '/user/change-password'
url_for('user.change_username') USER_CHANGE_USERNAME_URL = '/user/change-username'
url_for('user.confirm_email') USER_CONFIRM_EMAIL_URL = '/user/confirm-email/<token>'
url_for('user.email_action') USER_EMAIL_ACTION_URL = '/user/email/<id>/<action>' # v0.5.1 and up
url_for('user.forgot_password') USER_FORGOT_PASSWORD_URL = '/user/forgot-password'
url_for('user.login') USER_LOGIN_URL = '/user/sign-in'
url_for('user.logout') USER_LOGOUT_URL = '/user/sign-out'
url_for('user.register') USER_REGISTER_URL = '/user/register'
url_for('user.resend_confirm_email') USER_RESEND_CONFIRM_EMAIL_URL = '/user/resend-confirm-email' # v0.5.0 and up
url_for('user.reset_password') USER_RESET_PASSWORD_URL = '/user/reset-password/<token>'
url_for('user.profile') USER_PROFILE_URL = '/user/profile' # v0.5.5 and up
UserManager¶
UserManager()¶
user_manager = UserManager(
db_adapter, # typically from SQLAlchemyAdapter()
app = None, # typically from Flask() or None
# Forms
add_email_form = forms.AddEmailForm,
change_username_form = forms.ChangeUsernameForm,
forgot_password_form = forms.ForgotPasswordForm,
login_form = forms.LoginForm,
register_form = forms.RegisterForm,
resend_confirm_email_form = forms.ResendConfirmEmailForm,
reset_password_form = forms.ResetPasswordForm,
# Validators
username_validator = forms.username_validator,
password_validator = forms.password_validator,
# View functions
change_password_view_function = views.change_password,
change_username_view_function = views.change_username,
confirm_email_view_function = views.confirm_email,
email_action_view_function = views.email_action,
forgot_password_view_function = views.forgot_password,
login_view_function = views.login,
logout_view_function = views.logout,
manage_emails_view_function = views.manage_emails,
register_view_function = views.register,
resend_confirm_email_view_function = views.resend_confirm_email_view_function,
reset_password_view_function = views.reset_password,
user_profile_view_function = views.user_profile,
unauthenticated_view_function = views.unauthenticated,
unauthorized_view_function = views.unauthorized,
# Miscellaneous
login_manager = LoginManager(),
password_crypt_context = None,
send_email_function = emails.send_email,
token_manager = tokens.TokenManager(),
)
Typical use:
app = Flask(__name__)
db = SQLAlchemy(app)
db_adapter = SQLAlchemyAdapter(db, User)
user_manager = UserManager(db_adapter, app,
register_form=my_register_form,
register_view_function=my_register_view_function)
Work in progress. See Basic App for now.
init_app()¶
init_app() is used by Application Factories to bind the UserManager to a specific app.
typical use:
db = SQLAlchemy()
db_adapter = SQLAlchemyAdapter(db, User)
user_manager = UserManager(db_adapter)
def create_app():
app = Flask(__name__)
db.init_app(app)
user_manager.init_app(app)
Work in progress. See Basic App for now.
hash_password()¶
user_manager.hash_password(password)
# Returns hashed 'password' using the configured password hash
# Config settings: USER_PASSWORD_HASH_MODE = 'passlib'
# USER_PASSWORD_HASH = 'bcrypt'
# USER_PASSWORD_SALT = SECRET_KEY
verify_password()¶
user_manager.verify_password(password, hashed_password)
# Returns True if 'password' matches 'hashed password'
# Returns False otherwise.
Signals¶
# Signal # Sent when ...
user_changed_password # a user changed their password
user_changed_username # a user changed their username
user_confirmed_email # a user confirmed their email
user_forgot_password # a user submitted a reset password request
user_logged_in # a user logged in
user_logged_out # a user logged out
user_registered # a user registered for a new account
user_reset_password # a user reset their password (forgot password)