Docs cleanup and linting

CHANGES.rst

@@ -2,20 +2,23 @@ Version 0.7.0
 ------------------
 
 Added
--   Use msgpack for serialization, along with ``SESSION_SERIALIZATION_FORMAT`` to choose between ``json`` and ``msgpack``.
+~~~~~~~
+-   Use msgpack for serialization, along with ``SESSION_SERIALIZATION_FORMAT`` to choose between ``'json'`` and ``'msgpack'``.
 -   Add time-to-live expiration for MongoDB.
 -   Add retry for SQL based storage.
 -   Add ``flask session_cleanup`` command and alternatively, ``SESSION_CLEANUP_N_REQUESTS`` for SQLAlchemy or future non-TTL backends.
 -   Type hints.
 -   Add logo and additional documentation.
 
 Deprecated
--   Deprecated pickle. It is still available to read existing sessions, but will be removed in 1.0.0. All sessions will transfer to msgspec upon first interaction with 0.7.0.
+~~~~~~~~~~
+-   Deprecated pickle. It is still available to read existing sessions, but will be removed in 1.0.0. All sessions will transfer to msgspec upon first interaction with 0.1.0.
 -   Remove null session in favour of specific exception messages.
 -   Deprecate ``SESSION_USE_SIGNER``.
--   Deprecate FileSystemSessionInterface in favor of the broader CacheLibSessionInterface.
+-   Deprecate :class:`flask_session.filesystem.FileSystemSessionInterface` in favor of the broader :class:`flask_session.cachelib.CacheLibSessionInterface`.
 
 Fixed
+~~~~~
 -   Prevent sid reuse on storage miss.
 -   Abstraction to improve consistency between backends.
 -   Enforce ``PERMANENT_SESSION_LIFETIME`` as expiration consistently for all backends.
@@ -28,7 +31,7 @@ Version 0.6.0
 
 Released 2024-01-16
 
--   Use ``should_set_cookie`` for preventing each request from saving the session again.
+-   Use :meth:`~ServerSideSession.should_set_cookie` for preventing each request from saving the session again.
 -   Permanent session otherwise empty will not be saved.
 -   Use `secrets` module to generate session identifiers, with 256 bits of
     entropy (was previously 122).

docs/_static/styles.css

@@ -3,3 +3,11 @@
 .padded {
     padding: 40px;
 }
+
+table {
+    max-width: 680px;
+    width: -webkit-fill-available;
+    width: -moz-available;
+    width: fill-available;
+    width: stretch;    
+}

docs/conf.py

@@ -14,6 +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),
 }
 
 

docs/config_cleanup.rst

@@ -1,16 +1,18 @@
 Scheduled session cleanup
 -------------------------
 
-This is not required for the ``Redis``, ``Memecached``, ``Filesystem``, ``Mongodb`` storage engines, as they support time-to-live for keys.
 
-.. caution ::
+.. important ::
+
+    In the case of ``SQLAlchemy``, expired sessions are not automatically deleted from the database. You must use one of the following scheduled cleanup methods.
 
-    In the case of the storage engines that do not support time-to-live (SQLAlchemy), expired sessions are not automatically deleted from the database. You must use one of the following scheduled cleanup methods.
 
 Run the the following command regularly with a cron job or scheduler such as Heroku Scheduler to clean up expired sessions. This is the recommended way to clean up expired sessions.
 
 .. code-block:: bash
 
     flask session_cleanup
 
-Alternatively, set the configuration variable `SESSION_CLEANUP_N_REQUESTS` to the average number of requests after which the cleanup should be performed. This is less desirable than using the scheduled app command cleanup as it may slow down some requests but may be useful for small applications or rapid development.
+Alternatively, set the configuration variable ``SESSION_CLEANUP_N_REQUESTS`` to the average number of requests after which the cleanup should be performed. This is less desirable than using the scheduled app command cleanup as it may slow down some requests but may be useful for small applications or rapid development.
+
+This is not required for the ``Redis``, ``Memecached``, ``Filesystem``, ``Mongodb`` storage engines, as they support time-to-live for records.

docs/config_example.rst

@@ -9,15 +9,13 @@ Here is an example of how to configure a redis backend:
     app.config['SESSION_REDIS'] = Redis.from_url('redis://127.0.0.1:6379')
 
 We are not supplying something like ``SESSION_REDIS_HOST`` and
-``SESSION_REDIS_PORT``, if you want to use the ``RedisSessionInterface``,
-you should configure ``SESSION_REDIS`` to your own ``redis.Redis`` instance.
-This gives you more flexibility, such as using the same
-``redis.Redis`` instance for cache purposes too, then you do not need to keep
-two ``redis.Redis`` instance in the same process.
+``SESSION_REDIS_PORT``, instead you should configure ``SESSION_REDIS`` to your own :meth:`redis.Redis` instance.
+This gives you more flexibility, such as using the same instance for cache purposes too, then you do not need to keep
+two instances in the same process.
 
 If you do not set ``SESSION_REDIS``, Flask-Session will assume you are developing locally and create a
-``redis.Redis`` instance for you. It is expected you supply an instance of
-``redis.Redis`` in production.
+:meth:`redis.Redis` instance for you. It is expected you supply an instance of
+:meth:`redis.Redis` in production.
 
 .. note::
 

docs/config_exceptions.rst

@@ -3,7 +3,7 @@ Retries
 
 Only for SQL based storage, upon an exception, Flask-Session will retry with backoff up to 3 times. If the operation still fails after 3 retries, the exception will be raised.
 
-For other storage types, the retry logic is either included or can be configured in the client setup. Refer to the client's documentation for more information.
+For other storage types, the retry logic is either included or can be configured in the client setup. Refer to the relevant client documentation for more information.
 
 Redis example with retries on certain errors:
 

docs/config_flask.rst

@@ -21,10 +21,10 @@ modify them at runtime.
 
 `SESSION_COOKIE_SAMESITE`_
 
-`PERMANENT_SESSION_LIFETIME`_
-
 `SESSION_REFRESH_EACH_REQUEST`_
 
+`PERMANENT_SESSION_LIFETIME`_
+
 .. _SESSION_COOKIE_NAME: https://flask.palletsprojects.com/en/latest/config/#SESSION_COOKIE_NAME
 .. _SESSION_COOKIE_DOMAIN: https://flask.palletsprojects.com/en/latest/config/#SESSION_COOKIE_DOMAIN
 .. _SESSION_COOKIE_PATH: https://flask.palletsprojects.com/en/latest/config/#SESSION_COOKIE_PATH

docs/config_flask_session.rst

@@ -30,6 +30,8 @@ These are specific to Flask-Session.
 
    Default: ``False``
 
+   .. deprecated:: 0.7.0
+
 .. py:data:: SESSION_KEY_PREFIX
 
    A prefix that is added before all session keys. This makes it easier to use the same backend storage server for different apps.
@@ -42,14 +44,21 @@ These are specific to Flask-Session.
 
    Default: ``32``
 
+   .. versionadded:: 0.6.0
+
 .. py:data:: SESSION_SERIALIZATION_FORMAT
    
-   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.
+   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.
 
    Default: ``'msgpack'``
 
+   .. versionadded:: 0.7.0
+
+.. deprecated:: 0.7.0
+    ``SESSION_USE_SIGNER``
+
 .. versionadded:: 0.7.0
     ``SESSION_SERIALIZATION_FORMAT``
 
-.. versionadded:: 0.6
+.. versionadded:: 0.6.0
     ``SESSION_ID_LENGTH``

docs/config_nonpermanent.rst

@@ -1,7 +1,7 @@
 Non-permanent session configuration
 ------------------------------------
 
-.. warning::
+.. caution::
 
     Flask-session is primarily designed to be used with permanent sessions. If you want to use non-permanent sessions, you must set ``SESSION_PERMANENT=False`` and be aware of significant limitations.
 

docs/config_security.rst

@@ -2,16 +2,12 @@
 Security configuration
 ----------------------
 
-.. caution::
+.. warning::
 
   Flask is a micro-framework and does not provide all security features out of the box. It is important to configure security settings for your application.
 
 Please refer to documentation for `Flask`_, `OWASP`_, and other resources such as `MDN`_ for the latest information on best practice.
 
-.. _Flask: https://flask.palletsprojects.com/en/2.3.x/security/#set-cookie-options
-.. _MDN: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies
-.. _OWASP: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
-
 Consider the following Flask configurations in production:
 
 .. list-table::
@@ -26,4 +22,10 @@ Consider the following Flask configurations in production:
    * - SESSION_COOKIE_SAMESITE
      - Use ``Lax`` or ``Strict``
 
-You can use a security plugin such as ``Flask-Talisman`` to set these and more.
+You can use a security plugin such as `Flask-Talisman`_ to set these and more.
+
+
+.. _Flask: https://flask.palletsprojects.com/en/2.3.x/security/#set-cookie-options
+.. _MDN: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies
+.. _OWASP: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
+.. _Flask-Talisman: https://github.com/wntrblm/flask-talisman

docs/config_storage.rst

@@ -31,33 +31,40 @@ FileSystem
 
    Default: ``flask_session`` directory under current working directory.
 
+   .. deprecated:: 0.7.0
+
 .. py:data:: SESSION_FILE_THRESHOLD
     
    The maximum number of items the session stores before it starts deleting some.
 
    Default: ``500``
 
+   .. deprecated:: 0.7.0
+
 .. py:data:: SESSION_FILE_MODE
     
    The file mode wanted for the session files.
 
    Default: ``0600``
 
-.. deprecated:: 0.7.0
-    ``SESSION_FILE_MODE``, ``SESSION_FILE_THRESHOLD`` and ``SESSION_FILE_DIR``. Use ``SESSION_CACHELIB`` instead.
+   .. deprecated:: 0.7.0
 
-Cachelib
+CacheLib
 ~~~~~~~~~~~~~~~~~~~~~~~
 .. py:data:: SESSION_CACHELIB
 
-   Any valid `cachelib backend <https://cachelib.readthedocs.io/en/stable/>`_. This allows you maximum flexibility in choosing the cache backend and its configuration.
+   Any valid `cachelib backend <https://cachelib.readthedocs.io/en/stable/>`_. This allows you maximum flexibility in choosing the cache backend and it's configuration.
 
    The following would set a cache directory called "flask_session" and a threshold of 500 items before it starts deleting some.
 
    .. code-block:: python
 
       app.config['SESSION_CACHELIB'] = FileSystemCache(cache_dir='flask_session', threshold=500)
    
+   .. important::
+
+      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.
+
    Default: ``FileSystemCache`` in ``./flask_session`` directory.
 
 MongoDB
@@ -123,8 +130,12 @@ SqlAlchemy
 
    Default: ``None``
 
+.. deprecated:: 0.7.0
+
+   ``SESSION_FILE_DIR``, ``SESSION_FILE_THRESHOLD``, ``SESSION_FILE_MODE``. Use ``SESSION_CACHELIB`` instead.
+
 .. versionadded:: 0.7.0
     ``SESSION_CLEANUP_N_REQUESTS``
 
-.. versionadded:: 0.6
+.. versionadded:: 0.6.0
     ``SESSION_SQLALCHEMY_BIND_KEY``, ``SESSION_SQLALCHEMY_SCHEMA``, ``SESSION_SQLALCHEMY_SEQUENCE``

docs/installation.rst

@@ -10,52 +10,44 @@ Install from PyPI using an installer such as pip:
 
 Flask-Session's only required dependency is msgspec for serialization, which has no sub-dependencies. 
 
-.. note::
-
-  You need to choose a storage type and install an appropriate client library.
-
-For example, if you want to use Redis as your storage, you will need to install the redis-py client library:
+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:
 
 .. 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.
 
-Support
---------
+Direct support
+---------------
 
-Directly supported storage and client libraries:
+Flask-Session has an increasing number of directly supported storage and client libraries.
 
 .. list-table::
    :header-rows: 1
+   :align: left
 
    * - Storage
      - Client Library
    * - Redis
      - redis-py_
    * - Memcached
-     - pylibmc_, python-memcached_ or pymemcache_
+     - pylibmc_, python-memcached_, libmc_ or pymemcache_
    * - MongoDB
      - pymongo_
    * - SQL Alchemy
      - flask-sqlalchemy_
 
-Other clients may work if they use the same commands as the ones listed above.
+Other libraries may work if they use the same commands as the ones listed above.
 
 Cachelib
 --------
 
-Flask-Session also indirectly supports storage and client libraries via cachelib_, which is a wrapper around various cache libraries and subject to change. You must also install cachelib_ itself to use these.
-
-.. warning::
-
-  As of writing, cachelib_ still use pickle_ as the default serializer, which may have security implications.
-
-Using cachlib :class:`FileSystemCache`` or :class:`SimpleCache` may be useful for development.
+Flask-Session also indirectly supports storage and client libraries via cachelib_, which is a wrapper around various cache libraries. You must also install cachelib_ itself to use these.
 
 .. list-table::
    :header-rows: 1
+   :align: left
 
    * - Storage
      - Client Library
@@ -75,6 +67,10 @@ Using cachlib :class:`FileSystemCache`` or :class:`SimpleCache` may be useful fo
      - boto3_
 
 
+.. warning::
+
+  As of writing, cachelib_ still uses pickle_ as the default serializer, which may have security implications in production.
+
 
 .. _redis-py: https://github.com/andymccurdy/redis-py
 .. _pylibmc: http://sendapatch.se/projects/pylibmc/

docs/introduction.rst

@@ -14,11 +14,11 @@ This is done by placing it in a cookie that is sent to and from the client on ea
 This can be any small, basic information about that client or their interactions for quick retrieval (up to 4kB). 
 
 Server-side sessions differ by storing session data in server-side storage. 
-A cookie is also used but it only contains the session identifier that links the client to their corresponding data on the server.
+A cookie is also used, but it only contains the session identifier that links the client to their corresponding data on the server.
 
-.. note::
-   There are no individual session size limitations on server-side sessions, 
-   but developers should be cautious about abusing them for data which would be more suited for actual database storage.
+.. tip::
+   There are generally (some exceptions) no individual session size limitations for server-side sessions, 
+   but developers should be cautious about abusing this for amounts or types data that would be more suited for actual database storage.
 
 Flask-Session sequence diagram
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/usage.rst

@@ -7,15 +7,9 @@ Quickstart
 .. currentmodule:: flask_session
 
 
-Create your Flask application, load the configuration of choice, and
+Create your :class:`~flask.Flask` application, load the configuration of choice, and
 then create the :class:`Session` object by passing it the application.
 
-.. note::
-
-        You can not use ``Session`` instance directly, what ``Session`` does
-        is just change the :attr:`~flask.Flask.session_interface` attribute on
-        your Flask applications. You should always use :class:`flask.session` when accessing the current session.
-
 .. code-block:: python
 
     from flask import Flask, session
@@ -38,24 +32,30 @@ then create the :class:`Session` object by passing it the application.
 
 This would automatically setup a redis client connected to `localhost:6379` and use it to store the session data.
 
-See the `configuration section <config.rst>`_ for more details.
+.. note::
+
+        You can not use :class:`~Session` instance directly, what :class:`~Session` does
+        is just change the :attr:`~flask.Flask.session_interface` attribute on
+        your Flask applications. You should always use :class:`flask.session` when accessing or modifying the current session.
+
+See the configuration section for more details.
 
 Alternative initialization
 ---------------------------
 
-Rather than calling `Session(app)`, you may initialize later using :meth:`~Session.init_app`.
+Rather than calling :class:`~Session`, you may initialize later using :meth:`~Session.init_app`.
 
 .. 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 the interface constructor directly to the :attr:`session_interface`.
+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_session.implementations.redis import RedisSessionInterface
-
+    from flask_session.redis import RedisSessionInterface
+    from redis import Redis
     ...
 
     redis = Redis(