Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Let Flask-Session be installed with optional dependencies. #228

Merged
merged 3 commits into from
Mar 24, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ 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

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
Expand Down Expand Up @@ -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

Expand All @@ -62,18 +62,18 @@ Using rye
~~~~~~~~~~~

.. code-block:: bash

$ rye pin 3.11
$ rye sync


.. code-block:: bash

$ rye run python examples/hello.py


etc.

Pull requests
--------------
Please check previous pull requests before submitting a new one.
Please check previous pull requests before submitting a new one.
62 changes: 49 additions & 13 deletions docs/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ 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 optional dependency:

.. 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.

Expand All @@ -23,10 +23,46 @@ 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
---------------
Enhanced Installation Options
-----------------------------

Flask-Session has an increasing number of directly supported storage and client libraries.
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:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think lines 26 to 32 are probably not needed as you said enough on line 13. Removing this would make it more concise.

Available Storage Options
^^^^^^^^^^^^^^^^^^^^^^^^^

To install Flask-Session with support for a specific storage backend, use the following command, replacing ``<storage-option>`` with your chosen backend from the list below:

.. code-block:: bash

pip install Flask-Session[<storage-option>]

Available storage options and their corresponding ``<storage-option>`` 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think dev here is misleading as it wont actually install all libraries required for development, eg pytest. There is PEP735 still in the works but for now this is covered by the requirements files and rye-dependencies. If you use [all] it makes much more sense as installing all extras.

You could then delete all of these lines as they are covered in contributing


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
Expand All @@ -35,15 +71,15 @@ Flask-Session has an increasing number of directly supported storage and client
* - Storage
- Client Library
* - Redis
- redis-py_
- ``redis`` (via ``redis-py``)
* - Memcached
- pylibmc_, python-memcached_, libmc_ or pymemcache_
- ``pymemcache``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here while we should put this one first and also use it in tests and the default client for installation, we should also list the others as they are still compatible

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if the above list on line 44 could be rolled into this table, thereby making it clear what client is being installed and also having a final column for alternative client libraries

* - MongoDB
- pymongo_
- ``pymongo``
* - SQL Alchemy
- flask-sqlalchemy_
- ``flask-sqlalchemy``

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
--------
Expand All @@ -70,7 +106,7 @@ Flask-Session also indirectly supports storage and client libraries via cachelib
- pymongo_
* - DynamoDB
- boto3_


.. warning::

Expand All @@ -88,4 +124,4 @@ Flask-Session also indirectly supports storage and client libraries via cachelib
.. _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
.. _pickle: https://docs.python.org/3/library/pickle.html
9 changes: 9 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,15 @@ dependencies = [
]
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]"]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be all


[project.urls]
Documentation = "https://flask-session.readthedocs.io"
Changes = "https://flask-session.readthedocs.io/changes.html"
Expand Down
2 changes: 1 addition & 1 deletion src/flask_session/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from .defaults import Defaults

__version__ = "0.7.0"
__version__ = "0.8.0"


class Session:
Expand Down
Loading