API
***


Core
====

class flask_security.core.Security(app=None, datastore=None, **kwargs)

   The "Security" class initializes the Flask-Security extension.

   Parameters:
      * **app** -- The application.

      * **datastore** -- An instance of a user datastore.

   init_app(app, datastore=None, register_blueprint=True, login_form=None, confirm_register_form=None, register_form=None, forgot_password_form=None, reset_password_form=None, change_password_form=None, send_confirmation_form=None, passwordless_login_form=None, anonymous_user=None)

      Initializes the Flask-Security extension for the specified
      application and datastore implentation.

      Parameters:
         * **app** -- The application.

         * **datastore** -- An instance of a user datastore.

         * **register_blueprint** -- to register the Security
           blueprint or not.

flask_security.core.current_user

   A proxy for the current user.


Protecting Views
================

flask_security.decorators.login_required(func)

   If you decorate a view with this, it will ensure that the current
   user is logged in and authenticated before calling the actual view.
   (If they are not, it calls the "LoginManager.unauthorized"
   callback.) For example:

      @app.route('/post')
      @login_required
      def post():
          pass

   If there are only certain times you need to require that your user
   is logged in, you can do so with:

      if not current_user.is_authenticated:
          return current_app.login_manager.unauthorized()

   ...which is essentially the code that this function adds to your
   views.

   It can be convenient to globally turn off authentication when unit
   testing. To enable this, if the application configuration variable
   *LOGIN_DISABLED* is set to *True*, this decorator will be ignored.

   Note: Per W3 guidelines for CORS preflight requests, HTTP
     "OPTIONS" requests are exempt from login checks.

   Parameters:
      **func** (*function*) -- The view function to decorate.

flask_security.decorators.roles_required(*roles)

   Decorator which specifies that a user must have all the specified
   roles. Example:

      @app.route('/dashboard')
      @roles_required('admin', 'editor')
      def dashboard():
          return 'Dashboard'

   The current user must have both the *admin* role and *editor* role
   in order to view the page.

   Parameters:
      **args** -- The required roles.

flask_security.decorators.roles_accepted(*roles)

   Decorator which specifies that a user must have at least one of the
   specified roles. Example:

      @app.route('/create_post')
      @roles_accepted('editor', 'author')
      def create_post():
          return 'Create Post'

   The current user must have either the *editor* role or *author*
   role in order to view the page.

   Parameters:
      **args** -- The possible roles.

flask_security.decorators.http_auth_required(realm)

   Decorator that protects endpoints using Basic HTTP authentication.
   The username should be set to the user's email address.

   Parameters:
      **realm** -- optional realm name

flask_security.decorators.auth_token_required(fn)

   Decorator that protects endpoints using token authentication. The
   token should be added to the request by the client by using a query
   string variable with a name equal to the configuration value of
   *SECURITY_TOKEN_AUTHENTICATION_KEY* or in a request header named
   that of the configuration value of
   *SECURITY_TOKEN_AUTHENTICATION_HEADER*


User Object Helpers
===================

class flask_security.core.UserMixin

   Mixin for *User* model definitions

   get_auth_token()

      Returns the user's authentication token.

   get_security_payload()

      Serialize user object as response payload.

   has_role(role)

      Returns *True* if the user identifies with the specified role.

      Parameters:
         **role** -- A role name or *Role* instance

   is_active

      Returns *True* if the user is active.

class flask_security.core.RoleMixin

   Mixin for *Role* model definitions

class flask_security.core.AnonymousUser

   AnonymousUser definition

   has_role(*args)

      Returns *False*


Datastores
==========

class flask_security.datastore.UserDatastore(user_model, role_model)

   Abstracted user datastore.

   Parameters:
      * **user_model** -- A user model class definition

      * **role_model** -- A role model class definition

   activate_user(user)

      Activates a specified user. Returns *True* if a change was made.

      Parameters:
         **user** -- The user to activate

   add_role_to_user(user, role)

      Adds a role to a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to add to the user

   create_role(**kwargs)

      Creates and returns a new role from the given parameters.

   create_user(**kwargs)

      Creates and returns a new user from the given parameters.

   deactivate_user(user)

      Deactivates a specified user. Returns *True* if a change was
      made.

      Parameters:
         **user** -- The user to deactivate

   delete_user(user)

      Deletes the specified user.

      Parameters:
         **user** -- The user to delete

   find_or_create_role(name, **kwargs)

      Returns a role matching the given name or creates it with any
      additionally provided parameters.

   find_role(*args, **kwargs)

      Returns a role matching the provided name.

   find_user(*args, **kwargs)

      Returns a user matching the provided parameters.

   get_user(id_or_email)

      Returns a user matching the specified ID or email address.

   remove_role_from_user(user, role)

      Removes a role from a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to remove from the user

   toggle_active(user)

      Toggles a user's active status. Always returns True.

class flask_security.datastore.SQLAlchemyUserDatastore(db, user_model, role_model)

   A SQLAlchemy datastore implementation for Flask-Security that
   assumes the use of the Flask-SQLAlchemy extension.

   activate_user(user)

      Activates a specified user. Returns *True* if a change was made.

      Parameters:
         **user** -- The user to activate

   add_role_to_user(user, role)

      Adds a role to a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to add to the user

   create_role(**kwargs)

      Creates and returns a new role from the given parameters.

   create_user(**kwargs)

      Creates and returns a new user from the given parameters.

   deactivate_user(user)

      Deactivates a specified user. Returns *True* if a change was
      made.

      Parameters:
         **user** -- The user to deactivate

   delete_user(user)

      Deletes the specified user.

      Parameters:
         **user** -- The user to delete

   find_or_create_role(name, **kwargs)

      Returns a role matching the given name or creates it with any
      additionally provided parameters.

   find_role(role)

      Returns a role matching the provided name.

   find_user(**kwargs)

      Returns a user matching the provided parameters.

   get_user(identifier)

      Returns a user matching the specified ID or email address.

   remove_role_from_user(user, role)

      Removes a role from a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to remove from the user

   toggle_active(user)

      Toggles a user's active status. Always returns True.

class flask_security.datastore.MongoEngineUserDatastore(db, user_model, role_model)

   A MongoEngine datastore implementation for Flask-Security that
   assumes the use of the Flask-MongoEngine extension.

   activate_user(user)

      Activates a specified user. Returns *True* if a change was made.

      Parameters:
         **user** -- The user to activate

   add_role_to_user(user, role)

      Adds a role to a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to add to the user

   create_role(**kwargs)

      Creates and returns a new role from the given parameters.

   create_user(**kwargs)

      Creates and returns a new user from the given parameters.

   deactivate_user(user)

      Deactivates a specified user. Returns *True* if a change was
      made.

      Parameters:
         **user** -- The user to deactivate

   delete_user(user)

      Deletes the specified user.

      Parameters:
         **user** -- The user to delete

   find_or_create_role(name, **kwargs)

      Returns a role matching the given name or creates it with any
      additionally provided parameters.

   find_role(role)

      Returns a role matching the provided name.

   find_user(**kwargs)

      Returns a user matching the provided parameters.

   get_user(identifier)

      Returns a user matching the specified ID or email address.

   remove_role_from_user(user, role)

      Removes a role from a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to remove from the user

   toggle_active(user)

      Toggles a user's active status. Always returns True.

class flask_security.datastore.PeeweeUserDatastore(db, user_model, role_model, role_link)

   A PeeweeD datastore implementation for Flask-Security that assumes
   the use of the Flask-Peewee extension.

   Parameters:
      * **user_model** -- A user model class definition

      * **role_model** -- A role model class definition

      * **role_link** -- A model implementing the many-to-many user-
        role relation

   activate_user(user)

      Activates a specified user. Returns *True* if a change was made.

      Parameters:
         **user** -- The user to activate

   add_role_to_user(user, role)

      Adds a role to a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to add to the user

   create_role(**kwargs)

      Creates and returns a new role from the given parameters.

   create_user(**kwargs)

      Creates and returns a new user from the given parameters.

   deactivate_user(user)

      Deactivates a specified user. Returns *True* if a change was
      made.

      Parameters:
         **user** -- The user to deactivate

   delete_user(user)

      Deletes the specified user.

      Parameters:
         **user** -- The user to delete

   find_or_create_role(name, **kwargs)

      Returns a role matching the given name or creates it with any
      additionally provided parameters.

   find_role(role)

      Returns a role matching the provided name.

   find_user(**kwargs)

      Returns a user matching the provided parameters.

   get_user(identifier)

      Returns a user matching the specified ID or email address.

   remove_role_from_user(user, role)

      Removes a role from a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to remove from the user

   toggle_active(user)

      Toggles a user's active status. Always returns True.

class flask_security.datastore.PonyUserDatastore(db, user_model, role_model)

   A Pony ORM datastore implementation for Flask-Security.

   Code primarily from https://github.com/ET-CS but taken over after
   being abandoned.

   activate_user(user)

      Activates a specified user. Returns *True* if a change was made.

      Parameters:
         **user** -- The user to activate

   add_role_to_user(*args, **kwargs)

      Adds a role to a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to add to the user

   create_role(**kwargs)

      Creates and returns a new role from the given parameters.

   create_user(**kwargs)

      Creates and returns a new user from the given parameters.

   deactivate_user(user)

      Deactivates a specified user. Returns *True* if a change was
      made.

      Parameters:
         **user** -- The user to deactivate

   delete_user(user)

      Deletes the specified user.

      Parameters:
         **user** -- The user to delete

   find_or_create_role(name, **kwargs)

      Returns a role matching the given name or creates it with any
      additionally provided parameters.

   find_role(role)

      Returns a role matching the provided name.

   find_user(**kwargs)

      Returns a user matching the provided parameters.

   get_user(identifier)

      Returns a user matching the specified ID or email address.

   remove_role_from_user(user, role)

      Removes a role from a user.

      Parameters:
         * **user** -- The user to manipulate

         * **role** -- The role to remove from the user

   toggle_active(user)

      Toggles a user's active status. Always returns True.


Utils
=====

flask_security.utils.login_user(user, remember=None)

   Perform the login routine.

   If SECURITY_TRACKABLE is used, make sure you commit changes after
   this request (i.e. "app.security.datastore.commit()").

   Parameters:
      * **user** -- The user to login

      * **remember** -- Flag specifying if the remember cookie
        should be set. Defaults to "False"

flask_security.utils.logout_user()

   Logs out the current.

   This will also clean up the remember me cookie if it exists.

flask_security.utils.get_hmac(password)

   Returns a Base64 encoded HMAC+SHA512 of the password signed with
   the salt specified by "SECURITY_PASSWORD_SALT".

   Parameters:
      **password** -- The password to sign

flask_security.utils.verify_password(password, password_hash)

   Returns "True" if the password matches the supplied hash.

   Parameters:
      * **password** -- A plaintext password to verify

      * **password_hash** -- The expected hash value of the password
        (usually from your database)

flask_security.utils.verify_and_update_password(password, user)

   Returns "True" if the password is valid for the specified user.

   Additionally, the hashed password in the database is updated if the
   hashing algorithm happens to have changed.

   Parameters:
      * **password** -- A plaintext password to verify

      * **user** -- The user to verify against

flask_security.utils.encrypt_password(password)

   Encrypt the specified plaintext password.

   It uses the configured encryption options.

   Deprecated since version 2.0.2: Use "hash_password()" instead.

   Parameters:
      **password** -- The plaintext password to encrypt

flask_security.utils.hash_password(password)

   Hash the specified plaintext password.

   It uses the configured hashing options.

   New in version 2.0.2.

   Parameters:
      **password** -- The plaintext password to hash

flask_security.utils.url_for_security(endpoint, **values)

   Return a URL for the security blueprint

   Parameters:
      * **endpoint** -- the endpoint of the URL (name of the
        function)

      * **values** -- the variable arguments of the URL rule

      * **_external** -- if set to *True*, an absolute URL is
        generated. Server address can be changed via *SERVER_NAME*
        configuration variable which defaults to *localhost*.

      * **_anchor** -- if provided this is added as anchor to the
        URL.

      * **_method** -- if provided this explicitly specifies an HTTP
        method.

flask_security.utils.get_within_delta(key, app=None)

   Get a timedelta object from the application configuration following
   the internal convention of:

      <Amount of Units> <Type of Units>

   Examples of valid config values:

      5 days
      10 minutes

   Parameters:
      * **key** -- The config value key without the '>>SECURITY_<<'
        prefix

      * **app** -- Optional application to inspect. Defaults to
        Flask's *current_app*

flask_security.utils.send_mail(subject, recipient, template, **context)

   Send an email via the Flask-Mail extension.

   Parameters:
      * **subject** -- Email subject

      * **recipient** -- Email recipient

      * **template** -- The name of the email template

      * **context** -- The context to render the template with

flask_security.utils.get_token_status(token, serializer, max_age=None, return_data=False)

   Get the status of a token.

   Parameters:
      * **token** -- The token to check

      * **serializer** -- The name of the seriailzer. Can be one of
        the following: "confirm", "login", "reset"

      * **max_age** -- The name of the max age config option. Can be
        on of the following: "CONFIRM_EMAIL", "LOGIN",
        "RESET_PASSWORD"


Signals
=======

See the Flask documentation on signals for information on how to use
these signals in your code.

See the documentation for the signals provided by the Flask-Login and
Flask-Principal extensions. In addition to those signals, Flask-
Security sends the following signals.

user_registered

   Sent when a user registers on the site. In addition to the app
   (which is the sender), it is passed *user* and *confirm_token*
   arguments.

user_confirmed

   Sent when a user is confirmed. In addition to the app (which is the
   sender), it is passed a *user* argument.

confirm_instructions_sent

   Sent when a user requests confirmation instructions. In addition to
   the app (which is the sender), it is passed a *user* argument.

login_instructions_sent

   Sent when passwordless login is used and user logs in. In addition
   to the app (which is the sender), it is passed *user* and
   *login_token* arguments.

password_reset

   Sent when a user completes a password reset. In addition to the app
   (which is the sender), it is passed a *user* argument.

password_changed

   Sent when a user completes a password change. In addition to the
   app (which is the sender), it is passed a *user* argument.

reset_password_instructions_sent

   Sent when a user requests a password reset. In addition to the app
   (which is the sender), it is passed *user* and *token* arguments.
