Debian Codegraph @

docs/config.rst

raw
1 Configuration
2 =============
3
4 .. include:: config_example.rst
5
6 .. include:: config_nonpermanent.rst
7
8 .. include:: config_cleanup.rst
9
10 .. include:: config_exceptions.rst
11
12 .. include:: config_serialization.rst
13
14 .. include:: config_flask.rst
15
16
17 Flask-Session configuration values
18 ----------------------------------
19
20 These are specific to Flask-Session.
21
22 .. py:data:: SESSION_TYPE
23
24 Specifies which type of session interface to use. Built-in session types:
25
26 - **redis**: RedisSessionInterface
27 - **memcached**: MemcachedSessionInterface
28 - **filesystem**: FileSystemSessionInterface (Deprecated in 0.7.0, will be removed in 1.0.0 in favor of CacheLibSessionInterface)
29 - **cachelib**: CacheLibSessionInterface
30 - **mongodb**: MongoDBSessionInterface
31 - **sqlalchemy**: SqlAlchemySessionInterface
32
33 .. py:data:: SESSION_PERMANENT
34
35 Whether use permanent session or not.
36
37 Default: ``True``
38
39 .. py:data:: SESSION_USE_SIGNER
40
41 Whether sign the session cookie sid or not, if set to ``True``, you have to set :attr:`flask.Flask.secret_key`.
42
43 .. note::
44 This feature is historical and generally only relevant if you are using client-side sessions ie. not Flask-Session. SESSION_ID_LENGTH provides the relevant entropy for session identifiers.
45
46 Default: ``False``
47
48 .. deprecated:: 0.7.0
49
50 .. py:data:: SESSION_KEY_PREFIX
51
52 A prefix that is added before all session keys. This makes it easier to use the same backend storage server for different apps.
53
54 Default: ``'session:'``
55
56 .. py:data:: SESSION_ID_LENGTH
57
58 The length of the session identifier in bytes (of entropy).
59
60 Default: ``32``
61
62 .. versionadded:: 0.6.0
63
64 .. py:data:: SESSION_SERIALIZATION_FORMAT
65
66 The serialization format to use. Can be `'msgpack'`` or `'json'`. Set to `'msgpack'`` for a more efficient serialization format. Set to `'json'`` for a human-readable format.
67
68 Default: ``'msgpack'``
69
70 .. versionadded:: 0.7.0
71
72 .. deprecated:: 0.7.0
73 ``SESSION_USE_SIGNER``
74
75 .. versionadded:: 0.7.0
76 ``SESSION_SERIALIZATION_FORMAT``
77
78 .. versionadded:: 0.6.0
79 ``SESSION_ID_LENGTH``
80
81
82 Storage configuration
83 ---------------------
84
85
86 Redis
87 ~~~~~~~~~~~~~~~~~~~~~~~
88
89 .. py:data:: SESSION_REDIS
90
91 A ``redis.Redis`` instance.
92
93 Default: Instance connected to ``127.0.0.1:6379``
94
95
96 Memcached
97 ~~~~~~~~~~~~~~~~~~~~~~~
98
99 .. py:data:: SESSION_MEMCACHED
100
101 A ``memcache.Client`` instance.
102
103 Default: Instance connected to ``127.0.0.1:6379``
104
105
106 FileSystem
107 ~~~~~~~~~~~~~~~~~~~~~~~
108
109 .. py:data:: SESSION_FILE_DIR
110
111 The directory where session files are stored.
112
113 Default: ``flask_session`` directory under current working directory.
114
115 .. deprecated:: 0.7.0
116
117 .. py:data:: SESSION_FILE_THRESHOLD
118
119 The maximum number of items the session stores before it starts deleting some.
120
121 Default: ``500``
122
123 .. deprecated:: 0.7.0
124
125 .. py:data:: SESSION_FILE_MODE
126
127 The file mode wanted for the session files.
128
129 Default: ``0600``
130
131 .. deprecated:: 0.7.0
132
133 CacheLib
134 ~~~~~~~~~~~~~~~~~~~~~~~
135 .. py:data:: SESSION_CACHELIB
136
137 Any valid `cachelib backend <https://cachelib.readthedocs.io/en/stable/>`_. This allows you maximum flexibility in choosing the cache backend and it's configuration.
138
139 The following would set a cache directory called "flask_session" and a threshold of 500 items before it starts deleting some.
140
141 .. code-block:: python
142
143 app.config['SESSION_CACHELIB'] = FileSystemCache(cache_dir='flask_session', threshold=500)
144
145 .. important::
146
147 A ``default_timeout`` set in any of the ``CacheLib`` backends will be overrode by the ``PERMANENT_SESSION_LIFETIME`` when each stored session's expiry is set.
148
149 Default: ``FileSystemCache`` in ``./flask_session`` directory.
150
151 MongoDB
152 ~~~~~~~~~~~~~~~~~~~~~~~
153
154 .. py:data:: SESSION_MONGODB
155
156 A ``pymongo.MongoClient`` instance.
157
158 Default: Instance connected to ``127.0.0.1:27017``
159
160 .. py:data:: SESSION_MONGODB_DB
161
162 The MongoDB database you want to use.
163
164 Default: ``'flask_session'``
165
166 .. py:data:: SESSION_MONGODB_COLLECT
167
168 The MongoDB collection you want to use.
169
170 Default: ``'sessions'``
171
172
173 SqlAlchemy
174 ~~~~~~~~~~~~~~~~~~~~~~~
175
176 .. py:data:: SESSION_SQLALCHEMY
177
178 A ``flask_sqlalchemy.SQLAlchemy`` instance whose database connection URI is configured using the ``SQLALCHEMY_DATABASE_URI`` parameter.
179
180 Must be set in flask_sqlalchemy version 3.0 or higher.
181
182 .. py:data:: SESSION_SQLALCHEMY_TABLE
183
184 The name of the SQL table you want to use.
185
186 Default: ``'sessions'``
187
188 .. py:data:: SESSION_SQLALCHEMY_SEQUENCE
189
190 The name of the sequence you want to use for the primary key.
191
192 Default: ``None``
193
194 .. py:data:: SESSION_SQLALCHEMY_SCHEMA
195
196 The name of the schema you want to use.
197
198 Default: ``None``
199
200 .. py:data:: SESSION_SQLALCHEMY_BIND_KEY
201
202 The name of the bind key you want to use.
203
204 Default: ``None``
205
206 .. py:data:: SESSION_CLEANUP_N_REQUESTS
207
208 Only applicable to non-TTL backends.
209
210 The average number of requests after which Flask-Session will perform a session cleanup. This involves removing all session data that is older than ``PERMANENT_SESSION_LIFETIME``. Using the app command ``flask session_cleanup`` instead is preferable.
211
212 Default: ``None``
213
214 Dynamodb
215 ~~~~~~~~~~~~~~~~~~~~~~~
216
217 .. py:data:: SESSION_DYNAMODB
218
219 A ``boto3.resource`` instance.
220
221 Default: Instance connected to ``'localhost:8000'``
222
223 .. py:data:: SESSION_DYNAMODB_TABLE_NAME
224
225 The name of the table you want to use.
226
227 Default: ``'Sessions'``
228
229 .. deprecated:: 0.7.0
230
231 ``SESSION_FILE_DIR``, ``SESSION_FILE_THRESHOLD``, ``SESSION_FILE_MODE``. Use ``SESSION_CACHELIB`` instead.
232
233 .. versionadded:: 0.7.0
234 ``SESSION_CLEANUP_N_REQUESTS``
235
236 .. versionadded:: 0.6.0
237 ``SESSION_SQLALCHEMY_BIND_KEY``, ``SESSION_SQLALCHEMY_SCHEMA``, ``SESSION_SQLALCHEMY_SEQUENCE``