diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index f8aafac8..07122b42 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,5 +1,6 @@ ## Contributors +- [eiriklid](https://github.com/eiriklid) - [nebolax](https://github.com/nebolax) - [Taragolis](https://github.com/Taragolis) - [Lxstr](https://github.com/Lxstr) diff --git a/docs/installation.rst b/docs/installation.rst index ccbe4496..99313035 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -10,7 +10,8 @@ Install from PyPI using an installer such as pip: Flask-Session's only required dependency is msgspec for serialization, which has no sub-dependencies. -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 optional dependency: +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_ library either directly or as an optional dependency like below: .. code-block:: bash @@ -23,14 +24,7 @@ Redis is the recommended storage type for Flask-Session, as it has the most comp 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. -Enhanced Installation Options ------------------------------ - -Flask-Session now supports a variety of storage backends directly through optional dependencies. This simplifies the installation process, allowing you to specify the required storage backend at the time of Flask-Session installation itself. - -Below is a guide on how to install Flask-Session with support for the desired storage backend: - -Available Storage Options +Available storage options ^^^^^^^^^^^^^^^^^^^^^^^^^ To install Flask-Session with support for a specific storage backend, use the following command, replacing ```` with your chosen backend from the list below: @@ -41,50 +35,47 @@ To install Flask-Session with support for a specific storage backend, use the fo Available storage options and their corresponding ```` values are: -- **Redis**: ``redis`` -- **Memcached**: ``memcached`` -- **MongoDB**: ``mongodb`` -- **SQLAlchemy**: ``sqlalchemy`` -- **FileSystem**: ``filesystem`` -- **CacheLib**: ``cachelib`` - -For Developers and Contributors -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you're developing with Flask-Session or contributing to its codebase, you might want to install all supported backends along with additional development tools. You can do so by specifying the ``dev`` option: - -.. code-block:: bash - - pip install Flask-Session[dev] - -This will install Flask-Session along with all the optional dependencies listed under the ``dev`` category in ``pyproject.toml``, facilitating a comprehensive development setup. - -Direct Support --------------- - -Flask-Session provides built-in support for a number of storage backends through the use of client libraries. Below is a list of supported storage options along with their respective client libraries: .. list-table:: :header-rows: 1 :align: left * - Storage - - Client Library - * - Redis - - ``redis`` (via ``redis-py``) - * - Memcached - - ``pymemcache`` - * - MongoDB - - ``pymongo`` - * - SQL Alchemy - - ``flask-sqlalchemy`` + - + - Default client library + - Alternative client libraries + * - **Redis** + - ``redis`` + - redis-py_ + - + * - **Memcached** + - ``memcached`` + - pymemcache_ + - pylibmc_, python-memcached_, libmc_ + * - **MongoDB** + - ``mongodb`` + - pymongo_ + - + * - **CacheLib** + - ``cachelib`` + - cachelib_ + - + * - **SQLAlchemy** + - ``sqlalchemy`` + - flask-sqlalchemy_ + - + * - **DynamoDB** + - ``dynamodb`` + - boto3_ + - Other storage backends might be compatible with Flask-Session as long as they adhere to the command interfaces used by the libraries listed above. Cachelib -------- -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. +Flask-Session also indirectly supports storage and client libraries via cachelib_, which is a wrapper around various cache libraries. +You must also install cachelib_ itselfand the relevant client library to use these. .. list-table:: :header-rows: 1 @@ -118,7 +109,7 @@ Flask-Session also indirectly supports storage and client libraries via cachelib .. _python-memcached: https://github.com/linsomniac/python-memcached .. _pymemcache: https://github.com/pinterest/pymemcache .. _pymongo: https://pymongo.readthedocs.io/en/stable -.. _Flask-SQLAlchemy: https://github.com/pallets-eco/flask-sqlalchemy +.. _flask-sqlalchemy: https://github.com/pallets-eco/flask-sqlalchemy .. _cachelib: https://cachelib.readthedocs.io/en/stable/ .. _google.appengine.api.memcached: https://cloud.google.com/appengine/docs/legacy/standard/python/memcache .. _boto3: https://boto3.amazonaws.com/v1/documentation/api/latest/index.html diff --git a/docs/usage.rst b/docs/usage.rst index ce389615..675d9e9e 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -62,4 +62,28 @@ Or, if you prefer to directly set parameters rather than using the configuration app = Flask(__name__) redis = Redis(host='localhost', port=6379) - app.session_interface = RedisSessionInterface(client=redis) \ No newline at end of file + app.session_interface = RedisSessionInterface(client=redis) + + +Using CacheLib as a session backend +------------------------------------ + +.. note:: + + FileSystemSession was recently deprecated in favor of CacheLib, which is what is was using under the hood. + +The following example demonstrates how to use CacheLib as a session backend with the file system cache. This might be useful for rapid development or testing. + +.. code-block:: python + + from flask import Flask, session + from flask_session import Session + from cachelib.file import FileSystemCache + + app = Flask(__name__) + + SESSION_TYPE = 'cachelib' + SESSION_SERIALIZATION_FORMAT = 'json' + SESSION_CACHELIB = FileSystemCache(threshold=500, cache_dir="/sessions"), + app.config.from_object(__name__) + Session(app) \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 4f6952b0..4c828700 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,12 +27,11 @@ dynamic = ["version"] [project.optional-dependencies] cachelib = ["cachelib>=0.10.2"] -filesystem = ["cachelib>=0.10.2"] memcached = ["pymemcache"] mongodb = ["pymongo>=4.6.2"] redis = ["redis>=5.0.3"] sqlalchemy = ["flask-sqlalchemy>=3.0.5"] -dev = ["Flask-Session[cachelib, filesystem, memcached, mongodb, redis, sqlalchemy]"] +all = ["Flask-Session[cachelib, memcached, mongodb, redis, sqlalchemy]"] [project.urls] Documentation = "https://flask-session.readthedocs.io"