Debian Codegraph @

docs/signals.rst

raw
1 .. module:: flask_dance.consumer
2
3 Signals
4 =======
5
6 Flask-Dance supports signals, :doc:`just as Flask does <flask:signals>`.
7 Signals are perfect for custom processing code that you want to run at a certain
8 point in the OAuth dance. For example, after the dance is complete, you might
9 need to update the user's profile, kick off a long-running task, or simply
10 :doc:`flash a message <flask:patterns/flashing>` to let the user know
11 that the login was successful. It's easy, just import the appropriate signal of
12 the ones listed below, and connect your custom processing code to the signal.
13
14 The following signals exist in Flask-Dance:
15
16 .. data:: oauth_before_login
17
18 .. versionadded:: 1.4.0
19
20 This signal is sent before redirecting to the provider login page. The signal
21 is sent with a ``url`` parameter specifying the redirect URL. This signal is mostly
22 useful for doing things like session construction/deconstruction before the user
23 is redirected.
24
25 Example subscriber::
26
27 import flask
28 from flask_dance.consumer import oauth_before_login
29
30 @oauth_before_login.connect
31 def before_login(blueprint, url):
32 flask.session["next_url"] = flask.request.args.get("next_url")
33
34 .. data:: oauth_authorized
35
36 This signal is sent when a user completes the OAuth dance by receiving a
37 response from the OAuth provider's authorize URL. The signal is invoked
38 with the blueprint instance as the first argument (the *sender*), and with
39 a dict of the OAuth provider's response (the *token*).
40
41 Example subscriber::
42
43 from flask import flash
44 from flask_dance.consumer import oauth_authorized
45
46 @oauth_authorized.connect
47 def logged_in(blueprint, token):
48 flash("Signed in successfully with {name}!".format(
49 name=blueprint.name.capitalize()
50 ))
51
52 If you are linking OAuth records to User records, you *must* implement an
53 ``@oauth_authorized`` subscriber that creates new ``User`` and ``OAuth``
54 database entries for any new users, and links those two new records via
55 the ``OAuth`` table's ``user_id`` field.
56
57 If you're using OAuth 2, the user may grant you different scopes from the
58 ones you requested: check the ``scope`` key in the *token* dict to
59 determine what scopes were actually granted. If you don't want the *token*
60 to be :doc:`stored <storages>`, simply return ``False`` from one of your
61 signal receiver functions -- this can be useful if the user has declined
62 to authorize your OAuth request, has granted insufficient scopes, or in some
63 other way has given you a token that you don't want.
64
65 You can also return a :class:`~flask.Response` instance from an event
66 subscriber. If you do, that response will be returned to the user instead
67 of the normal redirect. For example::
68
69 from flask import redirect, url_for
70
71 @oauth_authorized.connect
72 def logged_in(blueprint, token):
73 return redirect(url_for("after_oauth"))
74
75 .. data:: oauth_error
76
77 This signal is sent when the OAuth provider indicates that there was an
78 error with the OAuth dance. This can happen if your application is
79 misconfigured somehow. The user will be redirected to the ``redirect_url``
80 anyway, so it is your responsibility to hook into this signal and inform
81 the user that there was an error.
82
83 You can also return a :class:`~flask.Response` instance from an event
84 subscriber. If you do, that response will be returned to the user instead
85 of the normal redirect. For example::
86
87 from flask import redirect, url_for
88
89 @oauth_error.connect
90 def handle_error(blueprint, error, error_description=None, error_uri=None):
91 return redirect(url_for("custom_error_page"))
92
93 .. _flash a message: http://flask.pocoo.org/docs/latest/patterns/flashing/
94 .. _blinker: http://pythonhosted.org/blinker/