diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8793b138..c531d449 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -8,7 +8,7 @@ Navigate to the project directory and run the following commands: Create and activate a virtual environment .. code-block:: bash - + $ python -m venv .venv $ source .venv/bin/activate @@ -16,7 +16,7 @@ Install dependencies .. code-block:: bash - $ pip install -r requirements/dev.in + $ pip install -r requirements/dev.txt $ pip install -r requirements/docs.in Install the package in editable mode @@ -47,11 +47,11 @@ or Run the tests together or individually .. code-block:: bash - + $ pytest tests $ pytest tests/test_basic.py -For easier startup and teardown of storage for testing you may use +For easier startup and teardown of storage for testing you may use .. code-block:: bash @@ -62,13 +62,13 @@ Using rye ~~~~~~~~~~~ .. code-block:: bash - + $ rye pin 3.11 $ rye sync .. code-block:: bash - + $ rye run python examples/hello.py diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index d0c4c815..62186cc4 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,5 +1,6 @@ ## Contributors +- [eiriklid](https://github.com/eiriklid) - [necat1](https://github.com/necat1) - [nebolax](https://github.com/nebolax) - [Taragolis](https://github.com/Taragolis) diff --git a/docs/installation.rst b/docs/installation.rst index fd00504c..99313035 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -8,13 +8,14 @@ Install from PyPI using an installer such as pip: $ pip install Flask-Session -Flask-Session's only required dependency is msgspec for serialization, which has no sub-dependencies. +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-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_ library either directly or as an optional dependency like below: .. code-block:: bash - $ pip install redis + $ pip install Flask-Session[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. @@ -23,34 +24,58 @@ 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. -Direct support ---------------- +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: + +.. code-block:: bash + + pip install Flask-Session[] + +Available storage options and their corresponding ```` values are: -Flask-Session has an increasing number of directly supported storage and client libraries. .. list-table:: :header-rows: 1 :align: left * - Storage - - Client Library - * - Redis + - + - Default client library + - Alternative client libraries + * - **Redis** + - ``redis`` - redis-py_ - * - Memcached - - pylibmc_, python-memcached_, libmc_ or pymemcache_ - * - MongoDB + - + * - **Memcached** + - ``memcached`` + - pymemcache_ + - pylibmc_, python-memcached_, libmc_ + * - **MongoDB** + - ``mongodb`` - pymongo_ - * - SQL Alchemy + - + * - **CacheLib** + - ``cachelib`` + - cachelib_ + - + * - **SQLAlchemy** + - ``sqlalchemy`` - flask-sqlalchemy_ - * - DynamoDB + - + * - **DynamoDB** + - ``dynamodb`` - boto3_ + - -Other libraries may work if they use the same commands as the ones listed above. +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 @@ -72,7 +97,7 @@ Flask-Session also indirectly supports storage and client libraries via cachelib - pymongo_ * - DynamoDB - boto3_ - + .. warning:: @@ -84,10 +109,10 @@ 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 .. _libmc: https://github.com/douban/libmc .. _uwsgi: https://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html -.. _pickle: https://docs.python.org/3/library/pickle.html \ No newline at end of file +.. _pickle: https://docs.python.org/3/library/pickle.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 49c2a4f5..b331e2b7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,6 +26,14 @@ dependencies = [ ] dynamic = ["version"] +[project.optional-dependencies] +cachelib = ["cachelib>=0.10.2"] +memcached = ["pymemcache"] +mongodb = ["pymongo>=4.6.2"] +redis = ["redis>=5.0.3"] +sqlalchemy = ["flask-sqlalchemy>=3.0.5"] +all = ["Flask-Session[cachelib, memcached, mongodb, redis, sqlalchemy]"] + [project.urls] Documentation = "https://flask-session.readthedocs.io" Changes = "https://flask-session.readthedocs.io/changes.html" diff --git a/src/flask_session/__init__.py b/src/flask_session/__init__.py index 0f9a5ee6..b95a0b05 100644 --- a/src/flask_session/__init__.py +++ b/src/flask_session/__init__.py @@ -1,6 +1,6 @@ from .defaults import Defaults -__version__ = "0.7.3rc2" +__version__ = "0.8.0" class Session: