Doc tweaks, include pickle warning

Documentation

Author: Lxstr

docs/_static/styles.css

@@ -10,4 +10,4 @@ table {
     width: -moz-available;
     width: fill-available;
     width: stretch;    
-}
+}

docs/conf.py

@@ -14,7 +14,7 @@
     "flask": ("http://flask.palletsprojects.com/", None),
     "werkzeug": ("http://werkzeug.palletsprojects.com/", None),
     "flask-sqlalchemy": ("http://flask-sqlalchemy.palletsprojects.com/", None),
-    "redis": ("http://redis-py.readthedocs.io/", None),
+    "redis": ("http://redis-py.readthedocs.io/en/stable/", None),
 }
 
 
@@ -59,6 +59,7 @@
 html_static_path = ["_static"]
 html_theme = "furo"
 html_theme_options = {
+    "announcement": "Flask-Session is switching serializers to msgpack in 1.0.0. Use version 0.7.0 if you need graceful migration for existing sessions.",
     "source_repository": "https://github.com/pallets-eco/flask-session/",
     "source_branch": "main",
     "source_directory": "docs/",

docs/config_flask.rst

@@ -35,4 +35,4 @@ modify them at runtime.
 .. _SESSION_REFRESH_EACH_REQUEST: https://flask.palletsprojects.com/en/latest/config/#SESSION_REFRESH_EACH_REQUEST
 
 .. note::
-      ``PERMANENT_SESSION_LIFETIME`` is also used to set the expiration time of the session data on the server side, regardless of permanence.
+      ``PERMANENT_SESSION_LIFETIME`` is also used to set the expiration time of the session data on the server side, regardless of ``SESSION_PERMANENT``.

docs/config_security.rst

@@ -12,6 +12,7 @@ Consider the following Flask configurations in production:
 
 .. list-table::
    :header-rows: 1
+   :align: left
 
    * - Setting
      - Consideration

docs/installation.rst

@@ -10,14 +10,19 @@ Install from PyPI using an installer such as pip:
 
 Flask-Session's only required dependency is msgspec for serialization, which has no sub-dependencies. 
 
-You need to choose a storage type and install an appropriate client library so the app can communicate with storage. For example, if you want to use Redis as your storage, you will need to install the redis-py client library:
+However, you also need to choose a storage type and install an appropriate client library so the app can communicate with storage. For example, if you want to use Redis as your storage, you will need to install the redis-py client library:
 
 .. code-block:: bash
 
     $ pip install redis
 
 Redis is the recommended storage type for Flask-Session, as it has the most complete support for the features of Flask-Session with minimal configuration.
 
+.. warning::
+
+  Flask-Session versions below 1.0.0 (not yet released), use pickle_ as the default serializer, which may have security implications in production if your storage is ever compromised.
+
+
 Direct support
 ---------------
 
@@ -60,7 +65,7 @@ Flask-Session also indirectly supports storage and client libraries via cachelib
    * - Redis
      - redis-py_
    * - Memcached
-     - pylibmc_, memcached, libmc_ or `google.appengine.api.memcached`_
+     - pylibmc_, python-memcached_, libmc_ or `google.appengine.api.memcached`_
    * - MongoDB
      - pymongo_
    * - DynamoDB
@@ -69,10 +74,10 @@ Flask-Session also indirectly supports storage and client libraries via cachelib
 
 .. warning::
 
-  As of writing, cachelib_ still uses pickle_ as the default serializer, which may have security implications in production.
+  As of writing, cachelib_ still uses pickle_ as the default serializer, which may have security implications in production if your storage is ever compromised.
 
 
-.. _redis-py: https://github.com/andymccurdy/redis-py
+.. _redis-py: https://github.com/redis/redis-py
 .. _pylibmc: http://sendapatch.se/projects/pylibmc/
 .. _python-memcached: https://github.com/linsomniac/python-memcached
 .. _pymemcache: https://github.com/pinterest/pymemcache

docs/usage.rst

@@ -18,6 +18,7 @@ then create the :class:`Session` object by passing it the application.
     app = Flask(__name__)
 
     SESSION_TYPE = 'redis'
+    SESSION_REDIS = Redis(host='localhost', port=6379)
     app.config.from_object(__name__)
     Session(app)
 
@@ -47,21 +48,21 @@ Rather than calling :class:`~Session`, you may initialize later using :meth:`~Se
 
 .. code-block:: python
     
+    ...
     sess = Session()
     sess.init_app(app)
 
 Or, if you prefer to directly set parameters rather than using the configuration constants, you can initialize by setting an instance of :class:`flask_session.redis.RedisSessionInterface` directly to the :attr:`flask.Flask.session_interface`.
 
 .. code-block:: python
 
+    from flask import Flask, session
     from flask_session.redis import RedisSessionInterface
     from redis import Redis
-    ...
 
-    redis = Redis(
-        host='localhost',
-        port=6379,
-    )
+    app = Flask(__name__)
+
+    redis = Redis(host='localhost', port=6379)
     app.session_interface = RedisSessionInterface(
         client=redis,
     )

src/flask_session/cachelib/__init__.py

@@ -1 +1 @@
-from .cachelib import CacheLibSessionInterface, CacheLibSession  # noqa: F401
+from .cachelib import CacheLibSession, CacheLibSessionInterface  # noqa: F401

src/flask_session/filesystem/filesystem.py

@@ -16,7 +16,7 @@ class FileSystemSession(ServerSideSession):
 class FileSystemSessionInterface(ServerSideSessionInterface):
     """Uses the :class:`cachelib.file.FileSystemCache` as a session storage.
 
-    :param key_prefix: A prefix that is added to stored keys.
+    :param key_prefix: A prefix that is added to storage keys.
     :param use_signer: Whether to sign the session id cookie or not.
     :param permanent: Whether to use permanent session or not.
     :param sid_length: The length of the generated session id in bytes.

src/flask_session/memcached/memcached.py

@@ -21,7 +21,7 @@ class MemcachedSessionInterface(ServerSideSessionInterface):
     """A Session interface that uses memcached as session storage. (`pylibmc`, `libmc`, `python-memcached` or `pymemcache` required)
 
     :param client: A ``memcache.Client`` instance.
-    :param key_prefix: A prefix that is added to all Memcached store keys.
+    :param key_prefix: A prefix that is added to all storage keys.
     :param use_signer: Whether to sign the session id cookie or not.
     :param permanent: Whether to use permanent session or not.
     :param sid_length: The length of the generated session id in bytes.