API 文档

这部分文档是从 Flask-Login 源码中自动生成的。

配置登录

class flask.ext.login.LoginManager(app=None, add_context_processor=True)

This object is used to hold the settings used for logging in. Instances of LoginManager are not bound to specific apps, so you can create one in the main body of your code and then bind it to your app in a factory function.

setup_app(app, add_context_processor=True)

This method has been deprecated. Please use LoginManager.init_app() instead.

unauthorized()

This is called when the user is required to log in. If you register a callback with LoginManager.unauthorized_handler(), then it will be called. Otherwise, it will take the following actions:

• Flash LoginManager.login_message to the user.
• If the app is using blueprints find the login view for the current blueprint using blueprint_login_views. If the app is not using blueprints or the login view for the current blueprint is not specified use the value of login_view. Redirect the user to the login view. (The page they were attempting to access will be passed in the next query string variable, so you can redirect there if present instead of the homepage.)

If LoginManager.login_view is not defined, then it will simply raise a HTTP 401 (Unauthorized) error instead.

This should be returned from a view or before/after_request function, otherwise the redirect will have no effect.

needs_refresh()

This is called when the user is logged in, but they need to be reauthenticated because their session is stale. If you register a callback with needs_refresh_handler, then it will be called. Otherwise, it will take the following actions:

• Flash LoginManager.needs_refresh_message to the user.
• Redirect the user to LoginManager.refresh_view. (The page they were attempting to access will be passed in the next query string variable, so you can redirect there if present instead of the homepage.)

If LoginManager.refresh_view is not defined, then it will simply raise a HTTP 401 (Unauthorized) error instead.

This should be returned from a view or before/after_request function, otherwise the redirect will have no effect.

General Configuration

user_loader(callback)

This sets the callback for reloading a user from the session. The function you set should take a user ID (a unicode) and return a user object, or None if the user does not exist.

Parameters: callback (callable) – The callback for retrieving a user object.

header_loader(callback)

This sets the callback for loading a user from a header value. The function you set should take an authentication token and return a user object, or None if the user does not exist.

Parameters: callback (callable) – The callback for retrieving a user object.

token_loader(callback)

This sets the callback for loading a user from an authentication token. The function you set should take an authentication token (a unicode, as returned by a user’s get_auth_token method) and return a user object, or None if the user does not exist.

Parameters: callback (callable) – The callback for retrieving a user object.

anonymous_user

A class or factory function that produces an anonymous user, which is used when no one is logged in.

unauthorized Configuration

login_view

The name of the view to redirect to when the user needs to log in. (This can be an absolute URL as well, if your authentication machinery is external to your application.)

login_message

The message to flash when a user is redirected to the login page.

unauthorized_handler(callback)

This will set the callback for the unauthorized method, which among other things is used by login_required. It takes no arguments, and should return a response to be sent to the user instead of their normal view.

Parameters: callback (callable) – The callback for unauthorized users.

needs_refresh Configuration

refresh_view

The name of the view to redirect to when the user needs to reauthenticate.

needs_refresh_message

The message to flash when a user is redirected to the reauthentication page.

needs_refresh_handler(callback)

This will set the callback for the needs_refresh method, which among other things is used by fresh_login_required. It takes no arguments, and should return a response to be sent to the user instead of their normal view.

Parameters: callback (callable) – The callback for unauthorized users.

登录机制

flask.ext.login.current_user

A proxy for the current user.

flask.ext.login.login_fresh()

This returns True if the current login is fresh.

flask.ext.login.login_user(user, remember=False, force=False, fresh=True)

Logs a user in. You should pass the actual user object to this. If the user’s is_active property is False, they will not be logged in unless force is True.

This will return True if the log in attempt succeeds, and False if it fails (i.e. because the user is inactive).

Parameters:

• user (object) – The user object to log in.
• remember (bool) – Whether to remember the user after their session expires. Defaults to False.
• force (bool) – If the user is inactive, setting this to True will log them in regardless. Defaults to False.
• fresh – setting this to False will log in the user with a session

marked as not “fresh”. Defaults to True. :type fresh: bool

flask.ext.login.logout_user()

Logs a user out. (You do not need to pass the actual user.) This will also clean up the remember me cookie if it exists.

lask.ext.login.confirm_login()

This sets the current session as fresh. Sessions become stale when they are reloaded from a cookie.

保护视图

flask.ext.login.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.

Parameters: func (function) – The view function to decorate.

flask.ext.login.fresh_login_required(func)

If you decorate a view with this, it will ensure that the current user’s login is fresh - i.e. there session was not restored from a ‘remember me’ cookie. Sensitive operations, like changing a password or e-mail, should be protected with this, to impede the efforts of cookie thieves.

If the user is not authenticated, LoginManager.unauthorized() is called as normal. If they are authenticated, but their session is not fresh, it will call LoginManager.needs_refresh() instead. (In that case, you will need to provide a LoginManager.refresh_view.)

Behaves identically to the login_required() decorator with respect to configutation variables.

Parameters: func (function) – The view function to decorate.

用户对象助手

class flask.ext.login.UserMixin

This provides default implementations for the methods that Flask-Login expects user objects to have.

工具

flask.ext.login.login_url(login_view, next_url=None, next_field='next')

Creates a URL for redirecting to a login page. If only login_view is provided, this will just return the URL for it. If next_url is provided, however, this will append a next=URL parameter to the query string so that the login view can redirect back to that URL.

Parameters:

• login_view (str) – The name of the login view. (Alternately, the actual URL to the login view.)
• next_url (str) – The URL to give the login view for redirection.
• next_field (str) – What field to store the next URL in. (It defaults to next.)

flask.ext.login.make_secure_token(*args, **options)

This will create a secure token that you can use as an authentication token for your users. It uses heavy-duty HMAC encryption to prevent people from guessing the information. (To make it even more effective, if you will never need to regenerate the token, you can pass some random data as one of the arguments.)

Parameters:

• *args – The data to include in the token.
• **options (kwargs) – To manually specify a secret key, pass key=THE_KEY. Otherwise, the current_app secret key will be used.

信号

如何在你的代码中使用这些信号请参阅 Flask documentation on signals。

flask.ext.login.user_logged_in

当一个用户登入的时候发出。除应用（信号的发送者）之外，它还传递正登入的用户 user 。

flask.ext.login.user_logged_out

当一个用户登出的时候发出。除应用（信号的发送者）之外，它还传递正登出的用户 user 。

flask.ext.login.user_login_confirmed

当用户的登入被证实，把它标记为活跃的。（它不用于常规登入的调用。） 它不接受应用以外的任何其它参数。

flask.ext.login.user_unauthorized

当 LoginManager 上的 unauthorized 方法被调用时发出。它不接受应用以外的任何其它参数。

flask.ext.login.user_needs_refresh

当 LoginManager 上的 needs_refresh 方法被调用时发出。它不接受应用以外的任何其它参数。

flask.ext.login.session_protected

当会话保护起作用时，且会话被标记为非活跃或删除时发出。它不接受应用以外的任何其它参数。