Debian Codegraph @

docs/storages.rst

raw
1 .. module:: flask_dance.consumer.storage
2
3 Token Storages
4 ==============
5
6 A Flask-Dance blueprint has a token storage associated with it,
7 which is an object that knows how to store and retrieve OAuth tokens
8 from some kind of persistent storage. A storage is most often
9 some kind of database, but it doesn't have to be.
10
11 .. _flask-session-storage:
12
13 Flask Session
14 -------------
15
16 The default token storage uses the
17 :ref:`Flask session <flask:sessions>` to store OAuth tokens, which is simple
18 and requires no configuration. However, when the user closes
19 their browser, their OAuth token will be lost, so its not a good choice for
20 production usage.
21
22 This is a great option for hobby projects, and for a "proof of concept"
23 to show that an idea is viable.
24
25 .. _sqlalchemy-storage:
26
27 SQLAlchemy
28 ----------
29
30 SQLAlchemy is the "standard" ORM_ for Flask applications, and Flask-Dance
31 has great support for it. First, define your database model with a ``token``
32 column and a ``provider`` column. Flask-Dance includes a
33 :class:`~flask_dance.consumer.storage.sqla.OAuthConsumerMixin`
34 class to make this easier::
35
36 from flask_sqlalchemy import SQLAlchemy
37 from flask_dance.consumer.storage.sqla import OAuthConsumerMixin
38
39 db = SQLAlchemy()
40 class OAuth(OAuthConsumerMixin, db.Model):
41 pass
42
43 Next, create an instance of the SQLAlchemy storage
44 and assign it to your blueprint::
45
46 from flask_dance.consumer.storage.sqla import SQLAlchemyStorage
47
48 blueprint.storage = SQLAlchemyStorage(OAuth, db.session)
49
50 And that's all you need -- if you don't have user accounts in your application.
51 If you do, it's slightly more complicated::
52
53 from flask_sqlalchemy import SQLAlchemy
54 from flask_login import current_user
55 from flask_dance.consumer.storage.sqla import OAuthConsumerMixin, SQLAlchemyStorage
56
57 db = SQLAlchemy()
58
59 class User(db.Model):
60 id = db.Column(db.Integer, primary_key=True)
61 # ... other columns as needed
62
63 class OAuth(OAuthConsumerMixin, db.Model):
64 user_id = db.Column(db.Integer, db.ForeignKey(User.id))
65 user = db.relationship(User)
66
67 blueprint.storage = SQLAlchemyStorage(OAuth, db.session, user=current_user)
68
69 There are two things to notice here. One, the model that you use for storing
70 OAuth tokens must have a :attr:`user` relationship to the user
71 that it is associated with.
72 Two, you must pass a reference to the currently logged-in user (if any)
73 to :class:`~flask_dance.consumer.storage.sqla.SQLAlchemyStorage`.
74 If you're using `Flask-Login`_, the :attr:`current_user` proxy works great,
75 but you could instead pass a function that returns the current
76 user, if you want.
77
78 You also probably want to use a caching system for your database, so that it
79 is more performant under heavy load. The SQLAlchemy token storage
80 also integrates with `Flask-Caching`_ if you pass an instance of
81 Flask-Caching to the storage, like this::
82
83 from flask import Flask
84 from flask_caching import Cache
85
86 app = Flask(__name__)
87 cache = Cache(app)
88
89 # setup Flask-Dance with SQLAlchemy models...
90
91 blueprint.storage = SQLAlchemyStorage(OAuth, db.session, cache=cache)
92
93
94 .. _SQLAlchemy: http://www.sqlalchemy.org/
95 .. _Flask-Login: https://flask-login.readthedocs.io/
96 .. _Flask-Caching: https://flask-caching.readthedocs.io/
97
98 Custom
99 ------
100
101 Of course, you don't have to use `SQLAlchemy`_, you're free to use whatever
102 storage system you want. Writing a custom token storage is easy:
103 just subclass :class:`flask_dance.consumer.storage.BaseStorage` and
104 override the :meth:`get`, :meth:`set`, and :meth:`delete` methods.
105 For example, here's a storage that uses a file on disk::
106
107 import os
108 import os.path
109 import json
110 from flask_dance.consumer.storage import BaseStorage
111
112 class FileStorage(BaseStorage):
113 def __init__(self, filepath):
114 super(FileStorage, self).__init__()
115 self.filepath = filepath
116
117 def get(self, blueprint):
118 if not os.path.exists(self.filepath):
119 return None
120 with open(self.filepath) as f:
121 return json.load(f)
122
123 def set(self, blueprint, token):
124 with open(self.filepath, "w") as f:
125 json.dump(token, f)
126
127 def delete(self, blueprint):
128 os.remove(self.filepath)
129
130 Then, just create an instance of your storage and assign it to the
131 :attr:`storage` attribute of your blueprint, and Flask-Dance will use it.
132
133 .. _ORM: https://docs.python.org/3.4/howto/webservers.html#data-persistence